extending.po

# SOME DESCRIPTIVE TITLE.
# Copyright (C) 1990-2010, Python Software Foundation
# This file is distributed under the same license as the Python package.
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
#, fuzzy
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2012-11-05 09:33\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language-Team: LANGUAGE <LL@li.org>\n"
"Language: \n"
"MIME-Version: 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"
"X-Generator: Translate Toolkit 1.7.0\n"

#: ../src/Doc/extending/building.rst:8
#, fuzzy
msgid "Building C and C++ Extensions with distutils"
msgstr "Construire les extensions C et C + + avec distutils"

#: ../src/Doc/extending/building.rst:13
msgid ""
"Starting in Python 1.4, Python provides, on Unix, a special make file for "
"building make files for building dynamically-linked extensions and custom "
"interpreters.  Starting with Python 2.0, this mechanism (known as related to "
"Makefile.pre.in, and Setup files) is no longer supported. Building custom "
"interpreters was rarely used, and extension modules can be built using "
"distutils."
msgstr ""

#: ../src/Doc/extending/building.rst:20
msgid ""
"Building an extension module using distutils requires that distutils is "
"installed on the build machine, which is included in Python 2.x and "
"available separately for Python 1.5. Since distutils also supports creation "
"of binary packages, users don't necessarily need a compiler and distutils to "
"install the extension."
msgstr ""

#: ../src/Doc/extending/building.rst:26
msgid ""
"A distutils package contains a driver script, :file:`setup.py`. This is a "
"plain Python file, which, in the most simple case, could look like this::"
msgstr ""

#: ../src/Doc/extending/building.rst:40
msgid "With this :file:`setup.py`, and a file :file:`demo.c`, running ::"
msgstr ""

#: ../src/Doc/extending/building.rst:44
msgid ""
"will compile :file:`demo.c`, and produce an extension module named ``demo`` "
"in the :file:`build` directory. Depending on the system, the module file "
"will end up in a subdirectory :file:`build/lib.system`, and may have a name "
"like :file:`demo.so` or :file:`demo.pyd`."
msgstr ""

#: ../src/Doc/extending/building.rst:49
msgid ""
"In the :file:`setup.py`, all execution is performed by calling the ``setup`` "
"function. This takes a variable number of keyword arguments, of which the "
"example above uses only a subset. Specifically, the example specifies meta-"
"information to build packages, and it specifies the contents of the "
"package.  Normally, a package will contain of addition modules, like Python "
"source modules, documentation, subpackages, etc. Please refer to the "
"distutils documentation in :ref:`distutils-index` to learn more about the "
"features of distutils; this section explains building extension modules only."
msgstr ""

#: ../src/Doc/extending/building.rst:58
msgid ""
"It is common to pre-compute arguments to :func:`setup`, to better structure "
"the driver script. In the example above, the\\ ``ext_modules`` argument to :"
"func:`setup` is a list of extension modules, each of which is an instance of "
"the :class:`Extension`. In the example, the instance defines an extension "
"named ``demo`` which is build by compiling a single source file, :file:`demo."
"c`."
msgstr ""

#: ../src/Doc/extending/building.rst:64
msgid ""
"In many cases, building an extension is more complex, since additional "
"preprocessor defines and libraries may be needed. This is demonstrated in "
"the example below. ::"
msgstr ""

#: ../src/Doc/extending/building.rst:90
msgid ""
"In this example, :func:`setup` is called with additional meta-information, "
"which is recommended when distribution packages have to be built. For the "
"extension itself, it specifies preprocessor defines, include directories, "
"library directories, and libraries. Depending on the compiler, distutils "
"passes this information in different ways to the compiler. For example, on "
"Unix, this may result in the compilation commands ::"
msgstr ""

#: ../src/Doc/extending/building.rst:101
msgid ""
"These lines are for demonstration purposes only; distutils users should "
"trust that distutils gets the invocations right."
msgstr ""

#: ../src/Doc/extending/building.rst:108
msgid "Distributing your extension modules"
msgstr ""

#: ../src/Doc/extending/building.rst:110
msgid ""
"When an extension has been successfully build, there are three ways to use "
"it."
msgstr ""

#: ../src/Doc/extending/building.rst:112
msgid ""
"End-users will typically want to install the module, they do so by running ::"
msgstr ""

#: ../src/Doc/extending/building.rst:116
msgid ""
"Module maintainers should produce source packages; to do so, they run ::"
msgstr ""

#: ../src/Doc/extending/building.rst:120
msgid ""
"In some cases, additional files need to be included in a source "
"distribution; this is done through a :file:`MANIFEST.in` file; see the "
"distutils documentation for details."
msgstr ""

#: ../src/Doc/extending/building.rst:124
msgid ""
"If the source distribution has been build successfully, maintainers can also "
"create binary distributions. Depending on the platform, one of the following "
"commands can be used to do so. ::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:8
msgid "Embedding Python in Another Application"
msgstr ""

#: ../src/Doc/extending/embedding.rst:10
msgid ""
"The previous chapters discussed how to extend Python, that is, how to extend "
"the functionality of Python by attaching a library of C functions to it.  It "
"is also possible to do it the other way around: enrich your C/C++ "
"application by embedding Python in it.  Embedding provides your application "
"with the ability to implement some of the functionality of your application "
"in Python rather than C or C++. This can be used for many purposes; one "
"example would be to allow users to tailor the application to their needs by "
"writing some scripts in Python.  You can also use it yourself if some of the "
"functionality can be written in Python more easily."
msgstr ""

#: ../src/Doc/extending/embedding.rst:20
msgid ""
"Embedding Python is similar to extending it, but not quite.  The difference "
"is that when you extend Python, the main program of the application is still "
"the Python interpreter, while if you embed Python, the main program may have "
"nothing to do with Python --- instead, some parts of the application "
"occasionally call the Python interpreter to run some Python code."
msgstr ""

# 3349405bb5884228afac17315062a7b3
#: ../src/Doc/extending/embedding.rst:26
msgid ""
"So if you are embedding Python, you are providing your own main program.  "
"One of the things this main program has to do is initialize the Python "
"interpreter.  At the very least, you have to call the function :c:func:"
"`Py_Initialize`.  There are optional calls to pass command line arguments to "
"Python.  Then later you can call the interpreter from any part of the "
"application."
msgstr ""

# 2fee2b21444c48fcbc33bf615faa320a
#: ../src/Doc/extending/embedding.rst:32
msgid ""
"There are several different ways to call the interpreter: you can pass a "
"string containing Python statements to :c:func:`PyRun_SimpleString`, or you "
"can pass a stdio file pointer and a file name (for identification in error "
"messages only) to :c:func:`PyRun_SimpleFile`.  You can also call the lower-"
"level operations described in the previous chapters to construct and use "
"Python objects."
msgstr ""

#: ../src/Doc/extending/embedding.rst:38
msgid ""
"A simple demo of embedding Python can be found in the directory :file:`Demo/"
"embed/` of the source distribution."
msgstr ""

#: ../src/Doc/extending/embedding.rst:45
msgid ""
"The details of Python's C interface are given in this manual. A great deal "
"of necessary information can be found here."
msgstr ""

#: ../src/Doc/extending/embedding.rst:52
msgid "Very High Level Embedding"
msgstr ""

#: ../src/Doc/extending/embedding.rst:54
msgid ""
"The simplest form of embedding Python is the use of the very high level "
"interface. This interface is intended to execute a Python script without "
"needing to interact with the application directly. This can for example be "
"used to perform some operation on a file. ::"
msgstr ""

# a8a877d20c464cfd840409fbdeba8d65
#: ../src/Doc/extending/embedding.rst:72
msgid ""
"The :c:func:`Py_SetProgramName` function should be called before :c:func:"
"`Py_Initialize` to inform the interpreter about paths to Python run-time "
"libraries.  Next, the Python interpreter is initialized with :c:func:"
"`Py_Initialize`, followed by the execution of a hard-coded Python script "
"that prints the date and time.  Afterwards, the :c:func:`Py_Finalize` call "
"shuts the interpreter down, followed by the end of the program.  In a real "
"program, you may want to get the Python script from another source, perhaps "
"a text-editor routine, a file, or a database.  Getting the Python code from "
"a file can better be done by using the :c:func:`PyRun_SimpleFile` function, "
"which saves you the trouble of allocating memory space and loading the file "
"contents."
msgstr ""

#: ../src/Doc/extending/embedding.rst:87
msgid "Beyond Very High Level Embedding: An overview"
msgstr ""

#: ../src/Doc/extending/embedding.rst:89
msgid ""
"The high level interface gives you the ability to execute arbitrary pieces "
"of Python code from your application, but exchanging data values is quite "
"cumbersome to say the least. If you want that, you should use lower level "
"calls. At the cost of having to write more C code, you can achieve almost "
"anything."
msgstr ""

#: ../src/Doc/extending/embedding.rst:94
msgid ""
"It should be noted that extending Python and embedding Python is quite the "
"same activity, despite the different intent. Most topics discussed in the "
"previous chapters are still valid. To show this, consider what the extension "
"code from Python to C really does:"
msgstr ""

#: ../src/Doc/extending/embedding.rst:99
msgid "Convert data values from Python to C,"
msgstr ""

#: ../src/Doc/extending/embedding.rst:101
msgid "Perform a function call to a C routine using the converted values, and"
msgstr ""

#: ../src/Doc/extending/embedding.rst:103
msgid "Convert the data values from the call from C to Python."
msgstr ""

#: ../src/Doc/extending/embedding.rst:105
msgid "When embedding Python, the interface code does:"
msgstr ""

#: ../src/Doc/extending/embedding.rst:107
msgid "Convert data values from C to Python,"
msgstr ""

#: ../src/Doc/extending/embedding.rst:109
msgid ""
"Perform a function call to a Python interface routine using the converted "
"values, and"
msgstr ""

#: ../src/Doc/extending/embedding.rst:112
msgid "Convert the data values from the call from Python to C."
msgstr ""

#: ../src/Doc/extending/embedding.rst:114
msgid ""
"As you can see, the data conversion steps are simply swapped to accommodate "
"the different direction of the cross-language transfer. The only difference "
"is the routine that you call between both data conversions. When extending, "
"you call a C routine, when embedding, you call a Python routine."
msgstr ""

#: ../src/Doc/extending/embedding.rst:119
msgid ""
"This chapter will not discuss how to convert data from Python to C and vice "
"versa.  Also, proper use of references and dealing with errors is assumed to "
"be understood.  Since these aspects do not differ from extending the "
"interpreter, you can refer to earlier chapters for the required information."
msgstr ""

#: ../src/Doc/extending/embedding.rst:128
msgid "Pure Embedding"
msgstr ""

#: ../src/Doc/extending/embedding.rst:130
msgid ""
"The first program aims to execute a function in a Python script. Like in the "
"section about the very high level interface, the Python interpreter does not "
"directly interact with the application (but that will change in the next "
"section)."
msgstr ""

#: ../src/Doc/extending/embedding.rst:135
msgid "The code to run a function defined in a Python script is:"
msgstr ""

#: ../src/Doc/extending/embedding.rst:140
msgid ""
"This code loads a Python script using ``argv[1]``, and calls the function "
"named in ``argv[2]``.  Its integer arguments are the other values of the "
"``argv`` array.  If you compile and link this program (let's call the "
"finished executable :program:`call`), and use it to execute a Python script, "
"such as::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:152
msgid "then the result should be::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:158
msgid ""
"Although the program is quite large for its functionality, most of the code "
"is for data conversion between Python and C, and for error reporting.  The "
"interesting part with respect to embedding Python starts with ::"
msgstr ""

# dc2a9d1c15044827aafd426bf84b472a
#: ../src/Doc/extending/embedding.rst:167
msgid ""
"After initializing the interpreter, the script is loaded using :c:func:"
"`PyImport_Import`.  This routine needs a Python string as its argument, "
"which is constructed using the :c:func:`PyString_FromString` data conversion "
"routine. ::"
msgstr ""

# 61325f6f158d4f3e93f341879b3d9276
#: ../src/Doc/extending/embedding.rst:180
msgid ""
"Once the script is loaded, the name we're looking for is retrieved using :c:"
"func:`PyObject_GetAttrString`.  If the name exists, and the object returned "
"is callable, you can safely assume that it is a function.  The program then "
"proceeds by constructing a tuple of arguments as normal.  The call to the "
"Python function is then made with::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:188
msgid ""
"Upon return of the function, ``pValue`` is either *NULL* or it contains a "
"reference to the return value of the function.  Be sure to release the "
"reference after examining the value."
msgstr ""

#: ../src/Doc/extending/embedding.rst:196
msgid "Extending Embedded Python"
msgstr ""

#: ../src/Doc/extending/embedding.rst:198
msgid ""
"Until now, the embedded Python interpreter had no access to functionality "
"from the application itself.  The Python API allows this by extending the "
"embedded interpreter.  That is, the embedded interpreter gets extended with "
"routines provided by the application. While it sounds complex, it is not so "
"bad.  Simply forget for a while that the application starts the Python "
"interpreter.  Instead, consider the application to be a set of subroutines, "
"and write some glue code that gives Python access to those routines, just "
"like you would write a normal Python extension.  For example::"
msgstr ""

# e3a28dc7453b48aaa3152dbb130353ec
#: ../src/Doc/extending/embedding.rst:224
msgid ""
"Insert the above code just above the :c:func:`main` function. Also, insert "
"the following two statements directly after :c:func:`Py_Initialize`::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:230
msgid ""
"These two lines initialize the ``numargs`` variable, and make the :func:`emb."
"numargs` function accessible to the embedded Python interpreter. With these "
"extensions, the Python script can do things like ::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:237
msgid ""
"In a real application, the methods will expose an API of the application to "
"Python."
msgstr ""

#: ../src/Doc/extending/embedding.rst:247
msgid "Embedding Python in C++"
msgstr ""

#: ../src/Doc/extending/embedding.rst:249
msgid ""
"It is also possible to embed Python in a C++ program; precisely how this is "
"done will depend on the details of the C++ system used; in general you will "
"need to write the main program in C++, and use the C++ compiler to compile "
"and link your program.  There is no need to recompile Python itself using C+"
"+."
msgstr ""

