# Copyright (C) 2001-2020, Python Software Foundation

# This file is distributed under the same license as the Python package.

# Maintained by the python-doc-es workteam.

# docs-es@python.org / https://mail.python.org/mailman3/lists/docs-es.python.org/

# Check https://github.com/PyCampES/python-docs-es/blob/3.7/TRANSLATORS to get the list of volunteers

#

#, fuzzy

msgid ""

msgstr ""

"Project-Id-Version: Python 3.7\n"

"Report-Msgid-Bugs-To: \n"

"POT-Creation-Date: 2019-05-06 11:59-0400\n"

"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"

"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"

"Language-Team: python-doc-es (https://mail.python.org/mailman3/lists/docs-es.python.org)\n"

"MIME-Version: 1.0\n"

"Content-Type: text/plain; charset=UTF-8\n"

"Content-Transfer-Encoding: 8bit\n"

#: ../Doc/extending/extending.rst:8

msgid "Extending Python with C or C++"

msgstr ""

#: ../Doc/extending/extending.rst:10

msgid ""

"It is quite easy to add new built-in modules to Python, if you know how to "

"program in C. Such :dfn:`extension modules` can do two things that can't be "

"done directly in Python: they can implement new built-in object types, and "

"they can call C library functions and system calls."

msgstr ""

#: ../Doc/extending/extending.rst:15

msgid ""

"To support extensions, the Python API (Application Programmers Interface) "

"defines a set of functions, macros and variables that provide access to most "

"aspects of the Python run-time system. The Python API is incorporated in a "

"C source file by including the header ``\"Python.h\"``."

msgstr ""

#: ../Doc/extending/extending.rst:20

msgid ""

"The compilation of an extension module depends on its intended use as well "

"as on your system setup; details are given in later chapters."

msgstr ""

#: ../Doc/extending/extending.rst:25

msgid ""

"The C extension interface is specific to CPython, and extension modules do "

"not work on other Python implementations. In many cases, it is possible to "

"avoid writing C extensions and preserve portability to other "

"implementations. For example, if your use case is calling C library "

"functions or system calls, you should consider using the :mod:`ctypes` "

"module or the `cffi <https://cffi.readthedocs.io/>`_ library rather than "

"writing custom C code. These modules let you write Python code to interface "

"with C code and are more portable between implementations of Python than "

"writing and compiling a C extension module."

msgstr ""

#: ../Doc/extending/extending.rst:40

msgid "A Simple Example"

msgstr ""

#: ../Doc/extending/extending.rst:42

msgid ""

"Let's create an extension module called ``spam`` (the favorite food of Monty "

"Python fans...) and let's say we want to create a Python interface to the C "

"library function :c:func:`system` [#]_. This function takes a null-"

"terminated character string as argument and returns an integer. We want "

"this function to be callable from Python as follows:"

msgstr ""

#: ../Doc/extending/extending.rst:53

msgid ""

"Begin by creating a file :file:`spammodule.c`. (Historically, if a module "

"is called ``spam``, the C file containing its implementation is called :file:"

"`spammodule.c`; if the module name is very long, like ``spammify``, the "

"module name can be just :file:`spammify.c`.)"

msgstr ""

#: ../Doc/extending/extending.rst:58

msgid "The first two lines of our file can be::"

msgstr ""

#: ../Doc/extending/extending.rst:63

msgid ""

"which pulls in the Python API (you can add a comment describing the purpose "

"of the module and a copyright notice if you like)."

msgstr ""

#: ../Doc/extending/extending.rst:68

msgid ""

"Since Python may define some pre-processor definitions which affect the "

"standard headers on some systems, you *must* include :file:`Python.h` before "

"any standard headers are included."

msgstr ""

#: ../Doc/extending/extending.rst:72

msgid ""

"It is recommended to always define ``PY_SSIZE_T_CLEAN`` before including "

"``Python.h``. See :ref:`parsetuple` for a description of this macro."

msgstr ""

#: ../Doc/extending/extending.rst:75

msgid ""

"All user-visible symbols defined by :file:`Python.h` have a prefix of ``Py`` "

"or ``PY``, except those defined in standard header files. For convenience, "

"and since they are used extensively by the Python interpreter, ``\"Python.h"

"\"`` includes a few standard header files: ``<stdio.h>``, ``<string.h>``, "

"``<errno.h>``, and ``<stdlib.h>``. If the latter header file does not exist "

"on your system, it declares the functions :c:func:`malloc`, :c:func:`free` "

"and :c:func:`realloc` directly."

msgstr ""

#: ../Doc/extending/extending.rst:83

msgid ""

"The next thing we add to our module file is the C function that will be "

"called when the Python expression ``spam.system(string)`` is evaluated "

"(we'll see shortly how it ends up being called)::"

msgstr ""

#: ../Doc/extending/extending.rst:99

msgid ""

"There is a straightforward translation from the argument list in Python (for "

"example, the single expression ``\"ls -l\"``) to the arguments passed to the "

"C function. The C function always has two arguments, conventionally named "

"*self* and *args*."

msgstr ""

#: ../Doc/extending/extending.rst:104

msgid ""

"The *self* argument points to the module object for module-level functions; "

"for a method it would point to the object instance."

