Usage
=====

To start using envanter, simply import ``env`` object from the
module. This object will contain various methods which parse
environment variables. For example:

.. code-block:: python

    from envanter import env

    SOME_CONSTANT = env.str("SOME_CONSTANT")


It is possible to specify a default value in case the variable
is not found in the environment:

.. code-block:: python

    SOME_CONSTANT = env.str("SOME_CONSTANT", default="hello")

The type of the default value does not have to comply with the
given method, any arbitrary Python object can be specified.

.. warning::

    If no default is specified, a ``KeyError`` is raised when the
    environment variable is not found. However, each method might
    throw various exceptions depending on their parser function. For
    example, ``env.decimal`` might throw ``decimal.InvalidOperation`` if
    the variable is not a valid one. Check out :doc:`api-reference` for
    specific information about the parser functions used.

Custom parser functions
-----------------------

It is possible to specify a custom parser function, for example:

.. code-block:: python

    >>> from envanter import env
    >>> from urllib.parse import urlparse

    >>> env.parse("SOME_URL", parser=urlparse)
    ParseResult(scheme='', netloc='', path='www.example.com', params='', query='', fragment='')



Custom environment parser
-------------------------

The environment parser class is exposed so that you can write your
own subclasses; however, if you are going to create a new subclass,
you will be responsible for maintaining the singleton instance, since
``env`` is bound to base class.

.. code-block:: python

    from envanter import EnvironmentParser
    from urllib.parse import urlparse, ParseResult


    class CustomEnvironmentParser(EnvironmentParser):
        def url(self, name: str) -> ParseResult:
            value = self.str(name)
            return urlparse(value)


    myenv = CustomEnvironmentParser()