#: ../src/Doc/extending/embedding.rst:258
msgid "Linking Requirements"
msgstr ""

#: ../src/Doc/extending/embedding.rst:260
msgid ""
"While the :program:`configure` script shipped with the Python sources will "
"correctly build Python to export the symbols needed by dynamically linked "
"extensions, this is not automatically inherited by applications which embed "
"the Python library statically, at least on Unix.  This is an issue when the "
"application is linked to the static runtime library (:file:`libpython.a`) "
"and needs to load dynamic extensions (implemented as :file:`.so` files)."
msgstr ""

#: ../src/Doc/extending/embedding.rst:267
msgid ""
"The problem is that some entry points are defined by the Python runtime "
"solely for extension modules to use.  If the embedding application does not "
"use any of these entry points, some linkers will not include those entries "
"in the symbol table of the finished executable.  Some additional options are "
"needed to inform the linker not to remove these symbols."
msgstr ""

#: ../src/Doc/extending/embedding.rst:273
msgid ""
"Determining the right options to use for any given platform can be quite "
"difficult, but fortunately the Python configuration already has those "
"values. To retrieve them from an installed Python interpreter, start an "
"interactive interpreter and have a short session like this::"
msgstr ""

#: ../src/Doc/extending/embedding.rst:284
msgid ""
"The contents of the string presented will be the options that should be "
"used. If the string is empty, there's no need to add any additional "
"options.  The :const:`LINKFORSHARED` definition corresponds to the variable "
"of the same name in Python's top-level :file:`Makefile`."
msgstr ""

#: ../src/Doc/extending/extending.rst:8
msgid "Extending Python with C or C++"
msgstr ""

#: ../src/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 ""

#: ../src/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 ""

#: ../src/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 ""

#: ../src/Doc/extending/extending.rst:23
msgid ""
"Do note that if your use case is calling C library functions or system "
"calls, you should consider using the :mod:`ctypes` module rather than "
"writing custom C code. Not only does :mod:`ctypes` let you write Python code "
"to interface with C code, but it is more portable between implementations of "
"Python than writing and compiling an extension module which typically ties "
"you to CPython."
msgstr ""

#: ../src/Doc/extending/extending.rst:34
#, fuzzy
msgid "A Simple Example"
msgstr "Un exemple simple"

# f29189ec471c41cd8fab25f67821795d
#: ../src/Doc/extending/extending.rst:36
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 ""

#: ../src/Doc/extending/extending.rst:45
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 ""

#: ../src/Doc/extending/extending.rst:50
#, fuzzy
msgid "The first line of our file can be::"
msgstr "La première ligne de notre fichier peut être:"

#: ../src/Doc/extending/extending.rst:54
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 ""

#: ../src/Doc/extending/extending.rst:59
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 ""

# fa43971877c844418f03b4566324fed6
#: ../src/Doc/extending/extending.rst:63
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 ""

#: ../src/Doc/extending/extending.rst:71
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 ""

#: ../src/Doc/extending/extending.rst:87
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 ""

#: ../src/Doc/extending/extending.rst:92
msgid ""
"The *self* argument points to the module object for module-level functions; "
"for a method it would point to the object instance."
msgstr ""

# e61902774f844d1b8dce17ac441fa96a
#: ../src/Doc/extending/extending.rst:95
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 ""

# d458a69cd398407e82c060b308578a62
#: ../src/Doc/extending/extending.rst:104
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 ""

#: ../src/Doc/extending/extending.rst:114
msgid "Intermezzo: Errors and Exceptions"
msgstr ""

# 0ec9cd212ade4dfc8a29b8a10b609289
#: ../src/Doc/extending/extending.rst:116
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 Python variables "
"``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback`` (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 ""

#: ../src/Doc/extending/extending.rst:128
msgid ""
"The Python API defines a number of functions to set various types of "
"exceptions."
msgstr ""

# 3b52f1f297084e77b5eeaa2944e452e9
#: ../src/Doc/extending/extending.rst:130
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 ""

# 001c9fa90bbe4d1ea1a579fe28bb70c7
#: ../src/Doc/extending/extending.rst:136
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 ""

# 83b4af02ae624c988ab82888b1811c18
#: ../src/Doc/extending/extending.rst:143
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 ""

# 2db65c5053424043b6d8619f45b62c74
#: ../src/Doc/extending/extending.rst:149
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 ""

# a60d5722171e461d908fd5c12be5c595
#: ../src/Doc/extending/extending.rst:159
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 ""

# bc0ae3fdb33642178f4235364ca70345
#: ../src/Doc/extending/extending.rst:165
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 ""

# a3f1e3ed53ff4e9e84717c861c3050dc
#: ../src/Doc/extending/extending.rst:171
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:`PyInt_FromLong`) already do this, "
"so this note is only relevant to those who call :c:func:`malloc` directly."
msgstr ""

# b1880b1a76504ea495d77744d7309b43
#: ../src/Doc/extending/extending.rst:177
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 ""

# 4033d5b3db594253a10a4a61fdcca46c
#: ../src/Doc/extending/extending.rst:181
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 ""

# a4e6513d01294765a4c83895d1cc41d7
#: ../src/Doc/extending/extending.rst:185
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 ""

#: ../src/Doc/extending/extending.rst:195
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 ""

# 018562d96ab044ee9733e3dc5a66e2d9
#: ../src/Doc/extending/extending.rst:200
msgid ""
"and initialize it in your module's initialization function (:c:func:"
"`initspam`) with an exception object (leaving out the error checking for "
"now)::"
msgstr ""

# a542a8a47a2e4145973b937428c8c4ba
#: ../src/Doc/extending/extending.rst:217
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 ""

# e4ea678a9dac41b0a0d697b67004fd86
#: ../src/Doc/extending/extending.rst:222
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 ""

# 9bb58cdf6e0248b897ca3339d1e71acf
#: ../src/Doc/extending/extending.rst:229
msgid ""
"We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in "
"this sample."
msgstr ""

# f2207311e9cd47a09df71e0ee5b09abb
#: ../src/Doc/extending/extending.rst:232
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 ""

#: ../src/Doc/extending/extending.rst:255
msgid "Back to the Example"
msgstr ""

#: ../src/Doc/extending/extending.rst:257
msgid ""
"Going back to our example function, you should now be able to understand "
"this statement::"
msgstr ""

# b9ce94da94db4682b9df03a7e11a1f90
#: ../src/Doc/extending/extending.rst:263
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 ""

# a9a5fa4f6dc14f6cba0a145b3843e4ae
#: ../src/Doc/extending/extending.rst:271
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 ""

# 34ecacf047f847ad9e0365f4910c5985
#: ../src/Doc/extending/extending.rst:276
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:`Py_BuildValue`, "
"which is something like the inverse of :c:func:`PyArg_ParseTuple`: it takes "
"a format string and an arbitrary number of C values, and returns a new "
"Python object. More info on :c:func:`Py_BuildValue` is given later. ::"
msgstr ""

#: ../src/Doc/extending/extending.rst:284
msgid ""
"In this case, it will return an integer object.  (Yes, even integers are "
"objects on the heap in Python!)"
msgstr ""

# 03157000bd2b4c3b982c21957d552b2f
#: ../src/Doc/extending/extending.rst:287
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 ""

# f736f602207c474897a72b25505f4f7c
#: ../src/Doc/extending/extending.rst:295
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 ""

#: ../src/Doc/extending/extending.rst:303
msgid "The Module's Method Table and Initialization Function"
msgstr ""

# c8c2986539094d0eb5c0c8b80478e3b5
#: ../src/Doc/extending/extending.rst:305
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 ""

# 38dd15849ef548d39f059171b23ddec6
#: ../src/Doc/extending/extending.rst:316
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 ""

# bb032e727939456ca78a5d4e4fdd6065
#: ../src/Doc/extending/extending.rst:321
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 ""

# 511a00001b2d4e028ce779b15d0e3aa4
#: ../src/Doc/extending/extending.rst:325
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 ""

# cc9de65bdce54c0a991ce0a2103f2f55
#: ../src/Doc/extending/extending.rst:331
msgid ""
"The method table must be passed to the interpreter in the module's "
"initialization function.  The initialization function must be named :c:func:"
"`initname`, where *name* is the name of the module, and should be the only "
"non-\\ ``static`` item defined in the module file::"
msgstr ""

# dff31425e0cf4905831c3fadd6f24b87
#: ../src/Doc/extending/extending.rst:342
msgid ""
"Note that PyMODINIT_FUNC declares the function as ``void`` return type, "
"declares any special linkage declarations required by the platform, and for  "
"C++ declares the function as ``extern \"C\"``."
msgstr ""

# 725ecbe2a3a641b9bf4b4f047a5bf175
#: ../src/Doc/extending/extending.rst:346
msgid ""
"When the Python program imports module :mod:`spam` for the first time, :c:"
"func:`initspam` is called. (See below for comments about embedding Python.) "
"It calls :c:func:`Py_InitModule`, which creates a \"module object\" (which "
"is inserted in the dictionary ``sys.modules`` under the key ``\"spam\"``), "
"and inserts built-in function objects into the newly created module based "
"upon the table (an array of :c:type:`PyMethodDef` structures) that was "
"passed as its second argument. :c:func:`Py_InitModule` returns a pointer to "
"the module object that it creates (which is unused here).  It may abort with "
"a fatal error for certain errors, or return *NULL* if the module could not "
"be initialized satisfactorily."
msgstr ""

# b689098d952a43d5908f62169cf86f2a
#: ../src/Doc/extending/extending.rst:357
msgid ""
"When embedding Python, the :c:func:`initspam` function is not called "
"automatically unless there's an entry in the :c:data:`_PyImport_Inittab` "
"table. The easiest way to handle this is to statically initialize your "
"statically-linked modules by directly calling :c:func:`initspam` after the "
"call to :c:func:`Py_Initialize`::"
msgstr ""

#: ../src/Doc/extending/extending.rst:375
msgid ""
"An example may be found in the file :file:`Demo/embed/demo.c` in the Python "
"source distribution."
msgstr ""

# ada00ca2e2c648baa1c2f4ce1724d95c
#: ../src/Doc/extending/extending.rst:380
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. Note also that the :func:`reload` "
"function can be used with extension modules, and will call the module "
"initialization function (:c:func:`initspam` in the example), but will not "
"load the module again if it was loaded from a dynamically loadable object "
"file (:file:`.so` on Unix, :file:`.dll` on Windows)."
msgstr ""

#: ../src/Doc/extending/extending.rst:390
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 ""

#: ../src/Doc/extending/extending.rst:398
msgid "Compilation and Linkage"
msgstr ""

#: ../src/Doc/extending/extending.rst:400
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 ""

#: ../src/Doc/extending/extending.rst:407
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 ""

#: ../src/Doc/extending/extending.rst:416
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 ""

#: ../src/Doc/extending/extending.rst:422
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 ""

#: ../src/Doc/extending/extending.rst:431
msgid "Calling Python Functions from C"
msgstr ""

#: ../src/Doc/extending/extending.rst:433
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 ""

#: ../src/Doc/extending/extending.rst:441
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 ""

# d84f06a0ed614ecb9d7bde191044c82e
#: ../src/Doc/extending/extending.rst:447
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 ""

# 1ab06a081f8446fe81d605883f039440
#: ../src/Doc/extending/extending.rst:477
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 ""

# 4773842aa8d6456e8dc7264ddc43012a
#: ../src/Doc/extending/extending.rst:482
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 ""

# e88a129dc38b4bc9bd312e6318c61645
#: ../src/Doc/extending/extending.rst:489
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 ""

# 3936e324f3b7408a815ce2014a7d2b88
#: ../src/Doc/extending/extending.rst:509
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 call."
msgstr ""

# e4fbc1a7d0a74b51a2a4925762265622
#: ../src/Doc/extending/extending.rst:515
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 ""

# 4932fd44516f426da10ba37e850525d9
#: ../src/Doc/extending/extending.rst:521
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 ""

# fee1f71d37aa42a49e3cc600b8809455
#: ../src/Doc/extending/extending.rst:534
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 ""

# fbe00a824b8e4d93a324f0fbff91e1cf
#: ../src/Doc/extending/extending.rst:553
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 ""

# a3e74e4418384c07aea2db87103f0981
#: ../src/Doc/extending/extending.rst:557
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 ""

#: ../src/Doc/extending/extending.rst:575
msgid "Extracting Parameters in Extension Functions"
msgstr ""

# d1c9a35a93434bd1b8a14f538b94f4df
#: ../src/Doc/extending/extending.rst:579
msgid "The :c:func:`PyArg_ParseTuple` function is declared as follows::"
msgstr ""

#: ../src/Doc/extending/extending.rst:583
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 ""

# c21f2837c53e4f72902bee5a23370d75
#: ../src/Doc/extending/extending.rst:589
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 ""

#: ../src/Doc/extending/extending.rst:594
msgid ""
"Note that any Python object references which are provided to the caller are "
"*borrowed* references; do not decrement their reference count!"
msgstr ""

#: ../src/Doc/extending/extending.rst:597
msgid "Some example calls::"
msgstr ""

#: ../src/Doc/extending/extending.rst:662
msgid "Keyword Parameters for Extension Functions"
msgstr ""

# d89167f747964aa08520b68971e6a727
#: ../src/Doc/extending/extending.rst:666
msgid ""
"The :c:func:`PyArg_ParseTupleAndKeywords` function is declared as follows::"
msgstr ""

# b5902e44fca34fdcb14b1b55884aa142
#: ../src/Doc/extending/extending.rst:671
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 ""

#: ../src/Doc/extending/extending.rst:681
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 ""

#: ../src/Doc/extending/extending.rst:687
msgid ""
"Here is an example module which uses keywords, based on an example by Geoff "
"Philbrick (philbrick@hks.com)::"
msgstr ""

#: ../src/Doc/extending/extending.rst:738
msgid "Building Arbitrary Values"
msgstr ""

