From 77c18b21145c8cf23d742b67c76c09e8f3477ea5 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 24 Apr 2022 02:19:59 -0700 Subject: [PATCH 1/4] Add that getenv uses os.environ --- Doc/library/os.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 471890e74c8e58..6fa3d82a302414 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -292,7 +292,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 ``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 @@ -514,7 +517,8 @@ process and user. Assignments to items in ``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``. + of ``os.environ``. This also applies to :func:`getenv`, which uses + ``os.environ`` in its implementation. .. note:: From 623c22e963b73d3b5efaba72e8c86456c290f12f Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 1 May 2022 20:34:55 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Jelle Zijlstra --- Doc/library/os.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 6fa3d82a302414..e33ab5a8c40070 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -293,7 +293,7 @@ process and user. Return the value of the environment variable *key* if it exists, or *default* if it doesn't. *key*, *default* and the result are str. Note that - since :func:`getenv` uses ``os.environ``, the mapping of :func:`getenv` is + 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. @@ -517,7 +517,7 @@ process and user. Assignments to items in ``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``. This also applies to :func:`getenv`, which uses + of ``os.environ``. This also applies to :func:`getenv` and :func:`getenvb`, which uses ``os.environ`` in its implementation. .. note:: From 7c816b08a9ab8c60262f0ca2c238200cadf65553 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 1 May 2022 20:46:59 -0700 Subject: [PATCH 3/4] Duplicate wording for environb --- Doc/library/os.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e33ab5a8c40070..e8de8f3c8513d4 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -307,7 +307,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``. @@ -517,8 +521,8 @@ process and user. Assignments to items in ``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``. This also applies to :func:`getenv` and :func:`getenvb`, which uses - ``os.environ`` in its implementation. + of ``os.environ``. This also applies to :func:`getenv` and :func:`getenvb`, which + respectively use ``os.environ`` and ``os.environb`` in their implementations. .. note:: From 9347356f15e3d0bf95f483acf915dc1e2d4c0471 Mon Sep 17 00:00:00 2001 From: slateny <46876382+slateny@users.noreply.github.com> Date: Sun, 1 May 2022 20:50:56 -0700 Subject: [PATCH 4/4] Add links to environ/b --- Doc/library/os.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index e8de8f3c8513d4..553625bef50386 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -177,8 +177,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 @@ -190,8 +190,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:: @@ -201,7 +201,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 @@ -518,11 +518,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``. This also applies to :func:`getenv` and :func:`getenvb`, which - respectively use ``os.environ`` and ``os.environb`` in their implementations. + 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:: @@ -721,10 +721,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