The structure definition for `PyTypeObject` is in `Include/cpython/object.h`,
not in `Include/object.h`.
(cherry picked from commit a0478c9f0c)
Co-authored-by: Yuki Kobayashi <drsuaimqjgar@gmail.com>
- Add alignment requirement
- Mention that ob_size is unreliable if you don't control it
- Add some links for context
- basicsize should include the base type in generaly not just PyObject
- suggest Py_SIZE & Py_SET_SIZE
This adds a “by-the-way” link to `PyObject_New`, which shouldn't be
used for GC types. In order to be comfortable linking to it, I also
add a link to `PyObject_GC_New` from its docs. And the same for
`*Var` variants, while I'm here.
(cherry picked from commit ad0f618ab3)
Co-authored-by: Petr Viktorin <encukou@gmail.com>
gh-130814: Enhance documentation for Python C API type objects (GH-130817)
The "Type Objects" title in `c-api/typeobj.rst`, duplicating the title of `c-api/type.rst`,
has been changed to "Type Objects Structures", thereby slightly improving Sphinx
search.
(cherry picked from commit 6b932edc52)
Co-authored-by: sharktide <meherrihaan@gmail.com>
* Clarify sys.getdefaultencoding() documentation
* Add missing documentation for PyUnicode_GetDefaultEncoding,
the C equivalent of sys.getdefaultencoding
(cherry picked from commit 9f25c1f012)
Co-authored-by: RUANG (James Roy) <longjinyii@outlook.com>
gh-46236: Document PyUnicode_RSplit, PyUnicode_Partition and PyUnicode_RPartition (GH-130191)
(cherry picked from commit 0f5b82169e)
Co-authored-by: Marc Mueller <30130371+cdce8p@users.noreply.github.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
We had the definition of what makes a character "printable" documented in three places, giving two different definitions.
The definition in the comment on `_PyUnicode_IsPrintable` was inverted; correct that.
With that correction, the two definitions turn out to be equivalent -- but to confirm that, you have to go look up, or happen to know, that those are the only five "Other" categories and only three "Separator" categories in the Unicode character database. That makes it hard for the reader to tell whether they really are the same, or if there's some subtle difference in the intended semantics.
Fix that by cutting the C API docs' and the C comment's copies of the subtle details, in favor of referring to the Python-level docs. That ensures it's explicit that these are all meant to agree, and also lets us concentrate improvements to the wording in one place.
Speaking of which, borrow some ideas from the C comment, along with other tweaks, to hopefully add a bit more clarity to that one newly-centralized copy in the docs.
Also add a thorough test that the implementation agrees with this definition.
Co-authored-by: Greg Price <gnprice@gmail.com>
(cherry picked from commit 3402e133ef)
gh-130169: Fix broken list markup in `Doc/c-api/function.rst` (GH-130174)
(cherry picked from commit 9837c2a214)
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Docs C API: Clarify what happens when null bytes are passed to `PyUnicode_AsUTF8` (GH-127458)
(cherry picked from commit e792f4bc2e)
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
Co-authored-by: Stan U. <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Tomas R. <tomas.roun8@gmail.com>
Co-authored-by: Victor Stinner <vstinner@python.org>
Doc: C API: Fix `Py_NewInterpreterFromConfig` example code (GH-126667)
(cherry picked from commit e3038e976b)
Co-authored-by: Richard Hansen <rhansen@rhansen.org>
Doc: C API: Demote sections to subsections for consistency (GH-126535)
The entire file should be a single section; the headings below the
first heading should be subsections.
(cherry picked from commit e3510bd3dd)
Co-authored-by: Richard Hansen <rhansen@rhansen.org>
Doc: C API: Delete claim that `PyObject_Init` is GC-aware (GH-126418)
(cherry picked from commit 407c0366d9)
Co-authored-by: Richard Hansen <rhansen@rhansen.org>
Doc: C API: Move `tp_dealloc` paragraph to `tp_dealloc` section (GH-125737)
It looks like commit 43cf44ddcc
(gh-31501) accidentally moved the paragraph to the `tp_finalize`
section when the intent was to move it to the `tp_dealloc` section
(according to the commit message).
(cherry picked from commit d880c83ff7)
Co-authored-by: Richard Hansen <rhansen@rhansen.org>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Barry Warsaw <barry@python.org>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
gh-115145: Update documentation about ``PyThreadState_DeleteCurrent`` (gh-124920)
(cherry picked from commit 9eeb21bf76)
Co-authored-by: Donghee Na <donghee.na@python.org>
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>
gh-123254: Improve `tuple` C API docs with more info about errors (GH-123255)
(cherry picked from commit 6f563e364d)
Co-authored-by: sobolevn <mail@sobolevn.me>
Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