msgstr ""

#: ../Doc/extending/extending.rst:107

msgid ""

"The *args* argument will be a pointer to a Python tuple object containing "

"the arguments. Each item of the tuple corresponds to an argument in the "

"call's argument list. The arguments are Python objects --- in order to do "

"anything with them in our C function we have to convert them to C values. "

"The function :c:func:`PyArg_ParseTuple` in the Python API checks the "

"argument types and converts them to C values. It uses a template string to "

"determine the required types of the arguments as well as the types of the C "

"variables into which to store the converted values. More about this later."

msgstr ""

#: ../Doc/extending/extending.rst:116

msgid ""

":c:func:`PyArg_ParseTuple` returns true (nonzero) if all arguments have the "

"right type and its components have been stored in the variables whose "

"addresses are passed. It returns false (zero) if an invalid argument list "

"was passed. In the latter case it also raises an appropriate exception so "

"the calling function can return *NULL* immediately (as we saw in the "

"example)."

msgstr ""

#: ../Doc/extending/extending.rst:126

msgid "Intermezzo: Errors and Exceptions"

msgstr ""

#: ../Doc/extending/extending.rst:128

msgid ""

"An important convention throughout the Python interpreter is the following: "

"when a function fails, it should set an exception condition and return an "

"error value (usually a *NULL* pointer). Exceptions are stored in a static "

"global variable inside the interpreter; if this variable is *NULL* no "

"exception has occurred. A second global variable stores the \"associated "

"value\" of the exception (the second argument to :keyword:`raise`). A third "

"variable contains the stack traceback in case the error originated in Python "

"code. These three variables are the C equivalents of the result in Python "

"of :meth:`sys.exc_info` (see the section on module :mod:`sys` in the Python "

"Library Reference). It is important to know about them to understand how "

"errors are passed around."

msgstr ""

#: ../Doc/extending/extending.rst:139

msgid ""

"The Python API defines a number of functions to set various types of "

"exceptions."

msgstr ""

#: ../Doc/extending/extending.rst:141

msgid ""

"The most common one is :c:func:`PyErr_SetString`. Its arguments are an "

"exception object and a C string. The exception object is usually a "

"predefined object like :c:data:`PyExc_ZeroDivisionError`. The C string "

"indicates the cause of the error and is converted to a Python string object "

"and stored as the \"associated value\" of the exception."

msgstr ""

#: ../Doc/extending/extending.rst:147

msgid ""

"Another useful function is :c:func:`PyErr_SetFromErrno`, which only takes an "

"exception argument and constructs the associated value by inspection of the "

"global variable :c:data:`errno`. The most general function is :c:func:"

"`PyErr_SetObject`, which takes two object arguments, the exception and its "

"associated value. You don't need to :c:func:`Py_INCREF` the objects passed "

"to any of these functions."

msgstr ""

#: ../Doc/extending/extending.rst:154

msgid ""

"You can test non-destructively whether an exception has been set with :c:"

"func:`PyErr_Occurred`. This returns the current exception object, or *NULL* "

"if no exception has occurred. You normally don't need to call :c:func:"

"`PyErr_Occurred` to see whether an error occurred in a function call, since "

"you should be able to tell from the return value."

msgstr ""

#: ../Doc/extending/extending.rst:160

msgid ""

"When a function *f* that calls another function *g* detects that the latter "

"fails, *f* should itself return an error value (usually *NULL* or ``-1``). "

"It should *not* call one of the :c:func:`PyErr_\\*` functions --- one has "

"already been called by *g*. *f*'s caller is then supposed to also return an "

"error indication to *its* caller, again *without* calling :c:func:`PyErr_"

"\\*`, and so on --- the most detailed cause of the error was already "

"reported by the function that first detected it. Once the error reaches the "

"Python interpreter's main loop, this aborts the currently executing Python "

"code and tries to find an exception handler specified by the Python "

"programmer."

msgstr ""

#: ../Doc/extending/extending.rst:170

msgid ""

"(There are situations where a module can actually give a more detailed error "

"message by calling another :c:func:`PyErr_\\*` function, and in such cases "

"it is fine to do so. As a general rule, however, this is not necessary, and "

"can cause information about the cause of the error to be lost: most "

"operations can fail for a variety of reasons.)"

msgstr ""

#: ../Doc/extending/extending.rst:176

msgid ""

"To ignore an exception set by a function call that failed, the exception "

"condition must be cleared explicitly by calling :c:func:`PyErr_Clear`. The "

"only time C code should call :c:func:`PyErr_Clear` is if it doesn't want to "

"pass the error on to the interpreter but wants to handle it completely by "

"itself (possibly by trying something else, or pretending nothing went wrong)."

msgstr ""

#: ../Doc/extending/extending.rst:182

msgid ""

"Every failing :c:func:`malloc` call must be turned into an exception --- the "

"direct caller of :c:func:`malloc` (or :c:func:`realloc`) must call :c:func:"

"`PyErr_NoMemory` and return a failure indicator itself. All the object-"

"creating functions (for example, :c:func:`PyLong_FromLong`) already do this, "

"so this note is only relevant to those who call :c:func:`malloc` directly."

msgstr ""

#: ../Doc/extending/extending.rst:188