# 2ee08b048127479f828b67340e87bdc1
#: ../src/Doc/extending/extending.rst:740
msgid ""
"This function is the counterpart to :c:func:`PyArg_ParseTuple`.  It is "
"declared as follows::"
msgstr ""

# 3e246e0199f646859e07f3081493e84d
#: ../src/Doc/extending/extending.rst:745
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 ""

# 3ee00798dc6246c995d4192457d61935
#: ../src/Doc/extending/extending.rst:750
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 ""

#: ../src/Doc/extending/extending.rst:758
msgid ""
"Examples (to the left the call, to the right the resulting Python value)::"
msgstr ""

#: ../src/Doc/extending/extending.rst:780
msgid "Reference Counts"
msgstr ""

# 42135682deb5488fb74974cb895a3fad
#: ../src/Doc/extending/extending.rst:782
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 ""

# c7282f2648e045b9a1d7c3ae46c9ed9f
#: ../src/Doc/extending/extending.rst:788
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 ""

#: ../src/Doc/extending/extending.rst:799
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 ""

# 6acc7159f6204ae6a3ba57f1db38d90e
#: ../src/Doc/extending/extending.rst:812
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 ""

# d8dc338348db44c7ba7833fb542ffd91
#: ../src/Doc/extending/extending.rst:820
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 ""

#: ../src/Doc/extending/extending.rst:832
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 ""

# 3448ac01407540809b83455bc097eb74
#: ../src/Doc/extending/extending.rst:843
msgid ""
"The cycle detector is able to detect garbage cycles and can reclaim them so "
"long as there are no finalizers implemented in Python (:meth:`__del__` "
"methods). When there are such finalizers, the detector exposes the cycles "
"through the :mod:`gc` module (specifically, the ``garbage`` variable in that "
"module).  The :mod:`gc` module also exposes a way to run the detector (the :"
"func:`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) or by "
"removing the definition of ``WITH_CYCLE_GC`` in the :file:`pyconfig.h` "
"header on other platforms.  If the cycle detector is disabled in this way, "
"the :mod:`gc` module will not be available."
msgstr ""

#: ../src/Doc/extending/extending.rst:861
msgid "Reference Counting in Python"
msgstr ""

# 68af22ed0f784d9585e253e010e6335e
#: ../src/Doc/extending/extending.rst:863
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 ""

# 1ba6d884cdd64d9992090dc37ca5c6dd
#: ../src/Doc/extending/extending.rst:870
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 ""

# b7214f2e9a7d44dd814e86bde6d31317
#: ../src/Doc/extending/extending.rst:879
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 ""

#: ../src/Doc/extending/extending.rst:885
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 ""

# cafe80da096043cc845b3fd8f0ad58fb
#: ../src/Doc/extending/extending.rst:893
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 ""

#: ../src/Doc/extending/extending.rst:903
msgid "Ownership Rules"
msgstr ""

#: ../src/Doc/extending/extending.rst:905
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 ""

# 8b720350a00d40a3a900b50b87afb338
#: ../src/Doc/extending/extending.rst:909
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:`PyInt_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:`PyInt_FromLong` maintains a cache of popular values and can return a "
"reference to a cached item."
msgstr ""

# 677a0bfbc98242a2856101994faa9fe5
#: ../src/Doc/extending/extending.rst:917
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 ""

# 693b43597c5b48348c9a1e2a6a173ad3
#: ../src/Doc/extending/extending.rst:924
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 ""

# c621af407da24089821bec0fce80e298
#: ../src/Doc/extending/extending.rst:928
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 ""

# b2c13dd2a346451897220e68569a5250
#: ../src/Doc/extending/extending.rst:936
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 ""

#: ../src/Doc/extending/extending.rst:942
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 ""

#: ../src/Doc/extending/extending.rst:950
msgid "Thin Ice"
msgstr ""

#: ../src/Doc/extending/extending.rst:952
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 ""

# 70007764af0241c986f0f0ab63498221
#: ../src/Doc/extending/extending.rst:956
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 ""

#: ../src/Doc/extending/extending.rst:968
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 ""

# 367552d2efb4438299b4aef87f36311f
#: ../src/Doc/extending/extending.rst:972
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 ""

# be4685630bf748ceb5bfc65c26adac8c
#: ../src/Doc/extending/extending.rst:979
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 "
"passed into :c:func:`bug` is accessible to the :meth:`__del__` method, it "
"could execute a statement to the effect of ``del list[0]``, and assuming "
"this was the last reference to that object, it would free the memory "
"associated with it, thereby invalidating ``item``."
msgstr ""

#: ../src/Doc/extending/extending.rst:987
msgid ""
"The solution, once you know the source of the problem, is easy: temporarily "
"increment the reference count.  The correct version of the function reads::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1001
msgid ""
"This is a true story.  An older version of Python contained variants of this "
"bug and someone spent a considerable amount of time in a C debugger to "
"figure out why his :meth:`__del__` methods would fail..."
msgstr ""

# 29500693ffb94748abf71cca185a35b3
#: ../src/Doc/extending/extending.rst:1005
msgid ""
"The second case of problems with a borrowed reference is a variant involving "
"threads.  Normally, multiple threads in the Python interpreter can't get in "
"each other's way, because there is a global lock protecting Python's entire "
"object space.  However, it is possible to temporarily release this lock "
"using the macro :c:macro:`Py_BEGIN_ALLOW_THREADS`, and to re-acquire it "
"using :c:macro:`Py_END_ALLOW_THREADS`.  This is common around blocking I/O "
"calls, to let other threads use the processor while waiting for the I/O to "
"complete. Obviously, the following function has the same problem as the "
"previous one::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1028
msgid "NULL Pointers"
msgstr ""

#: ../src/Doc/extending/extending.rst:1030
msgid ""
"In general, functions that take object references as arguments do not expect "
"you to pass them *NULL* pointers, and will dump core (or cause later core "
"dumps) if you do so.  Functions that return object references generally "
"return *NULL* only to indicate that an exception occurred.  The reason for "
"not testing for *NULL* arguments is that functions often pass the objects "
"they receive on to other function --- if each function were to test for "
"*NULL*, there would be a lot of redundant tests and the code would run more "
"slowly."
msgstr ""

# 91b09be1f881491395bda1b96b4dd385
#: ../src/Doc/extending/extending.rst:1038
msgid ""
"It is better to test for *NULL* only at the \"source:\" when a pointer that "
"may be *NULL* is received, for example, from :c:func:`malloc` or from a "
"function that may raise an exception."
msgstr ""

# bb324c25da81451ea3739fa956bd4a0e
#: ../src/Doc/extending/extending.rst:1042
msgid ""
"The macros :c:func:`Py_INCREF` and :c:func:`Py_DECREF` do not check for "
"*NULL* pointers --- however, their variants :c:func:`Py_XINCREF` and :c:func:"
"`Py_XDECREF` do."
msgstr ""

#: ../src/Doc/extending/extending.rst:1046
msgid ""
"The macros for checking for a particular object type (``Pytype_Check()``) "
"don't check for *NULL* pointers --- again, there is much code that calls "
"several of these in a row to test an object against various different "
"expected types, and this would generate redundant tests.  There are no "
"variants with *NULL* checking."
msgstr ""

#: ../src/Doc/extending/extending.rst:1052
msgid ""
"The C function calling mechanism guarantees that the argument list passed to "
"C functions (``args`` in the examples) is never *NULL* --- in fact it "
"guarantees that it is always a tuple. [#]_"
msgstr ""

#: ../src/Doc/extending/extending.rst:1056
msgid ""
"It is a severe error to ever let a *NULL* pointer \"escape\" to the Python "
"user."
msgstr ""

#: ../src/Doc/extending/extending.rst:1067
msgid "Writing Extensions in C++"
msgstr ""

#: ../src/Doc/extending/extending.rst:1069
msgid ""
"It is possible to write extension modules in C++.  Some restrictions apply.  "
"If the main program (the Python interpreter) is compiled and linked by the C "
"compiler, global or static objects with constructors cannot be used.  This "
"is not a problem if the main program is linked by the C++ compiler.  "
"Functions that will be called by the Python interpreter (in particular, "
"module initialization functions) have to be declared using ``extern \"C\"``. "
"It is unnecessary to enclose the Python header files in ``extern \"C\" {...}"
"`` --- they use this form already if the symbol ``__cplusplus`` is defined "
"(all recent C++ compilers define this symbol)."
msgstr ""

#: ../src/Doc/extending/extending.rst:1083
msgid "Providing a C API for an Extension Module"
msgstr ""

#: ../src/Doc/extending/extending.rst:1088
msgid ""
"Many extension modules just provide new functions and types to be used from "
"Python, but sometimes the code in an extension module can be useful for "
"other extension modules. For example, an extension module could implement a "
"type \"collection\" which works like lists without order. Just like the "
"standard Python list type has a C API which permits extension modules to "
"create and manipulate lists, this new collection type should have a set of C "
"functions for direct manipulation from other extension modules."
msgstr ""

#: ../src/Doc/extending/extending.rst:1096
msgid ""
"At first sight this seems easy: just write the functions (without declaring "
"them ``static``, of course), provide an appropriate header file, and "
"document the C API. And in fact this would work if all extension modules "
"were always linked statically with the Python interpreter. When modules are "
"used as shared libraries, however, the symbols defined in one module may not "
"be visible to another module. The details of visibility depend on the "
"operating system; some systems use one global namespace for the Python "
"interpreter and all extension modules (Windows, for example), whereas others "
"require an explicit list of imported symbols at module link time (AIX is one "
"example), or offer a choice of different strategies (most Unices). And even "
"if symbols are globally visible, the module whose functions one wishes to "
"call might not have been loaded yet!"
msgstr ""

#: ../src/Doc/extending/extending.rst:1108
msgid ""
"Portability therefore requires not to make any assumptions about symbol "
"visibility. This means that all symbols in extension modules should be "
"declared ``static``, except for the module's initialization function, in "
"order to avoid name clashes with other extension modules (as discussed in "
"section :ref:`methodtable`). And it means that symbols that *should* be "
"accessible from other extension modules must be exported in a different way."
msgstr ""

# 81fe4deee4884f42b186510b8b3b039c
#: ../src/Doc/extending/extending.rst:1115
msgid ""
"Python provides a special mechanism to pass C-level information (pointers) "
"from one extension module to another one: Capsules. A Capsule is a Python "
"data type which stores a pointer (:c:type:`void \\*`).  Capsules can only be "
"created and accessed via their C API, but they can be passed around like any "
"other Python object. In particular,  they can be assigned to a name in an "
"extension module's namespace. Other extension modules can then import this "
"module, retrieve the value of this name, and then retrieve the pointer from "
"the Capsule."
msgstr ""

#: ../src/Doc/extending/extending.rst:1123
msgid ""
"There are many ways in which Capsules can be used to export the C API of an "
"extension module. Each function could get its own Capsule, or all C API "
"pointers could be stored in an array whose address is published in a "
"Capsule. And the various tasks of storing and retrieving the pointers can be "
"distributed in different ways between the module providing the code and the "
"client modules."
msgstr ""

# 87caf616ef4b46f8aeb3e88519482dc5
#: ../src/Doc/extending/extending.rst:1129
msgid ""
"Whichever method you choose, it's important to name your Capsules properly. "
"The function :c:func:`PyCapsule_New` takes a name parameter (:c:type:`const "
"char \\*`); you're permitted to pass in a *NULL* name, but we strongly "
"encourage you to specify a name.  Properly named Capsules provide a degree "
"of runtime type-safety; there is no feasible way to tell one unnamed Capsule "
"from another."
msgstr ""

#: ../src/Doc/extending/extending.rst:1136
msgid ""
"In particular, Capsules used to expose C APIs should be given a name "
"following this convention::"
msgstr ""

# 916a3f9ae2304f0187feffa2d85d2d57
#: ../src/Doc/extending/extending.rst:1141
msgid ""
"The convenience function :c:func:`PyCapsule_Import` makes it easy to load a "
"C API provided via a Capsule, but only if the Capsule's name matches this "
"convention.  This behavior gives C API users a high degree of certainty that "
"the Capsule they load contains the correct C API."
msgstr ""

# fbe61b4d0a1b4eab9d43b1309f2fac12
#: ../src/Doc/extending/extending.rst:1146
msgid ""
"The following example demonstrates an approach that puts most of the burden "
"on the writer of the exporting module, which is appropriate for commonly "
"used library modules. It stores all C API pointers (just one in the "
"example!) in an array of :c:type:`void` pointers which becomes the value of "
"a Capsule. The header file corresponding to the module provides a macro that "
"takes care of importing the module and retrieving its C API pointers; client "
"modules only have to call this macro before accessing the C API."
msgstr ""

# 79be34d50f564cf5811b0753cb0d5219
#: ../src/Doc/extending/extending.rst:1154
msgid ""
"The exporting module is a modification of the :mod:`spam` module from "
"section :ref:`extending-simpleexample`. The function :func:`spam.system` "
"does not call the C library function :c:func:`system` directly, but a "
"function :c:func:`PySpam_System`, which would of course do something more "
"complicated in reality (such as adding \"spam\" to every command). This "
"function :c:func:`PySpam_System` is also exported to other extension modules."
msgstr ""

# accc63ad59b247cbb105dde259b23587
#: ../src/Doc/extending/extending.rst:1161
msgid ""
"The function :c:func:`PySpam_System` is a plain C function, declared "
"``static`` like everything else::"
msgstr ""

# 7ce21b481e234201a5f3b6b5e0d127a1
#: ../src/Doc/extending/extending.rst:1170
msgid "The function :c:func:`spam_system` is modified in a trivial way::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1184
msgid "In the beginning of the module, right after the line ::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1188
msgid "two more lines must be added::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1193
msgid ""
"The ``#define`` is used to tell the header file that it is being included in "
"the exporting module, not a client module. Finally, the module's "
"initialization function must take care of initializing the C API pointer "
"array::"
msgstr ""

