OS Module
=========

.. toctree::
   :maxdepth: 1


Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


Introduction
------------
Sometimes, OS dependent functionality is required by your application, module or function. To expose this in a platform agnostic way, Python provides the :py:mod:`os` module.

.. tip:: All functions in the :py:mod:`os` module raise :py:exc:`OSError` when raising exceptions.

The following examples are a non-exhaustive list of functionality available in the :py:mod:`os` module.

There is no coverage of the process management functions that are part of the :py:mod:`os` module as it is better to work with processes using the :py:mod:`subprocess` module.


.. _section_heading-Accessing_Environment_Variables:

Accessing Environment Variables
-------------------------------

The :py:data:`os.environ` dictionary can be used to add, get and delete environment variables:

>>> #
>>> # Fetch all environment variables
>>> #
>>> os.environ
environ({'PYTHONSTARTUP': '/etc/pythonstart', 'PYTHONPATH': '/opt/pycharm/pycharm-2017.3, 'HOST': 'mike-dt', 'LANGUAGE': 'en_US'})

>>> #
>>> # Set a (possibly new) environment variable
>>> #
>>> os.environ['new_var'] = "foobar"
>>> os.environ
environ({'new_var': 'foobar', 'PYTHONSTARTUP': '/etc/pythonstart', 'PYTHONPATH': '/opt/pycharm/pycharm-2017.3, 'HOST': 'mike-dt', 'LANGUAGE': 'en_US'})

>>> #
>>> # Getting an environment variable
>>> #
>>> os.environ['new_var']
'foobar'

>>> #
>>> # Removing an environment variable
>>> #
>>> del os.environ['new_var']

If the environment variable requested doesn't exist, :py:data:`os.environ` will return a :py:exc:`KeyError`. To get around this, you can use the :py:func:`os.getenv` function which takes a default value to return if the key doesn't exist:

>>> # Continuing our example above
>>> #
>>> # Fetch an environment variable that doesn't exist
>>> #
>>> os.getenv('foobar', 'I_DONT_EXIST')
'I_DONT_EXIST'

.. tip:: The :py:mod:`os` module also has the :py:func:`os.putenv` function to add environment variables, and :py:func:`os.unsetenv` to delete them. However, these functions do not update :py:data:`os.environ` so it is preferable to use :py:data:`os.environ` directly.


.. _section_heading-Getting_User_And_Group_Information:

Getting User and Group Information
----------------------------------

Simple "get" functions are provided to retrieve basic user, group and process IDs:

>>> os.getlogin()
'mike'
>>> os.getgid()
100
>>> os.getuid()
1000
>>> os.getpid()
13286

If you have permissions on the system to do it, you can also change the GID, UID and umask using the following functions:

:py:func:`os.setgid`

:py:func:`os.setuid`

:py:func:`os.umask`



.. _section_heading-Working_With_Directories:

Working With Directories
------------------------
>>> #
>>> # Get the current working directory
>>> #
>>> os.getcwd()
'/home/mike/gitsandbox/pythonedu-2017'

>>> #
>>> # Change to a different directory
>>> #
>>> os.chdir('/home/mike/gitsandbox')
>>> os.getcwd()
'/home/mike/gitsandbox'

>>> #
>>> # List the contents of a directory
>>> #
>>> os.listdir()
['pythonedustudent.bitbucket.org', 'pythonedu-2017']

.. tip:: Be sure to checkout the :py:mod:`glob` module. Similar to :py:func:`os.listdir` it allows you to get a directory listing. However, it also supports recursive searching and it allows you to filter the results so only items that match a given pattern are returned.

>>> #
>>> # Create a directory
>>> #
>>> os.mkdir('new_dir')
>>> os.listdir()
['new_dir', 'pythonedustudent.bitbucket.org', 'pythonedu-2017']

>>> #
>>> # Make multiple nested directories
>>> #
>>> os.makedirs('a/b/c')
>>> os.listdirs()
['a', 'new_dir', 'pythonedustudent.bitbucket.org', 'pythonedu-2017']
>>> os.listdirs('a')
['b']
>>> os.listdirs('a/b')
['c']

>>> #
>>> # Rename a directory
>>> #
>>> os.rename('new_dir', 'new_dir2')
>>> os.listdirs()
['a', 'new_dir2', 'pythonedustudent.bitbucket.org', 'pythonedu-2017']

>>> #
>>> # Remove a directory
>>> #
>>> os.rmdir('a/b/c')
>>> os.rmdir('a/b')
>>> os.rmdir('a')
>>> os.rmdir('new_dir2')
>>> os.listdir()
['pythonedustudent.bitbucket.org', 'pythonedu-2017']


.. _section_heading-Working_With_Files:

Working with files
------------------

>>> #
>>> # Status of the file
>>> #
>>> os.stat('README.md')
os.stat_result(st_mode=33188, st_ino=8652074, st_dev=2051, st_nlink=1, st_uid=1000, st_gid=100, st_size=561, st_atime=1517362573, st_mtime=1517362570, st_ctime=1517362570)

>>> #
>>> # Change the permissions on the file
>>> #
>>> os.chmod('README.md', 0o644)

>>> #
>>> # Change the file owner (change the uid and gid values)
>>> #
>>> os.chown('README.md', 1003, 100)

>>> #
>>> # Change the root directory of the current process
>>> # :NOTE: This creates a chroot jail for security
>>> #
>>> os.chroot('/opt/my_program')
>>> #
>>> # Create a hard link to a file
>>> #
>>> os.link('README.md', 'my_link')
>>> os.listdir()
['.git',
 'my_link',
 'README.md']

>>> #
>>> # Rename a file
>>> #
>>> os.rename('my_link', 'link_by_new_name')
>>> os.listdir()
['.git',
 'link_by_new_name',
 'README.md']

>>> #
>>> # Remove a file
>>> #
>>> os.remove('link_by_new_name')
>>> os.listdir()
['.git',
 'README.md']