This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: os.putenv should be documented as not affecting os.getenv's return value
Type: behavior Stage:
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Daniel Martin, docs@python
Priority: normal Keywords:

Created on 2020-06-12 14:36 by Daniel Martin, last changed 2022-04-11 14:59 by admin.

Messages (1)
msg371377 - (view) Author: Daniel Martin (Daniel Martin) Date: 2020-06-12 14:36
I find this behavior extremely surprising:

$ ABC=def python
Python 3.7.4 (v3.7.4:e09359112e, Jul  8 2019, 14:54:52) 
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.getenv('ABC')
>>> os.putenv('ABC', 'xyz')
>>> os.getenv('ABC')

Although the documentation for the os module does say in the documentation for putenv that

> "When putenv() is supported, assignments to items in os.environ
> are automatically translated into corresponding calls to putenv();
> however, calls to putenv() don’t update os.environ, so it is
> actually preferable to assign to items of os.environ"

, there is absolutely nothing in the documentation to give the impression that os.putenv WILL NOT affect the result of os.getenv in the same process, as it is completely undocumented that os.getenv is a wrapper around os.environ.get().

The documentation for os.environ is careful to note that the copy of the environment stored in os.environ is read only once at startup, and has a note specifically about putenv; however, given this care the lack of any similar language in the os.getenv documentation gives the impression that os.getenv behaves differently.

Ideally, the documentation of both os.getenv and os.putenv would be modified. The getenv documentation should note that it pulls from a mapping captured at first import and does not, as the name may imply, result in a call to the C function getenv. The putenv documentation should note that calls to putenv don’t update os.environ, and therefore do not affect the result of os.getenv.

Possibly, given the thread safety issues, direct calls to os.getenv and os.putenv should be deprecated in favor of os.environ use.
Date User Action Args
2022-04-11 14:59:32adminsetgithub: 85133
2020-06-12 14:36:10Daniel Martincreate