# be94a4a2227e43758eb15f598049854a
#: ../src/Doc/extending/extending.rst:1218
msgid ""
"Note that ``PySpam_API`` is declared ``static``; otherwise the pointer array "
"would disappear when :func:`initspam` terminates!"
msgstr ""

#: ../src/Doc/extending/extending.rst:1221
msgid ""
"The bulk of the work is in the header file :file:`spammodule.h`, which looks "
"like this::"
msgstr ""

# cd0acf46805e4a61bdbae021ce29d019
#: ../src/Doc/extending/extending.rst:1272
msgid ""
"All that a client module must do in order to have access to the function :c:"
"func:`PySpam_System` is to call the function (or rather macro) :c:func:"
"`import_spam` in its initialization function::"
msgstr ""

#: ../src/Doc/extending/extending.rst:1289
msgid ""
"The main disadvantage of this approach is that the file :file:`spammodule.h` "
"is rather complicated. However, the basic structure is the same for each "
"function that is exported, so it has to be learned only once."
msgstr ""

#: ../src/Doc/extending/extending.rst:1293
msgid ""
"Finally it should be mentioned that Capsules offer additional functionality, "
"which is especially useful for memory allocation and deallocation of the "
"pointer stored in a Capsule. The details are described in the Python/C API "
"Reference Manual in the section :ref:`capsules` and in the implementation of "
"Capsules (files :file:`Include/pycapsule.h` and :file:`Objects/pycapsule.c` "
"in the Python source code distribution)."
msgstr ""

#: ../src/Doc/extending/extending.rst:1301
#: ../src/Doc/extending/newtypes.rst:1565
msgid "Footnotes"
msgstr ""

#: ../src/Doc/extending/extending.rst:1302
msgid ""
"An interface for this function already exists in the standard module :mod:"
"`os` --- it was chosen as a simple and straightforward example."
msgstr ""

#: ../src/Doc/extending/extending.rst:1305
msgid ""
"The metaphor of \"borrowing\" a reference is not completely correct: the "
"owner still has a copy of the reference."
msgstr ""

#: ../src/Doc/extending/extending.rst:1308
msgid ""
"Checking that the reference count is at least 1 **does not work** --- the "
"reference count itself could be in freed memory and may thus be reused for "
"another object!"
msgstr ""

#: ../src/Doc/extending/extending.rst:1312
msgid ""
"These guarantees don't hold when you use the \"old\" style calling "
"convention --- this is still found in much existing code."
msgstr ""

#: ../src/Doc/extending/index.rst:5
msgid "Extending and Embedding the Python Interpreter"
msgstr ""

#: ../src/Doc/extending/index.rst:7
msgid ""
"This document describes how to write modules in C or C++ to extend the "
"Python interpreter with new modules.  Those modules can define new functions "
"but also new object types and their methods.  The document also describes "
"how to embed the Python interpreter in another application, for use as an "
"extension language. Finally, it shows how to compile and link extension "
"modules so that they can be loaded dynamically (at run time) into the "
"interpreter, if the underlying operating system supports this feature."
msgstr ""

#: ../src/Doc/extending/index.rst:15
msgid ""
"This document assumes basic knowledge about Python.  For an informal "
"introduction to the language, see :ref:`tutorial-index`.  :ref:`reference-"
"index` gives a more formal definition of the language.  :ref:`library-index` "
"documents the existing object types, functions and modules (both built-in "
"and written in Python) that give the language its wide application range."
msgstr ""

#: ../src/Doc/extending/index.rst:21
msgid ""
"For a detailed description of the whole Python/C API, see the separate :ref:"
"`c-api-index`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:8
msgid "Defining New Types"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:15
msgid ""
"As mentioned in the last chapter, Python allows the writer of an extension "
"module to define new types that can be manipulated from Python code, much "
"like strings and lists in core Python."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:19
msgid ""
"This is not hard; the code for all extension types follows a pattern, but "
"there are some details that you need to understand before you can get "
"started."
msgstr ""

# 523c611a3a02419583af16677a1e3376
#: ../src/Doc/extending/newtypes.rst:24
msgid ""
"The way new types are defined changed dramatically (and for the better) in "
"Python 2.2.  This document documents how to define new types for Python 2.2 "
"and later.  If you need to support older versions of Python, you will need "
"to refer to `older versions of this documentation <http://www.python.org/doc/"
"versions/>`_."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:34
msgid "The Basics"
msgstr ""

# 5bfead6d0d214c1a8f74069637b0a552
#: ../src/Doc/extending/newtypes.rst:36
msgid ""
"The Python runtime sees all Python objects as variables of type :c:type:"
"`PyObject\\*`.  A :c:type:`PyObject` is not a very magnificent object - it "
"just contains the refcount and a pointer to the object's \"type object\".  "
"This is where the action is; the type object determines which (C) functions "
"get called when, for instance, an attribute gets looked up on an object or "
"it is multiplied by another object.  These C functions are called \"type "
"methods\"."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:43
msgid ""
"So, if you want to define a new object type, you need to create a new type "
"object."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:46
msgid ""
"This sort of thing can only be explained by example, so here's a minimal, "
"but complete, module that defines a new type:"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:52
msgid ""
"Now that's quite a bit to take in at once, but hopefully bits will seem "
"familiar from the last chapter."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:55
msgid "The first bit that will be new is::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:61
msgid ""
"This is what a Noddy object will contain---in this case, nothing more than "
"every Python object contains, namely a refcount and a pointer to a type "
"object.  These are the fields the ``PyObject_HEAD`` macro brings in.  The "
"reason for the macro is to standardize the layout and to enable special "
"debugging fields in debug builds.  Note that there is no semicolon after the "
"``PyObject_HEAD`` macro; one is included in the macro definition.  Be wary "
"of adding one by accident; it's easy to do from habit, and your compiler "
"might not complain, but someone else's probably will!  (On Windows, MSVC is "
"known to call this an error and refuse to compile the code.)"
msgstr ""

# fb32a938d4d741f0994828e4508e7602
#: ../src/Doc/extending/newtypes.rst:71
msgid ""
"For contrast, let's take a look at the corresponding definition for standard "
"Python integers::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:79
msgid "Moving on, we come to the crunch --- the type object. ::"
msgstr ""

# 33467881d013421cbb0673810f603c9a
#: ../src/Doc/extending/newtypes.rst:106
msgid ""
"Now if you go and look up the definition of :c:type:`PyTypeObject` in :file:"
"`object.h` you'll see that it has many more fields that the definition "
"above.  The remaining fields will be filled with zeros by the C compiler, "
"and it's common practice to not specify them explicitly unless you need them."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:111
msgid ""
"This is so important that we're going to pick the top of it apart still "
"further::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:116
msgid "This line is a bit of a wart; what we'd like to write is::"
msgstr ""

# b1080ad4b0a74008ad802887456494f4
#: ../src/Doc/extending/newtypes.rst:120
msgid ""
"as the type of a type object is \"type\", but this isn't strictly conforming "
"C and some compilers complain.  Fortunately, this member will be filled in "
"for us by :c:func:`PyType_Ready`. ::"
msgstr ""

# 3d9e94192bfb4ff5a785acff075a6171
#: ../src/Doc/extending/newtypes.rst:126
msgid ""
"The :attr:`ob_size` field of the header is not used; its presence in the "
"type structure is a historical artifact that is maintained for binary "
"compatibility with extension modules compiled for older versions of Python.  "
"Always set this field to zero. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:133
msgid ""
"The name of our type.  This will appear in the default textual "
"representation of our objects and in some error messages, for example::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:141
msgid ""
"Note that the name is a dotted name that includes both the module name and "
"the name of the type within the module. The module in this case is :mod:"
"`noddy` and the type is :class:`Noddy`, so we set the type name to :class:"
"`noddy.Noddy`. ::"
msgstr ""

# 755fa43fe0014955ba719e5185f6b204
#: ../src/Doc/extending/newtypes.rst:147
msgid ""
"This is so that Python knows how much memory to allocate when you call :c:"
"func:`PyObject_New`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:152
msgid ""
"If you want your type to be subclassable from Python, and your type has the "
"same :attr:`tp_basicsize` as its base type, you may have problems with "
"multiple inheritance.  A Python subclass of your type will have to list your "
"type first in its :attr:`__bases__`, or else it will not be able to call "
"your type's :meth:`__new__` method without getting an error.  You can avoid "
"this problem by ensuring that your type has a larger value for :attr:"
"`tp_basicsize` than its base type does.  Most of the time, this will be true "
"anyway, because either your base type will be :class:`object`, or else you "
"will be adding data members to your base type, and therefore increasing its "
"size."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:166
msgid ""
"This has to do with variable length objects like lists and strings. Ignore "
"this for now."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:169
msgid ""
"Skipping a number of type methods that we don't provide, we set the class "
"flags to :const:`Py_TPFLAGS_DEFAULT`. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:174
msgid ""
"All types should include this constant in their flags.  It enables all of "
"the members defined by the current version of Python."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:177
msgid "We provide a doc string for the type in :attr:`tp_doc`. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:181
msgid ""
"Now we get into the type methods, the things that make your objects "
"different from the others.  We aren't going to implement any of these in "
"this version of the module.  We'll expand this example later to have more "
"interesting behavior."
msgstr ""

# 51eff6a2868841d5b1d60c1a1cfd6b22
#: ../src/Doc/extending/newtypes.rst:185
msgid ""
"For now, all we want to be able to do is to create new :class:`Noddy` "
"objects. To enable object creation, we have to provide a :attr:`tp_new` "
"implementation. In this case, we can just use the default implementation "
"provided by the API function :c:func:`PyType_GenericNew`.  We'd like to just "
"assign this to the :attr:`tp_new` slot, but we can't, for portability sake, "
"On some platforms or compilers, we can't statically initialize a structure "
"member with a function defined in another C module, so, instead, we'll "
"assign the :attr:`tp_new` slot in the module initialization function just "
"before calling :c:func:`PyType_Ready`::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:199
msgid ""
"All the other type methods are *NULL*, so we'll go over them later --- "
"that's for a later section!"
msgstr ""

# ece689d46045496291f14470c80d5575
#: ../src/Doc/extending/newtypes.rst:202
msgid ""
"Everything else in the file should be familiar, except for some code in :c:"
"func:`initnoddy`::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:208
msgid ""
"This initializes the :class:`Noddy` type, filing in a number of members, "
"including :attr:`ob_type` that we initially set to *NULL*. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:213
msgid ""
"This adds the type to the module dictionary.  This allows us to create :"
"class:`Noddy` instances by calling the :class:`Noddy` class::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:219
msgid ""
"That's it!  All that remains is to build it; put the above code in a file "
"called :file:`noddy.c` and ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:226
msgid "in a file called :file:`setup.py`; then typing ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:230
msgid ""
"at a shell should produce a file :file:`noddy.so` in a subdirectory; move to "
"that directory and fire up Python --- you should be able to ``import noddy`` "
"and play around with Noddy objects."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:234
msgid "That wasn't so hard, was it?"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:236
msgid ""
"Of course, the current Noddy type is pretty uninteresting. It has no data "
"and doesn't do anything. It can't even be subclassed."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:241
msgid "Adding data and methods to the Basic example"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:243
msgid ""
"Let's expend the basic example to add some data and methods.  Let's also "
"make the type usable as a base class. We'll create a new module, :mod:"
"`noddy2` that adds these capabilities:"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:250
msgid "This version of the module has a number of changes."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:252
msgid "We've added an extra include::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:256
msgid ""
"This include provides declarations that we use to handle attributes, as "
"described a bit later."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:259
msgid ""
"The name of the :class:`Noddy` object structure has been shortened to :class:"
"`Noddy`.  The type object name has been shortened to :class:`NoddyType`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:262
msgid ""
"The  :class:`Noddy` type now has three data attributes, *first*, *last*, and "
"*number*.  The *first* and *last* variables are Python strings containing "
"first and last names. The *number* attribute is an integer."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:266
msgid "The object structure is updated accordingly::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:275
msgid ""
"Because we now have data to manage, we have to be more careful about object "
"allocation and deallocation.  At a minimum, we need a deallocation method::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:286
msgid "which is assigned to the :attr:`tp_dealloc` member::"
msgstr ""

# c717347c6d5a4f878db16b46ac0fe9c9
#: ../src/Doc/extending/newtypes.rst:290
msgid ""
"This method decrements the reference counts of the two Python attributes. We "
"use :c:func:`Py_XDECREF` here because the :attr:`first` and :attr:`last` "
"members could be *NULL*.  It then calls the :attr:`tp_free` member of the "
"object's type to free the object's memory.  Note that the object's type "
"might not be :class:`NoddyType`, because the object may be an instance of a "
"subclass."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:296
msgid ""
"We want to make sure that the first and last names are initialized to empty "
"strings, so we provide a new method::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:326
msgid "and install it in the :attr:`tp_new` member::"
msgstr ""

# 4325f9f0f3a442f9ae74020777eb1fee
#: ../src/Doc/extending/newtypes.rst:330
msgid ""
"The new member is responsible for creating (as opposed to initializing) "
"objects of the type.  It is exposed in Python as the :meth:`__new__` "
"method.  See the paper titled \"Unifying types and classes in Python\" for a "
"detailed discussion of the :meth:`__new__` method.  One reason to implement "
"a new method is to assure the initial values of instance variables.  In this "
"case, we use the new method to make sure that the initial values of the "
"members :attr:`first` and :attr:`last` are not *NULL*. If we didn't care "
"whether the initial values were *NULL*, we could have used :c:func:"
"`PyType_GenericNew` as our new method, as we did before.  :c:func:"
"`PyType_GenericNew` initializes all of the instance variable members to "
"*NULL*."
msgstr ""

