| Name | gamma-config JSON |
| Version |
0.8.11
JSON |
| download |
| home_page | |
| Summary | Config handling for data science projects |
| upload_time | 2024-01-27 18:56:34 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gamma Config
  
An opinionated way of setting up configuration for data science projects.
## Overview
Gamma config provides a standard and flexible way of implementing application
configuration primarily based on YAML files. It promotes best practices by:
- simplify separation of code and config data;
- breaking large, complex configuration into multiple files;
- providing a way to write environment-aware config files;
- facilitating security best-practices, like proper secrets management;
- providing a immutable central global object storing **all** contextual data.
Another benefit of a standard config mechanism is allowing Gamma extension
libraries to provide configuration in a common way.
## Features
- Configuration expressed as a set of YAML files (by defaul) inside a
`config` folder in the root of the project.
- Multiple YAML files merged following simple rules. Simple file ordering convention
using two digit prefixes.
- Builtin support for environment specific parameters (production, development, etc.)
- Support for `.env` files via `python-dotenv`, including `.local.env` that
can be added to `.gitignore`
- Dynamic evaluation via YAML tags. For instance, the `!ref` tag allow you to
reference other parameters in any config file.
- Custom tag support via simple and cool multiple dispatch mechanism.
- Round-trip dump of config back into YAML. Support for hiding sensitive data
on dump.
- Simplified key access via dot (`.`). Eg. for `config: {foo: {bar: 100}}`,
this is True: `config.foo.bar == 100`
[Click here to view the full documentation](https://cjalmeida.github.io/gamma-config/)
## Getting started
Using pip:
```bash
pip install gamma-config
```
In most cases, you'll want to use the `!j2` tag to interpolate values using Jinja2.
This requires manually installing the `jinja2` package or using the `jinja2` extras.
```bash
pip install gamma-config[jinja2]
```
You must install `pydantic` if using the [structured configuration][structured] feature.
```bash
pip install gamma-config[pydantic]
```
## Basic Usage
The package comes with "scaffolding" to help you get started. In your project folder:
```bash
python -m gamma.config.scaffold
```
Remove the sample files, then create yourself a `config/20-myconfig.yaml` file
with the contents:
```yaml
foo: 1
user: !env USER
```
To access the config from within your Python program:
```python
import os
from gamma.config import get_config
def run():
# it's safe and efficient to call this multiple times
config = get_config()
# get static value using the dict keys or attribute access
assert config["foo"] == 1
assert config.foo == 1
# get dynamic variables
assert config["user"] == os.getenv("USER")
assert config.user == os.getenv("USER")
```
Most of the magic happen via tags. Look at the documentation for info on the [built-in tags](tags) available.
## Changelog
### Breaking in 0.8
- We **DEPRECATED** `!py` and `!obj` tags, replacing them by the cleaner/simpler
[`!call` tag](built-in-tags/#call). Those are schedule to be removed by release 1.0.
- We **DEPRECATED** "Structured configuration" support, We recommend directly using
[Pydantic's V2 discriminated unions](https://docs.pydantic.dev/latest/usage/types/unions/#discriminated-unions-aka-tagged-unions)
as an alternative.
- By default, `!env`, `!expr` and `!call` will not dump the contents on a `to_yaml`
call. We provide `!env:dump`, `!expr:dump`, `!call:dump` to force dumping. Tag
`!env_secret` is still supported but use is discouraged.
- We have `!j2:secret` in addition to `!j2_secret` for consistency. Use of
`!j2_secret` is discouraged.
### Breaking in 0.7
- We've **DEPRECATED** our homegrown multiple dispatch system `gamma.dispatch`,
replacing it by [`plum`][plum]. Unless you were using `gamma.dispatch` directly, or
extending via [custom tags][custom tags], no need to worry. The `gamma.dispatch`
package will be removed by release 1.0.
### New in 0.7
- We have a new home in https://github.com/cjalmeida/gamma-config !
### Breaking in 0.6
- Strict support for [YAML 1.2 Core Schema](https://yaml.org/spec/1.2.1/#id2804923).
In practice, unquoted ISO8610 dates (eg. `2022-12-20`) won't get converted
to `datetime.date` or `datetime.datetime` objects. Use `!date` or `!datetime`
if needed.
- `.env` files are loaded automatically and get precedence over `config.env`
and `config.local.env`.
- Use of `config.env` and `config.local.env` is deprecated.
- Default scaffolded `include_folder` interpret `ENVIRONMENT` variable string like
`foo bar` as two separate environment subfolders.
- (dispatch) `Val` arguments passed as class (eg. `foo(Val['bar'])`) will be converted
to instance, as if it were called `foo(Val['bar']())`
- The `!py:<module>:<func>` will no longer a single `None` argument
### New in 0.6
- Support for [YAML Anchors and Aliases](https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#anchors)
### Breaking changes in 0.5
- When using the dot (`.`) syntax, missing values raise `AttributeError` instead of returning
a false-y object.
- Dropped support for Python 3.7
### New in 0.5
- We're now in PyPI!
- Options for installing extra dependencies (eg. `jinja2`, `pydantic`)
[structured]: https://cjalmeida.github.io/gamma-config/structured/
[plum]: https://github.com/beartype/plum
[custom tags]: https://cjalmeida.github.io/gamma-config/custom-tags/
Raw data
{
"_id": null,
"home_page": "",
"name": "gamma-config",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "",
"author_email": "Cloves Almeida <cjalmeida@gmail.com>",
"download_url": "",
"platform": null,
"description": "# Gamma Config\n\n  \n\nAn opinionated way of setting up configuration for data science projects.\n\n## Overview\n\nGamma config provides a standard and flexible way of implementing application\nconfiguration primarily based on YAML files. It promotes best practices by:\n\n- simplify separation of code and config data;\n- breaking large, complex configuration into multiple files;\n- providing a way to write environment-aware config files;\n- facilitating security best-practices, like proper secrets management;\n- providing a immutable central global object storing **all** contextual data.\n\nAnother benefit of a standard config mechanism is allowing Gamma extension\nlibraries to provide configuration in a common way.\n\n## Features\n\n- Configuration expressed as a set of YAML files (by defaul) inside a\n `config` folder in the root of the project.\n- Multiple YAML files merged following simple rules. Simple file ordering convention\n using two digit prefixes.\n- Builtin support for environment specific parameters (production, development, etc.)\n- Support for `.env` files via `python-dotenv`, including `.local.env` that\n can be added to `.gitignore`\n- Dynamic evaluation via YAML tags. For instance, the `!ref` tag allow you to\n reference other parameters in any config file.\n- Custom tag support via simple and cool multiple dispatch mechanism.\n- Round-trip dump of config back into YAML. Support for hiding sensitive data\n on dump.\n- Simplified key access via dot (`.`). Eg. for `config: {foo: {bar: 100}}`,\n this is True: `config.foo.bar == 100`\n\n[Click here to view the full documentation](https://cjalmeida.github.io/gamma-config/)\n\n## Getting started\n\nUsing pip:\n\n```bash\npip install gamma-config\n```\n\nIn most cases, you'll want to use the `!j2` tag to interpolate values using Jinja2.\nThis requires manually installing the `jinja2` package or using the `jinja2` extras.\n\n```bash\npip install gamma-config[jinja2]\n```\n\nYou must install `pydantic` if using the [structured configuration][structured] feature.\n\n```bash\npip install gamma-config[pydantic]\n```\n\n## Basic Usage\n\nThe package comes with \"scaffolding\" to help you get started. In your project folder:\n\n```bash\n python -m gamma.config.scaffold\n```\n\nRemove the sample files, then create yourself a `config/20-myconfig.yaml` file\nwith the contents:\n\n```yaml\nfoo: 1\nuser: !env USER\n```\n\nTo access the config from within your Python program:\n\n```python\nimport os\nfrom gamma.config import get_config\n\ndef run():\n\n # it's safe and efficient to call this multiple times\n config = get_config()\n\n # get static value using the dict keys or attribute access\n assert config[\"foo\"] == 1\n assert config.foo == 1\n\n # get dynamic variables\n assert config[\"user\"] == os.getenv(\"USER\")\n assert config.user == os.getenv(\"USER\")\n```\n\nMost of the magic happen via tags. Look at the documentation for info on the [built-in tags](tags) available.\n\n## Changelog\n\n### Breaking in 0.8\n\n- We **DEPRECATED** `!py` and `!obj` tags, replacing them by the cleaner/simpler\n [`!call` tag](built-in-tags/#call). Those are schedule to be removed by release 1.0.\n\n- We **DEPRECATED** \"Structured configuration\" support, We recommend directly using \n [Pydantic's V2 discriminated unions](https://docs.pydantic.dev/latest/usage/types/unions/#discriminated-unions-aka-tagged-unions) \n as an alternative.\n\n- By default, `!env`, `!expr` and `!call` will not dump the contents on a `to_yaml`\n call. We provide `!env:dump`, `!expr:dump`, `!call:dump` to force dumping. Tag \n `!env_secret` is still supported but use is discouraged.\n\n- We have `!j2:secret` in addition to `!j2_secret` for consistency. Use of\n `!j2_secret` is discouraged.\n\n### Breaking in 0.7\n\n- We've **DEPRECATED** our homegrown multiple dispatch system `gamma.dispatch`,\n replacing it by [`plum`][plum]. Unless you were using `gamma.dispatch` directly, or\n extending via [custom tags][custom tags], no need to worry. The `gamma.dispatch`\n package will be removed by release 1.0.\n\n### New in 0.7\n\n- We have a new home in https://github.com/cjalmeida/gamma-config !\n\n### Breaking in 0.6\n\n- Strict support for [YAML 1.2 Core Schema](https://yaml.org/spec/1.2.1/#id2804923).\n In practice, unquoted ISO8610 dates (eg. `2022-12-20`) won't get converted\n to `datetime.date` or `datetime.datetime` objects. Use `!date` or `!datetime`\n if needed.\n- `.env` files are loaded automatically and get precedence over `config.env`\n and `config.local.env`.\n- Use of `config.env` and `config.local.env` is deprecated.\n- Default scaffolded `include_folder` interpret `ENVIRONMENT` variable string like\n `foo bar` as two separate environment subfolders.\n- (dispatch) `Val` arguments passed as class (eg. `foo(Val['bar'])`) will be converted\n to instance, as if it were called `foo(Val['bar']())`\n- The `!py:<module>:<func>` will no longer a single `None` argument\n\n### New in 0.6\n\n- Support for [YAML Anchors and Aliases](https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#anchors)\n\n### Breaking changes in 0.5\n\n- When using the dot (`.`) syntax, missing values raise `AttributeError` instead of returning\n a false-y object.\n- Dropped support for Python 3.7\n\n### New in 0.5\n\n- We're now in PyPI!\n- Options for installing extra dependencies (eg. `jinja2`, `pydantic`)\n\n[structured]: https://cjalmeida.github.io/gamma-config/structured/\n[plum]: https://github.com/beartype/plum\n[custom tags]: https://cjalmeida.github.io/gamma-config/custom-tags/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Config handling for data science projects",
"version": "0.8.11",
"project_urls": {
"Documentation": "https://github.gamma.bcg.com/pages/BCG/gamma-config/",
"Source": "https://github.gamma.bcg.com/BCG/gamma-config/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "263ffc293b5fae88ae9b80b477566ece725fe76d058aefa899a80ff444a08522",
"md5": "0ed5c57f92477ea820a410a0268eaced",
"sha256": "ec050d0745b0e47019d6e07b86fcd0d09fae4d2d2e671c8087dbe1309fc1e71c"
},
"downloads": -1,
"filename": "gamma_config-0.8.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0ed5c57f92477ea820a410a0268eaced",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41547,
"upload_time": "2024-01-27T18:56:34",
"upload_time_iso_8601": "2024-01-27T18:56:34.895010Z",
"url": "https://files.pythonhosted.org/packages/26/3f/fc293b5fae88ae9b80b477566ece725fe76d058aefa899a80ff444a08522/gamma_config-0.8.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-27 18:56:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "gamma-config"
}
