Skip to content

[3.14] gh-101100: Resolve some os sphinx reference warnings (GH-139636) #151765

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

Closed
miss-islington wants to merge 2 commits into from
+14 −14
Closed

[3.14] gh-101100: Resolve some os sphinx reference warnings (GH-139636) #151765

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
39323db
gh-101100: Resolve some `os` sphinx reference warnings (GH-139636)
cmaloney Oct 8, 2025
c47ba6b
Merge branch '3.14' into backport-fa60354-3.14
serhiy-storchaka Jun 20, 2026
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
28 changes: 14 additions & 14 deletions Doc/library/os.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,8 +219,8 @@ process and user.

You can delete items in this mapping to unset environment variables.
:func:`unsetenv` will be called automatically when an item is deleted from
:data:`os.environ`, and when one of the :meth:`pop` or :meth:`clear` methods is
called.
:data:`os.environ`, and when one of the :meth:`~dict.pop` or

@serhiy-storchaka serhiy-storchaka Jun 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I do not think this was correct. This is not a dict, it has different pop and clear methods. Please revert in main.

@cmaloney cmaloney Jun 20, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I disagree. The special behavior (ex. unsetenv call) is documented as well as the general documentation for mapping types which lives inside the stdtypes documention of dict (https://docs.python.org/3/library/stdtypes.html#mapping-types-dict).

I agree we could document the _Environ special type specifically and/or refer to generic collections.abc.MutableMapping + the specialized __getitem__ and __setitem__ which _Environ uses to specialize behavior. I am happy to review those changes as new PRs and further improvements.

@serhiy-storchaka serhiy-storchaka Jun 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

_Environ is not a dict subclass. It should refer to MutableMapping.

@cmaloney cmaloney Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

That unfortunately doesn't define what pop or clear should generally do: https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping

@serhiy-storchaka serhiy-storchaka Jun 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is a separate issue, bur references to dict are incorrect.

This is why we have to keep warnings. As a signal that something need to be fixed.

@cmaloney cmaloney Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I'm happy for others to work on these changes. I was attempting to make improvements.

:meth:`~dict.clear` methods is called.

.. seealso::

Expand Down Expand Up @@ -433,8 +433,8 @@ process and user.
associated with the effective user id of the process; the group access
list may change over the lifetime of the process, it is not affected by
calls to :func:`setgroups`, and its length is not limited to 16. The
deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be
obtained with :func:`sysconfig.get_config_var`.
deployment target value can be obtained with
:func:`sysconfig.get_config_var('MACOSX_DEPLOYMENT_TARGET') <sysconfig.get_config_var>`.


.. function:: getlogin()
Expand Down Expand Up @@ -2596,10 +2596,10 @@ features:

Create a filesystem node (file, device special file or named pipe) named
*path*. *mode* specifies both the permissions to use and the type of node
to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``,
``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are
available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``,
*device* defines the newly created device special file (probably using
to be created, being combined (bitwise OR) with one of :const:`stat.S_IFREG`,
:const:`stat.S_IFCHR`, :const:`stat.S_IFBLK`, and :const:`stat.S_IFIFO`.
For :const:`stat.S_IFCHR` and :const:`stat.S_IFBLK`, *device* defines the
newly created device special file (probably using
:func:`os.makedev`), otherwise it is ignored.

This function can also support :ref:`paths relative to directory descriptors
Expand All @@ -2617,13 +2617,13 @@ features:
.. function:: major(device, /)

Extract the device major number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :c:struct:`stat`).
:attr:`~stat_result.st_dev` or :attr:`~stat_result.st_rdev` field from :c:struct:`stat`).


.. function:: minor(device, /)

Extract the device minor number from a raw device number (usually the
:attr:`st_dev` or :attr:`st_rdev` field from :c:struct:`stat`).
:attr:`~stat_result.st_dev` or :attr:`~stat_result.st_rdev` field from :c:struct:`stat`).


.. function:: makedev(major, minor, /)
Expand Down Expand Up @@ -3350,8 +3350,8 @@ features:

.. versionchanged:: 3.8
On Windows, the :attr:`st_mode` member now identifies special
files as :const:`S_IFCHR`, :const:`S_IFIFO` or :const:`S_IFBLK`
as appropriate.
files as :const:`~stat.S_IFCHR`, :const:`~stat.S_IFIFO` or
:const:`~stat.S_IFBLK` as appropriate.

.. versionchanged:: 3.12
On Windows, :attr:`st_ctime` is deprecated. Eventually, it will
Expand Down Expand Up @@ -4270,10 +4270,10 @@ to be ignored.

.. function:: abort()

Generate a :const:`SIGABRT` signal to the current process. On Unix, the default
Generate a :const:`~signal.SIGABRT` signal to the current process. On Unix, the default
behavior is to produce a core dump; on Windows, the process immediately returns
an exit code of ``3``. Be aware that calling this function will not call the
Python signal handler registered for :const:`SIGABRT` with
Python signal handler registered for :const:`~signal.SIGABRT` with
:func:`signal.signal`.


Expand Down
Loading