Metadata-Version: 2.1
Name: e2e.env
Version: 0.1.0
Summary: Easily model and convert environment variables you care about.
Home-page: https://github.com/nickroeker/e2e.env
Author: Nic Kroeker
License: Apache 2.0
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Acceptance
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: tox ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'

# e2e.env

_Class-based modeling of environment variables and their type conversions._

Especially suited to test automation where environment variables are used in
abundance, or even in applications that could benefit from these mappings.

## Requirements

For ease of implementation, Python 3.6 is required in order to use
[PEP-526](https://www.python.org/dev/peps/pep-0526/) variable
annotations.

## Overview

Environment variable access is common, and usually done via a module-based
approach.

```python
SERVICE_HOST = os.getenv('COMPANY_APP_HOST')
SERVICE_PORT = int(os.getenv('COMPANY_APP_PORT'))
```

This works just fine, but sometimes they need to be refreshed...

```python
# Whoops, forgot the int conversion!
SERVICE_PORT = os.getenv('COMPANY_APP_PORT')
```

... which isn't very [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).

Additionally, you may sometimes need to keep track of the name _and_ the value from the environment,

```python
# This is getting verbose quickly
ENVNAME_SERVICE_HOST = 'COMPANY_APP_HOST'
SERVICE_HOST = os.getenv(ENVNAME_SERVICE_HOST)
ENVNAME_SERVICE_PORT = 'COMPANY_APP_PORT'
SERVICE_PORT = int(os.getenv(ENVNAME_SERVICE_PORT))
```

In one swoop, we can map the environment variables as well as their
conversions to native types, and fetch either the value or the name:

```python
class ServiceVars(e2e.env.EnvMapper):
    host: str = 'COMPANY_APP_HOST'
    port: int = 'COMPANY_APP_PORT'

# Get the port via instance
print(ServiceVars().port)   # 8080
type(ServiceVars().port)    # <class 'int'>

# Get the name of the port environment variable via class
print(ServiceVars.port)     # COMPANY_APP_PORT
type(ServiceVars.port)      # <class 'str'>
```

## Using your own "converters"

All `EnvMapper` does is read the type annotation and constructs the returned
value by passing the environment value to it.

That is, when modeling,
```python
    mapped_name: annotated_type = 'ENV_VAR_NAME'
```
... on access via the `EnvMapper` instance, becomes ...
```python
    annotated_type(os.getenv('ENV_VAR_NAME'))
```

In the above examples for example, we had `port: int = 'COMPANY_APP_PORT'`.
This essentially gets shuffled into `int(os.getenv('COMPANY_APP_PORT'))`. So
any callable that can take a single `str` in its constructor and return the
appropriate type will work.

## Production use

The code is incredibly simple, and will adhere to these contracts:

- Variables that do not exist will cause a
  `e2e.env.exceptions.NoSuchVariableError` to be raised.\*
- Access of an unmapped environment variable will raise an `AttributeError`, as
  would be reasonably expected.
- Access of a mapping without an annotation will raise a `TypeError` with the
  mapping name and model class.

\* Open for discussion. Returning `None` could work. Passing `None` to the type
converter usually won't produce consistent behaviour across types, and so can't
be determined as a special case (e.g. `str(None)` gives `"None"`, `int(None)`
raises a `TypeError`). See
[Issue #1](https://github.com/nickroeker/e2e.env/issues/1) for more info.

## Future work

- Support `raise_on_dne` or something similar to change what happens when an
  environment variable is not found. Please add a thumbs-up for
  [Issue #1](https://github.com/nickroeker/e2e.env/issues/1) if you'd like to
  see this feature.
    ```python
    class ServiceVars(e2e.env.EnvMapper, raise_on_dne=False): ...
    ```
    ```python
    class ServiceVars(e2e.env.EnvMapper, dne=lambda: None): ...
    ```
- Support for combining mappings into one larger mapping, for organizational
  purposes. Please add a thumbs-up for
  [Issue #2](https://github.com/nickroeker/e2e.env/issues/2) if you'd like to
  see this feature.

