Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .github/codecov.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ codecov:
comment: off
ignore:
- "Doc/**/*"
- "Misc/**/*"
- "Misc/*"
- "Mac/**/*"
- "PC/**/*"
- "PCbuild/**/*"
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/coverage.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ jobs:
|| true
- name: 'Publish code coverage results'
run: |
source ./.venv/bin/activate
./.venv/bin/python -m coverage xml
bash <(curl -s https://codecov.io/bash)
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
Expand Down
18 changes: 9 additions & 9 deletions .github/workflows/doc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,17 +23,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: 'Install Dependencies'
run: sudo ./.github/workflows/posix-deps-apt.sh && sudo apt-get install wamerican
- name: 'Configure CPython'
run: ./configure --with-pydebug
- name: 'Build CPython'
run: make -s -j4
- uses: actions/setup-python@v1
with:
python-version: '3.7'
architecture: 'x64'
- name: 'Install build dependencies'
run: make -C Doc/ PYTHON=../python venv
run: python -m pip install sphinx==2.2.0 blurb python-docs-theme
- name: 'Build documentation'
run: xvfb-run make -C Doc/ PYTHON=../python SPHINXOPTS="-q -W -j4" doctest suspicious html
- name: 'Upload'
run: |
cd Doc
make check suspicious html PYTHON=python
- name: Upload
uses: actions/upload-artifact@v1
with:
name: doc-html
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/code.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ bound into a function.

.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *lnotab)

Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positional-only arguments.
Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positonal-only arguments.

.. versionadded:: 3.8

Expand Down
9 changes: 4 additions & 5 deletions Doc/c-api/dict.rst
Original file line number Diff line number Diff line change
Expand Up @@ -62,20 +62,19 @@ Dictionary Objects

.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)

Insert *val* into the dictionary *p* with a key of *key*. *key* must be
Insert *value* into the dictionary *p* with a key of *key*. *key* must be
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure. This function *does not* steal a
reference to *val*.
``0`` on success or ``-1`` on failure.


.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)

.. index:: single: PyUnicode_FromString()

Insert *val* into the dictionary *p* using *key* as a key. *key* should
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :c:type:`const char\*`. The key object is created using
``PyUnicode_FromString(key)``. Return ``0`` on success or ``-1`` on
failure. This function *does not* steal a reference to *val*.
failure.


.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
Expand Down
60 changes: 19 additions & 41 deletions Doc/c-api/init.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1048,10 +1048,6 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
Reset all information in a thread state object. The global interpreter lock
must be held.

.. versionchanged:: 3.9
This function now calls the :c:member:`PyThreadState.on_delete` callback.
Previously, that happened in :c:func:`PyThreadState_Delete`.


.. c:function:: void PyThreadState_Delete(PyThreadState *tstate)

Expand Down Expand Up @@ -1114,7 +1110,7 @@ All of the following functions must be called after :c:func:`Py_Initialize`.
.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate)

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.
*tstate*, which should not be ``NULL``. The lock must have been created earlier.
If this thread already has the lock, deadlock ensues.

.. note::
Expand Down Expand Up @@ -1193,7 +1189,7 @@ 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.
:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.

You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
function. You can create and destroy them using the following functions:
Expand Down Expand Up @@ -1234,31 +1230,15 @@ function. You can create and destroy them using the following functions:
single: Py_FinalizeEx()
single: Py_Initialize()

Extension modules are shared between (sub-)interpreters as follows:

* 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.

* 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).

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.
Extension modules are shared between (sub-)interpreters as follows: 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. 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.

.. index:: single: close() (in module os)

Expand All @@ -1284,16 +1264,14 @@ 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.

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.
work properly; this is especially likely when the extension makes use of
(static) global variables, or when the extension manipulates its module's
dictionary after its initialization. It is possible to insert objects created
in one sub-interpreter into a namespace of another sub-interpreter; this should
be done with great care 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.