msgid ""

"Also note that, with the important exception of :c:func:`PyArg_ParseTuple` "

"and friends, functions that return an integer status usually return a "

"positive value or zero for success and ``-1`` for failure, like Unix system "

"calls."

msgstr ""

#: ../Doc/extending/extending.rst:192

msgid ""

"Finally, be careful to clean up garbage (by making :c:func:`Py_XDECREF` or :"

"c:func:`Py_DECREF` calls for objects you have already created) when you "

"return an error indicator!"

msgstr ""

#: ../Doc/extending/extending.rst:196

msgid ""

"The choice of which exception to raise is entirely yours. There are "

"predeclared C objects corresponding to all built-in Python exceptions, such "

"as :c:data:`PyExc_ZeroDivisionError`, which you can use directly. Of course, "

"you should choose exceptions wisely --- don't use :c:data:`PyExc_TypeError` "

"to mean that a file couldn't be opened (that should probably be :c:data:"

"`PyExc_IOError`). If something's wrong with the argument list, the :c:func:"

"`PyArg_ParseTuple` function usually raises :c:data:`PyExc_TypeError`. If "

"you have an argument whose value must be in a particular range or must "

"satisfy other conditions, :c:data:`PyExc_ValueError` is appropriate."

msgstr ""

#: ../Doc/extending/extending.rst:206

msgid ""

"You can also define a new exception that is unique to your module. For this, "

"you usually declare a static object variable at the beginning of your file::"

msgstr ""

#: ../Doc/extending/extending.rst:211

msgid ""

"and initialize it in your module's initialization function (:c:func:"

"`PyInit_spam`) with an exception object (leaving out the error checking for "

"now)::"

msgstr ""

#: ../Doc/extending/extending.rst:229

msgid ""

"Note that the Python name for the exception object is :exc:`spam.error`. "

"The :c:func:`PyErr_NewException` function may create a class with the base "

"class being :exc:`Exception` (unless another class is passed in instead of "

"*NULL*), described in :ref:`bltin-exceptions`."

msgstr ""

#: ../Doc/extending/extending.rst:234

msgid ""

"Note also that the :c:data:`SpamError` variable retains a reference to the "

"newly created exception class; this is intentional! Since the exception "

"could be removed from the module by external code, an owned reference to the "

"class is needed to ensure that it will not be discarded, causing :c:data:"

"`SpamError` to become a dangling pointer. Should it become a dangling "

"pointer, C code which raises the exception could cause a core dump or other "

"unintended side effects."

msgstr ""

#: ../Doc/extending/extending.rst:241

msgid ""

"We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in "

"this sample."

msgstr ""

#: ../Doc/extending/extending.rst:244

msgid ""

"The :exc:`spam.error` exception can be raised in your extension module using "

"a call to :c:func:`PyErr_SetString` as shown below::"

msgstr ""

#: ../Doc/extending/extending.rst:267

msgid "Back to the Example"

msgstr ""

#: ../Doc/extending/extending.rst:269

msgid ""

"Going back to our example function, you should now be able to understand "

"this statement::"

msgstr ""

#: ../Doc/extending/extending.rst:275

msgid ""

"It returns *NULL* (the error indicator for functions returning object "

"pointers) if an error is detected in the argument list, relying on the "

"exception set by :c:func:`PyArg_ParseTuple`. Otherwise the string value of "

"the argument has been copied to the local variable :c:data:`command`. This "

"is a pointer assignment and you are not supposed to modify the string to "

"which it points (so in Standard C, the variable :c:data:`command` should "

"properly be declared as ``const char *command``)."

msgstr ""

#: ../Doc/extending/extending.rst:283

msgid ""

"The next statement is a call to the Unix function :c:func:`system`, passing "

"it the string we just got from :c:func:`PyArg_ParseTuple`::"

msgstr ""

#: ../Doc/extending/extending.rst:288

msgid ""

"Our :func:`spam.system` function must return the value of :c:data:`sts` as a "

"Python object. This is done using the function :c:func:`PyLong_FromLong`. ::"

msgstr ""

#: ../Doc/extending/extending.rst:293

msgid ""

"In this case, it will return an integer object. (Yes, even integers are "

"objects on the heap in Python!)"

msgstr ""

#: ../Doc/extending/extending.rst:296

msgid ""

"If you have a C function that returns no useful argument (a function "

"returning :c:type:`void`), the corresponding Python function must return "

"``None``. You need this idiom to do so (which is implemented by the :c:"

"macro:`Py_RETURN_NONE` macro)::"

msgstr ""

#: ../Doc/extending/extending.rst:304

msgid ""

":c:data:`Py_None` is the C name for the special Python object ``None``. It "

"is a genuine Python object rather than a *NULL* pointer, which means \"error"

"\" in most contexts, as we have seen."

msgstr ""

#: ../Doc/extending/extending.rst:312

msgid "The Module's Method Table and Initialization Function"

msgstr ""

#: ../Doc/extending/extending.rst:314

msgid ""

"I promised to show how :c:func:`spam_system` is called from Python programs. "

"First, we need to list its name and address in a \"method table\"::"

msgstr ""

#: ../Doc/extending/extending.rst:325

msgid ""

