plox.tools.environment
======================

.. py:module:: plox.tools.environment

.. autoapi-nested-parse::

   Assorted utilities for dealing with anything related the current process' environment.

   .. code-block:: python

       from plox.tools import environment



Exceptions
----------

.. autoapisummary::

   plox.tools.environment.MissingEnvironmentVariableError


Functions
---------

.. autoapisummary::

   plox.tools.environment.add_to_env_from_file
   plox.tools.environment.ensure_envars_set
   plox.tools.environment.envvar_or_bail
   plox.tools.environment.modified_environ
   plox.tools.environment.parse_environment_file_to_values


Module Contents
---------------

.. py:exception:: MissingEnvironmentVariableError

   Bases: :py:obj:`Exception`


   Custom exception to represent a missing environment variable.


.. py:function:: add_to_env_from_file(environment_file)

   Add a set of ``key=value`` pairs from an env file to the current environment.

   The environment file should consistent of a set of <keys>=<values> where the
   keys represent environment variable names, and <values> are their value.

   For example, if the following envfile resided at ``/tmp/foo.env``:

   .. code-block:: text

       FOOBAR=/tmp/some_key
       FOOBAZ=${HOME}/some_other_key

   ``add_to_env_from_file("/tmp/foo.env")`` would result in the following items
   being added to the process' environ:

   .. code-block:: python

       {"FOOBAR": "/tmp/some_key", "FOOBAZ": "<expanded HOME variable>/some_other_key"}

   :param environment_file: Path to local file on disk containing vars
                            to parse into environment.


.. py:function:: ensure_envars_set(to_validate, are_paths = False, create_ok = False)

   Validate that a list of variables exists in current environment.

   :param to_validate: A list of envar names to check existence of.
   :param are_paths: Whether or not the envars are representing local file system paths
                     that should exist; if set to ``True``, each envar's value will be checked to
                     ensure is an existing path.
   :param create_ok: Whether or not the path should be created if not existent.

   :raises MissingEnvironmentVariableError: If any specified items in ``to_validate`` are
       not in present env.
   :raises OSError: If error encountered when trying to make directory to path when
       ``are_paths`` is also ``True``.


.. py:function:: envvar_or_bail(k)

   Read and return an environment variable or raise an Exception.

   :param k: Key name for environment variable to read.

   :raises MissingEnvironmentVariableError: If specified ``k`` not in present env.

   :returns: Value of environment variable
   :rtype: str


.. py:function:: modified_environ(*remove, **update)

   Temporarily modify process environment within a contextmanger wrapping.

   Will remove and/or update process' environment values based on based
   arguments. Useful for running a command/sub-process with a temporarily modified
   env. If ``"ALL"`` is passed as an argument to remove, then the entirety of the
   existing environment will be removed.

   .. admonition:: Example

      >>> # removing all vars
      >>> from plox.tools.environment import modified_environ
      >>> from os import environ
      >>> len(environ)
      72
      >>> with modified_environ("ALL"):
      >>>     print(len(env))
      0
      >>> len(environ)
      72
      >>> # Adding a temporary var
      >>> environ.get("FOOBAR", "not set")
      'not set'
      >>> with modified_environ(FOOBAR="set"):
      >>>     print(environ.get("FOOBAR", "not set"))
      set
      >>> environ.get("FOOBAR", "not set")
      'not set'
      >>> # both
      >>> with modified_environ("ALL", FOOBAR="set"):
      >>>     print(len(env))
      1

   :param remove: Name of environment variables to _remove_ from the environment.
   :param update: Dictionary pairing of key:value items to _add_ to the environment.

   :returns: Modified envrionment
             that will be reverted upon context manager exiting scope.
   :rtype: typing.Generator[None, None, None]


.. py:function:: parse_environment_file_to_values(envfile, expand_vars = True)

   Parse local file containing key=value environment pairs into their values and return as dict.

   The environment file should consistent of a set of <keys>=<values> where the
   keys represent environment variable names, and <values> are their value.

   An example envfile:

   .. code-block:: text

       FOOBAR=/tmp/some_key
       FOOBAZ=${HOME}/some_other_key

   ``parse_environment_file_to_values`` would return the following dict:

   .. code-block:: python

       {"FOOBAR": "/tmp/some_key", "FOOBAZ": "<expanded HOME variable>/some_other_key"}

   :param envfile: Path to local file on disk containing vars to parse into the environment.
   :param expand_vars: Whether or not to expand variables in the values. Default ``true``.

   :returns: The dictionary representing the key:value pairs of
             the env file.
   :rtype: dict[typing.Any, typing.Any]