# aaa2ffa1897744b2a452246976de2068
#: ../src/Doc/extending/newtypes.rst:341
msgid ""
"The new method is a static method that is passed the type being instantiated "
"and any arguments passed when the type was called, and that returns the new "
"object created. New methods always accept positional and keyword arguments, "
"but they often ignore the arguments, leaving the argument handling to "
"initializer methods. Note that if the type supports subclassing, the type "
"passed may not be the type being defined.  The new method calls the tp_alloc "
"slot to allocate memory. We don't fill the :attr:`tp_alloc` slot ourselves. "
"Rather :c:func:`PyType_Ready` fills it for us by inheriting it from our base "
"class, which is :class:`object` by default.  Most types use the default "
"allocation."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:353
msgid ""
"If you are creating a co-operative :attr:`tp_new` (one that calls a base "
"type's :attr:`tp_new` or :meth:`__new__`), you must *not* try to determine "
"what method to call using method resolution order at runtime.  Always "
"statically determine what type you are going to call, and call its :attr:"
"`tp_new` directly, or via ``type->tp_base->tp_new``.  If you do not do this, "
"Python subclasses of your type that also inherit from other Python-defined "
"classes may not work correctly. (Specifically, you may not be able to create "
"instances of such subclasses without getting a :exc:`TypeError`.)"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:362
msgid "We provide an initialization function::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:393
msgid "by filling the :attr:`tp_init` slot. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:397
msgid ""
"The :attr:`tp_init` slot is exposed in Python as the :meth:`__init__` "
"method. It is used to initialize an object after it's created. Unlike the "
"new method, we can't guarantee that the initializer is called.  The "
"initializer isn't called when unpickling objects and it can be overridden.  "
"Our initializer accepts arguments to provide initial values for our "
"instance. Initializers always accept positional and keyword arguments."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:404
msgid ""
"Initializers can be called multiple times.  Anyone can call the :meth:"
"`__init__` method on our objects.  For this reason, we have to be extra "
"careful when assigning the new values.  We might be tempted, for example to "
"assign the :attr:`first` member like this::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:415
msgid ""
"But this would be risky.  Our type doesn't restrict the type of the :attr:"
"`first` member, so it could be any kind of object.  It could have a "
"destructor that causes code to be executed that tries to access the :attr:"
"`first` member.  To be paranoid and protect ourselves against this "
"possibility, we almost always reassign members before decrementing their "
"reference counts.  When don't we have to do this?"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:422
msgid "when we absolutely know that the reference count is greater than 1"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:424
msgid ""
"when we know that deallocation of the object [#]_ will not cause any calls "
"back into our type's code"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:427
msgid ""
"when decrementing a reference count in a :attr:`tp_dealloc` handler when "
"garbage-collections is not supported [#]_"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:430
msgid ""
"We want to expose our instance variables as attributes. There are a number "
"of ways to do that. The simplest way is to define member definitions::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:443
msgid "and put the definitions in the :attr:`tp_members` slot::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:447
msgid ""
"Each member definition has a member name, type, offset, access flags and "
"documentation string. See the :ref:`Generic-Attribute-Management` section "
"below for details."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:451
msgid ""
"A disadvantage of this approach is that it doesn't provide a way to restrict "
"the types of objects that can be assigned to the Python attributes.  We "
"expect the first and last names to be strings, but any Python objects can be "
"assigned. Further, the attributes can be deleted, setting the C pointers to "
"*NULL*.  Even though we can make sure the members are initialized to non-"
"*NULL* values, the members can be set to *NULL* if the attributes are "
"deleted."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:458
msgid ""
"We define a single method, :meth:`name`, that outputs the objects name as "
"the concatenation of the first and last names. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:493
msgid ""
"The method is implemented as a C function that takes a :class:`Noddy` (or :"
"class:`Noddy` subclass) instance as the first argument.  Methods always take "
"an instance as the first argument. Methods often take positional and keyword "
"arguments as well, but in this cased we don't take any and don't need to "
"accept a positional argument tuple or keyword argument dictionary. This "
"method is equivalent to the Python method::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:503
msgid ""
"Note that we have to check for the possibility that our :attr:`first` and :"
"attr:`last` members are *NULL*.  This is because they can be deleted, in "
"which case they are set to *NULL*.  It would be better to prevent deletion "
"of these attributes and to restrict the attribute values to be strings.  "
"We'll see how to do that in the next section."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:509
msgid ""
"Now that we've defined the method, we need to create an array of method "
"definitions::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:519
msgid "and assign them to the :attr:`tp_methods` slot::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:523
msgid ""
"Note that we used the :const:`METH_NOARGS` flag to indicate that the method "
"is passed no arguments."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:526
msgid ""
"Finally, we'll make our type usable as a base class.  We've written our "
"methods carefully so far so that they don't make any assumptions about the "
"type of the object being created or used, so all we need to do is to add "
"the :const:`Py_TPFLAGS_BASETYPE` to our class flag definition::"
msgstr ""

# 2e4b2a74f31e436a98a64533e1b16736
#: ../src/Doc/extending/newtypes.rst:533
msgid ""
"We rename :c:func:`initnoddy` to :c:func:`initnoddy2` and update the module "
"name passed to :c:func:`Py_InitModule3`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:536
msgid "Finally, we update our :file:`setup.py` file to build the new module::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:547
msgid "Providing finer control over data attributes"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:549
msgid ""
"In this section, we'll provide finer control over how the :attr:`first` and :"
"attr:`last` attributes are set in the :class:`Noddy` example. In the "
"previous version of our module, the instance variables :attr:`first` and :"
"attr:`last` could be set to non-string values or even deleted. We want to "
"make sure that these attributes always contain strings."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:558
msgid ""
"To provide greater control, over the :attr:`first` and :attr:`last` "
"attributes, we'll use custom getter and setter functions.  Here are the "
"functions for getting and setting the :attr:`first` attribute::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:589
msgid ""
"The getter function is passed a :class:`Noddy` object and a \"closure\", "
"which is void pointer. In this case, the closure is ignored. (The closure "
"supports an advanced usage in which definition data is passed to the getter "
"and setter. This could, for example, be used to allow a single set of getter "
"and setter functions that decide the attribute to get or set based on data "
"in the closure.)"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:595
msgid ""
"The setter function is passed the :class:`Noddy` object, the new value, and "
"the closure. The new value may be *NULL*, in which case the attribute is "
"being deleted.  In our setter, we raise an error if the attribute is deleted "
"or if the attribute value is not a string."
msgstr ""

# dcc82a5e26d04bddb8a747acec5eac47
#: ../src/Doc/extending/newtypes.rst:600
msgid "We create an array of :c:type:`PyGetSetDef` structures::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:614
msgid "and register it in the :attr:`tp_getset` slot::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:618
msgid "to register our attribute getters and setters."
msgstr ""

# 2774eb67e20b4ef98edca407b0c19485
#: ../src/Doc/extending/newtypes.rst:620
msgid ""
"The last item in a :c:type:`PyGetSetDef` structure is the closure mentioned "
"above. In this case, we aren't using the closure, so we just pass *NULL*."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:623
msgid "We also remove the member definitions for these attributes::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:631
msgid ""
"We also need to update the :attr:`tp_init` handler to only allow strings [#]"
"_ to be passed::"
msgstr ""

# 4b02044d9a3448b4aa31b62c14379188
#: ../src/Doc/extending/newtypes.rst:663
msgid ""
"With these changes, we can assure that the :attr:`first` and :attr:`last` "
"members are never *NULL* so we can remove checks for *NULL* values in almost "
"all cases. This means that most of the :c:func:`Py_XDECREF` calls can be "
"converted to :c:func:`Py_DECREF` calls. The only place we can't change these "
"calls is in the deallocator, where there is the possibility that the "
"initialization of these members failed in the constructor."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:670
msgid ""
"We also rename the module initialization function and module name in the "
"initialization function, as we did before, and we add an extra definition to "
"the :file:`setup.py` file."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:676
msgid "Supporting cyclic garbage collection"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:678
msgid ""
"Python has a cyclic-garbage collector that can identify unneeded objects "
"even when their reference counts are not zero. This can happen when objects "
"are involved in cycles.  For example, consider::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:686
msgid ""
"In this example, we create a list that contains itself. When we delete it, "
"it still has a reference from itself. Its reference count doesn't drop to "
"zero. Fortunately, Python's cyclic-garbage collector will eventually figure "
"out that the list is garbage and free it."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:691
msgid ""
"In the second version of the :class:`Noddy` example, we allowed any kind of "
"object to be stored in the :attr:`first` or :attr:`last` attributes. [#]_ "
"This means that :class:`Noddy` objects can participate in cycles::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:700
msgid ""
"This is pretty silly, but it gives us an excuse to add support for the "
"cyclic-garbage collector to the :class:`Noddy` example.  To support cyclic "
"garbage collection, types need to fill two slots and set a class flag that "
"enables these slots:"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:708
msgid ""
"The traversal method provides access to subobjects that could participate in "
"cycles::"
msgstr ""

# 7524d7496e0d4378828e18652374d941
#: ../src/Doc/extending/newtypes.rst:730
msgid ""
"For each subobject that can participate in cycles, we need to call the :c:"
"func:`visit` function, which is passed to the traversal method. The :c:func:"
"`visit` function takes as arguments the subobject and the extra argument "
"*arg* passed to the traversal method.  It returns an integer value that must "
"be returned if it is non-zero."
msgstr ""

# ba146252a9a448e5bb4f87f798a44b8d
#: ../src/Doc/extending/newtypes.rst:736
msgid ""
"Python 2.4 and higher provide a :c:func:`Py_VISIT` macro that automates "
"calling visit functions.  With :c:func:`Py_VISIT`, :c:func:`Noddy_traverse` "
"can be simplified::"
msgstr ""

# e365d2c715ce4b2db6335dbeeb9cb277
#: ../src/Doc/extending/newtypes.rst:750
msgid ""
"Note that the :attr:`tp_traverse` implementation must name its arguments "
"exactly *visit* and *arg* in order to use :c:func:`Py_VISIT`.  This is to "
"encourage uniformity across these boring implementations."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:754
msgid ""
"We also need to provide a method for clearing any subobjects that can "
"participate in cycles.  We implement the method and reimplement the "
"deallocator to use it::"
msgstr ""

# bc81362c001e4b1b829c5dd6ec89ab84
#: ../src/Doc/extending/newtypes.rst:781
msgid ""
"Notice the use of a temporary variable in :c:func:`Noddy_clear`. We use the "
"temporary variable so that we can set each member to *NULL* before "
"decrementing its reference count.  We do this because, as was discussed "
"earlier, if the reference count drops to zero, we might cause code to run "
"that calls back into the object.  In addition, because we now support "
"garbage collection, we also have to worry about code being run that triggers "
"garbage collection.  If garbage collection is run, our :attr:`tp_traverse` "
"handler could get called. We can't take a chance of having :c:func:"
"`Noddy_traverse` called when a member's reference count has dropped to zero "
"and its value hasn't been set to *NULL*."
msgstr ""

# 465bbd3cc10a41469c8e5a384e88f55a
#: ../src/Doc/extending/newtypes.rst:791
msgid ""
"Python 2.4 and higher provide a :c:func:`Py_CLEAR` that automates the "
"careful decrementing of reference counts.  With :c:func:`Py_CLEAR`, the :c:"
"func:`Noddy_clear` function can be simplified::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:803
msgid ""
"Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:807
msgid ""
"That's pretty much it.  If we had written custom :attr:`tp_alloc` or :attr:"
"`tp_free` slots, we'd need to modify them for cyclic-garbage collection. "
"Most extensions will use the versions automatically provided."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:813
msgid "Subclassing other types"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:815
msgid ""
"It is possible to create new extension types that are derived from existing "
"types. It is easiest to inherit from the built in types, since an extension "
"can easily use the :class:`PyTypeObject` it needs. It can be difficult to "
"share these :class:`PyTypeObject` structures between extension modules."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:820
msgid ""
"In this example we will create a :class:`Shoddy` type that inherits from the "
"built-in :class:`list` type. The new type will be completely compatible with "
"regular lists, but will have an additional :meth:`increment` method that "
"increases an internal counter. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:838
msgid ""
"As you can see, the source code closely resembles the :class:`Noddy` "
"examples in previous sections. We will break down the main differences "
"between them. ::"
msgstr ""

# f013c10ee075443ba5033fd7384c2707
#: ../src/Doc/extending/newtypes.rst:846
msgid ""
"The primary difference for derived type objects is that the base type's "
"object structure must be the first value. The base type will already include "
"the :c:func:`PyObject_HEAD` at the beginning of its structure."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:850
msgid ""
"When a Python object is a :class:`Shoddy` instance, its *PyObject\\** "
"pointer can be safely cast to both *PyListObject\\** and *Shoddy\\**. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:862
msgid ""
"In the :attr:`__init__` method for our type, we can see how to call through "
"to the :attr:`__init__` method of the base type."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:865
msgid ""
"This pattern is important when writing a type with custom :attr:`new` and :"
"attr:`dealloc` methods. The :attr:`new` method should not actually create "
"the memory for the object with :attr:`tp_alloc`, that will be handled by the "
"base class when calling its :attr:`tp_new`."
msgstr ""

# a6668a8e67b441fca842c5e8c4963754
#: ../src/Doc/extending/newtypes.rst:870
msgid ""
"When filling out the :c:func:`PyTypeObject` for the :class:`Shoddy` type, "
"you see a slot for :c:func:`tp_base`. Due to cross platform compiler issues, "
"you can't fill that field directly with the :c:func:`PyList_Type`; it can be "
"done later in the module's :c:func:`init` function. ::"
msgstr ""

# 6afdd2f0324a41b9b8f318da7195c6e2
#: ../src/Doc/extending/newtypes.rst:892
msgid ""
"Before calling :c:func:`PyType_Ready`, the type structure must have the :"
"attr:`tp_base` slot filled in. When we are deriving a new type, it is not "
"necessary to fill out the :attr:`tp_alloc` slot with :c:func:"
"`PyType_GenericNew` -- the allocate function from the base type will be "
"inherited."
msgstr ""

# f13f0bbe190c45b8b4bb00a9422780a9
#: ../src/Doc/extending/newtypes.rst:897
msgid ""
"After that, calling :c:func:`PyType_Ready` and adding the type object to the "
"module is the same as with the basic :class:`Noddy` examples."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:904
msgid "Type Methods"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:906
msgid ""
"This section aims to give a quick fly-by on the various type methods you can "
"implement and what they do."
msgstr ""

