Skip to content

Clarify argument/result ownership/validity for PyModule_* functions #141159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
encukou merged 2 commits into from
Nov 7, 2025
Merged

Clarify argument/result ownership/validity for PyModule_* functions #141159

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b4f757
Clarify argument/result ownership/validity for PyModule_* functions
encukou Nov 6, 2025
eab71c5
Apply suggestions from code review
encukou Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion Doc/c-api/module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Module Objects
.. index:: single: ModuleType (in module types)

This instance of :c:type:`PyTypeObject` represents the Python module type. This
is exposed to Python programs as ``types.ModuleType``.
is exposed to Python programs as :py:class:`types.ModuleType`.


.. c:function:: int PyModule_Check(PyObject *p)
Expand Down Expand Up @@ -71,6 +71,9 @@ Module Objects
``PyObject_*`` functions rather than directly manipulate a module's
:attr:`~object.__dict__`.

The returned reference is borrowed from the module; it is valid until
the module is destroyed.


.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)

Expand All @@ -90,6 +93,10 @@ Module Objects
Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
``'utf-8'``.

The returned buffer is only valid until the module is renamed or destroyed.
Note that Python code may rename a module by setting its :py:attr:`~module.__name__`
attribute.

.. c:function:: void* PyModule_GetState(PyObject *module)

Return the "state" of the module, that is, a pointer to the block of memory
Expand Down Expand Up @@ -126,6 +133,9 @@ Module Objects
Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
encoded to 'utf-8'.

The returned buffer is only valid until the module's :py:attr:`~module.__file__` attribute
is reassigned or the module is destroyed.

.. deprecated:: 3.2
:c:func:`PyModule_GetFilename` raises :exc:`UnicodeEncodeError` on
unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
Expand Down Expand Up @@ -671,6 +681,9 @@ or code that creates modules dynamically.
:c:type:`PyMethodDef` arrays; in that case they should call this function
directly.

The *functions* array must be statically allocated (or otherwise guaranteed
to outlive the module object).
Comment on lines +684 to +685
Copy link
Member

@ZeroIntensity ZeroIntensity Nov 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a little bit confusing to say something must be true, and then immediately contradict it. How about we say something like this?

The *functions* array must outlive the module object. A common way to do
this is to statically allocate it.

Comment on lines +684 to +685
Copy link
Member Author

@encukou encukou Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think there is a practical alternative unless you're doing something really special, so I would like keep this footnote-ish -- but part of the same sentence to avoid wording like “as a special exception”.

Copy link
Member

@ZeroIntensity ZeroIntensity Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I don't wholly agree, but I won't bother arguing about it.


.. versionadded:: 3.5

.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
Expand Down
Loading