[Python-checkins] gh-85133: os docs: Add that getenv uses os.environ (GH-91874)
miss-islington
webhook-mailer at python.org
Mon May 2 11:08:48 EDT 2022
https://github.com/python/cpython/commit/5a0f3ae22f8e56fe2e149a73329bd4bcc8987eda
commit: 5a0f3ae22f8e56fe2e149a73329bd4bcc8987eda
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-05-02T08:08:40-07:00
summary:
gh-85133: os docs: Add that getenv uses os.environ (GH-91874)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra at gmail.com>
(cherry picked from commit b25352a5c039d95e019dd8ca111f6f77c43ca1f7)
Co-authored-by: slateny <46876382+slateny at users.noreply.github.com>
files:
M Doc/library/os.rst
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index f8985a1f3ab9d..35a7e1e96d346 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -109,8 +109,8 @@ process and user.
This mapping is captured the first time the :mod:`os` module is imported,
typically during Python startup as part of processing :file:`site.py`. Changes
- to the environment made after this time are not reflected in ``os.environ``,
- except for changes made by modifying ``os.environ`` directly.
+ to the environment made after this time are not reflected in :data:`os.environ`,
+ except for changes made by modifying :data:`os.environ` directly.
This mapping may be used to modify the environment as well as query the
environment. :func:`putenv` will be called automatically when the mapping
@@ -122,8 +122,8 @@ process and user.
.. note::
- Calling :func:`putenv` directly does not change ``os.environ``, so it's better
- to modify ``os.environ``.
+ Calling :func:`putenv` directly does not change :data:`os.environ`, so it's better
+ to modify :data:`os.environ`.
.. note::
@@ -133,7 +133,7 @@ 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
- ``os.environ``, and when one of the :meth:`pop` or :meth:`clear` methods is
+ :data:`os.environ`, and when one of the :meth:`pop` or :meth:`clear` methods is
called.
.. versionchanged:: 3.9
@@ -224,7 +224,10 @@ process and user.
.. function:: getenv(key, default=None)
Return the value of the environment variable *key* if it exists, or
- *default* if it doesn't. *key*, *default* and the result are str.
+ *default* if it doesn't. *key*, *default* and the result are str. Note that
+ since :func:`getenv` uses :data:`os.environ`, the mapping of :func:`getenv` is
+ similarly also captured on import, and the function may not reflect
+ future environment changes.
On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
@@ -236,7 +239,11 @@ process and user.
.. function:: getenvb(key, default=None)
Return the value of the environment variable *key* if it exists, or
- *default* if it doesn't. *key*, *default* and the result are bytes.
+ *default* if it doesn't. *key*, *default* and the result are bytes. Note that
+ since :func:`getenvb` uses :data:`os.environb`, the mapping of :func:`getenvb` is
+ similarly also captured on import, and the function may not reflect
+ future environment changes.
+
:func:`getenvb` is only available if :data:`supports_bytes_environ`
is ``True``.
@@ -443,10 +450,11 @@ process and user.
changes to the environment affect subprocesses started with :func:`os.system`,
:func:`popen` or :func:`fork` and :func:`execv`.
- Assignments to items in ``os.environ`` are automatically translated into
+ Assignments to items in :data:`os.environ` are automatically translated into
corresponding calls to :func:`putenv`; however, calls to :func:`putenv`
- don't update ``os.environ``, so it is actually preferable to assign to items
- of ``os.environ``.
+ don't update :data:`os.environ`, so it is actually preferable to assign to items
+ of :data:`os.environ`. This also applies to :func:`getenv` and :func:`getenvb`, which
+ respectively use :data:`os.environ` and :data:`os.environb` in their implementations.
.. note::
@@ -645,10 +653,10 @@ process and user.
environment affect subprocesses started with :func:`os.system`, :func:`popen` or
:func:`fork` and :func:`execv`.
- Deletion of items in ``os.environ`` is automatically translated into a
+ Deletion of items in :data:`os.environ` is automatically translated into a
corresponding call to :func:`unsetenv`; however, calls to :func:`unsetenv`
- don't update ``os.environ``, so it is actually preferable to delete items of
- ``os.environ``.
+ don't update :data:`os.environ`, so it is actually preferable to delete items of
+ :data:`os.environ`.
.. audit-event:: os.unsetenv key os.unsetenv
More information about the Python-checkins
mailing list