# c386aab2c51a410785156697b9298f25
#: ../src/Doc/extending/newtypes.rst:909
msgid ""
"Here is the definition of :c:type:`PyTypeObject`, with some fields only used "
"in debug builds omitted:"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:915
msgid ""
"Now that's a *lot* of methods.  Don't worry too much though - if you have a "
"type you want to define, the chances are very good that you will only "
"implement a handful of these."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:919
msgid ""
"As you probably expect by now, we're going to go over this and give more "
"information about the various handlers.  We won't go in the order they are "
"defined in the structure, because there is a lot of historical baggage that "
"impacts the ordering of the fields; be sure your type initialization keeps "
"the fields in the right order!  It's often easiest to find an example that "
"includes all the fields you need (even if they're initialized to ``0``) and "
"then change the values to suit your new type. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:929
msgid ""
"The name of the type - as mentioned in the last section, this will appear in "
"various places, almost entirely for diagnostic purposes. Try to choose "
"something that will be helpful in such a situation! ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:935
msgid ""
"These fields tell the runtime how much memory to allocate when new objects "
"of this type are created.  Python has some built-in support for variable "
"length structures (think: strings, lists) which is where the :attr:"
"`tp_itemsize` field comes in.  This will be dealt with later. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:942
msgid ""
"Here you can put a string (or its address) that you want returned when the "
"Python script references ``obj.__doc__`` to retrieve the doc string."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:945
msgid ""
"Now we come to the basic type methods---the ones most extension types will "
"implement."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:950
msgid "Finalization and De-allocation"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:962
msgid ""
"This function is called when the reference count of the instance of your "
"type is reduced to zero and the Python interpreter wants to reclaim it.  If "
"your type has memory to free or other clean-up to perform, put it here.  The "
"object itself needs to be freed here as well.  Here is an example of this "
"function::"
msgstr ""

# 8dfa9cb2ef1e49f2a34948c39479ccc7
#: ../src/Doc/extending/newtypes.rst:978
msgid ""
"One important requirement of the deallocator function is that it leaves any "
"pending exceptions alone.  This is important since deallocators are "
"frequently called as the interpreter unwinds the Python stack; when the "
"stack is unwound due to an exception (rather than normal returns), nothing "
"is done to protect the deallocators from seeing that an exception has "
"already been set.  Any actions which a deallocator performs which may cause "
"additional Python code to be executed may detect that an exception has been "
"set.  This can lead to misleading errors from the interpreter.  The proper "
"way to protect against this is to save a pending exception before performing "
"the unsafe action, and restoring it when done.  This can be done using the :"
"c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` functions::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1019
msgid "Object Presentation"
msgstr ""

# 91c3874334a5418c938f41bdffb4341b
#: ../src/Doc/extending/newtypes.rst:1025
msgid ""
"In Python, there are three ways to generate a textual representation of an "
"object: the :func:`repr` function (or equivalent back-tick syntax), the :"
"func:`str` function, and the :keyword:`print` statement.  For most objects, "
"the :keyword:`print` statement is equivalent to the :func:`str` function, "
"but it is possible to special-case printing to a :c:type:`FILE\\*` if "
"necessary; this should only be done if efficiency is identified as a problem "
"and profiling suggests that creating a temporary string object to be written "
"to a file is too expensive."
msgstr ""

# 6102caf6a8d64fab84da74261a357f7f
#: ../src/Doc/extending/newtypes.rst:1034
msgid ""
"These handlers are all optional, and most types at most need to implement "
"the :attr:`tp_str` and :attr:`tp_repr` handlers. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1041
msgid ""
"The :attr:`tp_repr` handler should return a string object containing a "
"representation of the instance for which it is called.  Here is a simple "
"example::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1052
msgid ""
"If no :attr:`tp_repr` handler is specified, the interpreter will supply a "
"representation that uses the type's :attr:`tp_name` and a uniquely-"
"identifying value for the object."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1056
msgid ""
"The :attr:`tp_str` handler is to :func:`str` what the :attr:`tp_repr` "
"handler described above is to :func:`repr`; that is, it is called when "
"Python code calls :func:`str` on an instance of your object.  Its "
"implementation is very similar to the :attr:`tp_repr` function, but the "
"resulting string is intended for human consumption.  If :attr:`tp_str` is "
"not specified, the :attr:`tp_repr` handler is used instead."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1063
msgid "Here is a simple example::"
msgstr ""

# 91ebb828f0b64802a9b0d2b826911004
#: ../src/Doc/extending/newtypes.rst:1072
msgid ""
"The print function will be called whenever Python needs to \"print\" an "
"instance of the type.  For example, if 'node' is an instance of type "
"TreeNode, then the print function is called when Python code calls::"
msgstr ""

# 802642aebd8b4646b09707453fee94b2
#: ../src/Doc/extending/newtypes.rst:1078
msgid ""
"There is a flags argument and one flag, :const:`Py_PRINT_RAW`, and it "
"suggests that you print without string quotes and possibly without "
"interpreting escape sequences."
msgstr ""

# 2704aed8d0774f6c893dc16fb8e17018
#: ../src/Doc/extending/newtypes.rst:1082
msgid ""
"The print function receives a file object as an argument. You will likely "
"want to write to that file object."
msgstr ""

# b79b806741da448d993574786c051ebe
#: ../src/Doc/extending/newtypes.rst:1085
msgid "Here is a sample print function::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1103
msgid "Attribute Management"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1105
msgid ""
"For every object which can support attributes, the corresponding type must "
"provide the functions that control how the attributes are resolved.  There "
"needs to be a function which can retrieve attributes (if any are defined), "
"and another to set attributes (if setting attributes is allowed).  Removing "
"an attribute is a special case, for which the new value passed to the "
"handler is *NULL*."
msgstr ""

# d9b3eb4088d949388554c62d4f22dfc9
#: ../src/Doc/extending/newtypes.rst:1111
msgid ""
"Python supports two pairs of attribute handlers; a type that supports "
"attributes only needs to implement the functions for one pair.  The "
"difference is that one pair takes the name of the attribute as a :c:type:"
"`char\\*`, while the other accepts a :c:type:`PyObject\\*`.  Each type can "
"use whichever pair makes more sense for the implementation's convenience. ::"
msgstr ""

# e9e88cdb49034409b680a672c75bb819
#: ../src/Doc/extending/newtypes.rst:1123
msgid ""
"If accessing attributes of an object is always a simple operation (this will "
"be explained shortly), there are generic implementations which can be used "
"to provide the :c:type:`PyObject\\*` version of the attribute management "
"functions. The actual need for type-specific attribute handlers almost "
"completely disappeared starting with Python 2.2, though there are many "
"examples which have not been updated to use some of the new generic "
"mechanism that is available."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1134
msgid "Generic Attribute Management"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1138
msgid ""
"Most extension types only use *simple* attributes.  So, what makes the "
"attributes simple?  There are only a couple of conditions that must be met:"
msgstr ""

# 51e507a3d6064c94a817606030211daf
#: ../src/Doc/extending/newtypes.rst:1141
msgid ""
"The name of the attributes must be known when :c:func:`PyType_Ready` is "
"called."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1144
msgid ""
"No special processing is needed to record that an attribute was looked up or "
"set, nor do actions need to be taken based on the value."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1147
msgid ""
"Note that this list does not place any restrictions on the values of the "
"attributes, when the values are computed, or how relevant data is stored."
msgstr ""

# b647b106d7304de0809fa51cf9c25cba
#: ../src/Doc/extending/newtypes.rst:1150
msgid ""
"When :c:func:`PyType_Ready` is called, it uses three tables referenced by "
"the type object to create :term:`descriptor`\\s which are placed in the "
"dictionary of the type object.  Each descriptor controls access to one "
"attribute of the instance object.  Each of the tables is optional; if all "
"three are *NULL*, instances of the type will only have attributes that are "
"inherited from their base type, and should leave the :attr:`tp_getattro` "
"and :attr:`tp_setattro` fields *NULL* as well, allowing the base type to "
"handle attributes."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1158
msgid "The tables are declared as three fields of the type object::"
msgstr ""

# 6e6313857f8d458e89bbe00d5d05e73d
#: ../src/Doc/extending/newtypes.rst:1164
msgid ""
"If :attr:`tp_methods` is not *NULL*, it must refer to an array of :c:type:"
"`PyMethodDef` structures.  Each entry in the table is an instance of this "
"structure::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1175
msgid ""
"One entry should be defined for each method provided by the type; no entries "
"are needed for methods inherited from a base type.  One additional entry is "
"needed at the end; it is a sentinel that marks the end of the array.  The :"
"attr:`ml_name` field of the sentinel must be *NULL*."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1180
msgid ""
"XXX Need to refer to some unified discussion of the structure fields, shared "
"with the next section."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1183
msgid ""
"The second table is used to define attributes which map directly to data "
"stored in the instance.  A variety of primitive C types are supported, and "
"access may be read-only or read-write.  The structures in the table are "
"defined as::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1195
msgid ""
"For each entry in the table, a :term:`descriptor` will be constructed and "
"added to the type which will be able to extract a value from the instance "
"structure.  The :attr:`type` field should contain one of the type codes "
"defined in the :file:`structmember.h` header; the value will be used to "
"determine how to convert Python values to and from C values.  The :attr:"
"`flags` field is used to store flags which control how the attribute can be "
"accessed."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1202
msgid "XXX Need to move some of this to a shared section!"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1204
msgid ""
"The following flag constants are defined in :file:`structmember.h`; they may "
"be combined using bitwise-OR."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1208
msgid "Constant"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1208
msgid "Meaning"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1210
msgid ":const:`READONLY`"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1210
msgid "Never writable."
msgstr ""

# d872706e4c3341338a81ab2f43fe0219
#: ../src/Doc/extending/newtypes.rst:1212
msgid ":const:`RO`"
msgstr ""

# fdf1fe5ac3484ce78a74d02009f940d2
#: ../src/Doc/extending/newtypes.rst:1212
msgid "Shorthand for :const:`READONLY`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1214
msgid ":const:`READ_RESTRICTED`"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1214
msgid "Not readable in restricted mode."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1216
msgid ":const:`WRITE_RESTRICTED`"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1216
msgid "Not writable in restricted mode."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1218
msgid ":const:`RESTRICTED`"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1218
msgid "Not readable or writable in restricted mode."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1228
msgid ""
"An interesting advantage of using the :attr:`tp_members` table to build "
"descriptors that are used at runtime is that any attribute defined this way "
"can have an associated doc string simply by providing the text in the "
"table.  An application can use the introspection API to retrieve the "
"descriptor from the class object, and get the doc string using its :attr:"
"`__doc__` attribute."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1234
msgid ""
"As with the :attr:`tp_methods` table, a sentinel entry with a :attr:`name` "
"value of *NULL* is required."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1248
msgid "Type-specific Attribute Management"
msgstr ""

# 31b07fd5698c47598736f80b081fd046
#: ../src/Doc/extending/newtypes.rst:1250
msgid ""
"For simplicity, only the :c:type:`char\\*` version will be demonstrated "
"here; the type of the name parameter is the only difference between the :c:"
"type:`char\\*` and :c:type:`PyObject\\*` flavors of the interface. This "
"example effectively does the same thing as the generic example above, but "
"does not use the generic support added in Python 2.2.  The value in showing "
"this is two-fold: it demonstrates how basic attribute management can be done "
"in a way that is portable to older versions of Python, and explains how the "
"handler functions are called, so that if you do need to extend their "
"functionality, you'll understand what needs to be done."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1260
msgid ""
"The :attr:`tp_getattr` handler is called when the object requires an "
"attribute look-up.  It is called in the same situations where the :meth:"
"`__getattr__` method of a class would be called."
msgstr ""

# 7d1af30d5c754ead97707eb29b0ab6ea
#: ../src/Doc/extending/newtypes.rst:1264
msgid ""
"A likely way to handle this is (1) to implement a set of functions (such as :"
"c:func:`newdatatype_getSize` and :c:func:`newdatatype_setSize` in the "
"example below), (2) provide a method table listing these functions, and (3) "
"provide a getattr function that returns the result of a lookup in that "
"table.  The method table uses the same structure as the :attr:`tp_methods` "
"field of the type object."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1271
msgid "Here is an example::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1287
msgid ""
"The :attr:`tp_setattr` handler is called when the :meth:`__setattr__` or :"
"meth:`__delattr__` method of a class instance would be called.  When an "
"attribute should be deleted, the third parameter will be *NULL*.  Here is an "
"example that simply raises an exception; if this were really all you wanted, "
"the :attr:`tp_setattr` handler should be set to *NULL*. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1302
msgid "Object Comparison"
msgstr ""

# 04aa8b80a00c4d76aa1debf2fadb0cbb
#: ../src/Doc/extending/newtypes.rst:1308
msgid ""
"The :attr:`tp_compare` handler is called when comparisons are needed and the "
"object does not implement the specific rich comparison method which matches "
"the requested comparison.  (It is always used if defined and the :c:func:"
"`PyObject_Compare` or :c:func:`PyObject_Cmp` functions are used, or if :func:"
"`cmp` is used from Python.) It is analogous to the :meth:`__cmp__` method. "
"This function should return ``-1`` if *obj1* is less than *obj2*, ``0`` if "
"they are equal, and ``1`` if *obj1* is greater than *obj2*. (It was "
"previously allowed to return arbitrary negative or positive integers for "
"less than and greater than, respectively; as of Python 2.2, this is no "
"longer allowed.  In the future, other return values may be assigned a "
"different meaning.)"
msgstr ""

# b47d209cd7be4596a770dbdf41902f4d
#: ../src/Doc/extending/newtypes.rst:1319
msgid ""
"A :attr:`tp_compare` handler may raise an exception.  In this case it should "
"return a negative value.  The caller has to test for the exception using :c:"
"func:`PyErr_Occurred`."
msgstr ""

