configur8
=========
Python type-safe configuration and validation library.
## Introduction
Configuration validation is a common problem in Python. This library aims to
provide a simple, type-safe way to validate configuration either by file or
environment variables.
An example:
/path/to/config.yaml:
```yaml
mysql:
host: localhost
port: 3306
user: not_root
password: my_password
```
```python
import configur8
from configur8 import env
class MySQL:
# define the fields and their types
host: str
# default values are supported
port: int = 3306
# default values can programmatically be defined, e.g. from an env var
user: str = env.str("MYSQL_USER", "definitely_not_root")
password: str
class Config:
mysql: MySQL
config = configur8.load(Config, "/path/to/config.yaml")
assert isinstance(config.mysql, MySQL) # True
```
The above example will load the configuration from the file at
``/path/to/config.yaml`` and validate it against the ``Config`` class. If the
configuration is invalid, an exception will be raised.
## Environment only
An example:
```python
from configur8 import env
SECRET_KEY = env.str("SECRET_KEY")
NUM_WORKERS = env.int("NUM_WORKERS", 2)
DEBUG = env.bool("DEBUG", False)
```
In the example above:
1. ``SECRET_KEY`` is a required environment variable - attempting execute the
code without it defined will result in an exception. This is typically what
you want so that apps and services don't start in an unintended state.
2. ``NUM_WORKERS`` will be parsed into an integer. If the env var is not
defined, ``2`` will be used as a default. If a non integer value is parsed,
an error will be raised.
3. ``DEBUG`` is a boolean with a default of ``False``. "Truthy" values can be
used, e.g. "on", "1", etc.
Everything is designed to be type safe.
## Types of values supported
* String - ``env.str``
* Integer - ``env.int``
* Float - ``env.float``
* Boolean - ``env.bool``
* Url - ``env.url``
* Path - ``env.path``
* Email - ``env.email`` - Validation provided by ``email-validator``
Each type can support optional values and work with lists:
```python
from configur8 import env
ALLOWED_HOSTS = env.url.list("ALLOWED_HOSTS")
```
Given the environment:
```
ALLOWED_HOSTS=http://localhost,http://my-staging-server
```
The python value of ``ALLOWED_HOSTS`` would be:
```python
["http://localhost", "http://my-staging-server"]
```
## Boolean flags
Boolean values are supported. See ``configur8.env.BOOLEAN_TRUTHY_VALUES``:
* `true`
* `1`
* `on`
* `yes`
* `ok`
Will all result in a ``True`` Python value. Anything else will result in
``False``.
## Urls
These are augmented objects that have extra attributes in case you need them:
```python
from configur8 import env
# https://my-bucket.s3.us-west-2.amazonaws.com
bucket = env.url("S3_BUCKET_URL")
assert bucket.protocol == "https"
assert bucket.host == "my-bucket.s3.us-west-2.amazonaws.com"
```
There are a bunch more properties - see ``configur8.url.Url``.
## Paths
These are augmented objects that have extra attributes in case you need them:
```python
from configur8 import env
# /var/run/secrets/my-mounted-volume/my-secret
my_creds = env.path("SERVICE_CREDS").read()
# my_creds will hold the contents of the file in the env var
```
## Development
1. [Install PDM](https://pdm.fming.dev/latest/)
2. [Install Task](https://taskfile.dev/installation/)
### Running tests
```shell
task test
```
### Publishing to PyPI
**NOTE** Replace `__VERSION__` with a semver identifier such as `0.9.3`
1. Ensure that you are on a clean master.
2. Update `__version__` in `src/configur8/__about__.py` to `__VERSION__`.
3. ```shell
git add src/configur8/__about__.py
git commit -m "Bump to __VERSION__"
git tag v__VERSION__
git push origin --tags
4. Wait for Github Actions to succeed and publish the library to the public PyPI.
Raw data
{
"_id": null,
"home_page": "",
"name": "configur8",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "config,configuration,configurations,settings,env,environment,environments,application,python-config",
"author": "",
"author_email": "Nick Joyce <nick@stratuscode.com>",
"download_url": "https://files.pythonhosted.org/packages/a2/b9/c5322aeca444730541dbcc490df826295c23be84fe8d02f9b82cca0a2fc4/configur8-2.0.0.tar.gz",
"platform": null,
"description": "configur8\n=========\n\nPython type-safe configuration and validation library.\n\n## Introduction\n\nConfiguration validation is a common problem in Python. This library aims to\nprovide a simple, type-safe way to validate configuration either by file or\nenvironment variables.\n\nAn example:\n\n/path/to/config.yaml:\n\n```yaml\nmysql:\n host: localhost\n port: 3306\n user: not_root\n password: my_password\n```\n\n```python\nimport configur8\nfrom configur8 import env\n\n\nclass MySQL:\n # define the fields and their types\n host: str\n # default values are supported\n port: int = 3306\n # default values can programmatically be defined, e.g. from an env var\n user: str = env.str(\"MYSQL_USER\", \"definitely_not_root\")\n password: str\n\n\nclass Config:\n mysql: MySQL\n\n\nconfig = configur8.load(Config, \"/path/to/config.yaml\")\n\nassert isinstance(config.mysql, MySQL) # True\n```\n\nThe above example will load the configuration from the file at\n``/path/to/config.yaml`` and validate it against the ``Config`` class. If the\nconfiguration is invalid, an exception will be raised.\n\n## Environment only\nAn example:\n\n```python\nfrom configur8 import env\n\n\nSECRET_KEY = env.str(\"SECRET_KEY\")\nNUM_WORKERS = env.int(\"NUM_WORKERS\", 2)\nDEBUG = env.bool(\"DEBUG\", False)\n```\n\nIn the example above:\n1. ``SECRET_KEY`` is a required environment variable - attempting execute the\n code without it defined will result in an exception. This is typically what\n you want so that apps and services don't start in an unintended state.\n2. ``NUM_WORKERS`` will be parsed into an integer. If the env var is not\n defined, ``2`` will be used as a default. If a non integer value is parsed,\n an error will be raised.\n3. ``DEBUG`` is a boolean with a default of ``False``. \"Truthy\" values can be\n used, e.g. \"on\", \"1\", etc.\n\nEverything is designed to be type safe.\n\n## Types of values supported\n\n* String - ``env.str``\n* Integer - ``env.int``\n* Float - ``env.float``\n* Boolean - ``env.bool``\n* Url - ``env.url``\n* Path - ``env.path``\n* Email - ``env.email`` - Validation provided by ``email-validator``\nEach type can support optional values and work with lists:\n\n```python\nfrom configur8 import env\n\nALLOWED_HOSTS = env.url.list(\"ALLOWED_HOSTS\")\n```\n\nGiven the environment:\n\n```\nALLOWED_HOSTS=http://localhost,http://my-staging-server\n```\n\nThe python value of ``ALLOWED_HOSTS`` would be:\n\n```python\n[\"http://localhost\", \"http://my-staging-server\"]\n```\n\n## Boolean flags\n\nBoolean values are supported. See ``configur8.env.BOOLEAN_TRUTHY_VALUES``:\n* `true`\n* `1`\n* `on`\n* `yes`\n* `ok`\n\nWill all result in a ``True`` Python value. Anything else will result in\n``False``.\n\n## Urls\n\nThese are augmented objects that have extra attributes in case you need them:\n\n```python\nfrom configur8 import env\n\n# https://my-bucket.s3.us-west-2.amazonaws.com\nbucket = env.url(\"S3_BUCKET_URL\")\n\nassert bucket.protocol == \"https\"\nassert bucket.host == \"my-bucket.s3.us-west-2.amazonaws.com\"\n```\n\nThere are a bunch more properties - see ``configur8.url.Url``.\n\n## Paths\n\nThese are augmented objects that have extra attributes in case you need them:\n\n```python\nfrom configur8 import env\n\n# /var/run/secrets/my-mounted-volume/my-secret\nmy_creds = env.path(\"SERVICE_CREDS\").read()\n\n# my_creds will hold the contents of the file in the env var\n```\n\n## Development\n\n1. [Install PDM](https://pdm.fming.dev/latest/)\n2. [Install Task](https://taskfile.dev/installation/)\n\n### Running tests\n\n```shell\ntask test\n```\n\n### Publishing to PyPI\n\n**NOTE** Replace `__VERSION__` with a semver identifier such as `0.9.3`\n\n1. Ensure that you are on a clean master.\n2. Update `__version__` in `src/configur8/__about__.py` to `__VERSION__`.\n3. ```shell\n git add src/configur8/__about__.py\n git commit -m \"Bump to __VERSION__\"\n git tag v__VERSION__\n git push origin --tags\n4. Wait for Github Actions to succeed and publish the library to the public PyPI.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Type-safe configuration and validation library",
"version": "2.0.0",
"split_keywords": [
"config",
"configuration",
"configurations",
"settings",
"env",
"environment",
"environments",
"application",
"python-config"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "de41385a88b0c561fafc9fce5e297a38c796985b36876e9b664c1bbff3cef817",
"md5": "86e0efd4c6b31de33ce6bb012157faa1",
"sha256": "07b9b02b5e9381cd5dc68104a4889bdbfc71dc0bfe527de4f3350a3343039fde"
},
"downloads": -1,
"filename": "configur8-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86e0efd4c6b31de33ce6bb012157faa1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 10447,
"upload_time": "2023-02-09T12:13:14",
"upload_time_iso_8601": "2023-02-09T12:13:14.570712Z",
"url": "https://files.pythonhosted.org/packages/de/41/385a88b0c561fafc9fce5e297a38c796985b36876e9b664c1bbff3cef817/configur8-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a2b9c5322aeca444730541dbcc490df826295c23be84fe8d02f9b82cca0a2fc4",
"md5": "de1b7adb3ff1bcaa4aca5c0fb317d95c",
"sha256": "ed862cc81844caa5dd9be72567ace036e1cf2ffb743411cb0becf73122294ed4"
},
"downloads": -1,
"filename": "configur8-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "de1b7adb3ff1bcaa4aca5c0fb317d95c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 14708,
"upload_time": "2023-02-09T12:13:16",
"upload_time_iso_8601": "2023-02-09T12:13:16.490614Z",
"url": "https://files.pythonhosted.org/packages/a2/b9/c5322aeca444730541dbcc490df826295c23be84fe8d02f9b82cca0a2fc4/configur8-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-09 12:13:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "configur8"
}
JSON