"Note the third entry (``METH_VARARGS``). This is a flag telling the "

"interpreter the calling convention to be used for the C function. It should "

"normally always be ``METH_VARARGS`` or ``METH_VARARGS | METH_KEYWORDS``; a "

"value of ``0`` means that an obsolete variant of :c:func:`PyArg_ParseTuple` "

"is used."

msgstr ""

#: ../Doc/extending/extending.rst:330

msgid ""

"When using only ``METH_VARARGS``, the function should expect the Python-"

"level parameters to be passed in as a tuple acceptable for parsing via :c:"

"func:`PyArg_ParseTuple`; more information on this function is provided below."

msgstr ""

#: ../Doc/extending/extending.rst:334

msgid ""

"The :const:`METH_KEYWORDS` bit may be set in the third field if keyword "

"arguments should be passed to the function. In this case, the C function "

"should accept a third ``PyObject *`` parameter which will be a dictionary of "

"keywords. Use :c:func:`PyArg_ParseTupleAndKeywords` to parse the arguments "

"to such a function."

msgstr ""

#: ../Doc/extending/extending.rst:340

msgid ""

"The method table must be referenced in the module definition structure::"

msgstr ""

#: ../Doc/extending/extending.rst:351

msgid ""

"This structure, in turn, must be passed to the interpreter in the module's "

"initialization function. The initialization function must be named :c:func:"

"`PyInit_name`, where *name* is the name of the module, and should be the "

"only non-\\ ``static`` item defined in the module file::"

msgstr ""

#: ../Doc/extending/extending.rst:362

msgid ""

"Note that PyMODINIT_FUNC declares the function as ``PyObject *`` return "

"type, declares any special linkage declarations required by the platform, "

"and for C++ declares the function as ``extern \"C\"``."

msgstr ""

#: ../Doc/extending/extending.rst:366

msgid ""

"When the Python program imports module :mod:`spam` for the first time, :c:"

"func:`PyInit_spam` is called. (See below for comments about embedding "

"Python.) It calls :c:func:`PyModule_Create`, which returns a module object, "

"and inserts built-in function objects into the newly created module based "

"upon the table (an array of :c:type:`PyMethodDef` structures) found in the "

"module definition. :c:func:`PyModule_Create` returns a pointer to the module "

"object that it creates. It may abort with a fatal error for certain errors, "

"or return *NULL* if the module could not be initialized satisfactorily. The "

"init function must return the module object to its caller, so that it then "

"gets inserted into ``sys.modules``."

msgstr ""

#: ../Doc/extending/extending.rst:377

msgid ""

"When embedding Python, the :c:func:`PyInit_spam` function is not called "

"automatically unless there's an entry in the :c:data:`PyImport_Inittab` "

"table. To add the module to the initialization table, use :c:func:"

"`PyImport_AppendInittab`, optionally followed by an import of the module::"

msgstr ""

#: ../Doc/extending/extending.rst:413

msgid ""

"Removing entries from ``sys.modules`` or importing compiled modules into "

"multiple interpreters within a process (or following a :c:func:`fork` "

"without an intervening :c:func:`exec`) can create problems for some "

"extension modules. Extension module authors should exercise caution when "

"initializing internal data structures."

msgstr ""

#: ../Doc/extending/extending.rst:419

msgid ""

"A more substantial example module is included in the Python source "

"distribution as :file:`Modules/xxmodule.c`. This file may be used as a "

"template or simply read as an example."

msgstr ""

#: ../Doc/extending/extending.rst:425

msgid ""

"Unlike our ``spam`` example, ``xxmodule`` uses *multi-phase initialization* "

"(new in Python 3.5), where a PyModuleDef structure is returned from "

"``PyInit_spam``, and creation of the module is left to the import machinery. "

"For details on multi-phase initialization, see :PEP:`489`."

msgstr ""

#: ../Doc/extending/extending.rst:434

msgid "Compilation and Linkage"

msgstr ""

#: ../Doc/extending/extending.rst:436

msgid ""

"There are two more things to do before you can use your new extension: "

"compiling and linking it with the Python system. If you use dynamic "

"loading, the details may depend on the style of dynamic loading your system "

"uses; see the chapters about building extension modules (chapter :ref:"

"`building`) and additional information that pertains only to building on "

"Windows (chapter :ref:`building-on-windows`) for more information about this."

msgstr ""

#: ../Doc/extending/extending.rst:443

msgid ""

"If you can't use dynamic loading, or if you want to make your module a "

"permanent part of the Python interpreter, you will have to change the "

"configuration setup and rebuild the interpreter. Luckily, this is very "

"simple on Unix: just place your file (:file:`spammodule.c` for example) in "

"the :file:`Modules/` directory of an unpacked source distribution, add a "

"line to the file :file:`Modules/Setup.local` describing your file:"

msgstr ""

#: ../Doc/extending/extending.rst:454

msgid ""

"and rebuild the interpreter by running :program:`make` in the toplevel "

"directory. You can also run :program:`make` in the :file:`Modules/` "

"subdirectory, but then you must first rebuild :file:`Makefile` there by "

"running ':program:`make` Makefile'. (This is necessary each time you change "

"the :file:`Setup` file.)"

msgstr ""

#: ../Doc/extending/extending.rst:460

