Issue #8603: Create a bytes version of os.environ for Unix
Create os.environb mapping and os.getenvb() function, os.unsetenv() encodes str
argument to the file system encoding with the surrogateescape error handler
(instead of utf8/strict) and accepts bytes, and posix.environ keys and values
are bytes.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index c41ee1b..6ad4785 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -107,6 +107,10 @@
to modify the environment as well as query the environment. :func:`putenv` will
be called automatically when the mapping is modified.
+ On Unix, keys and values use :func:`sys.getfilesystemencoding` and
+ ``'surrogateescape'`` error handler. Use :data:`environb` if you would like
+ to use a different encoding.
+
.. note::
Calling :func:`putenv` directly does not change ``os.environ``, so it's better
@@ -128,6 +132,16 @@
one of the :meth:`pop` or :meth:`clear` methods is called.
+.. data:: environb
+
+ Bytes version of :data:`environ`: a mapping object representing the
+ environment as byte strings. :data:`environ` and :data:`environb` are
+ synchronized (modify :data:`environb` updates :data:`environ`, and vice
+ versa).
+
+ Availability: Unix.
+
+
.. function:: chdir(path)
fchdir(fd)
getcwd()
@@ -251,7 +265,19 @@
.. function:: getenv(key, default=None)
Return the value of the environment variable *key* if it exists, or
- *default* if it doesn't. Availability: most flavors of Unix, Windows.
+ *default* if it doesn't. *key*, *default* and the result are str.
+ Availability: most flavors of Unix, Windows.
+
+ On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding`
+ and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you
+ would like to use a different encoding.
+
+
+.. 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.
+ Availability: most flavors of Unix.
.. function:: putenv(key, value)
diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst
index c33d9e5..d65b999 100644
--- a/Doc/library/posix.rst
+++ b/Doc/library/posix.rst
@@ -69,17 +69,22 @@
.. data:: environ
A dictionary representing the string environment at the time the interpreter
- was started. For example, ``environ['HOME']`` is the pathname of your home
- directory, equivalent to ``getenv("HOME")`` in C.
+ was started. Keys and values are bytes on Unix and str on Windows. For
+ example, ``environ[b'HOME']`` (``environ['HOME']`` on Windows) is the
+ pathname of your home directory, equivalent to ``getenv("HOME")`` in C.
Modifying this dictionary does not affect the string environment passed on by
:func:`execv`, :func:`popen` or :func:`system`; if you need to change the
environment, pass ``environ`` to :func:`execve` or add variable assignments and
export statements to the command string for :func:`system` or :func:`popen`.
+ .. versionchanged:: 3.2
+ On Unix, keys and values are bytes.
+
.. note::
- The :mod:`os` module provides an alternate implementation of ``environ`` which
- updates the environment on modification. Note also that updating ``os.environ``
- will render this dictionary obsolete. Use of the :mod:`os` module version of
- this is recommended over direct access to the :mod:`posix` module.
+ The :mod:`os` module provides an alternate implementation of ``environ``
+ which updates the environment on modification. Note also that updating
+ :data:`os.environ` will render this dictionary obsolete. Use of the
+ :mod:`os` module version of this is recommended over direct access to the
+ :mod:`posix` module.