summaryrefslogtreecommitdiffstats
path: root/Doc/c-api/module.rst
Commit message (Collapse)AuthorAgeFilesLines
* [3.12] gh-113993: Make interned strings mortal (GH-120520, GH-121364, ↵Petr Viktorin2024-09-271-0/+15
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | GH-121903, GH-122303) (#123065) This backports several PRs for gh-113993, making interned strings mortal so they can be garbage-collected when no longer needed. * Allow interned strings to be mortal, and fix related issues (GH-120520) * Add an InternalDocs file describing how interning should work and how to use it. * Add internal functions to *explicitly* request what kind of interning is done: - `_PyUnicode_InternMortal` - `_PyUnicode_InternImmortal` - `_PyUnicode_InternStatic` * Switch uses of `PyUnicode_InternInPlace` to those. * Disallow using `_Py_SetImmortal` on strings directly. You should use `_PyUnicode_InternImmortal` instead: - Strings should be interned before immortalization, otherwise you're possibly interning a immortalizing copy. - `_Py_SetImmortal` doesn't handle the `SSTATE_INTERNED_MORTAL` to `SSTATE_INTERNED_IMMORTAL` update, and those flags can't be changed in backports, as they are now part of public API and version-specific ABI. * Add private `_only_immortal` argument for `sys.getunicodeinternedsize`, used in refleak test machinery. Make sure the statically allocated string singletons are unique. This means these sets are now disjoint: - `_Py_ID` - `_Py_STR` (including the empty string) - one-character latin-1 singletons Now, when you intern a singleton, that exact singleton will be interned. * Add a `_Py_LATIN1_CHR` macro, use it instead of `_Py_ID`/`_Py_STR` for one-character latin-1 singletons everywhere (including Clinic). * Intern `_Py_STR` singletons at startup. * Beef up the tests. Cover internal details (marked with `@cpython_only`). * Add lots of assertions * Don't immortalize in PyUnicode_InternInPlace; keep immortalizing in other API (GH-121364) * Switch PyUnicode_InternInPlace to _PyUnicode_InternMortal, clarify docs * Document immortality in some functions that take `const char *` This is PyUnicode_InternFromString; PyDict_SetItemString, PyObject_SetAttrString; PyObject_DelAttrString; PyUnicode_InternFromString; and the PyModule_Add convenience functions. Always point out a non-immortalizing alternative. * Don't immortalize user-provided attr names in _ctypes * Immortalize names in code objects to avoid crash (GH-121903) * Intern latin-1 one-byte strings at startup (GH-122303) There are some 3.12-specific changes, mainly to allow statically allocated strings in deepfreeze. (In 3.13, deepfreeze switched to the general `_Py_ID`/`_Py_STR`.) Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
* [3.12] GH-121970: Rewrite the C-API annotations extension (GH-121985) (#122025)Adam Turner2024-07-191-2/+4
| | | | | (cherry picked from commit 22c9d9c1fcc3bb6186524330b169eda6df450f1b) Co-authored-by: Petr Viktorin <encukou@gmail.com>
* [3.12] gh-121749: Fix discrepancy in docs for `PyModule_AddObjectRef` ↵Miss Islington (bot)2024-07-141-1/+1
| | | | | | | (GH-121750) (GH-121753) (cherry picked from commit 26dfb2771236bfd96cdaa1081103f75141ecff47) Co-authored-by: Dominic H <dom@dominic.sk>
* [3.12] gh-121615: Improve `module.rst` C-API docs with better error ↵sobolevn2024-07-111-7/+14
| | | | | descriptions (GH-121616) (#121619) (cherry picked from commit e6264b44dc7221c713b14dfa0f5929b33d362829)
* [3.12] gh-107298: Fix numerous ref errors and typos in the C API docs ↵Miss Islington (bot)2023-08-221-0/+4
| | | | | | | | (GH-108258) (#108284) gh-107298: Fix numerous ref errors and typos in the C API docs (GH-108258) (cherry picked from commit d7202e4879bf4e7e00a69500ddcb3143864139b4) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* [3.12] gh-98154: Clarify Usage of "Reference Count" In the Docs (gh-107552) ↵Miss Islington (bot)2023-08-081-1/+1
| | | | | | | | | | | | | | | | | | (#107752) * gh-98154: Clarify Usage of "Reference Count" In the Docs (gh-107552) 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. (cherry picked from commit 5dc825d504ad08d64c9d1ce578f9deebbe012604) Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com> * Fix a typo. --------- Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
* [3.12] gh-107306: Add a Doc Entry for Py_mod_multiple_interpreters ↵Miss Islington (bot)2023-07-311-0/+31
| | | | | | | | | | (GH-107403) (gh-107521) gh-107306: Add a Doc Entry for Py_mod_multiple_interpreters (GH-107403) It was added in 3.12 for PEP 684 (per-interpreter GIL). (cherry picked from commit fb344e99aa0da5bef9318684ade69978585fe060) Co-authored-by: Eric Snow <ericsnowcurrently@gmail.com>
* [3.12] gh-107298: Fix yet more Sphinx warnings in the C API doc (GH-107345) ↵Serhiy Storchaka2023-07-281-1/+1
| | | | | (GH-107380) (cherry picked from commit 983305268e2291b0a7835621b81bf40cba7c27f3)
* [3.12] gh-107298: Fix more Sphinx warnings in the C API doc (GH-107329) ↵Serhiy Storchaka2023-07-281-4/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | (GH-107376) 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. (cherry picked from commit 8d61a71f9c81619e34d4a30b625922ebc83c561b) Co-authored-by: Victor Stinner <vstinner@python.org>
* [3.12] gh-107091: Fix some uses of :c:member: role (GH-107129) (GH-107310)Miss Islington (bot)2023-07-261-4/+4
| | | | | (cherry picked from commit af61cb9c7837ff3c11da79e3ee1cab3fdd0ba4da) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* [3.12] gh-107091: Fix the use of some C domain roles (GH-107092) (GH-107113)Miss Islington (bot)2023-07-231-1/+1
| | | | | (cherry picked from commit 08a228da05a7aec937b65eea21f4091fa3c6b5cf) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
* [3.12] gh-106919: Use role :c:macro: for referencing the C "constants" ↵Serhiy Storchaka2023-07-211-3/+3
| | | | | (GH-106920) (GH-106951) (cherry picked from commit fcc816dbff7ca66c26f57a506e4d2330fe41d0ff)
* GH-97950: Use new-style index directive ('object') (#104158)Adam Turner2023-05-041-1/+1
| | | | | | | | | | | * 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
* gh-101973: Fix parameter reference for PyModule_FromDefAndSpec (#101976)Oleg Iarygin2023-02-171-2/+2
|
* gh-93738: Documentation C syntax (Function glob patterns -> literal markup) ↵Adam Turner2022-10-051-2/+2
| | | | (#97774)
* Note that tp_clear and m_clear are not always called (GH-27581)Petr Viktorin2021-08-041-0/+6
|
* bpo-42528: Improve the docs of most Py*_Check{,Exact} API calls (GH-23602)Antonio Cuni2021-01-061-1/+2
| | | | | 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.
* bpo-1635741: Add PyModule_AddObjectRef() function (GH-23122)Victor Stinner2020-11-041-14/+90
| | | | | Added PyModule_AddObjectRef() function: similar to PyModule_AddObjectRef() but don't steal a reference to the value on success.
* bpo-40204, doc: Fix syntax of C variables (GH-21846)Victor Stinner2020-08-131-2/+2
| | | | | | | | | | | | | | | 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.
* bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607)Brad Solomon2020-04-271-1/+1
| | | | | | | 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.
* bpo-38644: Make tstate more explicit inside pystate.c (GH-19182)Victor Stinner2020-03-261-0/+4
| | | | Fix PyInterpreterState_New(): Don't call PyErr_SetString() when there is no current Python thread state (if tstate is NULL).
* bpo-40024: Add PyModule_AddType() helper function (GH-19088)Dong-hee Na2020-03-221-1/+11
|
* bpo-39824: module_traverse() don't call m_traverse if md_state=NULL (GH-18738)Victor Stinner2020-03-171-10/+34
| | | | | | | | | | | | | 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>
* bpo-38159: Clarify documentation of PyState_AddModule (GH-16101)Petr Viktorin2019-11-011-0/+11
| | | | | This was never intented to be called manually from PyInit_*. Also, clarify PyState_RemoveModule return value.
* bpo-38600: Change the mark up of NULL in the C API documentation. (GH-16950)Serhiy Storchaka2019-10-301-17/+17
| | | | Replace all *NULL* with ``NULL``.
* bpo-26868: Fix example usage of PyModule_AddObject. (#15725)Brandt Bucher2019-09-121-1/+16
| | | | | | | | | | | | | | | | * 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
* Doc: Replace the deprecated highlightlang directive by highlight. (#13377)Stéphane Wirtel2019-05-171-1/+1
| | | | highlightlang is deprecated since April 2018 in Sphinx. See https://github.com/sphinx-doc/sphinx/pull/4845
* bpo-32374: m_traverse may be called with m_state=NULL (GH-5140)Marcel Plch2018-03-171-3/+9
| | | | | 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.
* bpo-30656: Fix Python C API Module Objects documentation (GH-2170)Emily Morehouse2017-06-131-1/+1
| | | `PyModule_New()` now refers to `PyModule_NewObject()`
* bpo-29918: Add missed "const" modifiers in C API documentation. (#846)Serhiy Storchaka2017-03-301-4/+4
|
* Issue #27782: Fix m_methods handling in multiphase initNick Coghlan2016-08-211-1/+1
| | | | | | | | 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.
* Issue #12946: Document that PyModule_GetDict can fail in some casesBerker Peksag2016-08-191-4/+7
|
* Issue #24314: Fix doc links for general attributes like __name__, __dict__Martin Panter2016-06-181-2/+2
|
* Issue #27125: Remove duplicated words from documentation and commentsMartin Panter2016-05-301-1/+1
|
* Correct “an” → “a” with “Unicode”, “user”, “UTF”, etcMartin Panter2016-04-151-1/+1
| | | | This affects documentation, code comments, and a debugging messages.
* Close #24458: PEP 489 documentationNick Coghlan2015-07-031-77/+243
| | | | Patch by Petr Viktorin.
* PEP 489: Multi-phase extension module initializationNick Coghlan2015-05-231-26/+66
| | | | | | | | | | | | | | | | | | | | | | | 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.
* Merge with 3.3Zachary Ware2014-02-261-1/+1
|\
| * Fix several C-API doc typos caught by tomo cocoa on docs@.Zachary Ware2014-02-261-1/+1
| | | | | | | | | | The signature and description of PyException_SetCause now use "cause" rather than "ctx" to match the code.
* | Issue #18668: Further clarify m_size setting for non-negative valuesEli Bendersky2013-08-101-4/+4
|\ \ | |/
| * Issue #18668: Further clarify m_size setting for non-negative valuesEli Bendersky2013-08-101-4/+4
| |
* | Closing #18668: Properly document setting m_size in PyModuleDefEli Bendersky2013-08-071-4/+10
|\ \ | |/
| * Issue #18668: Properly document setting m_size in PyModuleDefEli Bendersky2013-08-071-4/+10
| |
* | #17115,17116: Have modules initialize the __package__ and __loader__Brett Cannon2013-05-041-2/+9
|/ | | | | | | | | | | | | | | | | 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.
* #17363: fix arguments in PyState_AddModule and PyState_RemoveModule docs.Ezio Melotti2013-03-061-2/+2
|
* Issue #15042: Add PyState_AddModule and PyState_RemoveModule.Martin v. Löwis2012-06-221-1/+21
| | | | | | Add version guard for Py_LIMITED_API additions. Issue #15081: Document PyState_FindModule. Patch by Robin Schreiber.
* Update C API docs for PEP 393.Georg Brandl2011-10-071-1/+1
|
* merge 3.2Benjamin Peterson2011-04-301-1/+1
|\
| * merge 3.1Benjamin Peterson2011-04-301-1/+1
| |\
| | * fix function name in example (closes #11966)Benjamin Peterson2011-04-301-1/+1
| | |
generated by cgit v0.12 at 2026-01-04 23:21:55 (GMT)