msgid ""

"If your module requires additional libraries to link with, these can be "

"listed on the line in the configuration file as well, for instance:"

msgstr ""

#: ../Doc/extending/extending.rst:471

msgid "Calling Python Functions from C"

msgstr ""

#: ../Doc/extending/extending.rst:473

msgid ""

"So far we have concentrated on making C functions callable from Python. The "

"reverse is also useful: calling Python functions from C. This is especially "

"the case for libraries that support so-called \"callback\" functions. If a "

"C interface makes use of callbacks, the equivalent Python often needs to "

"provide a callback mechanism to the Python programmer; the implementation "

"will require calling the Python callback functions from a C callback. Other "

"uses are also imaginable."

msgstr ""

#: ../Doc/extending/extending.rst:481

msgid ""

"Fortunately, the Python interpreter is easily called recursively, and there "

"is a standard interface to call a Python function. (I won't dwell on how to "

"call the Python parser with a particular string as input --- if you're "

"interested, have a look at the implementation of the :option:`-c` command "

"line option in :file:`Modules/main.c` from the Python source code.)"

msgstr ""

#: ../Doc/extending/extending.rst:487

msgid ""

"Calling a Python function is easy. First, the Python program must somehow "

"pass you the Python function object. You should provide a function (or some "

"other interface) to do this. When this function is called, save a pointer "

"to the Python function object (be careful to :c:func:`Py_INCREF` it!) in a "

"global variable --- or wherever you see fit. For example, the following "

"function might be part of a module definition::"

msgstr ""

#: ../Doc/extending/extending.rst:517

msgid ""

"This function must be registered with the interpreter using the :const:"

"`METH_VARARGS` flag; this is described in section :ref:`methodtable`. The :"

"c:func:`PyArg_ParseTuple` function and its arguments are documented in "

"section :ref:`parsetuple`."

msgstr ""

#: ../Doc/extending/extending.rst:522

msgid ""

"The macros :c:func:`Py_XINCREF` and :c:func:`Py_XDECREF` increment/decrement "

"the reference count of an object and are safe in the presence of *NULL* "

"pointers (but note that *temp* will not be *NULL* in this context). More "

"info on them in section :ref:`refcounts`."

msgstr ""

#: ../Doc/extending/extending.rst:529

msgid ""

"Later, when it is time to call the function, you call the C function :c:func:"

"`PyObject_CallObject`. This function has two arguments, both pointers to "

"arbitrary Python objects: the Python function, and the argument list. The "

"argument list must always be a tuple object, whose length is the number of "

"arguments. To call the Python function with no arguments, pass in NULL, or "

"an empty tuple; to call it with one argument, pass a singleton tuple. :c:"

"func:`Py_BuildValue` returns a tuple when its format string consists of zero "

"or more format codes between parentheses. For example::"

msgstr ""

#: ../Doc/extending/extending.rst:549

msgid ""

":c:func:`PyObject_CallObject` returns a Python object pointer: this is the "

"return value of the Python function. :c:func:`PyObject_CallObject` is "

"\"reference-count-neutral\" with respect to its arguments. In the example a "

"new tuple was created to serve as the argument list, which is :c:func:"

"`Py_DECREF`\\ -ed immediately after the :c:func:`PyObject_CallObject` call."

msgstr ""

#: ../Doc/extending/extending.rst:556

msgid ""

"The return value of :c:func:`PyObject_CallObject` is \"new\": either it is a "

"brand new object, or it is an existing object whose reference count has been "

"incremented. So, unless you want to save it in a global variable, you "

"should somehow :c:func:`Py_DECREF` the result, even (especially!) if you are "

"not interested in its value."

msgstr ""

#: ../Doc/extending/extending.rst:562

msgid ""

"Before you do this, however, it is important to check that the return value "

"isn't *NULL*. If it is, the Python function terminated by raising an "

"exception. If the C code that called :c:func:`PyObject_CallObject` is called "

"from Python, it should now return an error indication to its Python caller, "

"so the interpreter can print a stack trace, or the calling Python code can "

"handle the exception. If this is not possible or desirable, the exception "

"should be cleared by calling :c:func:`PyErr_Clear`. For example::"

msgstr ""

#: ../Doc/extending/extending.rst:575

msgid ""

"Depending on the desired interface to the Python callback function, you may "

"also have to provide an argument list to :c:func:`PyObject_CallObject`. In "

"some cases the argument list is also provided by the Python program, through "

"the same interface that specified the callback function. It can then be "

"saved and used in the same manner as the function object. In other cases, "

"you may have to construct a new tuple to pass as the argument list. The "

"simplest way to do this is to call :c:func:`Py_BuildValue`. For example, if "

"you want to pass an integral event code, you might use the following code::"

msgstr ""

#: ../Doc/extending/extending.rst:594

msgid ""

"Note the placement of ``Py_DECREF(arglist)`` immediately after the call, "

"before the error check! Also note that strictly speaking this code is not "

"complete: :c:func:`Py_BuildValue` may run out of memory, and this should be "

"checked."

msgstr ""

#: ../Doc/extending/extending.rst:598

msgid ""

"You may also call a function with keyword arguments by using :c:func:"