Also note that combining this functionality with :c:func:`PyGILState_\*` APIs
is delicate, because these APIs assume a bijection between Python thread states
Expand Down
16 changes: 10 additions & 6 deletions Doc/c-api/init_config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -466,7 +466,7 @@ PyConfig

.. c:member:: int dev_mode

If non-zero, enable the :ref:`Python Development Mode <devmode>`.
Development mode: see :option:`-X dev <-X>`.

.. c:member:: int dump_refs

Expand Down Expand Up @@ -627,6 +627,14 @@ PyConfig

``python3 -m MODULE`` argument. Used by :c:func:`Py_RunMain`.

.. c:member:: int show_alloc_count

Show allocation counts at exit?

Set to 1 by :option:`-X showalloccount <-X>` command line option.

Need a special Python build with ``COUNT_ALLOCS`` macro defined.

.. c:member:: int show_ref_count

Show total reference count at exit?
Expand Down Expand Up @@ -694,10 +702,6 @@ arguments are stripped from ``argv``: see :ref:`Command Line Arguments
The ``xoptions`` options are parsed to set other options: see :option:`-X`
option.

.. versionchanged:: 3.9

The ``show_alloc_count`` field has been removed.


Initialization with PyConfig
----------------------------
Expand Down Expand Up @@ -753,7 +757,7 @@ configuration, and then override some parameters::
PyConfig config;
PyConfig_InitPythonConfig(&config);

/* Set the program name before reading the configuration
/* Set the program name before reading the configuraton
(decode byte string from the locale encoding).

Implicitly preinitialize Python. */
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/iter.rst
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ something like this::
/* propagate error */
}

while ((item = PyIter_Next(iterator))) {
while (item = PyIter_Next(iterator)) {
/* do something with item */
...
/* release reference when done */
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/long.rst
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate.
:c:type:`PyLongObject`.

Raise :exc:`OverflowError` if the value of *obj* is out of range for a
:c:type:`long long`.
:c:type:`long`.

Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate.

Expand Down
3 changes: 1 addition & 2 deletions Doc/c-api/mapping.rst
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,7 @@ See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and

Map the string *key* to the value *v* in object *o*. Returns ``-1`` on
failure. This is the equivalent of the Python statement ``o[key] = v``.
See also :c:func:`PyObject_SetItem`. This function *does not* steal a
reference to *v*.
See also :c:func:`PyObject_SetItem`.


.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
Expand Down
3 changes: 1 addition & 2 deletions Doc/c-api/object.rst
Original file line number Diff line number Diff line change
Expand Up @@ -331,8 +331,7 @@ Object Protocol

Map the object *key* to the value *v*. Raise an exception and
return ``-1`` on failure; return ``0`` on success. This is the
equivalent of the Python statement ``o[key] = v``. This function *does
not* steal a reference to *v*.
equivalent of the Python statement ``o[key] = v``.


.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/structures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -350,7 +350,7 @@ Accessing attributes of extension types
.. _pymemberdef-offsets:

Heap allocated types (created using :c:func:`PyType_FromSpec` or similar),
``PyMemberDef`` may contain definitions for the special members
``PyMemberDef`` may contain defintitions for the special members
``__dictoffset__`` and ``__weaklistoffset__``, corresponding to
:c:member:`~PyTypeObject.tp_dictoffset` and
:c:member:`~PyTypeObject.tp_weaklistoffset` in type objects.
Expand Down
34 changes: 34 additions & 0 deletions Doc/c-api/typeobj.rst
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,15 @@ Quick Reference
| :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | |
+------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+

If :const:`COUNT_ALLOCS` is defined then the following (internal-only)
fields exist as well:

* :c:member:`~PyTypeObject.tp_allocs`
* :c:member:`~PyTypeObject.tp_frees`
* :c:member:`~PyTypeObject.tp_maxalloc`
* :c:member:`~PyTypeObject.tp_prev`
* :c:member:`~PyTypeObject.tp_next`

.. [#slots]
A slot name in parentheses indicates it is (effectively) deprecated.
Names in angle brackets should be treated as read-only.
Expand Down Expand Up @@ -1895,6 +1904,31 @@ and :c:type:`PyType_Type` effectively act as defaults.)
.. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9)


The remaining fields are only defined if the feature test macro
:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
documented here for completeness. None of these fields are inherited by
subtypes.

.. c:member:: Py_ssize_t PyTypeObject.tp_allocs

Number of allocations.

.. c:member:: Py_ssize_t PyTypeObject.tp_frees

Number of frees.

.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc

Maximum simultaneously allocated objects.

.. c:member:: PyTypeObject* PyTypeObject.tp_prev

Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.

.. c:member:: PyTypeObject* PyTypeObject.tp_next

Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field.

Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from
any Python thread, not just the thread which created the object (if the object
becomes part of a refcount cycle, that cycle might be collected by a garbage
Expand Down
2 changes: 1 addition & 1 deletion Doc/copyright.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Copyright

Python and this documentation is:

Copyright © 2001-2020 Python Software Foundation. All rights reserved.
Copyright © 2001-2019 Python Software Foundation. All rights reserved.

Copyright © 2000 BeOpen.com. All rights reserved.

Expand Down
2 changes: 1 addition & 1 deletion Doc/distutils/examples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,7 @@ Running the ``check`` command will display some warnings:
running check
warning: check: missing required meta-data: version, url
warning: check: missing meta-data: either (author and author_email) or
(maintainer and maintainer_email) should be supplied
(maintainer and maintainer_email) must be supplied


If you use the reStructuredText syntax in the ``long_description`` field and
Expand Down
2 changes: 0 additions & 2 deletions Doc/faq/design.rst
Original file line number Diff line number Diff line change
Expand Up @@ -148,8 +148,6 @@ variables and instance variables live in two different namespaces, and you need
to tell Python which namespace to use.


.. _why-can-t-i-use-an-assignment-in-an-expression:

Why can't I use an assignment in an expression?
-----------------------------------------------

Expand Down
2 changes: 1 addition & 1 deletion Doc/faq/programming.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1019,7 +1019,7 @@ That's a tough one, in general. First, here are a list of things to
remember before diving further:

* Performance characteristics vary across Python implementations. This FAQ
focuses on :term:`CPython`.
focusses on :term:`CPython`.
* Behaviour can vary across operating systems, especially when talking about
I/O or multi-threading.
* You should always find the hot spots in your program *before* attempting to
Expand Down
8 changes: 3 additions & 5 deletions Doc/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -824,11 +824,9 @@ Glossary
.. _positional-only_parameter:

* :dfn:`positional-only`: specifies an argument that can be supplied only
by position. Positional-only parameters can be defined by including a
``/`` character in the parameter list of the function definition after
them, for example *posonly1* and *posonly2* in the following::

def func(posonly1, posonly2, /, positional_or_keyword): ...
by position. Python has no syntax for defining positional-only
parameters. However, some built-in functions have positional-only
parameters (e.g. :func:`abs`).

.. _keyword-only_parameter:

Expand Down
6 changes: 3 additions & 3 deletions Doc/howto/functional.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1229,9 +1229,9 @@ Text Processing".

Mertz also wrote a 3-part series of articles on functional programming
for IBM's DeveloperWorks site; see
`part 1 <https://developer.ibm.com/articles/l-prog/>`__,
`part 2 <https://developer.ibm.com/tutorials/l-prog2/>`__, and
`part 3 <https://developer.ibm.com/tutorials/l-prog3/>`__,
`part 1 <https://www.ibm.com/developerworks/linux/library/l-prog/index.html>`__,
`part 2 <https://www.ibm.com/developerworks/linux/library/l-prog2/index.html>`__, and
`part 3 <https://www.ibm.com/developerworks/linux/library/l-prog3/index.html>`__,


Python documentation
Expand Down
Loading