PEP 683 (immortal objects) revealed some ways in which the Python documentation has been unnecessarily coupled to the implementation details of reference counts. In the end users should focus on reference ownership, including taking references and releasing them, rather than on how many reference counts an object has.
This change updates the documentation to reflect that perspective. It also updates the docs relative to immortal objects in a handful of places.
Declare the following functions as macros, since they are actually
macros. It avoids a warning on "TYPE" or "macro" argument.
* PyMem_New()
* PyMem_Resize()
* PyModule_AddIntMacro()
* PyModule_AddStringMacro()
* PyObject_GC_New()
* PyObject_GC_NewVar()
* PyObject_New()
* PyObject_NewVar()
Add C standard C types to nitpick_ignore in Doc/conf.py:
* int64_t
* uint64_t
* uintptr_t
No longer ignore non existing "__int" type in nitpick_ignore.
Update Doc/tools/.nitignore
* Uncomment object removal in pairindextypes
* Use new-style index directive ('object') - C API
* Use new-style index directive ('object') - Library
* Use new-style index directive ('object') - Reference
* Use new-style index directive ('object') - Tutorial
I think that none of these API calls can fail, but only few of them are
documented as such. Add the sentence "This function always succeeds" (which is
the same already used e.g. by PyNumber_Check) to all of them.
For example, fix the following Sphinx 3 errors:
Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
void \*obj
-----^
Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
PyObject*
--------^
The modified documentation is compatible with Sphinx 2 and Sphinx 3.
Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs.
Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvar#c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`.
Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link.
Extension modules: m_traverse, m_clear and m_free functions of
PyModuleDef are no longer called if the module state was requested
but is not allocated yet. This is the case immediately after the
module is created and before the module is executed (Py_mod_exec
function). More precisely, these functions are not called if m_size is
greater than 0 and the module state (as returned by
PyModule_GetState()) is NULL.
Extension modules without module state (m_size <= 0) are not affected.
Co-Authored-By: Petr Viktorin <encukou@gmail.com>
* Add a note to the PyModule_AddObject docs.
* Correct example usages of PyModule_AddObject.
* Whitespace.
* Clean up wording.
* 📜🤖 Added by blurb_it.
* First code review.
* Add < 0 in the tests with PyModule_AddObject
Multi-phase initialized modules allow m_traverse to be called while the
module is still being initialized, so module authors may need to account
for that.
Multi-phase extension module import now correctly allows the
``m_methods`` field to be used to add module level functions
to instances of non-module types returned from ``Py_create_mod``.
Patch by Xiang Zhang.
Known limitations of the current implementation:
- documentation changes are incomplete
- there's a reference leak I haven't tracked down yet
The leak is most visible by running:
./python -m test -R3:3 test_importlib
However, you can also see it by running:
./python -X showrefcount
Importing the array or _testmultiphase modules, and
then deleting them from both sys.modules and the local
namespace shows significant increases in the total
number of active references each cycle. By contrast,
with _testcapi (which continues to use single-phase
initialisation) the global refcounts stabilise after
a couple of cycles.
attributes to None.
The long-term goal is for people to be able to rely on these
attributes existing and checking for None to see if they have been
set. Since import itself sets these attributes when a loader does not
the only instances when the attributes are None are from someone
overloading __import__() and not using a loader or someone creating a
module from scratch.
This patch also unifies module initialization. Before you could have
different attributes with default values depending on how the module
object was created. Now the only way to not get the same default set
of attributes is to circumvent initialization by calling
ModuleType.__new__() directly.
repr(module) uses %R to format module name and filenames, instead of '%s' and
'%U', so surrogates from undecodable bytes in a filename (PEP 383) are escaped.
Serhiy Storchaka
Eric Snow
Victor Stinner
Adam Turner
Oleg Iarygin
Petr Viktorin
Antonio Cuni
Brad Solomon
Dong-hee Na
Brandt Bucher
Stéphane Wirtel
Marcel Plch
Emily Morehouse
Nick Coghlan
Berker Peksag
Martin Panter
Zachary Ware
Eli Bendersky
Brett Cannon
Ezio Melotti
Martin v. Löwis
Georg Brandl
Benjamin Peterson
Victor Stinner