"`PyObject_Call`, which supports arguments and keyword arguments. As in the "

"above example, we use :c:func:`Py_BuildValue` to construct the dictionary. ::"

msgstr ""

#: ../Doc/extending/extending.rst:616

msgid "Extracting Parameters in Extension Functions"

msgstr ""

#: ../Doc/extending/extending.rst:620

msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::"

msgstr ""

#: ../Doc/extending/extending.rst:624

msgid ""

"The *arg* argument must be a tuple object containing an argument list passed "

"from Python to a C function. The *format* argument must be a format string, "

"whose syntax is explained in :ref:`arg-parsing` in the Python/C API "

"Reference Manual. The remaining arguments must be addresses of variables "

"whose type is determined by the format string."

msgstr ""

#: ../Doc/extending/extending.rst:630

msgid ""

"Note that while :c:func:`PyArg_ParseTuple` checks that the Python arguments "

"have the required types, it cannot check the validity of the addresses of C "

"variables passed to the call: if you make mistakes there, your code will "

"probably crash or at least overwrite random bits in memory. So be careful!"

msgstr ""

#: ../Doc/extending/extending.rst:635

msgid ""

"Note that any Python object references which are provided to the caller are "

"*borrowed* references; do not decrement their reference count!"

msgstr ""

#: ../Doc/extending/extending.rst:638

msgid "Some example calls::"

msgstr ""

#: ../Doc/extending/extending.rst:708

msgid "Keyword Parameters for Extension Functions"

msgstr ""

#: ../Doc/extending/extending.rst:712

msgid ""

"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::"

msgstr ""

#: ../Doc/extending/extending.rst:717

msgid ""

"The *arg* and *format* parameters are identical to those of the :c:func:"

"`PyArg_ParseTuple` function. The *kwdict* parameter is the dictionary of "

"keywords received as the third parameter from the Python runtime. The "

"*kwlist* parameter is a *NULL*-terminated list of strings which identify the "

"parameters; the names are matched with the type information from *format* "

"from left to right. On success, :c:func:`PyArg_ParseTupleAndKeywords` "

"returns true, otherwise it returns false and raises an appropriate exception."

msgstr ""

#: ../Doc/extending/extending.rst:727

msgid ""

"Nested tuples cannot be parsed when using keyword arguments! Keyword "

"parameters passed in which are not present in the *kwlist* will cause :exc:"

"`TypeError` to be raised."

msgstr ""

#: ../Doc/extending/extending.rst:733

msgid ""

"Here is an example module which uses keywords, based on an example by Geoff "

"Philbrick (philbrick@hks.com)::"

msgstr ""

#: ../Doc/extending/extending.rst:788

msgid "Building Arbitrary Values"

msgstr ""

#: ../Doc/extending/extending.rst:790

msgid ""

"This function is the counterpart to :c:func:`PyArg_ParseTuple`. It is "

"declared as follows::"

msgstr ""

#: ../Doc/extending/extending.rst:795

msgid ""

"It recognizes a set of format units similar to the ones recognized by :c:"

"func:`PyArg_ParseTuple`, but the arguments (which are input to the function, "

"not output) must not be pointers, just values. It returns a new Python "

"object, suitable for returning from a C function called from Python."

msgstr ""

#: ../Doc/extending/extending.rst:800

msgid ""

"One difference with :c:func:`PyArg_ParseTuple`: while the latter requires "

"its first argument to be a tuple (since Python argument lists are always "

"represented as tuples internally), :c:func:`Py_BuildValue` does not always "

"build a tuple. It builds a tuple only if its format string contains two or "

"more format units. If the format string is empty, it returns ``None``; if it "

"contains exactly one format unit, it returns whatever object is described by "

"that format unit. To force it to return a tuple of size 0 or one, "

"parenthesize the format string."

msgstr ""

#: ../Doc/extending/extending.rst:808

msgid ""

"Examples (to the left the call, to the right the resulting Python value):"

msgstr ""

#: ../Doc/extending/extending.rst:834

msgid "Reference Counts"

msgstr ""

#: ../Doc/extending/extending.rst:836

msgid ""

"In languages like C or C++, the programmer is responsible for dynamic "

"allocation and deallocation of memory on the heap. In C, this is done using "

"the functions :c:func:`malloc` and :c:func:`free`. In C++, the operators "

"``new`` and ``delete`` are used with essentially the same meaning and we'll "

"restrict the following discussion to the C case."

msgstr ""

#: ../Doc/extending/extending.rst:842

msgid ""

"Every block of memory allocated with :c:func:`malloc` should eventually be "

"returned to the pool of available memory by exactly one call to :c:func:"

"`free`. It is important to call :c:func:`free` at the right time. If a "

"block's address is forgotten but :c:func:`free` is not called for it, the "

"memory it occupies cannot be reused until the program terminates. This is "

"called a :dfn:`memory leak`. On the other hand, if a program calls :c:func:"

"`free` for a block and then continues to use the block, it creates a "

"conflict with re-use of the block through another :c:func:`malloc` call. "

"This is called :dfn:`using freed memory`. It has the same bad consequences "

"as referencing uninitialized data --- core dumps, wrong results, mysterious "

"crashes."

msgstr ""

#: ../Doc/extending/extending.rst:853

