forked from AFPy/python-docs-fr
642 lines
28 KiB
Plaintext
642 lines
28 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2001-2016, 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: Python 3.6\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"POT-Creation-Date: 2016-10-30 10:40+0100\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"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: ../Doc/c-api/intro.rst:8
|
|
msgid "Introduction"
|
|
msgstr "Introduction"
|
|
|
|
#: ../Doc/c-api/intro.rst:10
|
|
msgid ""
|
|
"The Application Programmer's Interface to Python gives C and C++ programmers "
|
|
"access to the Python interpreter at a variety of levels. The API is equally "
|
|
"usable from C++, but for brevity it is generally referred to as the Python/C "
|
|
"API. There are two fundamentally different reasons for using the Python/C "
|
|
"API. The first reason is to write *extension modules* for specific purposes; "
|
|
"these are C modules that extend the Python interpreter. This is probably "
|
|
"the most common use. The second reason is to use Python as a component in a "
|
|
"larger application; this technique is generally referred to as :dfn:"
|
|
"`embedding` Python in an application."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:20
|
|
msgid ""
|
|
"Writing an extension module is a relatively well-understood process, where "
|
|
"a \"cookbook\" approach works well. There are several tools that automate "
|
|
"the process to some extent. While people have embedded Python in other "
|
|
"applications since its early existence, the process of embedding Python is "
|
|
"less straightforward than writing an extension."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:26
|
|
msgid ""
|
|
"Many API functions are useful independent of whether you're embedding or "
|
|
"extending Python; moreover, most applications that embed Python will need "
|
|
"to provide a custom extension as well, so it's probably a good idea to "
|
|
"become familiar with writing an extension before attempting to embed Python "
|
|
"in a real application."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:36
|
|
msgid "Include Files"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:38
|
|
msgid ""
|
|
"All function, type and macro definitions needed to use the Python/C API are "
|
|
"included in your code by the following line::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:43
|
|
msgid ""
|
|
"This implies inclusion of the following standard headers: ``<stdio.h>``, "
|
|
"``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib."
|
|
"h>`` (if available)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:49
|
|
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 ""
|
|
"Python pouvant définir certaines définitions pré-processeur qui affectent "
|
|
"les têtes standard sur certains systèmes, vous *devez* inclure :file:`Python."
|
|
"h` avant les en-têtes standards."
|
|
|
|
#: ../Doc/c-api/intro.rst:53
|
|
msgid ""
|
|
"All user visible names defined by Python.h (except those defined by the "
|
|
"included standard headers) have one of the prefixes ``Py`` or ``_Py``. "
|
|
"Names beginning with ``_Py`` are for internal use by the Python "
|
|
"implementation and should not be used by extension writers. Structure member "
|
|
"names do not have a reserved prefix."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:58
|
|
msgid ""
|
|
"**Important:** user code should never define names that begin with ``Py`` or "
|
|
"``_Py``. This confuses the reader, and jeopardizes the portability of the "
|
|
"user code to future Python versions, which may define additional names "
|
|
"beginning with one of these prefixes."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:63
|
|
msgid ""
|
|
"The header files are typically installed with Python. On Unix, these are "
|
|
"located in the directories :file:`{prefix}/include/pythonversion/` and :file:"
|
|
"`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and :envvar:"
|
|
"`exec_prefix` are defined by the corresponding parameters to Python's :"
|
|
"program:`configure` script and *version* is ``'%d.%d' % sys."
|
|
"version_info[:2]``. On Windows, the headers are installed in :file:"
|
|
"`{prefix}/include`, where :envvar:`prefix` is the installation directory "
|
|
"specified to the installer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:72
|
|
msgid ""
|
|
"To include the headers, place both directories (if different) on your "
|
|
"compiler's search path for includes. Do *not* place the parent directories "
|
|
"on the search path and then use ``#include <pythonX.Y/Python.h>``; this will "
|
|
"break on multi-platform builds since the platform independent headers under :"
|
|
"envvar:`prefix` include the platform specific headers from :envvar:"
|
|
"`exec_prefix`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:79
|
|
msgid ""
|
|
"C++ users should note that though the API is defined entirely using C, the "
|
|
"header files do properly declare the entry points to be ``extern \"C\"``, so "
|
|
"there is no need to do anything special to use the API from C++."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:87
|
|
msgid "Objects, Types and Reference Counts"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:91
|
|
msgid ""
|
|
"Most Python/C API functions have one or more arguments as well as a return "
|
|
"value of type :c:type:`PyObject\\*`. This type is a pointer to an opaque "
|
|
"data type representing an arbitrary Python object. Since all Python object "
|
|
"types are treated the same way by the Python language in most situations (e."
|
|
"g., assignments, scope rules, and argument passing), it is only fitting that "
|
|
"they should be represented by a single C type. Almost all Python objects "
|
|
"live on the heap: you never declare an automatic or static variable of type :"
|
|
"c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\\*` can "
|
|
"be declared. The sole exception are the type objects; since these must "
|
|
"never be deallocated, they are typically static :c:type:`PyTypeObject` "
|
|
"objects."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:102
|
|
msgid ""
|
|
"All Python objects (even Python integers) have a :dfn:`type` and a :dfn:"
|
|
"`reference count`. An object's type determines what kind of object it is (e."
|
|
"g., an integer, a list, or a user-defined function; there are many more as "
|
|
"explained in :ref:`types`). For each of the well-known types there is a "
|
|
"macro to check whether an object is of that type; for instance, "
|
|
"``PyList_Check(a)`` is true if (and only if) the object pointed to by *a* is "
|
|
"a Python list."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:113
|
|
msgid "Reference Counts"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:115
|
|
msgid ""
|
|
"The reference count is important because today's computers have a finite "
|
|
"(and often severely limited) memory size; it counts how many different "
|
|
"places there are that have a reference to an object. Such a place could be "
|
|
"another object, or a global (or static) C variable, or a local variable in "
|
|
"some C function. When an object's reference count becomes zero, the object "
|
|
"is deallocated. If it contains references to other objects, their "
|
|
"reference count is decremented. Those other objects may be deallocated in "
|
|
"turn, if this decrement makes their reference count become zero, and so on. "
|
|
"(There's an obvious problem with objects that reference each other here; "
|
|
"for now, the solution is \"don't do that.\")"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:130
|
|
msgid ""
|
|
"Reference counts are always manipulated explicitly. The normal way is to "
|
|
"use the macro :c:func:`Py_INCREF` to increment an object's reference count "
|
|
"by one, and :c:func:`Py_DECREF` to decrement it by one. The :c:func:"
|
|
"`Py_DECREF` macro is considerably more complex than the incref one, since it "
|
|
"must check whether the reference count becomes zero and then cause the "
|
|
"object's deallocator to be called. The deallocator is a function pointer "
|
|
"contained in the object's type structure. The type-specific deallocator "
|
|
"takes care of decrementing the reference counts for other objects contained "
|
|
"in the object if this is a compound object type, such as a list, as well as "
|
|
"performing any additional finalization that's needed. There's no chance "
|
|
"that the reference count can overflow; at least as many bits are used to "
|
|
"hold the reference count as there are distinct memory locations in virtual "
|
|
"memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``). Thus, the "
|
|
"reference count increment is a simple operation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:144
|
|
msgid ""
|
|
"It is not necessary to increment an object's reference count for every "
|
|
"local variable that contains a pointer to an object. In theory, the "
|
|
"object's reference count goes up by one when the variable is made to point "
|
|
"to it and it goes down by one when the variable goes out of scope. "
|
|
"However, these two cancel each other out, so at the end the reference count "
|
|
"hasn't changed. The only real reason to use the reference count is to "
|
|
"prevent the object from being deallocated as long as our variable is "
|
|
"pointing to it. If we know that there is at least one other reference to "
|
|
"the object that lives at least as long as our variable, there is no need to "
|
|
"increment the reference count temporarily. An important situation where "
|
|
"this arises is in objects that are passed as arguments to C functions in an "
|
|
"extension module that are called from Python; the call mechanism guarantees "
|
|
"to hold a reference to every argument for the duration of the call."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:158
|
|
msgid ""
|
|
"However, a common pitfall is to extract an object from a list and hold on to "
|
|
"it for a while without incrementing its reference count. Some other "
|
|
"operation might conceivably remove the object from the list, decrementing "
|
|
"its reference count and possible deallocating it. The real danger is that "
|
|
"innocent-looking operations may invoke arbitrary Python code which could do "
|
|
"this; there is a code path which allows control to flow back to the user "
|
|
"from a :c:func:`Py_DECREF`, so almost any operation is potentially dangerous."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:166
|
|
msgid ""
|
|
"A safe approach is to always use the generic operations (functions whose "
|
|
"name begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or "
|
|
"``PyMapping_``). These operations always increment the reference count of "
|
|
"the object they return. This leaves the caller with the responsibility to "
|
|
"call :c:func:`Py_DECREF` when they are done with the result; this soon "
|
|
"becomes second nature."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:176
|
|
msgid "Reference Count Details"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:178
|
|
msgid ""
|
|
"The reference count behavior of functions in the Python/C API is best "
|
|
"explained in terms of *ownership of references*. Ownership pertains to "
|
|
"references, never to objects (objects are not owned: they are always "
|
|
"shared). \"Owning a reference\" means being responsible for calling "
|
|
"Py_DECREF on it when the reference is no longer needed. Ownership can also "
|
|
"be transferred, meaning that the code that receives ownership of the "
|
|
"reference then becomes responsible for eventually decref'ing it by calling :"
|
|
"c:func:`Py_DECREF` or :c:func:`Py_XDECREF` when it's no longer needed---or "
|
|
"passing on this responsibility (usually to its caller). When a function "
|
|
"passes ownership of a reference on to its caller, the caller is said to "
|
|
"receive a *new* reference. When no ownership is transferred, the caller is "
|
|
"said to *borrow* the reference. Nothing needs to be done for a borrowed "
|
|
"reference."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:191
|
|
msgid ""
|
|
"Conversely, when a calling function passes in a reference to an object, "
|
|
"there are two possibilities: the function *steals* a reference to the "
|
|
"object, or it does not. *Stealing a reference* means that when you pass a "
|
|
"reference to a function, that function assumes that it now owns that "
|
|
"reference, and you are not responsible for it any longer."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:201
|
|
msgid ""
|
|
"Few functions steal references; the two notable exceptions are :c:func:"
|
|
"`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which steal a reference to "
|
|
"the item (but not to the tuple or list into which the item is put!). These "
|
|
"functions were designed to steal a reference because of a common idiom for "
|
|
"populating a tuple or list with newly created objects; for example, the code "
|
|
"to create the tuple ``(1, 2, \"three\")`` could look like this (forgetting "
|
|
"about error handling for the moment; a better way to code this is shown "
|
|
"below)::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:216
|
|
msgid ""
|
|
"Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately "
|
|
"stolen by :c:func:`PyTuple_SetItem`. When you want to keep using an object "
|
|
"although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab "
|
|
"another reference before calling the reference-stealing function."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:221
|
|
msgid ""
|
|
"Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple "
|
|
"items; :c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to "
|
|
"do this since tuples are an immutable data type. You should only use :c:"
|
|
"func:`PyTuple_SetItem` for tuples that you are creating yourself."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:226
|
|
msgid ""
|
|
"Equivalent code for populating a list can be written using :c:func:"
|
|
"`PyList_New` and :c:func:`PyList_SetItem`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:229
|
|
msgid ""
|
|
"However, in practice, you will rarely use these ways of creating and "
|
|
"populating a tuple or list. There's a generic function, :c:func:"
|
|
"`Py_BuildValue`, that can create most common objects from C values, directed "
|
|
"by a :dfn:`format string`. For example, the above two blocks of code could "
|
|
"be replaced by the following (which also takes care of the error checking)::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:240
|
|
msgid ""
|
|
"It is much more common to use :c:func:`PyObject_SetItem` and friends with "
|
|
"items whose references you are only borrowing, like arguments that were "
|
|
"passed in to the function you are writing. In that case, their behaviour "
|
|
"regarding reference counts is much saner, since you don't have to increment "
|
|
"a reference count so you can give a reference away (\"have it be stolen\"). "
|
|
"For example, this function sets all items of a list (actually, any mutable "
|
|
"sequence) to a given item::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:270
|
|
msgid ""
|
|
"The situation is slightly different for function return values. While "
|
|
"passing a reference to most functions does not change your ownership "
|
|
"responsibilities for that reference, many functions that return a reference "
|
|
"to an object give you ownership of the reference. The reason is simple: in "
|
|
"many cases, the returned object is created on the fly, and the reference "
|
|
"you get is the only reference to the object. Therefore, the generic "
|
|
"functions that return object references, like :c:func:`PyObject_GetItem` "
|
|
"and :c:func:`PySequence_GetItem`, always return a new reference (the caller "
|
|
"becomes the owner of the reference)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:279
|
|
msgid ""
|
|
"It is important to realize that whether you own a reference returned by a "
|
|
"function depends on which function you call only --- *the plumage* (the type "
|
|
"of the object passed as an argument to the function) *doesn't enter into it!"
|
|
"* Thus, if you extract an item from a list using :c:func:`PyList_GetItem`, "
|
|
"you don't own the reference --- but if you obtain the same item from the "
|
|
"same list using :c:func:`PySequence_GetItem` (which happens to take exactly "
|
|
"the same arguments), you do own a reference to the returned object."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:291
|
|
msgid ""
|
|
"Here is an example of how you could write a function that computes the sum "
|
|
"of the items in a list of integers; once using :c:func:`PyList_GetItem`, "
|
|
"and once using :c:func:`PySequence_GetItem`. ::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:355
|
|
msgid "Types"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:357
|
|
msgid ""
|
|
"There are few other data types that play a significant role in the Python/C "
|
|
"API; most are simple C types such as :c:type:`int`, :c:type:`long`, :c:type:"
|
|
"`double` and :c:type:`char\\*`. A few structure types are used to describe "
|
|
"static tables used to list the functions exported by a module or the data "
|
|
"attributes of a new object type, and another is used to describe the value "
|
|
"of a complex number. These will be discussed together with the functions "
|
|
"that use them."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:369
|
|
msgid "Exceptions"
|
|
msgstr "Les exceptions"
|
|
|
|
#: ../Doc/c-api/intro.rst:371
|
|
msgid ""
|
|
"The Python programmer only needs to deal with exceptions if specific error "
|
|
"handling is required; unhandled exceptions are automatically propagated to "
|
|
"the caller, then to the caller's caller, and so on, until they reach the top-"
|
|
"level interpreter, where they are reported to the user accompanied by a "
|
|
"stack traceback."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:379
|
|
msgid ""
|
|
"For C programmers, however, error checking always has to be explicit. All "
|
|
"functions in the Python/C API can raise exceptions, unless an explicit claim "
|
|
"is made otherwise in a function's documentation. In general, when a "
|
|
"function encounters an error, it sets an exception, discards any object "
|
|
"references that it owns, and returns an error indicator. If not documented "
|
|
"otherwise, this indicator is either *NULL* or ``-1``, depending on the "
|
|
"function's return type. A few functions return a Boolean true/false result, "
|
|
"with false indicating an error. Very few functions return no explicit error "
|
|
"indicator or have an ambiguous return value, and require explicit testing "
|
|
"for errors with :c:func:`PyErr_Occurred`. These exceptions are always "
|
|
"explicitly documented."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:394
|
|
msgid ""
|
|
"Exception state is maintained in per-thread storage (this is equivalent to "
|
|
"using global storage in an unthreaded application). A thread can be in one "
|
|
"of two states: an exception has occurred, or not. The function :c:func:"
|
|
"`PyErr_Occurred` can be used to check for this: it returns a borrowed "
|
|
"reference to the exception type object when an exception has occurred, and "
|
|
"*NULL* otherwise. There are a number of functions to set the exception "
|
|
"state: :c:func:`PyErr_SetString` is the most common (though not the most "
|
|
"general) function to set the exception state, and :c:func:`PyErr_Clear` "
|
|
"clears the exception state."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:404
|
|
msgid ""
|
|
"The full exception state consists of three objects (all of which can be "
|
|
"*NULL*): the exception type, the corresponding exception value, and the "
|
|
"traceback. These have the same meanings as the Python result of ``sys."
|
|
"exc_info()``; however, they are not the same: the Python objects represent "
|
|
"the last exception being handled by a Python :keyword:`try` ... :keyword:"
|
|
"`except` statement, while the C level exception state only exists while an "
|
|
"exception is being passed on between C functions until it reaches the Python "
|
|
"bytecode interpreter's main loop, which takes care of transferring it to "
|
|
"``sys.exc_info()`` and friends."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:416
|
|
msgid ""
|
|
"Note that starting with Python 1.5, the preferred, thread-safe way to access "
|
|
"the exception state from Python code is to call the function :func:`sys."
|
|
"exc_info`, which returns the per-thread exception state for Python code. "
|
|
"Also, the semantics of both ways to access the exception state have changed "
|
|
"so that a function which catches an exception will save and restore its "
|
|
"thread's exception state so as to preserve the exception state of its "
|
|
"caller. This prevents common bugs in exception handling code caused by an "
|
|
"innocent-looking function overwriting the exception being handled; it also "
|
|
"reduces the often unwanted lifetime extension for objects that are "
|
|
"referenced by the stack frames in the traceback."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:427
|
|
msgid ""
|
|
"As a general principle, a function that calls another function to perform "
|
|
"some task should check whether the called function raised an exception, and "
|
|
"if so, pass the exception state on to its caller. It should discard any "
|
|
"object references that it owns, and return an error indicator, but it "
|
|
"should *not* set another exception --- that would overwrite the exception "
|
|
"that was just raised, and lose important information about the exact cause "
|
|
"of the error."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:436
|
|
msgid ""
|
|
"A simple example of detecting exceptions and passing them on is shown in "
|
|
"the :c:func:`sum_sequence` example above. It so happens that this example "
|
|
"doesn't need to clean up any owned references when it detects an error. The "
|
|
"following example function shows some error cleanup. First, to remind you "
|
|
"why you like Python, we show the equivalent Python code::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:451
|
|
msgid "Here is the corresponding C code, in all its glory::"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:503
|
|
msgid ""
|
|
"This example represents an endorsed use of the ``goto`` statement in C! It "
|
|
"illustrates the use of :c:func:`PyErr_ExceptionMatches` and :c:func:"
|
|
"`PyErr_Clear` to handle specific exceptions, and the use of :c:func:"
|
|
"`Py_XDECREF` to dispose of owned references that may be *NULL* (note the "
|
|
"``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a "
|
|
"*NULL* reference). It is important that the variables used to hold owned "
|
|
"references are initialized to *NULL* for this to work; likewise, the "
|
|
"proposed return value is initialized to ``-1`` (failure) and only set to "
|
|
"success after the final call made is successful."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:517
|
|
msgid "Embedding Python"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:519
|
|
msgid ""
|
|
"The one important task that only embedders (as opposed to extension writers) "
|
|
"of the Python interpreter have to worry about is the initialization, and "
|
|
"possibly the finalization, of the Python interpreter. Most functionality of "
|
|
"the interpreter can only be used after the interpreter has been initialized."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:532
|
|
msgid ""
|
|
"The basic initialization function is :c:func:`Py_Initialize`. This "
|
|
"initializes the table of loaded modules, and creates the fundamental "
|
|
"modules :mod:`builtins`, :mod:`__main__`, and :mod:`sys`. It also "
|
|
"initializes the module search path (``sys.path``)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:539
|
|
msgid ""
|
|
":c:func:`Py_Initialize` does not set the \"script argument list\" (``sys."
|
|
"argv``). If this variable is needed by Python code that will be executed "
|
|
"later, it must be set explicitly with a call to ``PySys_SetArgvEx(argc, "
|
|
"argv, updatepath)`` after the call to :c:func:`Py_Initialize`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:544
|
|
msgid ""
|
|
"On most systems (in particular, on Unix and Windows, although the details "
|
|
"are slightly different), :c:func:`Py_Initialize` calculates the module "
|
|
"search path based upon its best guess for the location of the standard "
|
|
"Python interpreter executable, assuming that the Python library is found in "
|
|
"a fixed location relative to the Python interpreter executable. In "
|
|
"particular, it looks for a directory named :file:`lib/python{X.Y}` relative "
|
|
"to the parent directory where the executable named :file:`python` is found "
|
|
"on the shell command search path (the environment variable :envvar:`PATH`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:553
|
|
msgid ""
|
|
"For instance, if the Python executable is found in :file:`/usr/local/bin/"
|
|
"python`, it will assume that the libraries are in :file:`/usr/local/lib/"
|
|
"python{X.Y}`. (In fact, this particular path is also the \"fallback\" "
|
|
"location, used when no executable file named :file:`python` is found along :"
|
|
"envvar:`PATH`.) The user can override this behavior by setting the "
|
|
"environment variable :envvar:`PYTHONHOME`, or insert additional directories "
|
|
"in front of the standard path by setting :envvar:`PYTHONPATH`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:568
|
|
msgid ""
|
|
"The embedding application can steer the search by calling "
|
|
"``Py_SetProgramName(file)`` *before* calling :c:func:`Py_Initialize`. Note "
|
|
"that :envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is "
|
|
"still inserted in front of the standard path. An application that requires "
|
|
"total control has to provide its own implementation of :c:func:"
|
|
"`Py_GetPath`, :c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and :c:"
|
|
"func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`)."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:578
|
|
msgid ""
|
|
"Sometimes, it is desirable to \"uninitialize\" Python. For instance, the "
|
|
"application may want to start over (make another call to :c:func:"
|
|
"`Py_Initialize`) or the application is simply done with its use of Python "
|
|
"and wants to free memory allocated by Python. This can be accomplished by "
|
|
"calling :c:func:`Py_FinalizeEx`. The function :c:func:`Py_IsInitialized` "
|
|
"returns true if Python is currently in the initialized state. More "
|
|
"information about these functions is given in a later chapter. Notice that :"
|
|
"c:func:`Py_FinalizeEx` does *not* free all memory allocated by the Python "
|
|
"interpreter, e.g. memory allocated by extension modules currently cannot be "
|
|
"released."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:592
|
|
msgid "Debugging Builds"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:594
|
|
msgid ""
|
|
"Python can be built with several macros to enable extra checks of the "
|
|
"interpreter and extension modules. These checks tend to add a large amount "
|
|
"of overhead to the runtime so they are not enabled by default."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:598
|
|
msgid ""
|
|
"A full list of the various types of debugging builds is in the file :file:"
|
|
"`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are "
|
|
"available that support tracing of reference counts, debugging the memory "
|
|
"allocator, or low-level profiling of the main interpreter loop. Only the "
|
|
"most frequently-used builds will be described in the remainder of this "
|
|
"section."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:604
|
|
msgid ""
|
|
"Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined "
|
|
"produces what is generally meant by \"a debug build\" of Python. :c:macro:"
|
|
"`Py_DEBUG` is enabled in the Unix build by adding ``--with-pydebug`` to the :"
|
|
"file:`./configure` command. It is also implied by the presence of the not-"
|
|
"Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is "
|
|
"enabled in the Unix build, compiler optimization is disabled."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:611
|
|
msgid ""
|
|
"In addition to the reference count debugging described below, the following "
|
|
"extra checks are performed:"
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:614
|
|
msgid "Extra checks are added to the object allocator."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:616
|
|
msgid "Extra checks are added to the parser and compiler."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:618
|
|
msgid ""
|
|
"Downcasts from wide types to narrow types are checked for loss of "
|
|
"information."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:620
|
|
msgid ""
|
|
"A number of assertions are added to the dictionary and set implementations. "
|
|
"In addition, the set object acquires a :meth:`test_c_api` method."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:623
|
|
msgid "Sanity checks of the input arguments are added to frame creation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:625
|
|
msgid ""
|
|
"The storage for ints is initialized with a known invalid pattern to catch "
|
|
"reference to uninitialized digits."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:628
|
|
msgid ""
|
|
"Low-level tracing and extra exception checking are added to the runtime "
|
|
"virtual machine."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:631
|
|
msgid "Extra checks are added to the memory arena implementation."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:633
|
|
msgid "Extra debugging is added to the thread module."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:635
|
|
msgid "There may be additional checks not mentioned here."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:637
|
|
msgid ""
|
|
"Defining :c:macro:`Py_TRACE_REFS` enables reference tracing. When defined, "
|
|
"a circular doubly linked list of active objects is maintained by adding two "
|
|
"extra fields to every :c:type:`PyObject`. Total allocations are tracked as "
|
|
"well. Upon exit, all existing references are printed. (In interactive mode "
|
|
"this happens after every statement run by the interpreter.) Implied by :c:"
|
|
"macro:`Py_DEBUG`."
|
|
msgstr ""
|
|
|
|
#: ../Doc/c-api/intro.rst:643
|
|
msgid ""
|
|
"Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source "
|
|
"distribution for more detailed information."
|
|
msgstr ""
|