os.putenv should be documented as not affecting os.getenv's return value

[DanielMartin]

BPO	40961

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-06-12.14:36:10.253>
labels = ['type-bug', '3.8', '3.9', '3.10', '3.7', 'docs']
title = "os.putenv should be documented as not affecting os.getenv's return value"
updated_at = <Date 2020-06-12.14:36:10.253>
user = 'https://bugs.python.org/DanielMartin'

bugs.python.org fields:

activity = <Date 2020-06-12.14:36:10.253>
actor = 'Daniel Martin'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-06-12.14:36:10.253>
creator = 'Daniel Martin'
dependencies = []
files = []
hgrepos = []
issue_num = 40961
keywords = []
message_count = 1.0
messages = ['371377']
nosy_count = 2.0
nosy_names = ['docs@python', 'Daniel Martin']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue40961'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9', 'Python 3.10']

[DanielMartin]

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')
'def'
>>> os.putenv('ABC', 'xyz')
>>> os.getenv('ABC')
'def'

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.