{"author":"Explosion","author_email":"contact@explosion.ai","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","Environment :: Console","Intended Audience :: Developers","Intended Audience :: Science/Research","License :: OSI Approved :: MIT License","Operating System :: MacOS :: MacOS X","Operating System :: Microsoft :: Windows","Operating System :: POSIX :: Linux","Programming Language :: Python :: 3","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.6","Programming Language :: Python :: 3.7","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Topic :: Scientific/Engineering"],"description":"

\n\n# Confection: The sweetest config system for Python\n\n`confection` :candy: is a lightweight library that offers a **configuration\nsystem** letting you conveniently describe arbitrary trees of objects.\n\nConfiguration is a huge challenge for machine-learning code because you may want\nto expose almost any detail of any function as a hyperparameter. The setting you\nwant to expose might be arbitrarily far down in your call stack, so it might\nneed to pass all the way through the CLI or REST API, through any number of\nintermediate functions, affecting the interface of everything along the way. And\nthen once those settings are added, they become hard to remove later. Default\nvalues also become hard to change without breaking backwards compatibility.\n\nTo solve this problem, `confection` offers a config system that lets you easily\ndescribe arbitrary trees of objects. The objects can be created via function\ncalls you register using a simple decorator syntax. You can even version the\nfunctions you create, allowing you to make improvements without breaking\nbackwards compatibility. The most similar config system we’re aware of is\n[Gin](https://github.com/google/gin-config), which uses a similar syntax, and\nalso allows you to link the configuration system to functions in your code using\na decorator. `confection`'s config system is simpler and emphasizes a different\nworkflow via a subset of Gin’s functionality.\n\n[![tests](https://github.com/explosion/confection/actions/workflows/tests.yml/badge.svg)](https://github.com/explosion/confection/actions/workflows/tests.yml)\n[![Current Release Version](https://img.shields.io/github/v/release/explosion/confection.svg?style=flat-square&include_prereleases&logo=github)](https://github.com/explosion/confection/releases)\n[![pypi Version](https://img.shields.io/pypi/v/confection.svg?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/confection/)\n[![conda Version](https://img.shields.io/conda/vn/conda-forge/confection.svg?style=flat-square&logo=conda-forge&logoColor=white)](https://anaconda.org/conda-forge/confection)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg?style=flat-square)](https://github.com/ambv/black)\n\n## ⏳ Installation\n\n```bash\npip install confection\n```\n\n```bash\nconda install -c conda-forge confection\n```\n\n## 👩‍💻 Usage\n\nThe configuration system parses a `.cfg` file like\n\n```ini\n[training]\npatience = 10\ndropout = 0.2\nuse_vectors = false\n\n[training.logging]\nlevel = \"INFO\"\n\n[nlp]\n# This uses the value of training.use_vectors\nuse_vectors = ${training.use_vectors}\nlang = \"en\"\n```\n\nand resolves it to a `Dict`:\n\n```json\n{\n \"training\": {\n \"patience\": 10,\n \"dropout\": 0.2,\n \"use_vectors\": false,\n \"logging\": {\n \"level\": \"INFO\"\n }\n },\n \"nlp\": {\n \"use_vectors\": false,\n \"lang\": \"en\"\n }\n}\n```\n\nThe config is divided into sections, with the section name in square brackets –\nfor example, `[training]`. Within the sections, config values can be assigned to\nkeys using `=`. Values can also be referenced from other sections using the dot\nnotation and placeholders indicated by the dollar sign and curly braces. For\nexample, `${training.use_vectors}` will receive the value of use_vectors in the\ntraining block. This is useful for settings that are shared across components.\n\nThe config format has three main differences from Python’s built-in\n`configparser`:\n\n1. JSON-formatted values. `confection` passes all values through `json.loads` to\n interpret them. You can use atomic values like strings, floats, integers or\n booleans, or you can use complex objects such as lists or maps.\n2. Structured sections. `confection` uses a dot notation to build nested\n sections. If you have a section named `[section.subsection]`, `confection`\n will parse that into a nested structure, placing subsection within section.\n3. References to registry functions. If a key starts with `@`, `confection` will\n interpret its value as the name of a function registry, load the function\n registered for that name and pass in the rest of the block as arguments. If\n type hints are available on the function, the argument values (and return\n value of the function) will be validated against them. This lets you express\n complex configurations, like a training pipeline where `batch_size` is\n populated by a function that yields floats.\n\nThere’s no pre-defined scheme you have to follow; how you set up the top-level\nsections is up to you. At the end of it, you’ll receive a dictionary with the\nvalues that you can use in your script – whether it’s complete initialized\nfunctions, or just basic settings.\n\nFor instance, let’s say you want to define a new optimizer. You'd define its\narguments in `config.cfg` like so:\n\n```ini\n[optimizer]\n@optimizers = \"my_cool_optimizer.v1\"\nlearn_rate = 0.001\ngamma = 1e-8\n```\n\nTo load and parse this configuration using a `catalogue` registry (install\n[`catalogue`](https://github.com/explosion/catalogue) separately):\n\n```python\nimport dataclasses\nfrom typing import Union, Iterable\nimport catalogue\nfrom confection import registry, Config\n\n# Create a new registry.\nregistry.optimizers = catalogue.create(\"confection\", \"optimizers\", entry_points=False)\n\n\n# Define a dummy optimizer class.\n@dataclasses.dataclass\nclass MyCoolOptimizer:\n learn_rate: float\n gamma: float\n\n\n@registry.optimizers.register(\"my_cool_optimizer.v1\")\ndef make_my_optimizer(learn_rate: Union[float, Iterable[float]], gamma: float):\n return MyCoolOptimizer(learn_rate, gamma)\n\n\n# Load the config file from disk, resolve it and fetch the instantiated optimizer object.\nconfig = Config().from_disk(\"./config.cfg\")\nresolved = registry.resolve(config)\noptimizer = resolved[\"optimizer\"] # MyCoolOptimizer(learn_rate=0.001, gamma=1e-08)\n```\n\n> ⚠️ Caution: Type-checkers such as `mypy` will mark adding new attributes to `registry` this way - i. e. \n> `registry.new_attr = ...` - as errors. This is because a new attribute is added to the class after initialization. If \n> you are using typecheckers, you can either ignore this (e. g. with `# type: ignore` for `mypy`) or use a typesafe \n> alternative: instead of `registry.new_attr = ...`, use `setattr(registry, \"new_attr\", ...)`. \n\nUnder the hood, `confection` will look up the `\"my_cool_optimizer.v1\"` function\nin the \"optimizers\" registry and then call it with the arguments `learn_rate`\nand `gamma`. If the function has type annotations, it will also validate the\ninput. For instance, if `learn_rate` is annotated as a float and the config\ndefines a string, `confection` will raise an error.\n\nThe Thinc documentation offers further information on the configuration system:\n\n- [recursive blocks](https://thinc.ai/docs/usage-config#registry-recursive)\n- [defining variable positional arguments](https://thinc.ai/docs/usage-config#registries-args)\n- [using interpolation](https://thinc.ai/docs/usage-config#config-interpolation)\n- [using custom registries](https://thinc.ai/docs/usage-config#registries-custom)\n- [advanced type annotations with Pydantic](https://thinc.ai/docs/usage-config#advanced-types)\n- [using base schemas](https://thinc.ai/docs/usage-config#advanced-types-base-schema)\n- [filling a configuration with defaults](https://thinc.ai/docs/usage-config#advanced-types-fill-defaults)\n\n## 🎛 API\n\n### class `Config`\n\nThis class holds the model and training\n[configuration](https://thinc.ai/docs/usage-config) and can load and save the\nINI-style configuration format from/to a string, file or bytes. The `Config`\nclass is a subclass of `dict` and uses Python’s `ConfigParser` under the hood.\n\n#### ^{method `Config.__init__`}\n\nInitialize a new `Config` object with optional data.\n\n```python\nfrom confection import Config\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\n```\n\n| Argument | Type | Description |\n| ----------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `data` | `Optional[Union[Dict[str, Any], Config]]` | Optional data to initialize the config with. |\n| `section_order` | `Optional[List[str]]` | Top-level section names, in order, used to sort the saved and loaded config. All other sections will be sorted alphabetically. |\n| `is_interpolated` | `Optional[bool]` | Whether the config is interpolated or whether it contains variables. Read from the `data` if it’s an instance of `Config` and otherwise defaults to `True`. |\n\n#### ^{method `Config.from_str`}\n\nLoad the config from a string.\n\n```python\nfrom confection import Config\n\nconfig_str = \"\"\"\n[training]\npatience = 10\ndropout = 0.2\n\"\"\"\nconfig = Config().from_str(config_str)\nprint(config[\"training\"]) # {'patience': 10, 'dropout': 0.2}}\n```\n\n| Argument | Type | Description |\n| ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `text` | `str` | The string config to load. |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n| `overrides` | `Dict[str, Any]` | Overrides for values and sections. Keys are provided in dot notation, e.g. `\"training.dropout\"` mapped to the value. |\n| **RETURNS** | `Config` | The loaded config. |\n\n#### ^{method `Config.to_str`}\n\nLoad the config from a string.\n\n```python\nfrom confection import Config\n\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\nprint(config.to_str()) # '[training]\\npatience = 10\\n\\ndropout = 0.2'\n```\n\n| Argument | Type | Description |\n| ------------- | ------ | --------------------------------------------------------------------------- |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n| **RETURNS** | `str` | The string config. |\n\n#### ^{method `Config.to_bytes`}\n\nSerialize the config to a byte string.\n\n```python\nfrom confection import Config\n\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\nconfig_bytes = config.to_bytes()\nprint(config_bytes) # b'[training]\\npatience = 10\\n\\ndropout = 0.2'\n```\n\n| Argument | Type | Description |\n| ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n| `overrides` | `Dict[str, Any]` | Overrides for values and sections. Keys are provided in dot notation, e.g. `\"training.dropout\"` mapped to the value. |\n| **RETURNS** | `str` | The serialized config. |\n\n#### ^{method `Config.from_bytes`}\n\nLoad the config from a byte string.\n\n```python\nfrom confection import Config\n\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\nconfig_bytes = config.to_bytes()\nnew_config = Config().from_bytes(config_bytes)\n```\n\n| Argument | Type | Description |\n| ------------- | -------- | --------------------------------------------------------------------------- |\n| `bytes_data` | `bool` | The data to load. |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n| **RETURNS** | `Config` | The loaded config. |\n\n#### ^{method `Config.to_disk`}\n\nSerialize the config to a file.\n\n```python\nfrom confection import Config\n\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\nconfig.to_disk(\"./config.cfg\")\n```\n\n| Argument | Type | Description |\n| ------------- | ------------------ | --------------------------------------------------------------------------- |\n| `path` | `Union[Path, str]` | The file path. |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n\n#### ^{method `Config.from_disk`}\n\nLoad the config from a file.\n\n```python\nfrom confection import Config\n\nconfig = Config({\"training\": {\"patience\": 10, \"dropout\": 0.2}})\nconfig.to_disk(\"./config.cfg\")\nnew_config = Config().from_disk(\"./config.cfg\")\n```\n\n| Argument | Type | Description |\n| ------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- |\n| `path` | `Union[Path, str]` | The file path. |\n| `interpolate` | `bool` | Whether to interpolate variables like `${section.key}`. Defaults to `True`. |\n| `overrides` | `Dict[str, Any]` | Overrides for values and sections. Keys are provided in dot notation, e.g. `\"training.dropout\"` mapped to the value. |\n| **RETURNS** | `Config` | The loaded config. |\n\n#### ^{method `Config.copy`}\n\nDeep-copy the config.\n\n| Argument | Type | Description |\n| ----------- | -------- | ------------------ |\n| **RETURNS** | `Config` | The copied config. |\n\n#### ^{method `Config.interpolate`}\n\nInterpolate variables like `${section.value}` or `${section.subsection}` and\nreturn a copy of the config with interpolated values. Can be used if a config is\nloaded with `interpolate=False`, e.g. via `Config.from_str`.\n\n```python\nfrom confection import Config\n\nconfig_str = \"\"\"\n[hyper_params]\ndropout = 0.2\n\n[training]\ndropout = ${hyper_params.dropout}\n\"\"\"\nconfig = Config().from_str(config_str, interpolate=False)\nprint(config[\"training\"]) # {'dropout': '${hyper_params.dropout}'}}\nconfig = config.interpolate()\nprint(config[\"training\"]) # {'dropout': 0.2}}\n```\n\n| Argument | Type | Description |\n| ----------- | -------- | ---------------------------------------------- |\n| **RETURNS** | `Config` | A copy of the config with interpolated values. |\n\n##### ^{method `Config.merge`}\n\nDeep-merge two config objects, using the current config as the default. Only\nmerges sections and dictionaries and not other values like lists. Values that\nare provided in the updates are overwritten in the base config, and any new\nvalues or sections are added. If a config value is a variable like\n`${section.key}` (e.g. if the config was loaded with `interpolate=False)`, **the\nvariable is preferred**, even if the updates provide a different value. This\nensures that variable references aren’t destroyed by a merge.\n\n> :warning: Note that blocks that refer to registered functions using the `@`\n> syntax are only merged if they are referring to the same functions. Otherwise,\n> merging could easily produce invalid configs, since different functions can\n> take different arguments. If a block refers to a different function, it’s\n> overwritten.\n\n```python\nfrom confection import Config\n\nbase_config_str = \"\"\"\n[training]\npatience = 10\ndropout = 0.2\n\"\"\"\nupdate_config_str = \"\"\"\n[training]\ndropout = 0.1\nmax_epochs = 2000\n\"\"\"\n\nbase_config = Config().from_str(base_config_str)\nupdate_config = Config().from_str(update_config_str)\nmerged = Config(base_config).merge(update_config)\nprint(merged[\"training\"]) # {'patience': 10, 'dropout': 0.1, 'max_epochs': 2000}\n```\n\n| Argument | Type | Description |\n| ----------- | ------------------------------- | --------------------------------------------------- |\n| `overrides` | `Union[Dict[str, Any], Config]` | The updates to merge into the config. |\n| **RETURNS** | `Config` | A new config instance containing the merged config. |\n\n### Config Attributes\n\n| Argument | Type | Description |\n| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `is_interpolated` | `bool` | Whether the config values have been interpolated. Defaults to `True` and is set to `False` if a config is loaded with `interpolate=False`, e.g. using `Config.from_str`. |\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":"https://github.com/explosion/confection","keywords":null,"license":"MIT","license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"confection","package_url":"https://pypi.org/project/confection/","platform":null,"project_url":"https://pypi.org/project/confection/","project_urls":{"Homepage":"https://github.com/explosion/confection"},"provides_extra":null,"release_url":"https://pypi.org/project/confection/0.1.5/","requires_dist":["pydantic!=1.8,!=1.8.1,<3.0.0,>=1.7.4","srsly<3.0.0,>=2.4.0","typing-extensions<5.0.0,>=3.7.4.1; python_version < \"3.8\""],"requires_python":">=3.6","summary":"The sweetest config system for Python","version":"0.1.5","yanked":false,"yanked_reason":null}

Dependencies of confection (3).
Dependency	Optional
pydantic	false
srsly	false
typing-extensions	false

Package search

confection

project_urls

Dependencies

All package metadata

Releases