# Copyright (C) 2001-2018, Python Software Foundation # For licence information, see README file. # msgid "" msgstr "" "Project-Id-Version: Python 3\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2020-08-24 09:01+0200\n" "PO-Revision-Date: 2018-11-29 18:22+0100\n" "Last-Translator: FULL NAME \n" "Language-Team: FRENCH \n" "Language: fr\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" #: c-api/init.rst:8 msgid "Initialization, Finalization, and Threads" msgstr "" #: c-api/init.rst:10 msgid "See also :ref:`Python Initialization Configuration `." msgstr "" #: c-api/init.rst:15 msgid "Before Python Initialization" msgstr "" #: c-api/init.rst:17 msgid "" "In an application embedding Python, the :c:func:`Py_Initialize` function " "must be called before using any other Python/C API functions; with the " "exception of a few functions and the :ref:`global configuration variables " "`." msgstr "" #: c-api/init.rst:22 msgid "" "The following functions can be safely called before Python is initialized:" msgstr "" #: c-api/init.rst:24 msgid "Configuration functions:" msgstr "" #: c-api/init.rst:26 msgid ":c:func:`PyImport_AppendInittab`" msgstr "" #: c-api/init.rst:27 msgid ":c:func:`PyImport_ExtendInittab`" msgstr "" #: c-api/init.rst:28 msgid ":c:func:`PyInitFrozenExtensions`" msgstr "" #: c-api/init.rst:29 msgid ":c:func:`PyMem_SetAllocator`" msgstr "" #: c-api/init.rst:30 msgid ":c:func:`PyMem_SetupDebugHooks`" msgstr "" #: c-api/init.rst:31 msgid ":c:func:`PyObject_SetArenaAllocator`" msgstr "" #: c-api/init.rst:32 msgid ":c:func:`Py_SetPath`" msgstr "" #: c-api/init.rst:33 msgid ":c:func:`Py_SetProgramName`" msgstr "" #: c-api/init.rst:34 msgid ":c:func:`Py_SetPythonHome`" msgstr "" #: c-api/init.rst:35 msgid ":c:func:`Py_SetStandardStreamEncoding`" msgstr "" #: c-api/init.rst:36 msgid ":c:func:`PySys_AddWarnOption`" msgstr "" #: c-api/init.rst:37 msgid ":c:func:`PySys_AddXOption`" msgstr "" #: c-api/init.rst:38 msgid ":c:func:`PySys_ResetWarnOptions`" msgstr "" #: c-api/init.rst:40 msgid "Informative functions:" msgstr "" #: c-api/init.rst:42 msgid ":c:func:`Py_IsInitialized`" msgstr "" #: c-api/init.rst:43 msgid ":c:func:`PyMem_GetAllocator`" msgstr "" #: c-api/init.rst:44 msgid ":c:func:`PyObject_GetArenaAllocator`" msgstr "" #: c-api/init.rst:45 msgid ":c:func:`Py_GetBuildInfo`" msgstr "" #: c-api/init.rst:46 msgid ":c:func:`Py_GetCompiler`" msgstr "" #: c-api/init.rst:47 msgid ":c:func:`Py_GetCopyright`" msgstr "" #: c-api/init.rst:48 msgid ":c:func:`Py_GetPlatform`" msgstr "" #: c-api/init.rst:49 msgid ":c:func:`Py_GetVersion`" msgstr "" #: c-api/init.rst:51 #, fuzzy msgid "Utilities:" msgstr "Utilitaires" #: c-api/init.rst:53 msgid ":c:func:`Py_DecodeLocale`" msgstr "" #: c-api/init.rst:55 msgid "Memory allocators:" msgstr "" #: c-api/init.rst:57 #, fuzzy msgid ":c:func:`PyMem_RawMalloc`" msgstr ":c:func:`PyMem_RawCalloc`," #: c-api/init.rst:58 #, fuzzy msgid ":c:func:`PyMem_RawRealloc`" msgstr ":c:func:`PyMem_RawCalloc`," #: c-api/init.rst:59 #, fuzzy msgid ":c:func:`PyMem_RawCalloc`" msgstr ":c:func:`PyMem_RawCalloc`," #: c-api/init.rst:60 msgid ":c:func:`PyMem_RawFree`" msgstr "" #: c-api/init.rst:64 msgid "" "The following functions **should not be called** before :c:func:" "`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`, :c:func:" "`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, :c:func:" "`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`, :c:func:" "`Py_GetProgramName` and :c:func:`PyEval_InitThreads`." msgstr "" #: c-api/init.rst:74 msgid "Global configuration variables" msgstr "" #: c-api/init.rst:76 msgid "" "Python has variables for the global configuration to control different " "features and options. By default, these flags are controlled by :ref:" "`command line options `." msgstr "" #: c-api/init.rst:80 msgid "" "When a flag is set by an option, the value of the flag is the number of " "times that the option was set. For example, ``-b`` sets :c:data:" "`Py_BytesWarningFlag` to 1 and ``-bb`` sets :c:data:`Py_BytesWarningFlag` to " "2." msgstr "" #: c-api/init.rst:86 msgid "" "Issue a warning when comparing :class:`bytes` or :class:`bytearray` with :" "class:`str` or :class:`bytes` with :class:`int`. Issue an error if greater " "or equal to ``2``." msgstr "" #: c-api/init.rst:90 msgid "Set by the :option:`-b` option." msgstr "" #: c-api/init.rst:94 msgid "" "Turn on parser debugging output (for expert only, depending on compilation " "options)." msgstr "" #: c-api/init.rst:97 msgid "" "Set by the :option:`-d` option and the :envvar:`PYTHONDEBUG` environment " "variable." msgstr "" #: c-api/init.rst:102 msgid "" "If set to non-zero, Python won't try to write ``.pyc`` files on the import " "of source modules." msgstr "" #: c-api/init.rst:105 msgid "" "Set by the :option:`-B` option and the :envvar:`PYTHONDONTWRITEBYTECODE` " "environment variable." msgstr "" #: c-api/init.rst:110 msgid "" "Suppress error messages when calculating the module search path in :c:func:" "`Py_GetPath`." msgstr "" #: c-api/init.rst:113 msgid "Private flag used by ``_freeze_importlib`` and ``frozenmain`` programs." msgstr "" #: c-api/init.rst:117 msgid "" "Set to ``1`` if the :envvar:`PYTHONHASHSEED` environment variable is set to " "a non-empty string." msgstr "" #: c-api/init.rst:120 msgid "" "If the flag is non-zero, read the :envvar:`PYTHONHASHSEED` environment " "variable to initialize the secret hash seed." msgstr "" #: c-api/init.rst:125 msgid "" "Ignore all :envvar:`PYTHON*` environment variables, e.g. :envvar:" "`PYTHONPATH` and :envvar:`PYTHONHOME`, that might be set." msgstr "" "Ignore toutes les variables d'environnement :envvar:`PYTHON*` qui pourraient " "être définies. Par exemple, :envvar:`PYTHONPATH` et :envvar:`PYTHONHOME`." #: c-api/init.rst:128 msgid "Set by the :option:`-E` and :option:`-I` options." msgstr "" #: c-api/init.rst:132 msgid "" "When a script is passed as first argument or the :option:`-c` option is " "used, enter interactive mode after executing the script or the command, even " "when :data:`sys.stdin` does not appear to be a terminal." msgstr "" #: c-api/init.rst:136 msgid "" "Set by the :option:`-i` option and the :envvar:`PYTHONINSPECT` environment " "variable." msgstr "" #: c-api/init.rst:141 msgid "Set by the :option:`-i` option." msgstr "" #: c-api/init.rst:145 msgid "" "Run Python in isolated mode. In isolated mode :data:`sys.path` contains " "neither the script's directory nor the user's site-packages directory." msgstr "" #: c-api/init.rst:148 msgid "Set by the :option:`-I` option." msgstr "" #: c-api/init.rst:154 msgid "" "If the flag is non-zero, use the ``mbcs`` encoding instead of the UTF-8 " "encoding for the filesystem encoding." msgstr "" #: c-api/init.rst:157 msgid "" "Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` environment " "variable is set to a non-empty string." msgstr "" #: c-api/init.rst:160 msgid "See :pep:`529` for more details." msgstr "Voir la :pep:`529` pour plus d'informations." #: c-api/init.rst:162 c-api/init.rst:174 msgid ":ref:`Availability `: Windows." msgstr ":ref:`Disponibilité ` : Windows." #: c-api/init.rst:166 msgid "" "If the flag is non-zero, use :class:`io.FileIO` instead of :class:" "`WindowsConsoleIO` for :mod:`sys` standard streams." msgstr "" #: c-api/init.rst:169 msgid "" "Set to ``1`` if the :envvar:`PYTHONLEGACYWINDOWSSTDIO` environment variable " "is set to a non-empty string." msgstr "" #: c-api/init.rst:172 #, fuzzy msgid "See :pep:`528` for more details." msgstr "Voir la :pep:`529` pour plus d'informations." #: c-api/init.rst:178 msgid "" "Disable the import of the module :mod:`site` and the site-dependent " "manipulations of :data:`sys.path` that it entails. Also disable these " "manipulations if :mod:`site` is explicitly imported later (call :func:`site." "main` if you want them to be triggered)." msgstr "" "Désactive l’importation du module :mod:`site` et les modifications locales " "de :data:`sys.path` qu’il implique. Désactive aussi ces manipulations si :" "mod:`site` est importé explicitement plus tard (appelez :func:`site.main` si " "vous voulez les déclencher)." #: c-api/init.rst:183 msgid "Set by the :option:`-S` option." msgstr "" #: c-api/init.rst:187 msgid "" "Don't add the :data:`user site-packages directory ` to :data:" "`sys.path`." msgstr "" "N'ajoute pas le répertoire utilisateur :data:`site-packages ` à :data:`sys.path`." #: c-api/init.rst:190 msgid "" "Set by the :option:`-s` and :option:`-I` options, and the :envvar:" "`PYTHONNOUSERSITE` environment variable." msgstr "" #: c-api/init.rst:195 msgid "" "Set by the :option:`-O` option and the :envvar:`PYTHONOPTIMIZE` environment " "variable." msgstr "" #: c-api/init.rst:200 msgid "" "Don't display the copyright and version messages even in interactive mode." msgstr "N'affiche pas le copyright et la version, même en mode interactif." #: c-api/init.rst:202 msgid "Set by the :option:`-q` option." msgstr "" #: c-api/init.rst:208 msgid "Force the stdout and stderr streams to be unbuffered." msgstr "" #: c-api/init.rst:210 msgid "" "Set by the :option:`-u` option and the :envvar:`PYTHONUNBUFFERED` " "environment variable." msgstr "" #: c-api/init.rst:215 msgid "" "Print a message each time a module is initialized, showing the place " "(filename or built-in module) from which it is loaded. If greater or equal " "to ``2``, print a message for each file that is checked for when searching " "for a module. Also provides information on module cleanup at exit." msgstr "" #: c-api/init.rst:220 msgid "" "Set by the :option:`-v` option and the :envvar:`PYTHONVERBOSE` environment " "variable." msgstr "" #: c-api/init.rst:225 msgid "Initializing and finalizing the interpreter" msgstr "" #: c-api/init.rst:243 msgid "" "Initialize the Python interpreter. In an application embedding Python, " "this should be called before using any other Python/C API functions; see :" "ref:`Before Python Initialization ` for the few exceptions." msgstr "" #: c-api/init.rst:247 msgid "" "This initializes the table of loaded modules (``sys.modules``), and creates " "the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It " "also initializes the module search path (``sys.path``). It does not set " "``sys.argv``; use :c:func:`PySys_SetArgvEx` for that. This is a no-op when " "called for a second time (without calling :c:func:`Py_FinalizeEx` first). " "There is no return value; it is a fatal error if the initialization fails." msgstr "" #: c-api/init.rst:256 msgid "" "On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which " "will also affect non-Python uses of the console using the C Runtime." msgstr "" #: c-api/init.rst:262 msgid "" "This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If " "*initsigs* is ``0``, it skips initialization registration of signal " "handlers, which might be useful when Python is embedded." msgstr "" #: c-api/init.rst:269 msgid "" "Return true (nonzero) when the Python interpreter has been initialized, " "false (zero) if not. After :c:func:`Py_FinalizeEx` is called, this returns " "false until :c:func:`Py_Initialize` is called again." msgstr "" #: c-api/init.rst:276 msgid "" "Undo all initializations made by :c:func:`Py_Initialize` and subsequent use " "of Python/C API functions, and destroy all sub-interpreters (see :c:func:" "`Py_NewInterpreter` below) that were created and not yet destroyed since the " "last call to :c:func:`Py_Initialize`. Ideally, this frees all memory " "allocated by the Python interpreter. This is a no-op when called for a " "second time (without calling :c:func:`Py_Initialize` again first). Normally " "the return value is ``0``. If there were errors during finalization " "(flushing buffered data), ``-1`` is returned." msgstr "" #: c-api/init.rst:285 msgid "" "This function is provided for a number of reasons. An embedding application " "might want to restart Python without having to restart the application " "itself. An application that has loaded the Python interpreter from a " "dynamically loadable library (or DLL) might want to free all memory " "allocated by Python before unloading the DLL. During a hunt for memory leaks " "in an application a developer might want to free all memory allocated by " "Python before exiting from the application." msgstr "" #: c-api/init.rst:293 msgid "" "**Bugs and caveats:** The destruction of modules and objects in modules is " "done in random order; this may cause destructors (:meth:`__del__` methods) " "to fail when they depend on other objects (even functions) or modules. " "Dynamically loaded extension modules loaded by Python are not unloaded. " "Small amounts of memory allocated by the Python interpreter may not be freed " "(if you find a leak, please report it). Memory tied up in circular " "references between objects is not freed. Some memory allocated by extension " "modules may not be freed. Some extensions may not work properly if their " "initialization routine is called more than once; this can happen if an " "application calls :c:func:`Py_Initialize` and :c:func:`Py_FinalizeEx` more " "than once." msgstr "" #: c-api/init.rst:305 msgid "" "Raises an :ref:`auditing event ` ``cpython." "_PySys_ClearAuditHooks`` with no arguments." msgstr "" #: c-api/init.rst:310 msgid "" "This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that " "disregards the return value." msgstr "" #: c-api/init.rst:315 msgid "Process-wide parameters" msgstr "" #: c-api/init.rst:325 msgid "" "This function should be called before :c:func:`Py_Initialize`, if it is " "called at all. It specifies which encoding and error handling to use with " "standard IO, with the same meanings as in :func:`str.encode`." msgstr "" #: c-api/init.rst:329 msgid "" "It overrides :envvar:`PYTHONIOENCODING` values, and allows embedding code to " "control IO encoding when the environment variable does not work." msgstr "" #: c-api/init.rst:332 msgid "" "*encoding* and/or *errors* may be ``NULL`` to use :envvar:`PYTHONIOENCODING` " "and/or default values (depending on other settings)." msgstr "" #: c-api/init.rst:336 msgid "" "Note that :data:`sys.stderr` always uses the \"backslashreplace\" error " "handler, regardless of this (or any other) setting." msgstr "" #: c-api/init.rst:339 msgid "" "If :c:func:`Py_FinalizeEx` is called, this function will need to be called " "again in order to affect subsequent calls to :c:func:`Py_Initialize`." msgstr "" #: c-api/init.rst:342 msgid "" "Returns ``0`` if successful, a nonzero value on error (e.g. calling after " "the interpreter has already been initialized)." msgstr "" #: c-api/init.rst:355 msgid "" "This function should be called before :c:func:`Py_Initialize` is called for " "the first time, if it is called at all. It tells the interpreter the value " "of the ``argv[0]`` argument to the :c:func:`main` function of the program " "(converted to wide characters). This is used by :c:func:`Py_GetPath` and " "some other functions below to find the Python run-time libraries relative to " "the interpreter executable. The default value is ``'python'``. The " "argument should point to a zero-terminated wide character string in static " "storage whose contents will not change for the duration of the program's " "execution. No code in the Python interpreter will change the contents of " "this storage." msgstr "" #: c-api/init.rst:366 c-api/init.rst:480 c-api/init.rst:586 c-api/init.rst:613 #: c-api/init.rst:630 msgid "" "Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a :c:type:" "`wchar_*` string." msgstr "" #: c-api/init.rst:374 msgid "" "Return the program name set with :c:func:`Py_SetProgramName`, or the " "default. The returned string points into static storage; the caller should " "not modify its value." msgstr "" #: c-api/init.rst:381 msgid "" "Return the *prefix* for installed platform-independent files. This is " "derived through a number of complicated rules from the program name set " "with :c:func:`Py_SetProgramName` and some environment variables; for " "example, if the program name is ``'/usr/local/bin/python'``, the prefix is " "``'/usr/local'``. The returned string points into static storage; the caller " "should not modify its value. This corresponds to the :makevar:`prefix` " "variable in the top-level :file:`Makefile` and the ``--prefix`` argument to " "the :program:`configure` script at build time. The value is available to " "Python code as ``sys.prefix``. It is only useful on Unix. See also the next " "function." msgstr "" #: c-api/init.rst:394 msgid "" "Return the *exec-prefix* for installed platform-*dependent* files. This is " "derived through a number of complicated rules from the program name set " "with :c:func:`Py_SetProgramName` and some environment variables; for " "example, if the program name is ``'/usr/local/bin/python'``, the exec-prefix " "is ``'/usr/local'``. The returned string points into static storage; the " "caller should not modify its value. This corresponds to the :makevar:" "`exec_prefix` variable in the top-level :file:`Makefile` and the ``--exec-" "prefix`` argument to the :program:`configure` script at build time. The " "value is available to Python code as ``sys.exec_prefix``. It is only useful " "on Unix." msgstr "" #: c-api/init.rst:404 msgid "" "Background: The exec-prefix differs from the prefix when platform dependent " "files (such as executables and shared libraries) are installed in a " "different directory tree. In a typical installation, platform dependent " "files may be installed in the :file:`/usr/local/plat` subtree while platform " "independent may be installed in :file:`/usr/local`." msgstr "" #: c-api/init.rst:410 msgid "" "Generally speaking, a platform is a combination of hardware and software " "families, e.g. Sparc machines running the Solaris 2.x operating system are " "considered the same platform, but Intel machines running Solaris 2.x are " "another platform, and Intel machines running Linux are yet another " "platform. Different major revisions of the same operating system generally " "also form different platforms. Non-Unix operating systems are a different " "story; the installation strategies on those systems are so different that " "the prefix and exec-prefix are meaningless, and set to the empty string. " "Note that compiled Python bytecode files are platform independent (but not " "independent from the Python version by which they were compiled!)." msgstr "" #: c-api/init.rst:421 msgid "" "System administrators will know how to configure the :program:`mount` or :" "program:`automount` programs to share :file:`/usr/local` between platforms " "while having :file:`/usr/local/plat` be a different filesystem for each " "platform." msgstr "" #: c-api/init.rst:433 msgid "" "Return the full program name of the Python executable; this is computed as " "a side-effect of deriving the default module search path from the program " "name (set by :c:func:`Py_SetProgramName` above). The returned string points " "into static storage; the caller should not modify its value. The value is " "available to Python code as ``sys.executable``." msgstr "" #: c-api/init.rst:447 msgid "" "Return the default module search path; this is computed from the program " "name (set by :c:func:`Py_SetProgramName` above) and some environment " "variables. The returned string consists of a series of directory names " "separated by a platform dependent delimiter character. The delimiter " "character is ``':'`` on Unix and Mac OS X, ``';'`` on Windows. The returned " "string points into static storage; the caller should not modify its value. " "The list :data:`sys.path` is initialized with this value on interpreter " "startup; it can be (and usually is) modified later to change the search path " "for loading modules." msgstr "" #: c-api/init.rst:467 msgid "" "Set the default module search path. If this function is called before :c:" "func:`Py_Initialize`, then :c:func:`Py_GetPath` won't attempt to compute a " "default search path but uses the one provided instead. This is useful if " "Python is embedded by an application that has full knowledge of the location " "of all modules. The path components should be separated by the platform " "dependent delimiter character, which is ``':'`` on Unix and Mac OS X, " "``';'`` on Windows." msgstr "" #: c-api/init.rst:475 msgid "" "This also causes :data:`sys.executable` to be set to the program full path " "(see :c:func:`Py_GetProgramFullPath`) and for :data:`sys.prefix` and :data:" "`sys.exec_prefix` to be empty. It is up to the caller to modify these if " "required after calling :c:func:`Py_Initialize`." msgstr "" #: c-api/init.rst:483 msgid "" "The path argument is copied internally, so the caller may free it after the " "call completes." msgstr "" #: c-api/init.rst:486 msgid "" "The program full path is now used for :data:`sys.executable`, instead of the " "program name." msgstr "" #: c-api/init.rst:493 msgid "" "Return the version of this Python interpreter. This is a string that looks " "something like ::" msgstr "" #: c-api/init.rst:500 msgid "" "The first word (up to the first space character) is the current Python " "version; the first three characters are the major and minor version " "separated by a period. The returned string points into static storage; the " "caller should not modify its value. The value is available to Python code " "as :data:`sys.version`." msgstr "" #: c-api/init.rst:510 msgid "" "Return the platform identifier for the current platform. On Unix, this is " "formed from the \"official\" name of the operating system, converted to " "lower case, followed by the major revision number; e.g., for Solaris 2.x, " "which is also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, " "it is ``'darwin'``. On Windows, it is ``'win'``. The returned string " "points into static storage; the caller should not modify its value. The " "value is available to Python code as ``sys.platform``." msgstr "" #: c-api/init.rst:521 msgid "" "Return the official copyright string for the current Python version, for " "example" msgstr "" #: c-api/init.rst:523 msgid "``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'``" msgstr "" #: c-api/init.rst:527 msgid "" "The returned string points into static storage; the caller should not modify " "its value. The value is available to Python code as ``sys.copyright``." msgstr "" #: c-api/init.rst:533 msgid "" "Return an indication of the compiler used to build the current Python " "version, in square brackets, for example::" msgstr "" #: c-api/init.rst:540 c-api/init.rst:554 msgid "" "The returned string points into static storage; the caller should not modify " "its value. The value is available to Python code as part of the variable " "``sys.version``." msgstr "" #: c-api/init.rst:547 msgid "" "Return information about the sequence number and build date and time of the " "current Python interpreter instance, for example ::" msgstr "" #: c-api/init.rst:566 msgid "" "Set :data:`sys.argv` based on *argc* and *argv*. These parameters are " "similar to those passed to the program's :c:func:`main` function with the " "difference that the first entry should refer to the script file to be " "executed rather than the executable hosting the Python interpreter. If " "there isn't a script that will be run, the first entry in *argv* can be an " "empty string. If this function fails to initialize :data:`sys.argv`, a " "fatal condition is signalled using :c:func:`Py_FatalError`." msgstr "" #: c-api/init.rst:574 msgid "" "If *updatepath* is zero, this is all the function does. If *updatepath* is " "non-zero, the function also modifies :data:`sys.path` according to the " "following algorithm:" msgstr "" #: c-api/init.rst:578 msgid "" "If the name of an existing script is passed in ``argv[0]``, the absolute " "path of the directory where the script is located is prepended to :data:`sys." "path`." msgstr "" #: c-api/init.rst:581 msgid "" "Otherwise (that is, if *argc* is ``0`` or ``argv[0]`` doesn't point to an " "existing file name), an empty string is prepended to :data:`sys.path`, which " "is the same as prepending the current working directory (``\".\"``)." msgstr "" #: c-api/init.rst:590 msgid "" "It is recommended that applications embedding the Python interpreter for " "purposes other than executing a single script pass ``0`` as *updatepath*, " "and update :data:`sys.path` themselves if desired. See `CVE-2008-5983 " "`_." msgstr "" #: c-api/init.rst:595 msgid "" "On versions before 3.1.3, you can achieve the same effect by manually " "popping the first :data:`sys.path` element after having called :c:func:" "`PySys_SetArgv`, for example using::" msgstr "" #: c-api/init.rst:609 msgid "" "This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to " "``1`` unless the :program:`python` interpreter was started with the :option:" "`-I`." msgstr "" #: c-api/init.rst:616 msgid "The *updatepath* value depends on :option:`-I`." msgstr "" #: c-api/init.rst:621 msgid "" "Set the default \"home\" directory, that is, the location of the standard " "Python libraries. See :envvar:`PYTHONHOME` for the meaning of the argument " "string." msgstr "" #: c-api/init.rst:625 msgid "" "The argument should point to a zero-terminated character string in static " "storage whose contents will not change for the duration of the program's " "execution. No code in the Python interpreter will change the contents of " "this storage." msgstr "" #: c-api/init.rst:636 msgid "" "Return the default \"home\", that is, the value set by a previous call to :c:" "func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` " "environment variable if it is set." msgstr "" #: c-api/init.rst:644 msgid "Thread State and the Global Interpreter Lock" msgstr "" #: c-api/init.rst:651 msgid "" "The Python interpreter is not fully thread-safe. In order to support multi-" "threaded Python programs, there's a global lock, called the :term:`global " "interpreter lock` or :term:`GIL`, that must be held by the current thread " "before it can safely access Python objects. Without the lock, even the " "simplest operations could cause problems in a multi-threaded program: for " "example, when two threads simultaneously increment the reference count of " "the same object, the reference count could end up being incremented only " "once instead of twice." msgstr "" #: c-api/init.rst:661 msgid "" "Therefore, the rule exists that only the thread that has acquired the :term:" "`GIL` may operate on Python objects or call Python/C API functions. In order " "to emulate concurrency of execution, the interpreter regularly tries to " "switch threads (see :func:`sys.setswitchinterval`). The lock is also " "released around potentially blocking I/O operations like reading or writing " "a file, so that other Python threads can run in the meantime." msgstr "" #: c-api/init.rst:672 msgid "" "The Python interpreter keeps some thread-specific bookkeeping information " "inside a data structure called :c:type:`PyThreadState`. There's also one " "global variable pointing to the current :c:type:`PyThreadState`: it can be " "retrieved using :c:func:`PyThreadState_Get`." msgstr "" #: c-api/init.rst:678 msgid "Releasing the GIL from extension code" msgstr "" #: c-api/init.rst:680 msgid "" "Most extension code manipulating the :term:`GIL` has the following simple " "structure::" msgstr "" #: c-api/init.rst:689 msgid "This is so common that a pair of macros exists to simplify it::" msgstr "" #: c-api/init.rst:699 msgid "" "The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a " "hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the " "block." msgstr "" #: c-api/init.rst:703 msgid "The block above expands to the following code::" msgstr "" #: c-api/init.rst:715 msgid "" "Here is how these functions work: the global interpreter lock is used to " "protect the pointer to the current thread state. When releasing the lock " "and saving the thread state, the current thread state pointer must be " "retrieved before the lock is released (since another thread could " "immediately acquire the lock and store its own thread state in the global " "variable). Conversely, when acquiring the lock and restoring the thread " "state, the lock must be acquired before storing the thread state pointer." msgstr "" #: c-api/init.rst:724 msgid "" "Calling system I/O functions is the most common use case for releasing the " "GIL, but it can also be useful before calling long-running computations " "which don't need access to Python objects, such as compression or " "cryptographic functions operating over memory buffers. For example, the " "standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when " "compressing or hashing data." msgstr "" #: c-api/init.rst:735 msgid "Non-Python created threads" msgstr "" #: c-api/init.rst:737 msgid "" "When threads are created using the dedicated Python APIs (such as the :mod:" "`threading` module), a thread state is automatically associated to them and " "the code showed above is therefore correct. However, when threads are " "created from C (for example by a third-party library with its own thread " "management), they don't hold the GIL, nor is there a thread state structure " "for them." msgstr "" #: c-api/init.rst:744 msgid "" "If you need to call Python code from these threads (often this will be part " "of a callback API provided by the aforementioned third-party library), you " "must first register these threads with the interpreter by creating a thread " "state data structure, then acquiring the GIL, and finally storing their " "thread state pointer, before you can start using the Python/C API. When you " "are done, you should reset the thread state pointer, release the GIL, and " "finally free the thread state data structure." msgstr "" #: c-api/init.rst:752 msgid "" "The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions " "do all of the above automatically. The typical idiom for calling into " "Python from a C thread is::" msgstr "" #: c-api/init.rst:766 msgid "" "Note that the :c:func:`PyGILState_\\*` functions assume there is only one " "global interpreter (created automatically by :c:func:`Py_Initialize`). " "Python supports the creation of additional interpreters (using :c:func:" "`Py_NewInterpreter`), but mixing multiple interpreters and the :c:func:" "`PyGILState_\\*` API is unsupported." msgstr "" #: c-api/init.rst:776 msgid "Cautions about fork()" msgstr "" #: c-api/init.rst:778 msgid "" "Another important thing to note about threads is their behaviour in the face " "of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a " "process forks only the thread that issued the fork will exist. This has a " "concrete impact both on how locks must be handled and on all stored state in " "CPython's runtime." msgstr "" #: c-api/init.rst:784 msgid "" "The fact that only the \"current\" thread remains means any locks held by " "other threads will never be released. Python solves this for :func:`os.fork` " "by acquiring the locks it uses internally before the fork, and releasing " "them afterwards. In addition, it resets any :ref:`lock-objects` in the " "child. When extending or embedding Python, there is no way to inform Python " "of additional (non-Python) locks that need to be acquired before or reset " "after a fork. OS facilities such as :c:func:`pthread_atfork` would need to " "be used to accomplish the same thing. Additionally, when extending or " "embedding Python, calling :c:func:`fork` directly rather than through :func:" "`os.fork` (and returning to or calling into Python) may result in a deadlock " "by one of Python's internal locks being held by a thread that is defunct " "after the fork. :c:func:`PyOS_AfterFork_Child` tries to reset the necessary " "locks, but is not always able to." msgstr "" #: c-api/init.rst:799 msgid "" "The fact that all other threads go away also means that CPython's runtime " "state there must be cleaned up properly, which :func:`os.fork` does. This " "means finalizing all other :c:type:`PyThreadState` objects belonging to the " "current interpreter and all other :c:type:`PyInterpreterState` objects. Due " "to this and the special nature of the :ref:`\"main\" interpreter `, :c:func:`fork` should only be called in that " "interpreter's \"main\" thread, where the CPython global runtime was " "originally initialized. The only exception is if :c:func:`exec` will be " "called immediately after." msgstr "" #: c-api/init.rst:812 #, fuzzy msgid "High-level API" msgstr "Bibliothèques de haut-niveau" #: c-api/init.rst:814 msgid "" "These are the most commonly used types and functions when writing C " "extension code, or when embedding the Python interpreter:" msgstr "" #: c-api/init.rst:819 msgid "" "This data structure represents the state shared by a number of cooperating " "threads. Threads belonging to the same interpreter share their module " "administration and a few other internal items. There are no public members " "in this structure." msgstr "" #: c-api/init.rst:824 msgid "" "Threads belonging to different interpreters initially share nothing, except " "process state like available memory, open file descriptors and such. The " "global interpreter lock is also shared by all threads, regardless of to " "which interpreter they belong." msgstr "" #: c-api/init.rst:832 msgid "" "This data structure represents the state of a single thread. The only " "public data member is :attr:`interp` (:c:type:`PyInterpreterState *`), which " "points to this thread's interpreter state." msgstr "" #: c-api/init.rst:845 msgid "Deprecated function which does nothing." msgstr "" #: c-api/init.rst:847 msgid "" "In Python 3.6 and older, this function created the GIL if it didn't exist." msgstr "" #: c-api/init.rst:849 msgid "The function now does nothing." msgstr "" #: c-api/init.rst:852 msgid "" "This function is now called by :c:func:`Py_Initialize()`, so you don't have " "to call it yourself anymore." msgstr "" #: c-api/init.rst:856 msgid "" "This function cannot be called before :c:func:`Py_Initialize()` anymore." msgstr "" #: c-api/init.rst:866 msgid "" "Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. " "This function can be called without holding the GIL, and therefore can be " "used to avoid calls to the locking API when running single-threaded." msgstr "" #: c-api/init.rst:870 msgid "The :term:`GIL` is now initialized by :c:func:`Py_Initialize()`." msgstr "" #: c-api/init.rst:878 msgid "" "Release the global interpreter lock (if it has been created) and reset the " "thread state to ``NULL``, returning the previous thread state (which is not " "``NULL``). If the lock has been created, the current thread must have " "acquired it." msgstr "" #: c-api/init.rst:886 msgid "" "Acquire the global interpreter lock (if it has been created) and set the " "thread state to *tstate*, which must not be ``NULL``. If the lock has been " "created, the current thread must not have acquired it, otherwise deadlock " "ensues." msgstr "" #: c-api/init.rst:892 c-api/init.rst:938 c-api/init.rst:1197 #: c-api/init.rst:1235 msgid "" "Calling this function from a thread when the runtime is finalizing will " "terminate the thread, even if the thread was not created by Python. You can " "use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to check if the " "interpreter is in process of being finalized before calling this function to " "avoid unwanted termination." msgstr "" #: c-api/init.rst:900 msgid "" "Return the current thread state. The global interpreter lock must be held. " "When the current thread state is ``NULL``, this issues a fatal error (so " "that the caller needn't check for ``NULL``)." msgstr "" #: c-api/init.rst:907 msgid "" "Swap the current thread state with the thread state given by the argument " "*tstate*, which may be ``NULL``. The global interpreter lock must be held " "and is not released." msgstr "" #: c-api/init.rst:912 msgid "" "The following functions use thread-local storage, and are not compatible " "with sub-interpreters:" msgstr "" #: c-api/init.rst:917 msgid "" "Ensure that the current thread is ready to call the Python C API regardless " "of the current state of Python, or of the global interpreter lock. This may " "be called as many times as desired by a thread as long as each call is " "matched with a call to :c:func:`PyGILState_Release`. In general, other " "thread-related APIs may be used between :c:func:`PyGILState_Ensure` and :c:" "func:`PyGILState_Release` calls as long as the thread state is restored to " "its previous state before the Release(). For example, normal usage of the :" "c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros " "is acceptable." msgstr "" #: c-api/init.rst:927 msgid "" "The return value is an opaque \"handle\" to the thread state when :c:func:" "`PyGILState_Ensure` was called, and must be passed to :c:func:" "`PyGILState_Release` to ensure Python is left in the same state. Even though " "recursive calls are allowed, these handles *cannot* be shared - each unique " "call to :c:func:`PyGILState_Ensure` must save the handle for its call to :c:" "func:`PyGILState_Release`." msgstr "" #: c-api/init.rst:934 msgid "" "When the function returns, the current thread will hold the GIL and be able " "to call arbitrary Python code. Failure is a fatal error." msgstr "" #: c-api/init.rst:946 msgid "" "Release any resources previously acquired. After this call, Python's state " "will be the same as it was prior to the corresponding :c:func:" "`PyGILState_Ensure` call (but generally this state will be unknown to the " "caller, hence the use of the GILState API)." msgstr "" #: c-api/init.rst:951 msgid "" "Every call to :c:func:`PyGILState_Ensure` must be matched by a call to :c:" "func:`PyGILState_Release` on the same thread." msgstr "" #: c-api/init.rst:957 msgid "" "Get the current thread state for this thread. May return ``NULL`` if no " "GILState API has been used on the current thread. Note that the main thread " "always has such a thread-state, even if no auto-thread-state call has been " "made on the main thread. This is mainly a helper/diagnostic function." msgstr "" #: c-api/init.rst:965 msgid "" "Return ``1`` if the current thread is holding the GIL and ``0`` otherwise. " "This function can be called from any thread at any time. Only if it has had " "its Python thread state initialized and currently is holding the GIL will it " "return ``1``. This is mainly a helper/diagnostic function. It can be useful " "for example in callback contexts or memory allocation functions when knowing " "that the GIL is locked can allow the caller to perform sensitive actions or " "otherwise behave differently." msgstr "" #: c-api/init.rst:977 msgid "" "The following macros are normally used without a trailing semicolon; look " "for example usage in the Python source distribution." msgstr "" #: c-api/init.rst:983 msgid "" "This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();" "``. Note that it contains an opening brace; it must be matched with a " "following :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further " "discussion of this macro." msgstr "" #: c-api/init.rst:991 msgid "" "This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it " "contains a closing brace; it must be matched with an earlier :c:macro:" "`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of this " "macro." msgstr "" #: c-api/init.rst:999 msgid "" "This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to :" "c:macro:`Py_END_ALLOW_THREADS` without the closing brace." msgstr "" #: c-api/init.rst:1005 msgid "" "This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to :" "c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable " "declaration." msgstr "" #: c-api/init.rst:1011 #, fuzzy msgid "Low-level API" msgstr "Bibliothèques de bas-niveau" #: c-api/init.rst:1013 msgid "" "All of the following functions must be called after :c:func:`Py_Initialize`." msgstr "" #: c-api/init.rst:1015 msgid ":c:func:`Py_Initialize()` now initializes the :term:`GIL`." msgstr "" #: c-api/init.rst:1021 msgid "" "Create a new interpreter state object. The global interpreter lock need not " "be held, but may be held if it is necessary to serialize calls to this " "function." msgstr "" #: c-api/init.rst:1025 msgid "" "Raises an :ref:`auditing event ` ``cpython." "PyInterpreterState_New`` with no arguments." msgstr "" #: c-api/init.rst:1030 msgid "" "Reset all information in an interpreter state object. The global " "interpreter lock must be held." msgstr "" #: c-api/init.rst:1033 msgid "" "Raises an :ref:`auditing event ` ``cpython." "PyInterpreterState_Clear`` with no arguments." msgstr "" #: c-api/init.rst:1038 msgid "" "Destroy an interpreter state object. The global interpreter lock need not " "be held. The interpreter state must have been reset with a previous call " "to :c:func:`PyInterpreterState_Clear`." msgstr "" #: c-api/init.rst:1045 msgid "" "Create a new thread state object belonging to the given interpreter object. " "The global interpreter lock need not be held, but may be held if it is " "necessary to serialize calls to this function." msgstr "" #: c-api/init.rst:1052 msgid "" "Reset all information in a thread state object. The global interpreter lock " "must be held." msgstr "" #: c-api/init.rst:1055 msgid "" "This function now calls the :c:member:`PyThreadState.on_delete` callback. " "Previously, that happened in :c:func:`PyThreadState_Delete`." msgstr "" #: c-api/init.rst:1062 msgid "" "Destroy a thread state object. The global interpreter lock need not be " "held. The thread state must have been reset with a previous call to :c:func:" "`PyThreadState_Clear`." msgstr "" #: c-api/init.rst:1069 msgid "" "Destroy the current thread state and release the global interpreter lock. " "Like :c:func:`PyThreadState_Delete`, the global interpreter lock need not be " "held. The thread state must have been reset with a previous call to :c:func:" "`PyThreadState_Clear`." msgstr "" #: c-api/init.rst:1077 msgid "Get the current frame of the Python thread state *tstate*." msgstr "" #: c-api/init.rst:1079 msgid "" "Return a strong reference. Return ``NULL`` if no frame is currently " "executing." msgstr "" #: c-api/init.rst:1082 msgid "See also :c:func:`PyEval_GetFrame`." msgstr "" #: c-api/init.rst:1084 c-api/init.rst:1093 c-api/init.rst:1102 msgid "*tstate* must not be ``NULL``." msgstr "" #: c-api/init.rst:1091 msgid "" "Get the unique thread state identifier of the Python thread state *tstate*." msgstr "" #: c-api/init.rst:1100 msgid "Get the interpreter of the Python thread state *tstate*." msgstr "" #: c-api/init.rst:1109 msgid "Get the current interpreter." msgstr "" #: c-api/init.rst:1111 msgid "" "Issue a fatal error if there no current Python thread state or no current " "interpreter. It cannot return NULL." msgstr "" #: c-api/init.rst:1114 c-api/init.rst:1124 msgid "The caller must hold the GIL." msgstr "" #: c-api/init.rst:1121 msgid "" "Return the interpreter's unique ID. If there was any error in doing so then " "``-1`` is returned and an error is set." msgstr "" #: c-api/init.rst:1131 msgid "" "Return a dictionary in which interpreter-specific data may be stored. If " "this function returns ``NULL`` then no exception has been raised and the " "caller should assume no interpreter-specific dict is available." msgstr "" #: c-api/init.rst:1135 msgid "" "This is not a replacement for :c:func:`PyModule_GetState()`, which " "extensions should use to store interpreter-specific state information." msgstr "" #: c-api/init.rst:1142 msgid "Type of a frame evaluation function." msgstr "" #: c-api/init.rst:1144 msgid "" "The *throwflag* parameter is used by the ``throw()`` method of generators: " "if non-zero, handle the current exception." msgstr "" #: c-api/init.rst:1147 msgid "The function now takes a *tstate* parameter." msgstr "" #: c-api/init.rst:1152 msgid "Get the frame evaluation function." msgstr "" #: c-api/init.rst:1154 c-api/init.rst:1162 msgid "See the :pep:`523` \"Adding a frame evaluation API to CPython\"." msgstr "" #: c-api/init.rst:1160 msgid "Set the frame evaluation function." msgstr "" #: c-api/init.rst:1169 msgid "" "Return a dictionary in which extensions can store thread-specific state " "information. Each extension should use a unique key to use to store state " "in the dictionary. It is okay to call this function when no current thread " "state is available. If this function returns ``NULL``, no exception has been " "raised and the caller should assume no current thread state is available." msgstr "" #: c-api/init.rst:1178 msgid "" "Asynchronously raise an exception in a thread. The *id* argument is the " "thread id of the target thread; *exc* is the exception object to be raised. " "This function does not steal any references to *exc*. To prevent naive " "misuse, you must write your own C extension to call this. Must be called " "with the GIL held. Returns the number of thread states modified; this is " "normally one, but will be zero if the thread id isn't found. If *exc* is :" "const:`NULL`, the pending exception (if any) for the thread is cleared. This " "raises no exceptions." msgstr "" #: c-api/init.rst:1186 msgid "" "The type of the *id* parameter changed from :c:type:`long` to :c:type:" "`unsigned long`." msgstr "" #: c-api/init.rst:1192 msgid "" "Acquire the global interpreter lock and set the current thread state to " "*tstate*, which must not be ``NULL``. The lock must have been created " "earlier. If this thread already has the lock, deadlock ensues." msgstr "" #: c-api/init.rst:1203 c-api/init.rst:1241 msgid "" "Updated to be consistent with :c:func:`PyEval_RestoreThread`, :c:func:" "`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`, and terminate the " "current thread if called while the interpreter is finalizing." msgstr "" #: c-api/init.rst:1208 msgid "" ":c:func:`PyEval_RestoreThread` is a higher-level function which is always " "available (even when threads have not been initialized)." msgstr "" #: c-api/init.rst:1214 msgid "" "Reset the current thread state to ``NULL`` and release the global " "interpreter lock. The lock must have been created earlier and must be held " "by the current thread. The *tstate* argument, which must not be ``NULL``, " "is only used to check that it represents the current thread state --- if it " "isn't, a fatal error is reported." msgstr "" #: c-api/init.rst:1220 msgid "" ":c:func:`PyEval_SaveThread` is a higher-level function which is always " "available (even when threads have not been initialized)." msgstr "" #: c-api/init.rst:1226 msgid "" "Acquire the global interpreter lock. The lock must have been created " "earlier. If this thread already has the lock, a deadlock ensues." msgstr "" #: c-api/init.rst:1229 msgid "" "This function does not update the current thread state. Please use :c:func:" "`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread` instead." msgstr "" #: c-api/init.rst:1249 msgid "" "Release the global interpreter lock. The lock must have been created " "earlier." msgstr "" #: c-api/init.rst:1251 msgid "" "This function does not update the current thread state. Please use :c:func:" "`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread` instead." msgstr "" #: c-api/init.rst:1260 msgid "Sub-interpreter support" msgstr "" #: c-api/init.rst:1262 msgid "" "While in most uses, you will only embed a single Python interpreter, there " "are cases where you need to create several independent interpreters in the " "same process and perhaps even in the same thread. Sub-interpreters allow you " "to do that." msgstr "" #: c-api/init.rst:1267 msgid "" "The \"main\" interpreter is the first one created when the runtime " "initializes. It is usually the only Python interpreter in a process. Unlike " "sub-interpreters, the main interpreter has unique process-global " "responsibilities like signal handling. It is also responsible for execution " "during runtime initialization and is usually the active interpreter during " "runtime finalization. The :c:func:`PyInterpreterState_Main` function " "returns a pointer to its state." msgstr "" #: c-api/init.rst:1274 msgid "" "You can switch between sub-interpreters using the :c:func:" "`PyThreadState_Swap` function. You can create and destroy them using the " "following functions:" msgstr "" #: c-api/init.rst:1288 msgid "" "Create a new sub-interpreter. This is an (almost) totally separate " "environment for the execution of Python code. In particular, the new " "interpreter has separate, independent versions of all imported modules, " "including the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:" "`sys`. The table of loaded modules (``sys.modules``) and the module search " "path (``sys.path``) are also separate. The new environment has no ``sys." "argv`` variable. It has new standard I/O stream file objects ``sys.stdin``, " "``sys.stdout`` and ``sys.stderr`` (however these refer to the same " "underlying file descriptors)." msgstr "" #: c-api/init.rst:1298 msgid "" "The return value points to the first thread state created in the new sub-" "interpreter. This thread state is made in the current thread state. Note " "that no actual thread is created; see the discussion of thread states " "below. If creation of the new interpreter is unsuccessful, ``NULL`` is " "returned; no exception is set since the exception state is stored in the " "current thread state and there may not be a current thread state. (Like all " "other Python/C API functions, the global interpreter lock must be held " "before calling this function and is still held when it returns; however, " "unlike most other Python/C API functions, there needn't be a current thread " "state on entry.)" msgstr "" #: c-api/init.rst:1313 msgid "Extension modules are shared between (sub-)interpreters as follows:" msgstr "" #: c-api/init.rst:1315 msgid "" "For modules using multi-phase initialization, e.g. :c:func:" "`PyModule_FromDefAndSpec`, a separate module object is created and " "initialized for each interpreter. Only C-level static and global variables " "are shared between these module objects." msgstr "" #: c-api/init.rst:1321 msgid "" "For modules using single-phase initialization, e.g. :c:func:" "`PyModule_Create`, the first time a particular extension is imported, it is " "initialized normally, and a (shallow) copy of its module's dictionary is " "squirreled away. When the same extension is imported by another " "(sub-)interpreter, a new module is initialized and filled with the contents " "of this copy; the extension's ``init`` function is not called. Objects in " "the module's dictionary thus end up shared across (sub-)interpreters, which " "might cause unwanted behavior (see `Bugs and caveats`_ below)." msgstr "" #: c-api/init.rst:1332 msgid "" "Note that this is different from what happens when an extension is imported " "after the interpreter has been completely re-initialized by calling :c:func:" "`Py_FinalizeEx` and :c:func:`Py_Initialize`; in that case, the extension's " "``initmodule`` function *is* called again. As with multi-phase " "initialization, this means that only C-level static and global variables are " "shared between these modules." msgstr "" #: c-api/init.rst:1346 msgid "" "Destroy the (sub-)interpreter represented by the given thread state. The " "given thread state must be the current thread state. See the discussion of " "thread states below. When the call returns, the current thread state is " "``NULL``. All thread states associated with this interpreter are " "destroyed. (The global interpreter lock must be held before calling this " "function and is still held when it returns.) :c:func:`Py_FinalizeEx` will " "destroy all sub-interpreters that haven't been explicitly destroyed at that " "point." msgstr "" #: c-api/init.rst:1356 msgid "Bugs and caveats" msgstr "" #: c-api/init.rst:1358 msgid "" "Because sub-interpreters (and the main interpreter) are part of the same " "process, the insulation between them isn't perfect --- for example, using " "low-level file operations like :func:`os.close` they can (accidentally or " "maliciously) affect each other's open files. Because of the way extensions " "are shared between (sub-)interpreters, some extensions may not work " "properly; this is especially likely when using single-phase initialization " "or (static) global variables. It is possible to insert objects created in " "one sub-interpreter into a namespace of another (sub-)interpreter; this " "should be avoided if possible." msgstr "" #: c-api/init.rst:1368 msgid "" "Special care should be taken to avoid sharing user-defined functions, " "methods, instances or classes between sub-interpreters, since import " "operations executed by such objects may affect the wrong (sub-)interpreter's " "dictionary of loaded modules. It is equally important to avoid sharing " "objects from which the above are reachable." msgstr "" #: c-api/init.rst:1374 msgid "" "Also note that combining this functionality with :c:func:`PyGILState_\\*` " "APIs is delicate, because these APIs assume a bijection between Python " "thread states and OS-level threads, an assumption broken by the presence of " "sub-interpreters. It is highly recommended that you don't switch sub-" "interpreters between a pair of matching :c:func:`PyGILState_Ensure` and :c:" "func:`PyGILState_Release` calls. Furthermore, extensions (such as :mod:" "`ctypes`) using these APIs to allow calling of Python code from non-Python " "created threads will probably be broken when using sub-interpreters." msgstr "" #: c-api/init.rst:1385 msgid "Asynchronous Notifications" msgstr "" #: c-api/init.rst:1387 msgid "" "A mechanism is provided to make asynchronous notifications to the main " "interpreter thread. These notifications take the form of a function pointer " "and a void pointer argument." msgstr "" #: c-api/init.rst:1396 msgid "" "Schedule a function to be called from the main interpreter thread. On " "success, ``0`` is returned and *func* is queued for being called in the main " "thread. On failure, ``-1`` is returned without setting any exception." msgstr "" #: c-api/init.rst:1400 msgid "" "When successfully queued, *func* will be *eventually* called from the main " "interpreter thread with the argument *arg*. It will be called " "asynchronously with respect to normally running Python code, but with both " "these conditions met:" msgstr "" #: c-api/init.rst:1405 msgid "on a :term:`bytecode` boundary;" msgstr "" #: c-api/init.rst:1406 msgid "" "with the main thread holding the :term:`global interpreter lock` (*func* can " "therefore use the full C API)." msgstr "" #: c-api/init.rst:1409 msgid "" "*func* must return ``0`` on success, or ``-1`` on failure with an exception " "set. *func* won't be interrupted to perform another asynchronous " "notification recursively, but it can still be interrupted to switch threads " "if the global interpreter lock is released." msgstr "" #: c-api/init.rst:1414 msgid "" "This function doesn't need a current thread state to run, and it doesn't " "need the global interpreter lock." msgstr "" #: c-api/init.rst:1417 msgid "" "To call this function in a subinterpreter, the caller must hold the GIL. " "Otherwise, the function *func* can be scheduled to be called from the wrong " "interpreter." msgstr "" #: c-api/init.rst:1422 msgid "" "This is a low-level function, only useful for very special cases. There is " "no guarantee that *func* will be called as quick as possible. If the main " "thread is busy executing a system call, *func* won't be called before the " "system call returns. This function is generally **not** suitable for " "calling Python code from arbitrary C threads. Instead, use the :ref:" "`PyGILState API`." msgstr "" #: c-api/init.rst:1429 msgid "" "If this function is called in a subinterpreter, the function *func* is now " "scheduled to be called from the subinterpreter, rather than being called " "from the main interpreter. Each subinterpreter now has its own list of " "scheduled calls." msgstr "" #: c-api/init.rst:1440 msgid "Profiling and Tracing" msgstr "" #: c-api/init.rst:1445 msgid "" "The Python interpreter provides some low-level support for attaching " "profiling and execution tracing facilities. These are used for profiling, " "debugging, and coverage analysis tools." msgstr "" #: c-api/init.rst:1449 msgid "" "This C interface allows the profiling or tracing code to avoid the overhead " "of calling through Python-level callable objects, making a direct C function " "call instead. The essential attributes of the facility have not changed; " "the interface allows trace functions to be installed per-thread, and the " "basic events reported to the trace function are the same as had been " "reported to the Python-level trace functions in previous versions." msgstr "" #: c-api/init.rst:1459 msgid "" "The type of the trace function registered using :c:func:`PyEval_SetProfile` " "and :c:func:`PyEval_SetTrace`. The first parameter is the object passed to " "the registration function as *obj*, *frame* is the frame object to which the " "event pertains, *what* is one of the constants :const:`PyTrace_CALL`, :const:" "`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`, :const:" "`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, :const:`PyTrace_C_RETURN`, " "or :const:`PyTrace_OPCODE`, and *arg* depends on the value of *what*:" msgstr "" #: c-api/init.rst:1468 msgid "Value of *what*" msgstr "" #: c-api/init.rst:1468 msgid "Meaning of *arg*" msgstr "" #: c-api/init.rst:1470 msgid ":const:`PyTrace_CALL`" msgstr "" #: c-api/init.rst:1470 c-api/init.rst:1475 c-api/init.rst:1486 msgid "Always :c:data:`Py_None`." msgstr "" #: c-api/init.rst:1472 msgid ":const:`PyTrace_EXCEPTION`" msgstr "" #: c-api/init.rst:1472 msgid "Exception information as returned by :func:`sys.exc_info`." msgstr "" #: c-api/init.rst:1475 msgid ":const:`PyTrace_LINE`" msgstr "" #: c-api/init.rst:1477 msgid ":const:`PyTrace_RETURN`" msgstr "" #: c-api/init.rst:1477 msgid "" "Value being returned to the caller, or ``NULL`` if caused by an exception." msgstr "" #: c-api/init.rst:1480 msgid ":const:`PyTrace_C_CALL`" msgstr "" #: c-api/init.rst:1480 c-api/init.rst:1482 c-api/init.rst:1484 msgid "Function object being called." msgstr "" #: c-api/init.rst:1482 msgid ":const:`PyTrace_C_EXCEPTION`" msgstr "" #: c-api/init.rst:1484 msgid ":const:`PyTrace_C_RETURN`" msgstr "" #: c-api/init.rst:1486 msgid ":const:`PyTrace_OPCODE`" msgstr "" #: c-api/init.rst:1491 msgid "" "The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " "a new call to a function or method is being reported, or a new entry into a " "generator. Note that the creation of the iterator for a generator function " "is not reported as there is no control transfer to the Python bytecode in " "the corresponding frame." msgstr "" #: c-api/init.rst:1500 msgid "" "The value of the *what* parameter to a :c:type:`Py_tracefunc` function when " "an exception has been raised. The callback function is called with this " "value for *what* when after any bytecode is processed after which the " "exception becomes set within the frame being executed. The effect of this " "is that as exception propagation causes the Python stack to unwind, the " "callback is called upon return to each frame as the exception propagates. " "Only trace functions receives these events; they are not needed by the " "profiler." msgstr "" #: c-api/init.rst:1511 msgid "" "The value passed as the *what* parameter to a :c:type:`Py_tracefunc` " "function (but not a profiling function) when a line-number event is being " "reported. It may be disabled for a frame by setting :attr:`f_trace_lines` to " "*0* on that frame." msgstr "" #: c-api/init.rst:1518 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a call is about to return." msgstr "" #: c-api/init.rst:1524 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function is about to be called." msgstr "" #: c-api/init.rst:1530 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function has raised an exception." msgstr "" #: c-api/init.rst:1536 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions when " "a C function has returned." msgstr "" #: c-api/init.rst:1542 msgid "" "The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but " "not profiling functions) when a new opcode is about to be executed. This " "event is not emitted by default: it must be explicitly requested by setting :" "attr:`f_trace_opcodes` to *1* on the frame." msgstr "" #: c-api/init.rst:1550 msgid "" "Set the profiler function to *func*. The *obj* parameter is passed to the " "function as its first parameter, and may be any Python object, or ``NULL``. " "If the profile function needs to maintain state, using a different value for " "*obj* for each thread provides a convenient and thread-safe place to store " "it. The profile function is called for all monitored events except :const:" "`PyTrace_LINE` :const:`PyTrace_OPCODE` and :const:`PyTrace_EXCEPTION`." msgstr "" #: c-api/init.rst:1557 c-api/init.rst:1569 msgid "The caller must hold the :term:`GIL`." msgstr "" #: c-api/init.rst:1562 msgid "" "Set the tracing function to *func*. This is similar to :c:func:" "`PyEval_SetProfile`, except the tracing function does receive line-number " "events and per-opcode events, but does not receive any event related to C " "function objects being called. Any trace function registered using :c:func:" "`PyEval_SetTrace` will not receive :const:`PyTrace_C_CALL`, :const:" "`PyTrace_C_EXCEPTION` or :const:`PyTrace_C_RETURN` as a value for the *what* " "parameter." msgstr "" #: c-api/init.rst:1575 msgid "Advanced Debugger Support" msgstr "Support avancé du débogueur" #: c-api/init.rst:1580 msgid "" "These functions are only intended to be used by advanced debugging tools." msgstr "" #: c-api/init.rst:1585 msgid "" "Return the interpreter state object at the head of the list of all such " "objects." msgstr "" #: c-api/init.rst:1590 msgid "Return the main interpreter state object." msgstr "" #: c-api/init.rst:1595 msgid "" "Return the next interpreter state object after *interp* from the list of all " "such objects." msgstr "" #: c-api/init.rst:1601 msgid "" "Return the pointer to the first :c:type:`PyThreadState` object in the list " "of threads associated with the interpreter *interp*." msgstr "" #: c-api/init.rst:1607 msgid "" "Return the next thread state object after *tstate* from the list of all such " "objects belonging to the same :c:type:`PyInterpreterState` object." msgstr "" #: c-api/init.rst:1614 msgid "Thread Local Storage Support" msgstr "" #: c-api/init.rst:1618 msgid "" "The Python interpreter provides low-level support for thread-local storage " "(TLS) which wraps the underlying native TLS implementation to support the " "Python-level thread local storage API (:class:`threading.local`). The " "CPython C level APIs are similar to those offered by pthreads and Windows: " "use a thread key and functions to associate a :c:type:`void*` value per " "thread." msgstr "" #: c-api/init.rst:1625 msgid "" "The GIL does *not* need to be held when calling these functions; they supply " "their own locking." msgstr "" #: c-api/init.rst:1628 msgid "" "Note that :file:`Python.h` does not include the declaration of the TLS APIs, " "you need to include :file:`pythread.h` to use thread-local storage." msgstr "" #: c-api/init.rst:1632 msgid "" "None of these API functions handle memory management on behalf of the :c:" "type:`void*` values. You need to allocate and deallocate them yourself. If " "the :c:type:`void*` values happen to be :c:type:`PyObject*`, these functions " "don't do refcount operations on them either." msgstr "" #: c-api/init.rst:1640 msgid "Thread Specific Storage (TSS) API" msgstr "" #: c-api/init.rst:1642 msgid "" "TSS API is introduced to supersede the use of the existing TLS API within " "the CPython interpreter. This API uses a new type :c:type:`Py_tss_t` " "instead of :c:type:`int` to represent thread keys." msgstr "" #: c-api/init.rst:1648 msgid "\"A New C-API for Thread-Local Storage in CPython\" (:pep:`539`)" msgstr "" #: c-api/init.rst:1653 msgid "" "This data structure represents the state of a thread key, the definition of " "which may depend on the underlying TLS implementation, and it has an " "internal field representing the key's initialization state. There are no " "public members in this structure." msgstr "" #: c-api/init.rst:1658 msgid "" "When :ref:`Py_LIMITED_API ` is not defined, static allocation of " "this type by :c:macro:`Py_tss_NEEDS_INIT` is allowed." msgstr "" #: c-api/init.rst:1664 msgid "" "This macro expands to the initializer for :c:type:`Py_tss_t` variables. Note " "that this macro won't be defined with :ref:`Py_LIMITED_API `." msgstr "" #: c-api/init.rst:1669 msgid "Dynamic Allocation" msgstr "" #: c-api/init.rst:1671 msgid "" "Dynamic allocation of the :c:type:`Py_tss_t`, required in extension modules " "built with :ref:`Py_LIMITED_API `, where static allocation of this " "type is not possible due to its implementation being opaque at build time." msgstr "" #: c-api/init.rst:1678 msgid "" "Return a value which is the same state as a value initialized with :c:macro:" "`Py_tss_NEEDS_INIT`, or ``NULL`` in the case of dynamic allocation failure." msgstr "" #: c-api/init.rst:1685 msgid "" "Free the given *key* allocated by :c:func:`PyThread_tss_alloc`, after first " "calling :c:func:`PyThread_tss_delete` to ensure any associated thread locals " "have been unassigned. This is a no-op if the *key* argument is `NULL`." msgstr "" #: c-api/init.rst:1691 msgid "" "A freed key becomes a dangling pointer, you should reset the key to `NULL`." msgstr "" #: c-api/init.rst:1696 msgid "Methods" msgstr "Méthodes" #: c-api/init.rst:1698 msgid "" "The parameter *key* of these functions must not be ``NULL``. Moreover, the " "behaviors of :c:func:`PyThread_tss_set` and :c:func:`PyThread_tss_get` are " "undefined if the given :c:type:`Py_tss_t` has not been initialized by :c:" "func:`PyThread_tss_create`." msgstr "" #: c-api/init.rst:1706 msgid "" "Return a non-zero value if the given :c:type:`Py_tss_t` has been initialized " "by :c:func:`PyThread_tss_create`." msgstr "" #: c-api/init.rst:1712 msgid "" "Return a zero value on successful initialization of a TSS key. The behavior " "is undefined if the value pointed to by the *key* argument is not " "initialized by :c:macro:`Py_tss_NEEDS_INIT`. This function can be called " "repeatedly on the same key -- calling it on an already initialized key is a " "no-op and immediately returns success." msgstr "" #: c-api/init.rst:1721 msgid "" "Destroy a TSS key to forget the values associated with the key across all " "threads, and change the key's initialization state to uninitialized. A " "destroyed key is able to be initialized again by :c:func:" "`PyThread_tss_create`. This function can be called repeatedly on the same " "key -- calling it on an already destroyed key is a no-op." msgstr "" #: c-api/init.rst:1730 msgid "" "Return a zero value to indicate successfully associating a :c:type:`void*` " "value with a TSS key in the current thread. Each thread has a distinct " "mapping of the key to a :c:type:`void*` value." msgstr "" #: c-api/init.rst:1737 msgid "" "Return the :c:type:`void*` value associated with a TSS key in the current " "thread. This returns ``NULL`` if no value is associated with the key in the " "current thread." msgstr "" #: c-api/init.rst:1745 msgid "Thread Local Storage (TLS) API" msgstr "" #: c-api/init.rst:1747 msgid "" "This API is superseded by :ref:`Thread Specific Storage (TSS) API `." msgstr "" #: c-api/init.rst:1752 msgid "" "This version of the API does not support platforms where the native TLS key " "is defined in a way that cannot be safely cast to ``int``. On such " "platforms, :c:func:`PyThread_create_key` will return immediately with a " "failure status, and the other TLS functions will all be no-ops on such " "platforms." msgstr "" #: c-api/init.rst:1757 msgid "" "Due to the compatibility problem noted above, this version of the API should " "not be used in new code." msgstr ""