msgid ""

"Common causes of memory leaks are unusual paths through the code. For "

"instance, a function may allocate a block of memory, do some calculation, "

"and then free the block again. Now a change in the requirements for the "

"function may add a test to the calculation that detects an error condition "

"and can return prematurely from the function. It's easy to forget to free "

"the allocated memory block when taking this premature exit, especially when "

"it is added later to the code. Such leaks, once introduced, often go "

"undetected for a long time: the error exit is taken only in a small fraction "

"of all calls, and most modern machines have plenty of virtual memory, so the "

"leak only becomes apparent in a long-running process that uses the leaking "

"function frequently. Therefore, it's important to prevent leaks from "

"happening by having a coding convention or strategy that minimizes this kind "

"of errors."

msgstr ""

#: ../Doc/extending/extending.rst:866

msgid ""

"Since Python makes heavy use of :c:func:`malloc` and :c:func:`free`, it "

"needs a strategy to avoid memory leaks as well as the use of freed memory. "

"The chosen method is called :dfn:`reference counting`. The principle is "

"simple: every object contains a counter, which is incremented when a "

"reference to the object is stored somewhere, and which is decremented when a "

"reference to it is deleted. When the counter reaches zero, the last "

"reference to the object has been deleted and the object is freed."

msgstr ""

#: ../Doc/extending/extending.rst:874

msgid ""

"An alternative strategy is called :dfn:`automatic garbage collection`. "

"(Sometimes, reference counting is also referred to as a garbage collection "

"strategy, hence my use of \"automatic\" to distinguish the two.) The big "

"advantage of automatic garbage collection is that the user doesn't need to "

"call :c:func:`free` explicitly. (Another claimed advantage is an "

"improvement in speed or memory usage --- this is no hard fact however.) The "

"disadvantage is that for C, there is no truly portable automatic garbage "

"collector, while reference counting can be implemented portably (as long as "

"the functions :c:func:`malloc` and :c:func:`free` are available --- which "

"the C Standard guarantees). Maybe some day a sufficiently portable automatic "

"garbage collector will be available for C. Until then, we'll have to live "

"with reference counts."

msgstr ""

#: ../Doc/extending/extending.rst:886

msgid ""

"While Python uses the traditional reference counting implementation, it also "

"offers a cycle detector that works to detect reference cycles. This allows "

"applications to not worry about creating direct or indirect circular "

"references; these are the weakness of garbage collection implemented using "

"only reference counting. Reference cycles consist of objects which contain "

"(possibly indirect) references to themselves, so that each object in the "

"cycle has a reference count which is non-zero. Typical reference counting "

"implementations are not able to reclaim the memory belonging to any objects "

"in a reference cycle, or referenced from the objects in the cycle, even "

"though there are no further references to the cycle itself."

msgstr ""

#: ../Doc/extending/extending.rst:897

msgid ""

"The cycle detector is able to detect garbage cycles and can reclaim them. "

"The :mod:`gc` module exposes a way to run the detector (the :func:`~gc."

"collect` function), as well as configuration interfaces and the ability to "

"disable the detector at runtime. The cycle detector is considered an "

"optional component; though it is included by default, it can be disabled at "

"build time using the :option:`!--without-cycle-gc` option to the :program:"

"`configure` script on Unix platforms (including Mac OS X). If the cycle "

"detector is disabled in this way, the :mod:`gc` module will not be available."

msgstr ""

#: ../Doc/extending/extending.rst:911

msgid "Reference Counting in Python"

msgstr ""

#: ../Doc/extending/extending.rst:913

msgid ""

"There are two macros, ``Py_INCREF(x)`` and ``Py_DECREF(x)``, which handle "

"the incrementing and decrementing of the reference count. :c:func:"

"`Py_DECREF` also frees the object when the count reaches zero. For "

"flexibility, it doesn't call :c:func:`free` directly --- rather, it makes a "

"call through a function pointer in the object's :dfn:`type object`. For "

"this purpose (and others), every object also contains a pointer to its type "

"object."

msgstr ""

#: ../Doc/extending/extending.rst:920

msgid ""

"The big question now remains: when to use ``Py_INCREF(x)`` and "

"``Py_DECREF(x)``? Let's first introduce some terms. Nobody \"owns\" an "

"object; however, you can :dfn:`own a reference` to an object. An object's "

"reference count is now defined as the number of owned references to it. The "

"owner of a reference is responsible for calling :c:func:`Py_DECREF` when the "

"reference is no longer needed. Ownership of a reference can be "

"transferred. There are three ways to dispose of an owned reference: pass it "

"on, store it, or call :c:func:`Py_DECREF`. Forgetting to dispose of an owned "

"reference creates a memory leak."

msgstr ""

#: ../Doc/extending/extending.rst:929

msgid ""

"It is also possible to :dfn:`borrow` [#]_ a reference to an object. The "

"borrower of a reference should not call :c:func:`Py_DECREF`. The borrower "

"must not hold on to the object longer than the owner from which it was "

"borrowed. Using a borrowed reference after the owner has disposed of it "

"risks using freed memory and should be avoided completely [#]_."

msgstr ""

#: ../Doc/extending/extending.rst:935

msgid ""

