Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1c51fdd

Browse files
josixjosix
committed
Deploying to gh-pages from @ ae8ba24 🚀
1 parent 62dbd2b commit 1c51fdd

File tree

575 files changed

+11083
-10136
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

575 files changed

+11083
-10136
lines changed

‎.buildinfo

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
# Sphinx build info version 1
2-
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3-
config: 5af9f8de6017218637efae8dd621863f
2+
# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: 0e07bb20b6755b9c2da536565da9cbbd
44
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎_sources/c-api/code.rst.txt

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,13 @@ bound into a function.
3232
3333
.. c:function:: Py_ssize_t PyCode_GetNumFree(PyCodeObject *co)
3434
35-
Return the number of free variables in a code object.
35+
Return the number of :term:`free (closure) variables <closure variable>`
36+
in a code object.
3637
3738
.. c:function:: int PyUnstable_Code_GetFirstFree(PyCodeObject *co)
3839
39-
Return the position of the first free variable in a code object.
40+
Return the position of the first :term:`free (closure) variable <closure variable>`
41+
in a code object.
4042
4143
.. versionchanged:: 3.13
4244
@@ -144,7 +146,8 @@ bound into a function.
144146
145147
Equivalent to the Python code ``getattr(co, 'co_freevars')``.
146148
Returns a new reference to a :c:type:`PyTupleObject` containing the names of
147-
the free variables. On error, ``NULL`` is returned and an exception is raised.
149+
the :term:`free (closure) variables <closure variable>`. On error, ``NULL`` is returned
150+
and an exception is raised.
148151
149152
.. versionadded:: 3.11
150153