# 892c7be86eb34136ab190237e5275426
#: ../src/Doc/extending/newtypes.rst:1323
msgid "Here is a sample implementation::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1346
msgid "Abstract Protocol Support"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1348
msgid ""
"Python supports a variety of *abstract* 'protocols;' the specific interfaces "
"provided to use these interfaces are documented in :ref:`abstract`."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1352
msgid ""
"A number of these abstract interfaces were defined early in the development "
"of the Python implementation.  In particular, the number, mapping, and "
"sequence protocols have been part of Python since the beginning.  Other "
"protocols have been added over time.  For protocols which depend on several "
"handler routines from the type implementation, the older protocols have been "
"defined as optional blocks of handlers referenced by the type object.  For "
"newer protocols there are additional slots in the main type object, with a "
"flag bit being set to indicate that the slots are present and should be "
"checked by the interpreter.  (The flag bit does not indicate that the slot "
"values are non-*NULL*. The flag may be set to indicate the presence of a "
"slot, but a slot may still be unfilled.) ::"
msgstr ""

# 2898f877349f4ab3811cce78a9661e8c
#: ../src/Doc/extending/newtypes.rst:1367
msgid ""
"If you wish your object to be able to act like a number, a sequence, or a "
"mapping object, then you place the address of a structure that implements "
"the C type :c:type:`PyNumberMethods`, :c:type:`PySequenceMethods`, or :c:"
"type:`PyMappingMethods`, respectively. It is up to you to fill in this "
"structure with appropriate values. You can find examples of the use of each "
"of these in the :file:`Objects` directory of the Python source "
"distribution. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1376
msgid ""
"This function, if you choose to provide it, should return a hash number for "
"an instance of your data type. Here is a moderately pointless example::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1392
msgid ""
"This function is called when an instance of your data type is \"called\", "
"for example, if ``obj1`` is an instance of your data type and the Python "
"script contains ``obj1('hello')``, the :attr:`tp_call` handler is invoked."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1396
msgid "This function takes three arguments:"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1398
msgid ""
"*arg1* is the instance of the data type which is the subject of the call. If "
"the call is ``obj1('hello')``, then *arg1* is ``obj1``."
msgstr ""

# 4d682322301d470faa0588ab1aa4ee6d
#: ../src/Doc/extending/newtypes.rst:1401
msgid ""
"*arg2* is a tuple containing the arguments to the call.  You can use :c:func:"
"`PyArg_ParseTuple` to extract the arguments."
msgstr ""

# e71b1a71a1f84e2e98737fca13909292
#: ../src/Doc/extending/newtypes.rst:1404
msgid ""
"*arg3* is a dictionary of keyword arguments that were passed. If this is non-"
"*NULL* and you support keyword arguments, use :c:func:"
"`PyArg_ParseTupleAndKeywords` to extract the arguments.  If you do not want "
"to support keyword arguments and this is non-*NULL*, raise a :exc:"
"`TypeError` with a message saying that keyword arguments are not supported."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1410
msgid ""
"Here is a desultory example of the implementation of the call function. ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1436
msgid "XXX some fields need to be added here... ::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1443
msgid ""
"These functions provide support for the iterator protocol.  Any object which "
"wishes to support iteration over its contents (which may be generated during "
"iteration) must implement the ``tp_iter`` handler.  Objects which are "
"returned by a ``tp_iter`` handler must implement both the ``tp_iter`` and "
"``tp_iternext`` handlers. Both handlers take exactly one parameter, the "
"instance for which they are being called, and return a new reference.  In "
"the case of an error, they should set an exception and return *NULL*."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1451
msgid ""
"For an object which represents an iterable collection, the ``tp_iter`` "
"handler must return an iterator object.  The iterator object is responsible "
"for maintaining the state of the iteration.  For collections which can "
"support multiple iterators which do not interfere with each other (as lists "
"and tuples do), a new iterator should be created and returned.  Objects "
"which can only be iterated over once (usually due to side effects of "
"iteration) should implement this handler by returning a new reference to "
"themselves, and should also implement the ``tp_iternext`` handler.  File "
"objects are an example of such an iterator."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1461
msgid ""
"Iterator objects should implement both handlers.  The ``tp_iter`` handler "
"should return a new reference to the iterator (this is the same as the "
"``tp_iter`` handler for objects which can only be iterated over "
"destructively).  The ``tp_iternext`` handler should return a new reference "
"to the next object in the iteration if there is one.  If the iteration has "
"reached the end, it may return *NULL* without setting an exception or it may "
"set :exc:`StopIteration`; avoiding the exception can yield slightly better "
"performance.  If an actual error occurs, it should set an exception and "
"return *NULL*."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1474
msgid "Weak Reference Support"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1476
msgid ""
"One of the goals of Python's weak-reference implementation is to allow any "
"type to participate in the weak reference mechanism without incurring the "
"overhead on those objects which do not benefit by weak referencing (such as "
"numbers)."
msgstr ""

# 66d44bd7829849ed937246306b92fb31
#: ../src/Doc/extending/newtypes.rst:1480
msgid ""
"For an object to be weakly referencable, the extension must include a :c:"
"type:`PyObject\\*` field in the instance structure for the use of the weak "
"reference mechanism; it must be initialized to *NULL* by the object's "
"constructor.  It must also set the :attr:`tp_weaklistoffset` field of the "
"corresponding type object to the offset of the field. For example, the "
"instance type is defined with the following structure::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1494
msgid "The statically-declared type object for instances is defined this way::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1511
msgid ""
"The type constructor is responsible for initializing the weak reference list "
"to *NULL*::"
msgstr ""

# 410261a740174cb19fb7ce987c121ca0
#: ../src/Doc/extending/newtypes.rst:1523
msgid ""
"The only further addition is that the destructor needs to call the weak "
"reference manager to clear any weak references.  This is only required if "
"the weak reference list is non-*NULL*::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1542
msgid "More Suggestions"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1544
msgid ""
"Remember that you can omit most of these functions, in which case you "
"provide ``0`` as a value.  There are type definitions for each of the "
"functions you must provide.  They are in :file:`object.h` in the Python "
"include directory that comes with the source distribution of Python."
msgstr ""

# 982f8feaea1d47929091ea51121b61a4
#: ../src/Doc/extending/newtypes.rst:1549
msgid ""
"In order to learn how to implement any specific method for your new data "
"type, do the following: Download and unpack the Python source distribution.  "
"Go the :file:`Objects` directory, then search the C source files for ``tp_`` "
"plus the function you want (for example, ``tp_print`` or ``tp_compare``).  "
"You will find examples of the function you want to implement."
msgstr ""

# 9576add852934d3f8e4605c3beba415c
#: ../src/Doc/extending/newtypes.rst:1555
msgid ""
"When you need to verify that an object is an instance of the type you are "
"implementing, use the :c:func:`PyObject_TypeCheck` function. A sample of its "
"use might be something like the following::"
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1566
msgid ""
"This is true when we know that the object is a basic type, like a string or "
"a float."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1569
msgid ""
"We relied on this in the :attr:`tp_dealloc` handler in this example, because "
"our type doesn't support garbage collection. Even if a type supports garbage "
"collection, there are calls that can be made to \"untrack\" the object from "
"garbage collection, however, these calls are advanced and not covered here."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1574
msgid ""
"We now know that the first and last members are strings, so perhaps we could "
"be less careful about decrementing their reference counts, however, we "
"accept instances of string subclasses. Even though deallocating normal "
"strings won't call back into our objects, we can't guarantee that "
"deallocating an instance of a string subclass won't call back into our "
"objects."
msgstr ""

#: ../src/Doc/extending/newtypes.rst:1580
msgid ""
"Even in the third version, we aren't guaranteed to avoid cycles.  Instances "
"of string subclasses are allowed and string subclasses could allow cycles "
"even if normal strings don't."
msgstr ""

#: ../src/Doc/extending/windows.rst:8
msgid "Building C and C++ Extensions on Windows"
msgstr ""

#: ../src/Doc/extending/windows.rst:10
msgid ""
"This chapter briefly explains how to create a Windows extension module for "
"Python using Microsoft Visual C++, and follows with more detailed background "
"information on how it works.  The explanatory material is useful for both "
"the Windows programmer learning to build Python extensions and the Unix "
"programmer interested in producing software which can be successfully built "
"on both Unix and Windows."
msgstr ""

#: ../src/Doc/extending/windows.rst:17
msgid ""
"Module authors are encouraged to use the distutils approach for building "
"extension modules, instead of the one described in this section. You will "
"still need the C compiler that was used to build Python; typically Microsoft "
"Visual C++."
msgstr ""

#: ../src/Doc/extending/windows.rst:24
msgid ""
"This chapter mentions a number of filenames that include an encoded Python "
"version number.  These filenames are represented with the version number "
"shown as ``XY``; in practice, ``'X'`` will be the major version number and "
"``'Y'`` will be the minor version number of the Python release you're "
"working with.  For example, if you are using Python 2.2.1, ``XY`` will "
"actually be ``22``."
msgstr ""

#: ../src/Doc/extending/windows.rst:34
msgid "A Cookbook Approach"
msgstr ""

#: ../src/Doc/extending/windows.rst:36
msgid ""
"There are two approaches to building extension modules on Windows, just as "
"there are on Unix: use the :mod:`distutils` package to control the build "
"process, or do things manually.  The distutils approach works well for most "
"extensions; documentation on using :mod:`distutils` to build and package "
"extension modules is available in :ref:`distutils-index`.  This section "
"describes the manual approach to building Python extensions written in C or C"
"++."
msgstr ""

#: ../src/Doc/extending/windows.rst:43
msgid ""
"To build extensions using these instructions, you need to have a copy of the "
"Python sources of the same version as your installed Python. You will need "
"Microsoft Visual C++ \"Developer Studio\"; project files are supplied for VC+"
"+ version 7.1, but you can use older versions of VC++.  Notice that you "
"should use the same version of VC++that was used to build Python itself. The "
"example files described here are distributed with the Python sources in the :"
"file:`PC\\\\example_nt\\\\` directory."
msgstr ""

#: ../src/Doc/extending/windows.rst:51
msgid ""
"**Copy the example files** ---  The :file:`example_nt` directory is a "
"subdirectory of the :file:`PC` directory, in order to keep all the PC-"
"specific files under the same directory in the source distribution.  "
"However, the :file:`example_nt` directory can't actually be used from this "
"location.  You first need to copy or move it up one level, so that :file:"
"`example_nt` is a sibling of the :file:`PC` and :file:`Include` "
"directories.  Do all your work from within this new location."
msgstr ""

#: ../src/Doc/extending/windows.rst:59
msgid ""
"**Open the project** ---  From VC++, use the :menuselection:`File --> Open "
"Solution` dialog (not :menuselection:`File --> Open`!).  Navigate to and "
"select the file :file:`example.sln`, in the *copy* of the :file:`example_nt` "
"directory you made above.  Click Open."
msgstr ""

#: ../src/Doc/extending/windows.rst:64
msgid ""
"**Build the example DLL** ---  In order to check that everything is set up "
"right, try building:"
msgstr ""

#: ../src/Doc/extending/windows.rst:67
msgid ""
"Select a configuration.  This step is optional.  Choose :menuselection:"
"`Build --> Configuration Manager --> Active Solution Configuration` and "
"select either :guilabel:`Release`  or :guilabel:`Debug`.  If you skip this "
"step, VC++ will use the Debug configuration by default."
msgstr ""

#: ../src/Doc/extending/windows.rst:72
msgid ""
"Build the DLL.  Choose :menuselection:`Build --> Build Solution`.  This "
"creates all intermediate and result files in a subdirectory called either :"
"file:`Debug` or :file:`Release`, depending on which configuration you "
"selected in the preceding step."
msgstr ""

#: ../src/Doc/extending/windows.rst:77
msgid ""
"**Testing the debug-mode DLL** ---  Once the Debug build has succeeded, "
"bring up a DOS box, and change to the :file:`example_nt\\\\Debug` "
"directory.  You should now be able to repeat the following session (``C>`` "
"is the DOS prompt, ``>>>`` is the Python prompt; note that build information "
"and various debug output from Python may not match this screen dump "
"exactly)::"
msgstr ""

#: ../src/Doc/extending/windows.rst:95
msgid ""
"Congratulations!  You've successfully built your first Python extension "
"module."
msgstr ""

# 2392e546ace14f5980fcb53837320efa
#: ../src/Doc/extending/windows.rst:97
msgid ""
"**Creating your own project** ---  Choose a name and create a directory for "
"it.  Copy your C sources into it.  Note that the module source file name "
"does not necessarily have to match the module name, but the name of the "
"initialization function should match the module name --- you can only import "
"a module :mod:`spam` if its initialization function is called :c:func:"
"`initspam`, and it should call :c:func:`Py_InitModule` with the string ``"
"\"spam\"`` as its first argument (use the minimal :file:`example.c` in this "
"directory as a guide). By convention, it lives in a file called :file:`spam."
"c` or :file:`spammodule.c`. The output file should be called :file:`spam."
"pyd` (in Release mode) or :file:`spam_d.pyd` (in Debug mode). The extension :"
"file:`.pyd` was chosen to avoid confusion with a system library :file:`spam."
"dll` to which your module could be a Python interface."
msgstr ""

#: ../src/Doc/extending/windows.rst:114
msgid "Now your options are:"
msgstr ""

# 1eb3c8728f4346a3a093a1c4ce7b25cd
#: ../src/Doc/extending/windows.rst:116
msgid ""
"Copy :file:`example.sln` and :file:`example.vcproj`, rename them to :file:"
"`spam.\\*`, and edit them by hand, or"
msgstr ""

#: ../src/Doc/extending/windows.rst:119
msgid "Create a brand new project; instructions are below."
msgstr ""

#: ../src/Doc/extending/windows.rst:121
msgid ""
"In either case, copy :file:`example_nt\\\\example.def` to :file:`spam\\"
"\\spam.def`, and edit the new :file:`spam.def` so its second line contains "
"the string '``initspam``'.  If you created a new project yourself, add the "
"file :file:`spam.def` to the project now.  (This is an annoying little file "
"with only two lines.  An alternative approach is to forget about the :file:`."
"def` file, and add the option :option:`/export:initspam` somewhere to the "
"Link settings, by manually editing the setting in Project Properties dialog)."
msgstr ""