"The advantage of borrowing over owning a reference is that you don't need to "

"take care of disposing of the reference on all possible paths through the "

"code --- in other words, with a borrowed reference you don't run the risk of "

"leaking when a premature exit is taken. The disadvantage of borrowing over "

"owning is that there are some subtle situations where in seemingly correct "

"code a borrowed reference can be used after the owner from which it was "

"borrowed has in fact disposed of it."

msgstr ""

#: ../Doc/extending/extending.rst:943

msgid ""

"A borrowed reference can be changed into an owned reference by calling :c:"

"func:`Py_INCREF`. This does not affect the status of the owner from which "

"the reference was borrowed --- it creates a new owned reference, and gives "

"full owner responsibilities (the new owner must dispose of the reference "

"properly, as well as the previous owner)."

msgstr ""

#: ../Doc/extending/extending.rst:953

msgid "Ownership Rules"

msgstr ""

#: ../Doc/extending/extending.rst:955

msgid ""

"Whenever an object reference is passed into or out of a function, it is part "

"of the function's interface specification whether ownership is transferred "

"with the reference or not."

msgstr ""

#: ../Doc/extending/extending.rst:959

msgid ""

"Most functions that return a reference to an object pass on ownership with "

"the reference. In particular, all functions whose function it is to create "

"a new object, such as :c:func:`PyLong_FromLong` and :c:func:`Py_BuildValue`, "

"pass ownership to the receiver. Even if the object is not actually new, you "

"still receive ownership of a new reference to that object. For instance, :c:"

"func:`PyLong_FromLong` maintains a cache of popular values and can return a "

"reference to a cached item."

msgstr ""

#: ../Doc/extending/extending.rst:967

msgid ""

"Many functions that extract objects from other objects also transfer "

"ownership with the reference, for instance :c:func:"

"`PyObject_GetAttrString`. The picture is less clear, here, however, since a "

"few common routines are exceptions: :c:func:`PyTuple_GetItem`, :c:func:"

"`PyList_GetItem`, :c:func:`PyDict_GetItem`, and :c:func:"

"`PyDict_GetItemString` all return references that you borrow from the tuple, "

"list or dictionary."

msgstr ""

#: ../Doc/extending/extending.rst:974

msgid ""

"The function :c:func:`PyImport_AddModule` also returns a borrowed reference, "

"even though it may actually create the object it returns: this is possible "

"because an owned reference to the object is stored in ``sys.modules``."

msgstr ""

#: ../Doc/extending/extending.rst:978

msgid ""

"When you pass an object reference into another function, in general, the "

"function borrows the reference from you --- if it needs to store it, it will "

"use :c:func:`Py_INCREF` to become an independent owner. There are exactly "

"two important exceptions to this rule: :c:func:`PyTuple_SetItem` and :c:func:"

"`PyList_SetItem`. These functions take over ownership of the item passed to "

"them --- even if they fail! (Note that :c:func:`PyDict_SetItem` and friends "

"don't take over ownership --- they are \"normal.\")"

msgstr ""

#: ../Doc/extending/extending.rst:986

msgid ""

"When a C function is called from Python, it borrows references to its "

"arguments from the caller. The caller owns a reference to the object, so "

"the borrowed reference's lifetime is guaranteed until the function returns. "

"Only when such a borrowed reference must be stored or passed on, it must be "

"turned into an owned reference by calling :c:func:`Py_INCREF`."

msgstr ""

#: ../Doc/extending/extending.rst:992

msgid ""

"The object reference returned from a C function that is called from Python "

"must be an owned reference --- ownership is transferred from the function to "

"its caller."

msgstr ""

#: ../Doc/extending/extending.rst:1000

msgid "Thin Ice"

msgstr ""

#: ../Doc/extending/extending.rst:1002

msgid ""

"There are a few situations where seemingly harmless use of a borrowed "

"reference can lead to problems. These all have to do with implicit "

"invocations of the interpreter, which can cause the owner of a reference to "

"dispose of it."

msgstr ""

#: ../Doc/extending/extending.rst:1006

msgid ""

"The first and most important case to know about is using :c:func:`Py_DECREF` "

"on an unrelated object while borrowing a reference to a list item. For "

"instance::"

msgstr ""

#: ../Doc/extending/extending.rst:1018

msgid ""

"This function first borrows a reference to ``list[0]``, then replaces "

"``list[1]`` with the value ``0``, and finally prints the borrowed reference. "

"Looks harmless, right? But it's not!"

msgstr ""

#: ../Doc/extending/extending.rst:1022

msgid ""

"Let's follow the control flow into :c:func:`PyList_SetItem`. The list owns "

"references to all its items, so when item 1 is replaced, it has to dispose "

"of the original item 1. Now let's suppose the original item 1 was an "

"instance of a user-defined class, and let's further suppose that the class "

"defined a :meth:`__del__` method. If this class instance has a reference "

"count of 1, disposing of it will call its :meth:`__del__` method."

msgstr ""

#: ../Doc/extending/extending.rst:1029

msgid ""

"Since it is written in Python, the :meth:`__del__` method can execute "

"arbitrary Python code. Could it perhaps do something to invalidate the "

"reference to ``item`` in :c:func:`bug`? You bet! Assuming that the list "