[New-bugs-announce] [issue40961] os.putenv should be documented as not affecting os.getenv's return value

[Daniel Martin]

New submission from Daniel Martin <daniel.martin at crowdstrike.com>:

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.

----------
assignee: docs at python
components: Documentation
messages: 371377
nosy: Daniel Martin, docs at python
priority: normal
severity: normal
status: open
title: os.putenv should be documented as not affecting os.getenv's return value
type: behavior
versions: Python 3.10, Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40961>
_______________________________________