#: ../src/Doc/extending/windows.rst:129
msgid ""
"**Creating a brand new project** ---  Use the :menuselection:`File --> New --"
"> Project` dialog to create a new Project Workspace.  Select :guilabel:"
"`Visual C++ Projects/Win32/ Win32 Project`, enter the name (``spam``), and "
"make sure the Location is set to parent of the :file:`spam` directory you "
"have created (which should be a direct subdirectory of the Python build "
"tree, a sibling of :file:`Include` and :file:`PC`).  Select Win32 as the "
"platform (in my version, this is the only choice).  Make sure the Create new "
"workspace radio button is selected.  Click OK."
msgstr ""

#: ../src/Doc/extending/windows.rst:138
msgid ""
"You should now create the file :file:`spam.def` as instructed in the "
"previous section. Add the source files to the project, using :menuselection:"
"`Project --> Add Existing Item`. Set the pattern to ``*.*`` and select both :"
"file:`spam.c` and :file:`spam.def` and click OK.  (Inserting them one by one "
"is fine too.)"
msgstr ""

#: ../src/Doc/extending/windows.rst:143
msgid ""
"Now open the :menuselection:`Project --> spam properties` dialog. You only "
"need to change a few settings.  Make sure :guilabel:`All Configurations` is "
"selected from the :guilabel:`Settings for:` dropdown list.  Select the C/C++ "
"tab.  Choose the General category in the popup menu at the top.  Type the "
"following text in the entry box labeled :guilabel:`Additional Include "
"Directories`::"
msgstr ""

#: ../src/Doc/extending/windows.rst:151
msgid "Then, choose the General category in the Linker tab, and enter ::"
msgstr ""

#: ../src/Doc/extending/windows.rst:155
msgid "in the text box labelled :guilabel:`Additional library Directories`."
msgstr ""

#: ../src/Doc/extending/windows.rst:157
msgid "Now you need to add some mode-specific settings:"
msgstr ""

#: ../src/Doc/extending/windows.rst:159
msgid ""
"Select :guilabel:`Release` in the :guilabel:`Configuration` dropdown list. "
"Choose the :guilabel:`Link` tab, choose the :guilabel:`Input` category, and "
"append ``pythonXY.lib`` to the list in the :guilabel:`Additional "
"Dependencies` box."
msgstr ""

#: ../src/Doc/extending/windows.rst:164
msgid ""
"Select :guilabel:`Debug` in the :guilabel:`Configuration` dropdown list, and "
"append ``pythonXY_d.lib`` to the list in the :guilabel:`Additional "
"Dependencies` box.  Then click the C/C++ tab, select :guilabel:`Code "
"Generation`, and select :guilabel:`Multi-threaded Debug DLL` from the :"
"guilabel:`Runtime library` dropdown list."
msgstr ""

#: ../src/Doc/extending/windows.rst:170
msgid ""
"Select :guilabel:`Release` again from the :guilabel:`Configuration` dropdown "
"list.  Select :guilabel:`Multi-threaded DLL` from the :guilabel:`Runtime "
"library` dropdown list."
msgstr ""

#: ../src/Doc/extending/windows.rst:174
msgid ""
"If your module creates a new type, you may have trouble with this line::"
msgstr ""

# ed7368577eba4616bdd2da116eb64bbe
#: ../src/Doc/extending/windows.rst:178
msgid ""
"Static type object initializers in extension modules may cause compiles to "
"fail with an error message like \"initializer not a constant\".  This shows "
"up when building DLL under MSVC.  Change it to::"
msgstr ""

#: ../src/Doc/extending/windows.rst:184
msgid "and add the following to the module initialization function::"
msgstr ""

#: ../src/Doc/extending/windows.rst:193
msgid "Differences Between Unix and Windows"
msgstr ""

#: ../src/Doc/extending/windows.rst:198
msgid ""
"Unix and Windows use completely different paradigms for run-time loading of "
"code.  Before you try to build a module that can be dynamically loaded, be "
"aware of how your system works."
msgstr ""

#: ../src/Doc/extending/windows.rst:202
msgid ""
"In Unix, a shared object (:file:`.so`) file contains code to be used by the "
"program, and also the names of functions and data that it expects to find in "
"the program.  When the file is joined to the program, all references to "
"those functions and data in the file's code are changed to point to the "
"actual locations in the program where the functions and data are placed in "
"memory. This is basically a link operation."
msgstr ""

#: ../src/Doc/extending/windows.rst:209
msgid ""
"In Windows, a dynamic-link library (:file:`.dll`) file has no dangling "
"references.  Instead, an access to functions or data goes through a lookup "
"table.  So the DLL code does not have to be fixed up at runtime to refer to "
"the program's memory; instead, the code already uses the DLL's lookup table, "
"and the lookup table is modified at runtime to point to the functions and "
"data."
msgstr ""

#: ../src/Doc/extending/windows.rst:215
msgid ""
"In Unix, there is only one type of library file (:file:`.a`) which contains "
"code from several object files (:file:`.o`).  During the link step to create "
"a shared object file (:file:`.so`), the linker may find that it doesn't know "
"where an identifier is defined.  The linker will look for it in the object "
"files in the libraries; if it finds it, it will include all the code from "
"that object file."
msgstr ""

#: ../src/Doc/extending/windows.rst:221
msgid ""
"In Windows, there are two types of library, a static library and an import "
"library (both called :file:`.lib`).  A static library is like a Unix :file:`."
"a` file; it contains code to be included as necessary. An import library is "
"basically used only to reassure the linker that a certain identifier is "
"legal, and will be present in the program when the DLL is loaded.  So the "
"linker uses the information from the import library to build the lookup "
"table for using identifiers that are not included in the DLL.  When an "
"application or a DLL is linked, an import library may be generated, which "
"will need to be used for all future DLLs that depend on the symbols in the "
"application or DLL."
msgstr ""

#: ../src/Doc/extending/windows.rst:231
msgid ""
"Suppose you are building two dynamic-load modules, B and C, which should "
"share another block of code A.  On Unix, you would *not* pass :file:`A.a` to "
"the linker for :file:`B.so` and :file:`C.so`; that would cause it to be "
"included twice, so that B and C would each have their own copy.  In Windows, "
"building :file:`A.dll` will also build :file:`A.lib`.  You *do* pass :file:"
"`A.lib` to the linker for B and C.  :file:`A.lib` does not contain code; it "
"just contains information which will be used at runtime to access A's code."
msgstr ""

#: ../src/Doc/extending/windows.rst:239
msgid ""
"In Windows, using an import library is sort of like using ``import spam``; "
"it gives you access to spam's names, but does not create a separate copy.  "
"On Unix, linking with a library is more like ``from spam import *``; it does "
"create a separate copy."
msgstr ""

#: ../src/Doc/extending/windows.rst:248
msgid "Using DLLs in Practice"
msgstr ""

#: ../src/Doc/extending/windows.rst:253
msgid ""
"Windows Python is built in Microsoft Visual C++; using other compilers may "
"or may not work (though Borland seems to).  The rest of this section is MSVC+"
"+ specific."
msgstr ""

#: ../src/Doc/extending/windows.rst:257
msgid ""
"When creating DLLs in Windows, you must pass :file:`pythonXY.lib` to the "
"linker. To build two DLLs, spam and ni (which uses C functions found in "
"spam), you could use these commands::"
msgstr ""

# 6b85f7fe52bc4ec5a6b35fd14a4e80a1
#: ../src/Doc/extending/windows.rst:264
msgid ""
"The first command created three files: :file:`spam.obj`, :file:`spam.dll` "
"and :file:`spam.lib`.  :file:`Spam.dll` does not contain any Python "
"functions (such as :c:func:`PyArg_ParseTuple`), but it does know how to find "
"the Python code thanks to :file:`pythonXY.lib`."
msgstr ""

#: ../src/Doc/extending/windows.rst:269
msgid ""
"The second command created :file:`ni.dll` (and :file:`.obj` and :file:`."
"lib`), which knows how to find the necessary functions from spam, and also "
"from the Python executable."
msgstr ""

#: ../src/Doc/extending/windows.rst:273
msgid ""
"Not every identifier is exported to the lookup table.  If you want any other "
"modules (including Python) to be able to see your identifiers, you have to "
"say ``_declspec(dllexport)``, as in ``void _declspec(dllexport) initspam"
"(void)`` or ``PyObject _declspec(dllexport) *NiGetSpamData(void)``."
msgstr ""

#: ../src/Doc/extending/windows.rst:278
msgid ""
"Developer Studio will throw in a lot of import libraries that you do not "
"really need, adding about 100K to your executable.  To get rid of them, use "
"the Project Settings dialog, Link tab, to specify *ignore default "
"libraries*.  Add the correct :file:`msvcrtxx.lib` to the list of libraries."
msgstr ""

#~ msgid "python setup.py build"
#~ msgstr "python setup.py build"

#~ msgid "python setup.py install"
#~ msgstr "python setup.py install"

#~ msgid "python setup.py sdist"
#~ msgstr "python setup.py sdist"

#~ msgid "See also"
#~ msgstr "Voir aussi"

#~ msgid ""
#~ "#include <Python.h>  int main(int argc, char *argv[]) {     PyObject "
#~ "*pName, *pModule, *pDict, *pFunc;     PyObject *pArgs, *pValue;     int "
#~ "i;      if (argc < 3) {         fprintf(stderr,\"Usage: call pythonfile "
#~ "funcname [args]\\n\");         return 1;     }      Py_Initialize();     "
#~ "pName = PyUnicode_FromString(argv[1]);     /* Error checking of pName "
#~ "left out */      pModule = PyImport_Import(pName);     Py_DECREF"
#~ "(pName);      if (pModule != NULL) {         pFunc = "
#~ "PyObject_GetAttrString(pModule, argv[2]);         /* pFunc is a new "
#~ "reference */          if (pFunc && PyCallable_Check(pFunc)) "
#~ "{             pArgs = PyTuple_New(argc - 3);             for (i = 0; i < "
#~ "argc - 3; ++i) {                 pValue = PyLong_FromLong(atoi(argv[i + "
#~ "3]));                 if (!pValue) {                     Py_DECREF"
#~ "(pArgs);                     Py_DECREF(pModule);                     "
#~ "fprintf(stderr, \"Cannot convert argument\\n\");                     "
#~ "return 1;                 }                 /* pValue reference stolen "
#~ "here: */                 PyTuple_SetItem(pArgs, i, "
#~ "pValue);             }             pValue = PyObject_CallObject(pFunc, "
#~ "pArgs);             Py_DECREF(pArgs);             if (pValue != NULL) "
#~ "{                 printf(\"Result of call: %ld\\n\", PyLong_AsLong"
#~ "(pValue));                 Py_DECREF(pValue);             }             "
#~ "else {                 Py_DECREF(pFunc);                 Py_DECREF"
#~ "(pModule);                 PyErr_Print();                 fprintf(stderr,"
#~ "\"Call failed\\n\");                 return "
#~ "1;             }         }         else {             if (PyErr_Occurred"
#~ "())                 PyErr_Print();             fprintf(stderr, \"Cannot "
#~ "find function \\\"%s\\\"\\n\", argv[2]);         }         Py_XDECREF"
#~ "(pFunc);         Py_DECREF(pModule);     }     else {         PyErr_Print"
#~ "();         fprintf(stderr, \"Failed to load \\\"%s\\\"\\n\", argv"
#~ "[1]);         return 1;     }     Py_Finalize();     return 0; }"
#~ msgstr ""
#~ "#include <Python.h>  int main(int argc, char *argv[]) { PyObject *pName, "
#~ "*pModule, *pDict, *pFunc; PyObject *pArgs, *pValue; int i; if (argc < 3) "
#~ "{ fprintf(stderr,\"Usage: call pythonfile funcname [args]\n"
#~ "\"); return 1; } Py_Initialize(); pName = PyUnicode_FromString(argv[1]); /"
#~ "* Error checking of pName left out */ pModule = PyImport_Import(pName); "
#~ "Py_DECREF(pName); if (pModule != NULL) { pFunc = PyObject_GetAttrString"
#~ "(pModule, argv[2]); /* pFunc is a new reference */ if (pFunc && "
#~ "PyCallable_Check(pFunc)) { pArgs = PyTuple_New(argc - 3); for (i = 0; i "
#~ "<  argc - 3; ++i) { pValue = PyLong_FromLong(atoi(argv[i + 3])); if (!"
#~ "pValue) { Py_DECREF(pArgs); Py_DECREF(pModule); fprintf(stderr, \"Cannot "
#~ "convert argument\n"
#~ "\"); return 1; } /* pValue reference stolen here: */ PyTuple_SetItem"
#~ "(pArgs, i, pValue); } pValue = PyObject_CallObject(pFunc, pArgs); "
#~ "Py_DECREF(pArgs); if (pValue != NULL) { printf(\"Result of call: %ld\n"
#~ "\", PyLong_AsLong(pValue)); Py_DECREF(pValue); } else { Py_DECREF(pFunc); "
#~ "Py_DECREF(pModule); PyErr_Print(); fprintf(stderr,\"Call failed\n"
#~ "\"); return 1; } } else { if (PyErr_Occurred()) PyErr_Print(); fprintf"
#~ "(stderr, \"Cannot find function \\\"%s\\\"\n"
#~ "\", argv[2]); } Py_XDECREF(pFunc); Py_DECREF(pModule); } else "
#~ "{ PyErr_Print(); fprintf(stderr, \"Failed to load \\\"%s\\\"\n"
#~ "\", argv[1]); return 1; } Py_Finalize(); return 0; }"

#~ msgid "pValue = PyObject_CallObject(pFunc, pArgs);"
#~ msgstr "pValue = PyObject_CallObject(pFunc, pArgs);"

#, fuzzy
#~ msgid ">>> import spam >>> status = spam.system(\"ls -l\")"
#~ msgstr ">>> import spam >>> status = spam.system(\"ls -l\")"

#~ msgid "#include <Python.h>"
#~ msgstr "#include <Python.h>"