‎_sources/c-api/import.rst.txt

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -136,14 +136,14 @@ Importing Modules
136136
such modules have no way to know that the module object is an unknown (and
137137
probably damaged with respect to the module author's intents) state.
138138
139-
The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
140-
not set already, with the appropriate values. The spec's loader will
141-
be set to the module's ``__loader__`` (if set) and to an instance of
142-
:class:`~importlib.machinery.SourceFileLoader` otherwise.
139+
The module's :attr:`~module.__spec__` and :attr:`~module.__loader__` will be
140+
set, if not set already, with the appropriate values. The spec's loader
141+
will be set to the module's :attr:`!__loader__` (if set) and to an instance
142+
of :class:`~importlib.machinery.SourceFileLoader` otherwise.
143143
144-
The module's :attr:`__file__` attribute will be set to the code object's
145-
:attr:`~codeobject.co_filename`. If applicable, :attr:`__cached__` will also
146-
be set.
144+
The module's :attr:`~module.__file__` attribute will be set to the code
145+
object's :attr:`~codeobject.co_filename`. If applicable,
146+
:attr:`~module.__cached__` will also be set.
147147
148148
This function will reload the module if it was already imported. See
149149
:c:func:`PyImport_ReloadModule` for the intended way to reload a module.
@@ -155,29 +155,29 @@ Importing Modules
155155
:c:func:`PyImport_ExecCodeModuleWithPathnames`.
156156
157157
.. versionchanged:: 3.12
158-
The setting of :attr:`__cached__` and :attr:`__loader__` is
159-
deprecated. See :class:`~importlib.machinery.ModuleSpec` for
158+
The setting of :attr:`~module.__cached__` and :attr:`~module.__loader__`
159+
is deprecated. See :class:`~importlib.machinery.ModuleSpec` for
160160
alternatives.
161161
162162
163163
.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
164164
165-
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
166-
the module object is set to *pathname* if it is non-``NULL``.
165+
Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`~module.__file__`
166+
attribute of the module object is set to *pathname* if it is non-``NULL``.
167167
168168
See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
169169
170170
171171
.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
172172
173-
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
173+
Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`~module.__cached__`
174174
attribute of the module object is set to *cpathname* if it is
175175
non-``NULL``. Of the three functions, this is the preferred one to use.
176176
177177
.. versionadded:: 3.3
178178
179179
.. versionchanged:: 3.12
180-
Setting :attr:`__cached__` is deprecated. See
180+
Setting :attr:`~module.__cached__` is deprecated. See
181181
:class:`~importlib.machinery.ModuleSpec` for alternatives.
182182
183183

‎_sources/c-api/init.rst.txt

Lines changed: 142 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
Initialization, Finalization, and Threads
88
*****************************************
99

10-
See also :ref:`Python Initialization Configuration <init-config>`.
10+
See :ref:`Python Initialization Configuration <init-config>` for details
11+
on how to configure the interpreter prior to initialization.
1112

1213
.. _pre-init-safe:
1314

@@ -21,6 +22,15 @@ a few functions and the :ref:`global configuration variables
2122

2223
The following functions can be safely called before Python is initialized:
2324

25+
* Functions that initialize the interpreter:
26+
27+
* :c:func:`Py_Initialize`
28+
* :c:func:`Py_InitializeEx`
29+
* :c:func:`Py_InitializeFromConfig`
30+
* :c:func:`Py_BytesMain`
31+
* :c:func:`Py_Main`
32+
* the runtime pre-initialization functions covered in :ref:`init-config`
33+
2434
* Configuration functions:
2535

2636
* :c:func:`PyImport_AppendInittab`
@@ -32,6 +42,7 @@ The following functions can be safely called before Python is initialized:
3242
* :c:func:`Py_SetProgramName`
3343
* :c:func:`Py_SetPythonHome`
3444
* :c:func:`PySys_ResetWarnOptions`
45+
* the configuration functions covered in :ref:`init-config`
3546

3647
* Informative functions:
3748

@@ -43,10 +54,12 @@ The following functions can be safely called before Python is initialized:
4354
* :c:func:`Py_GetCopyright`
4455
* :c:func:`Py_GetPlatform`
4556
* :c:func:`Py_GetVersion`
57+
* :c:func:`Py_IsInitialized`
4658

4759
* Utilities:
4860

4961
* :c:func:`Py_DecodeLocale`
62+
* the status reporting and utility functions covered in :ref:`init-config`
5063

5164
* Memory allocators:
5265

@@ -62,11 +75,13 @@ The following functions can be safely called before Python is initialized:
6275

6376
.. note::
6477

65-
The following functions **should not be called** before
66-
:c:func:`Py_Initialize`: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
78+
Despite their apparent similarity to some of the functions listed above,
79+
the following functions **should not be called** before the interpreter has
80+
been initialized: :c:func:`Py_EncodeLocale`, :c:func:`Py_GetPath`,
6781
:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`,
6882
:c:func:`Py_GetProgramFullPath`, :c:func:`Py_GetPythonHome`,
69-
:c:func:`Py_GetProgramName` and :c:func:`PyEval_InitThreads`.
83+
:c:func:`Py_GetProgramName`, :c:func:`PyEval_InitThreads`, and
84+
:c:func:`Py_RunMain`.
7085

7186

7287
.. _global-conf-vars:
@@ -346,34 +361,42 @@ Initializing and finalizing the interpreter
346361
this should be called before using any other Python/C API functions; see
347362
:ref:`Before Python Initialization <pre-init-safe>` for the few exceptions.
348363

349-
This initializes
350-
the table of loaded modules (``sys.modules``), and creates the fundamental
351-
modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. It also initializes
352-
the module search path (``sys.path``). It does not set ``sys.argv``; use
353-
the new :c:type:`PyConfig` API of the :ref:`Python Initialization
354-
Configuration <init-config>` for that. This is a no-op when called for a
355-
second time
356-
(without calling :c:func:`Py_FinalizeEx` first). There is no return value; it is a
357-
fatal error if the initialization fails.
358-
359-
Use the :c:func:`Py_InitializeFromConfig` function to customize the
364+
This initializes the table of loaded modules (``sys.modules``), and creates
365+
the fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`.
366+
It also initializes the module search path (``sys.path``). It does not set
367+
``sys.argv``; use the :ref:`Python Initialization Configuration <init-config>`
368+
API for that. This is a no-op when called for a second time (without calling
369+
:c:func:`Py_FinalizeEx` first). There is no return value; it is a fatal
370+
error if the initialization fails.
371+
372+
Use :c:func:`Py_InitializeFromConfig` to customize the
360373
:ref:`Python Initialization Configuration <init-config>`.
361374

362375
.. note::
363-
On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``, which will
364-
also affect non-Python uses of the console using the C Runtime.
376+
On Windows, changes the console mode from ``O_TEXT`` to ``O_BINARY``,
377+
which will also affect non-Python uses of the console using the C Runtime.
365378

366379

367380
.. c:function:: void Py_InitializeEx(int initsigs)
368381
369382
This function works like :c:func:`Py_Initialize` if *initsigs* is ``1``. If
370-
*initsigs* is ``0``, it skips initialization registration of signal handlers, which
371-
might be useful when Python is embedded.
383+
*initsigs* is ``0``, it skips initialization registration of signal handlers,
384+
which may be useful when CPython is embedded as part of a larger application.
372385
373-
Use the :c:func:`Py_InitializeFromConfig` function to customize the
386+
Use :c:func:`Py_InitializeFromConfig` to customize the
374387
:ref:`Python Initialization Configuration <init-config>`.
375388
376389
390+
.. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config)
391+
392+
Initialize Python from *config* configuration, as described in
393+
:ref:`init-from-config`.
394+
395+
See the :ref:`init-config` section for details on pre-initializing the
396+
interpreter, populating the runtime configuration structure, and querying
397+
the returned status structure.
398+
399+
377400
.. c:function:: int Py_IsInitialized()
378401
379402
Return true (nonzero) when the Python interpreter has been initialized, false
@@ -430,12 +453,111 @@ Initializing and finalizing the interpreter
430453
431454
.. versionadded:: 3.6
432455
456+
433457
.. c:function:: void Py_Finalize()
434458
435459
This is a backwards-compatible version of :c:func:`Py_FinalizeEx` that
436460
disregards the return value.
437461
438462
463+
.. c:function:: int Py_BytesMain(int argc, char **argv)
464+
465+
Similar to :c:func:`Py_Main` but *argv* is an array of bytes strings,
466+
allowing the calling application to delegate the text decoding step to
467+
the CPython runtime.
468+
469+
.. versionadded:: 3.8
470+
471+
472+
.. c:function:: int Py_Main(int argc, wchar_t **argv)
473+
474+
The main program for the standard interpreter, encapsulating a full
475+
initialization/finalization cycle, as well as additional
476+
behaviour to implement reading configurations settings from the environment
477+
and command line, and then executing ``__main__`` in accordance with
478+
:ref:`using-on-cmdline`.
479+
480+
This is made available for programs which wish to support the full CPython
481+
command line interface, rather than just embedding a Python runtime in a
482+
larger application.
483+
484+
The *argc* and *argv* parameters are similar to those which are passed to a
485+
C program's :c:func:`main` function, except that the *argv* entries are first
486+
converted to ``wchar_t`` using :c:func:`Py_DecodeLocale`. It is also
487+
important to note that the argument list entries may be modified to point to
488+
strings other than those passed in (however, the contents of the strings
489+
pointed to by the argument list are not modified).
490+
491+
The return value will be ``0`` if the interpreter exits normally (i.e.,
492+
without an exception), ``1`` if the interpreter exits due to an exception,
493+
or ``2`` if the argument list does not represent a valid Python command
494+
line.
495+
496+
Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
497+
function will not return ``1``, but exit the process, as long as
498+
``Py_InspectFlag`` is not set. If ``Py_InspectFlag`` is set, execution will
499+
drop into the interactive Python prompt, at which point a second otherwise
500+
unhandled :exc:`SystemExit` will still exit the process, while any other
501+
means of exiting will set the return value as described above.
502+
503+
In terms of the CPython runtime configuration APIs documented in the
504+
:ref:`runtime configuration <init-config>` section (and without accounting
505+
for error handling), ``Py_Main`` is approximately equivalent to::
506+
507+
PyConfig config;
508+
PyConfig_InitPythonConfig(&config);
509+
PyConfig_SetArgv(&config, argc, argv);
510+
Py_InitializeFromConfig(&config);
511+
PyConfig_Clear(&config);
512+
513+
Py_RunMain();
514+
515+
In normal usage, an embedding application will call this function
516+
*instead* of calling :c:func:`Py_Initialize`, :c:func:`Py_InitializeEx` or
517+
:c:func:`Py_InitializeFromConfig` directly, and all settings will be applied
518+
as described elsewhere in this documentation. If this function is instead
519+
called *after* a preceding runtime initialization API call, then exactly
520+
which environmental and command line configuration settings will be updated
521+
is version dependent (as it depends on which settings correctly support
522+
being modified after they have already been set once when the runtime was
523+
first initialized).
524+
525+
526+
.. c:function:: int Py_RunMain(void)
527+
528+
Executes the main module in a fully configured CPython runtime.
529+
530+
Executes the command (:c:member:`PyConfig.run_command`), the script
531+
(:c:member:`PyConfig.run_filename`) or the module
532+
(:c:member:`PyConfig.run_module`) specified on the command line or in the
533+
configuration. If none of these values are set, runs the interactive Python
534+
prompt (REPL) using the ``__main__`` module's global namespace.
535+
536+
If :c:member:`PyConfig.inspect` is not set (the default), the return value
537+
will be ``0`` if the interpreter exits normally (that is, without raising
538+
an exception), or ``1`` if the interpreter exits due to an exception. If an
539+
otherwise unhandled :exc:`SystemExit` is raised, the function will immediately
540+
exit the process instead of returning ``1``.
541+
542+
If :c:member:`PyConfig.inspect` is set (such as when the :option:`-i` option
543+
is used), rather than returning when the interpreter exits, execution will
544+
instead resume in an interactive Python prompt (REPL) using the ``__main__``
545+
module's global namespace. If the interpreter exited with an exception, it
546+
is immediately raised in the REPL session. The function return value is
547+
then determined by the way the *REPL session* terminates: returning ``0``
548+
if the session terminates without raising an unhandled exception, exiting
549+
immediately for an unhandled :exc:`SystemExit`, and returning ``1`` for
550+
any other unhandled exception.
551+
552+
This function always finalizes the Python interpreter regardless of whether
553+
it returns a value or immediately exits the process due to an unhandled
554+
:exc:`SystemExit` exception.
555+
556+
See :ref:`Python Configuration <init-python-config>` for an example of a
557+
customized Python that always runs in isolated mode using
558+
:c:func:`Py_RunMain`.
559+
560+
439561
Process-wide parameters
440562
=======================
441563

‎_sources/c-api/init_config.rst.txt

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1348,14 +1348,13 @@ the :option:`-X` command line option.
13481348
The ``show_alloc_count`` field has been removed.
13491349
13501350
1351+
.. _init-from-config:
1352+
13511353
Initialization with PyConfig
13521354
============================
13531355
1354-
Function to initialize Python:
1355-
1356-
.. c:function:: PyStatus Py_InitializeFromConfig(const PyConfig *config)
1357-
1358-
Initialize Python from *config* configuration.
1356+
Initializing the interpreter from a populated configuration struct is handled
1357+
by calling :c:func:`Py_InitializeFromConfig`.
13591358
13601359
The caller is responsible to handle exceptions (error or exit) using
13611360
:c:func:`PyStatus_Exception` and :c:func:`Py_ExitStatusException`.
@@ -1585,26 +1584,6 @@ The ``__PYVENV_LAUNCHER__`` environment variable is used to set
15851584
:c:member:`PyConfig.base_executable`.
15861585
15871586
1588-
Py_RunMain()
1589-
============
1590-
1591-
.. c:function:: int Py_RunMain(void)
1592-
1593-
Execute the command (:c:member:`PyConfig.run_command`), the script
1594-
(:c:member:`PyConfig.run_filename`) or the module
1595-
(:c:member:`PyConfig.run_module`) specified on the command line or in the
1596-
configuration.
1597-
1598-
By default and when if :option:`-i` option is used, run the REPL.
1599-
1600-
Finally, finalizes Python and returns an exit status that can be passed to
1601-
the ``exit()`` function.
1602-
1603-
See :ref:`Python Configuration <init-python-config>` for an example of
1604-
customized Python always running in isolated mode using
1605-
:c:func:`Py_RunMain`.
1606-
1607-
16081587
Py_GetArgcArgv()
16091588
================
16101589

0 commit comments

Comments
 (0)