# envee
Read variables from the environment or files into dataclasses.
While it is convenient to configure applications using environment variables during development, it is advised not to store sensitive information such as passwords in environment variables in production environments. The `envee` library allows reading variables either from the environment variables or files (which are typically used by e.g. [docker secrets](https://docs.docker.com/engine/swarm/secrets/)), thus keeping code used for development and production environments as close to each other as possible.
## Usage
Variables to read from the environment are declared using classes annotated with the `@envee.environment` decorator. Using `envee.read()` the fields of the classes are filled using the environment.
Example:
```python
from typing import Optional
import envee
@envee.environment
class Environment:
username: str
debug: Optional[str]
workers: int = 5
env = envee.read(Environment)
```
### Environment variables names and file paths
For each field, per default `envee` looks for environment variables with the upper case name of the field. The corresponding file is looked in the directory `/run/secrets` and has the lower case field name as filename. If a corresponding file is found, the file will take precedence over an environment variable. For the example above, the `read()` method looks for the environment variables `USERNAME`, `DEBUG`, and `WORKERS`, respectively the files `/run/secrets/username`, `/run/secrets/debug`, and `/run/secrets/workers`.
### Types
Variables are typed using the dataclasses. Primitive types such as `int`, `float`, or `str` are automatically converted while reading. For more complex types, a conversion function needs to be provided. If fields are typed as `Optional`, their value will be set to `None` if no variable is found. If a default value is defined, this value will be used when no corresponding environment variable or file is found. Otherwise, when no environment variable is found and the field is not typed as `Optional`, a `RuntimeError` is raised.
### dotenv (.env) support
`envee` provides rudimentary support for `.env` files. Currently, the path to the `.env` file must be specified in the `read()` method. The name of the variable name must be the upper case name of the field name. Comments and multiline variables are supported. Variables found in a `.env` file take precedence over environment variables but not files.
The following `.env` file can be read using the following Python code:
```
DEBUG="True" # a comment
WORKERS=5
MULTILINE="first
second
3"
```
```python
@envee.environment
class Environment:
debug: str
workers: int
multiline: str
env = envee.read(Environment, dotenv_path="/path/to/.env/file")
```
## Advanced usage
### Override environment variable names
In the following example the field debug is filled using the environment variable `PROJECT_DEBUG`.
```python
import envee
@envee.environment
class Environment:
debug: str = envee.field(env_name="PROJECT_DEBUG")
env = envee.read(Environment)
```
### Override file locations
The default location can be changed by passing a different location to the `read()` method.
```python
import envee
@envee.environment
class Environment:
debug: str
env = envee.read(Environment, default_files_location="/path/to/a/directory")
```
Alternatively, the fields metadata can specify the `file_location` or `file_name`. The parameter `file_location` overrides `default_files_location`. `file_name` overrides the default file name. The direct path to a file can be specified using `file_path`. `file_path` will take precedence over `file_location` or `file_name`.
```python
import envee
@envee.environment
class Environment:
debug: str = envee.field(file_location="/other/dir", file_name="DEBUG.txt")
env = envee.read(Environment)
```
### Complex datatypes
For complex datatypes, a conversion function needs to be passed to the field.
```python
import envee
@envee.environment
class Environment:
timestamp: datetime.datetime = envee.field(
conversion_func=lambda x: datetime.datetime.fromisoformat(x)
)
env = envee.read(Environment)
```
Raw data
{
"_id": null,
"home_page": "",
"name": "envee",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "env,environment variables,docker secrets,settings,.env,dotenv",
"author": "",
"author_email": "Ren\u00e9 Buffat <rene@ctechnology.io>",
"download_url": "https://files.pythonhosted.org/packages/38/8c/d758968ded3c43260e0966499fe34697b2984c3518992f64195bc1bb9f43/envee-0.2.0.tar.gz",
"platform": null,
"description": "# envee\n\n\n\nRead variables from the environment or files into dataclasses.\n\nWhile it is convenient to configure applications using environment variables during development, it is advised not to store sensitive information such as passwords in environment variables in production environments. The `envee` library allows reading variables either from the environment variables or files (which are typically used by e.g. [docker secrets](https://docs.docker.com/engine/swarm/secrets/)), thus keeping code used for development and production environments as close to each other as possible.\n\n## Usage\n\nVariables to read from the environment are declared using classes annotated with the `@envee.environment` decorator. Using `envee.read()` the fields of the classes are filled using the environment.\n\nExample:\n\n```python\nfrom typing import Optional\nimport envee\n\n@envee.environment\nclass Environment:\n username: str\n debug: Optional[str]\n workers: int = 5\n\nenv = envee.read(Environment)\n\n```\n\n### Environment variables names and file paths\n\nFor each field, per default `envee` looks for environment variables with the upper case name of the field. The corresponding file is looked in the directory `/run/secrets` and has the lower case field name as filename. If a corresponding file is found, the file will take precedence over an environment variable. For the example above, the `read()` method looks for the environment variables `USERNAME`, `DEBUG`, and `WORKERS`, respectively the files `/run/secrets/username`, `/run/secrets/debug`, and `/run/secrets/workers`.\n\n### Types\n\nVariables are typed using the dataclasses. Primitive types such as `int`, `float`, or `str` are automatically converted while reading. For more complex types, a conversion function needs to be provided. If fields are typed as `Optional`, their value will be set to `None` if no variable is found. If a default value is defined, this value will be used when no corresponding environment variable or file is found. Otherwise, when no environment variable is found and the field is not typed as `Optional`, a `RuntimeError` is raised.\n\n### dotenv (.env) support\n\n`envee` provides rudimentary support for `.env` files. Currently, the path to the `.env` file must be specified in the `read()` method. The name of the variable name must be the upper case name of the field name. Comments and multiline variables are supported. Variables found in a `.env` file take precedence over environment variables but not files.\n\nThe following `.env` file can be read using the following Python code:\n\n```\nDEBUG=\"True\" # a comment\nWORKERS=5\nMULTILINE=\"first\nsecond\n3\"\n```\n\n```python\n@envee.environment\nclass Environment:\n debug: str\n workers: int\n multiline: str\n\nenv = envee.read(Environment, dotenv_path=\"/path/to/.env/file\")\n```\n\n## Advanced usage\n\n### Override environment variable names\n\nIn the following example the field debug is filled using the environment variable `PROJECT_DEBUG`.\n\n```python\nimport envee\n\n@envee.environment\nclass Environment:\n debug: str = envee.field(env_name=\"PROJECT_DEBUG\")\n\nenv = envee.read(Environment)\n```\n\n### Override file locations\n\nThe default location can be changed by passing a different location to the `read()` method.\n\n```python\nimport envee\n\n@envee.environment\nclass Environment:\n debug: str\n\nenv = envee.read(Environment, default_files_location=\"/path/to/a/directory\")\n```\n\nAlternatively, the fields metadata can specify the `file_location` or `file_name`. The parameter `file_location` overrides `default_files_location`. `file_name` overrides the default file name. The direct path to a file can be specified using `file_path`. `file_path` will take precedence over `file_location` or `file_name`.\n\n```python\nimport envee\n\n@envee.environment\nclass Environment:\n debug: str = envee.field(file_location=\"/other/dir\", file_name=\"DEBUG.txt\")\n\nenv = envee.read(Environment)\n```\n\n### Complex datatypes\n\nFor complex datatypes, a conversion function needs to be passed to the field.\n\n```python\nimport envee\n\n@envee.environment\nclass Environment:\n timestamp: datetime.datetime = envee.field(\n conversion_func=lambda x: datetime.datetime.fromisoformat(x)\n )\n\n\nenv = envee.read(Environment)\n```\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License",
"summary": "Read variables from environment or files into dataclasses",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/c-technology/envee"
},
"split_keywords": [
"env",
"environment variables",
"docker secrets",
"settings",
".env",
"dotenv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "71394be8028f50e0e5e6aac2369c8b4c78b8a5139b01b3bc554da0bb95c667db",
"md5": "5b2b157df7b24635b0fba0187761bff8",
"sha256": "15a306a09f4ee86f5a84ebfea4e9c08e8a907272142e3cd3098d3283e0befea2"
},
"downloads": -1,
"filename": "envee-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5b2b157df7b24635b0fba0187761bff8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7148,
"upload_time": "2024-01-03T12:27:41",
"upload_time_iso_8601": "2024-01-03T12:27:41.773631Z",
"url": "https://files.pythonhosted.org/packages/71/39/4be8028f50e0e5e6aac2369c8b4c78b8a5139b01b3bc554da0bb95c667db/envee-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "388cd758968ded3c43260e0966499fe34697b2984c3518992f64195bc1bb9f43",
"md5": "b9f4afcbb0ea4e7d3049b734fb960253",
"sha256": "62da67b91ad58ab01d5c97ac73418996d82078555633deb5d332c41198247c13"
},
"downloads": -1,
"filename": "envee-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b9f4afcbb0ea4e7d3049b734fb960253",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8626,
"upload_time": "2024-01-03T12:27:42",
"upload_time_iso_8601": "2024-01-03T12:27:42.961083Z",
"url": "https://files.pythonhosted.org/packages/38/8c/d758968ded3c43260e0966499fe34697b2984c3518992f64195bc1bb9f43/envee-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 12:27:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "c-technology",
"github_project": "envee",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "envee"
}
JSON
