classification
Title: os.environ.get documentation missing
Type: Stage: resolved
Components: Documentation Versions: Python 3.5
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: DennisJensen, docs@python, ned.deily
Priority: normal Keywords:

Created on 2016-09-21 15:26 by DennisJensen, last changed 2016-09-21 18:18 by ned.deily. This issue is now closed.

Messages (4)
msg277159 - (view) Author: Dennis Jensen (DennisJensen) Date: 2016-09-21 15:26
I was encountering what seemed to be odd behavior from os.environ.get() from what I could find out about it and so I tried to locate the actual documentation on how it is supposed to be used now.  However, all I can find is a minor reference to os.environ.  There appears to be no documentation on os.environ.get() and/or any other methods of this sort associated with os.environ.  The alternate functionality os.getenv() is documented but this is not supposed to work the same as os.environ.get()   Still the behavior that I encountered is that it seems that either os.environ.get()) has been changed and/or it is now just simply a proxy for os.getenv() -- as these two seem to function the same way now.  Note: From what I was able to discern about how os.environ.get() worked is that it accepts only 1 parameter and if the item does not exist it throws an error -- while os.getenv() takes 2 parameters and does not throw an error if the item does not exist.
msg277165 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2016-09-21 15:51
os.environ is documented as being a "mapping" object.  The "get" method is a standard method for all mapping objects; it's not unique to os.environ.  Thus, there is no need to specially call out "get" or any of the other "mapping" methods and operations available with os.environ or any other example of a mapping object.  The "Built-in Types" chapter of the Python Standard Library reference describes the standard types and their methods and operations.


https://docs.python.org/3/library/os.html#os.environ
https://docs.python.org/3/library/stdtypes.html#mapping-types-dict
https://docs.python.org/3/library/stdtypes.html
msg277168 - (view) Author: Dennis Jensen (DennisJensen) Date: 2016-09-21 16:27
Okay well thanks for that information but after investigating this then I have to ask what is the difference between:

os.environ.get()

and

os.getenv()

As these 2 functions now appear to do exactly the same thing?  If this is the case then should there not be something added to either os.environ or to os.getenv() that states something to this effect.

Something along the lines of:  Since version: "whatever version that changed how .get() works" made the os.environ.get() work exactly the same as the os.getenv() -- this way since there are still references floating around that state that these 2 do not function the same and nothing outlined clearly within documentation stating that this is no longer the case.  Creates a bit of confusion on what should and should not be.
msg277175 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2016-09-21 18:18
The difference is that os.environ is a reference to a mapping object, essentially a dict, that has all of the process environment variables. By using the get('x') method on that object, you ask the object to find and return the value corresponding to key 'x' or to return None if the key is not found.  It's the same as using os.environ['x'] except that the latter raises a KeyError exception if the the key is not found.  This is how all mapping objects work.  (Also, os.environ() does not work because os.environ is not callable.)  os.getenv('x') is a call to the function that returns the value corresponding to key 'x' or None.  Yes, the end results of os.getenv('x') and os.environ.get('x') are the same but how they get there is conceptually different.  Why are there two similar ways to do this?  I can only speculate at this point.  It looks like os.environ and os.putenv have been around since the very early days of Python.  os.getenv appeared somewhat later but has been around since at least 2001 (http://bugs.python.org/issue429059).  Since os.putenv already existed, os.getenv could have been added as a convenience to mimic the underlying libc function names.  In any case, it's perfectly fine to use either approach and has been for at least 15 years!

>>> import os
>>> os.environ()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '_Environ' object is not callable
>>> os.environ
environ({'TERM': 'xterm-256color', 'HISTCONTROL': 'erasedups', 'HOME': '/Users/nad'})
>>> os.environ.get('HOME')
'/Users/nad'
>>> os.environ['HOME']
'/Users/nad'
>>> os.getenv
<function getenv at 0x1007318c8>
>>> os.getenv('HOME')
'/Users/nad'
History
Date User Action Args
2016-09-21 18:18:28ned.deilysetstatus: open -> closed
type: resource usage ->
resolution: not a bug
messages: + msg277175
2016-09-21 16:41:38DennisJensensetstatus: pending -> open
2016-09-21 16:27:41DennisJensensetstatus: closed -> pending
resolution: not a bug -> (no value)
messages: + msg277168
2016-09-21 15:51:44ned.deilysetstatus: open -> closed

nosy: + ned.deily
messages: + msg277165

resolution: not a bug
stage: resolved
2016-09-21 15:26:21DennisJensencreate