# dataclass-settings
[](https://github.com/dancardin/dataclass-settings/actions)
[](https://coveralls.io/github/DanCardin/dataclass-settings?branch=main)
[](https://dataclass-settings.readthedocs.io/en/latest/?badge=latest)
- [Full documentation here](https://dataclass-settings.readthedocs.io/en/latest/).
- [Bundled Loaders](https://dataclass-settings.readthedocs.io/en/latest/loaders.html).
`dataclass-settings` intends to work with any
[PEP-681](https://peps.python.org/pep-0681/)-compliant dataclass-like object,
including but not limited to:
- [Pydantic models](https://pydantic-docs.helpmanual.io/) (v1/v2),
- [dataclasses](https://docs.python.org/3/library/dataclasses.html)
- [attrs classes](https://www.attrs.org/en/stable/).
`dataclass-settings` owes its existence
[pydantic-settings](https://github.com/pydantic/pydantic-settings), in that
pydantic-settings will be a benchmark for `dataclass-settings`'s featureset.
However it was bourne out of frustration with pydantic-setting's approach to
implementing that featureset.
## Example
```python
from __future__ import annotations
from dataclass_settings import load_settings, Env, Secret
from pydantic import BaseModel
class Example(BaseModel):
env: Annotated[str, Env("ENVIRONMENT")] = "local"
dsn: Annotated[str, Env("DSN"), Secret('dsn')] = "dsn://"
sub_config: SubConfig
class SubConfig(BaseModel):
nested: Annotated[int, Env("NESTED")] = "4"
example: Example = load_settings(Example)
# or, if you want `nested` to be `SUB_CONFIG_NESTED`
example: Example = load_settings(Example, nested_delimiter='_')
```
## vs Pydantic Settings
### Simplicity
- `pydantic-settings` alters how you go about defining your normal pydantic
models. You need to switch (some of the) base classes, you need to configure
the magical `model_config = SettingsConfigDict(...)` object, etc.
The model becomes inherently entangled with the settings-loading library.
- `dataclass-settings` attaches targeted Annotations metadata to a vanilla
pydantic model. You can **choose** to not use `load_settings` (for example, in
tests), and construct the model instance however you'd like.
### Clarity
- `pydantic-settings` makes it really, really difficult to intuit what the
concrete environment varibale that's going to be loaded for a given field is
**actually** going to be. Based on my own experience, and from perusing their
issue tracker, it seems like this is not an uncommon experience.
The combination of field name, `SettingsConfigDict` settings, casing,
`alias`/`validation_alias`/`serialization_alias`, and relative position of the
env var in the greater config all contribute to it being a **task** to deduce
which concrete name will be used when loading.
- `dataclass-settings` by **default** requires an explicit, concrete name, which
maps directly to the value being loaded (`Env('FOO')` loads `FOO`, for sure!)
If you want to opt into a less explcict, more inferred setup (like
pydantic-settings), you can do so by utilizing the `nested_delimiter='_'` and
`infer_name=True` arguments.
### Typing
- `pydantic-settings` does not play **super** well with type checkers,
necessitating the use of a mypy plugin for it to not emit type errors into
user code.
The code recommended in their documentation for namespacing settings, looks
like:
```python
class Settings(BaseSettings):
more_settings: SubModel = SubModel()
```
This only type-checks with mypy (after using the plugin), but not
pyright/pylance. Additionally, this **actually** evaluates the `SubModel`
constructor during module parsing!
These issues seem(?) to be inherent to the strategy of subclassing
`BaseModel`, and building in its logic into the object construction process
- `dataclass-settings` sidesteps this problem by decoupling the definition of
the settings from the loading of settings.
As such, you're more able to define the model, exactly as you would have with
vanilla pydantic:
```python
class Settings(BaseModel):
more_settings: SubModel
```
Internally, the `load_settings` function handles the work of constructing the
requisite input structure pydantic expects to construct the whole object tree.
### Compatibility
- `pydantic-settings`'s `BaseSettings` inherits from pydantic's `BaseModel`. And
thus can only function against pydantic models, as the name would imply.
- `dataclass-settings`'s primary entrypoint is a function that accepts a
supportable type. As such, it can theoretically support any type that has a
well defined object structure, like all of `pydantic`, `dataclasses`, and
`attrs`.
Practically, `pydantic` has the most robust system for parsing/validating a
json-like structure into the models, so it's probably to be the most flexible
anyways. But for many simple cases, particuarly those without nesting, or that
only deal in simple types (like int, float, str, etc); then dataclasses/attrs
can certainly provide a similar experience.
### Flexibility
- At time of writing, `pydantic-settings`'s strategy around "loaders", i.e.
supportable settings sources is relatively inflexible. Their issue tracker
contains a decent number of requests for a more flexible way of defining
settings priorities among different loaders, or even using different settings
from within a loader.
This, at least, doesn't seem to be an inherent issue to the library
necessarily. Just that at present, their API appears to try to reuse
pydantic's `Field` and `alias` mechanisms to infer the settings for all
loaders.
- `dataclass-settings` instead annotates each field individually, with the
loaders that field should use. That means you can have different priorities
(or entirely different loaders!) per field.
Raw data
{
"_id": null,
"home_page": "https://github.com/dancardin/dataclass-settings",
"name": "dataclass-settings",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "dataclass, attrs, pydantic, msgspec, env, settings",
"author": "DanCardin",
"author_email": "ddcardin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f2/e4/55d61bfbe199ca8b02f47e4d9491a9c705fc3a14cc34b1fdc05cb8ea1e35/dataclass_settings-0.5.0.tar.gz",
"platform": null,
"description": "# dataclass-settings\n\n[](https://github.com/dancardin/dataclass-settings/actions)\n[](https://coveralls.io/github/DanCardin/dataclass-settings?branch=main)\n[](https://dataclass-settings.readthedocs.io/en/latest/?badge=latest)\n\n- [Full documentation here](https://dataclass-settings.readthedocs.io/en/latest/).\n- [Bundled Loaders](https://dataclass-settings.readthedocs.io/en/latest/loaders.html).\n\n`dataclass-settings` intends to work with any\n[PEP-681](https://peps.python.org/pep-0681/)-compliant dataclass-like object,\nincluding but not limited to:\n\n- [Pydantic models](https://pydantic-docs.helpmanual.io/) (v1/v2),\n- [dataclasses](https://docs.python.org/3/library/dataclasses.html)\n- [attrs classes](https://www.attrs.org/en/stable/).\n\n`dataclass-settings` owes its existence\n[pydantic-settings](https://github.com/pydantic/pydantic-settings), in that\npydantic-settings will be a benchmark for `dataclass-settings`'s featureset.\nHowever it was bourne out of frustration with pydantic-setting's approach to\nimplementing that featureset.\n\n## Example\n\n```python\nfrom __future__ import annotations\nfrom dataclass_settings import load_settings, Env, Secret\nfrom pydantic import BaseModel\n\n\nclass Example(BaseModel):\n env: Annotated[str, Env(\"ENVIRONMENT\")] = \"local\"\n dsn: Annotated[str, Env(\"DSN\"), Secret('dsn')] = \"dsn://\"\n\n sub_config: SubConfig\n\n\nclass SubConfig(BaseModel):\n nested: Annotated[int, Env(\"NESTED\")] = \"4\"\n\n\nexample: Example = load_settings(Example)\n\n# or, if you want `nested` to be `SUB_CONFIG_NESTED`\nexample: Example = load_settings(Example, nested_delimiter='_')\n```\n\n## vs Pydantic Settings\n\n### Simplicity\n\n- `pydantic-settings` alters how you go about defining your normal pydantic\n models. You need to switch (some of the) base classes, you need to configure\n the magical `model_config = SettingsConfigDict(...)` object, etc.\n\n The model becomes inherently entangled with the settings-loading library.\n\n- `dataclass-settings` attaches targeted Annotations metadata to a vanilla\n pydantic model. You can **choose** to not use `load_settings` (for example, in\n tests), and construct the model instance however you'd like.\n\n### Clarity\n\n- `pydantic-settings` makes it really, really difficult to intuit what the\n concrete environment varibale that's going to be loaded for a given field is\n **actually** going to be. Based on my own experience, and from perusing their\n issue tracker, it seems like this is not an uncommon experience.\n\n The combination of field name, `SettingsConfigDict` settings, casing,\n `alias`/`validation_alias`/`serialization_alias`, and relative position of the\n env var in the greater config all contribute to it being a **task** to deduce\n which concrete name will be used when loading.\n\n- `dataclass-settings` by **default** requires an explicit, concrete name, which\n maps directly to the value being loaded (`Env('FOO')` loads `FOO`, for sure!)\n\n If you want to opt into a less explcict, more inferred setup (like\n pydantic-settings), you can do so by utilizing the `nested_delimiter='_'` and\n `infer_name=True` arguments.\n\n### Typing\n\n- `pydantic-settings` does not play **super** well with type checkers,\n necessitating the use of a mypy plugin for it to not emit type errors into\n user code.\n\n The code recommended in their documentation for namespacing settings, looks\n like:\n\n ```python\n class Settings(BaseSettings):\n more_settings: SubModel = SubModel()\n ```\n\n This only type-checks with mypy (after using the plugin), but not\n pyright/pylance. Additionally, this **actually** evaluates the `SubModel`\n constructor during module parsing!\n\n These issues seem(?) to be inherent to the strategy of subclassing\n `BaseModel`, and building in its logic into the object construction process\n\n- `dataclass-settings` sidesteps this problem by decoupling the definition of\n the settings from the loading of settings.\n\n As such, you're more able to define the model, exactly as you would have with\n vanilla pydantic:\n\n ```python\n class Settings(BaseModel):\n more_settings: SubModel\n ```\n\n Internally, the `load_settings` function handles the work of constructing the\n requisite input structure pydantic expects to construct the whole object tree.\n\n### Compatibility\n\n- `pydantic-settings`'s `BaseSettings` inherits from pydantic's `BaseModel`. And\n thus can only function against pydantic models, as the name would imply.\n\n- `dataclass-settings`'s primary entrypoint is a function that accepts a\n supportable type. As such, it can theoretically support any type that has a\n well defined object structure, like all of `pydantic`, `dataclasses`, and\n `attrs`.\n\n Practically, `pydantic` has the most robust system for parsing/validating a\n json-like structure into the models, so it's probably to be the most flexible\n anyways. But for many simple cases, particuarly those without nesting, or that\n only deal in simple types (like int, float, str, etc); then dataclasses/attrs\n can certainly provide a similar experience.\n\n### Flexibility\n\n- At time of writing, `pydantic-settings`'s strategy around \"loaders\", i.e.\n supportable settings sources is relatively inflexible. Their issue tracker\n contains a decent number of requests for a more flexible way of defining\n settings priorities among different loaders, or even using different settings\n from within a loader.\n\n This, at least, doesn't seem to be an inherent issue to the library\n necessarily. Just that at present, their API appears to try to reuse\n pydantic's `Field` and `alias` mechanisms to infer the settings for all\n loaders.\n\n- `dataclass-settings` instead annotates each field individually, with the\n loaders that field should use. That means you can have different priorities\n (or entirely different loaders!) per field.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Declarative dataclass settings.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/dancardin/dataclass-settings",
"Repository": "https://github.com/dancardin/dataclass-settings"
},
"split_keywords": [
"dataclass",
" attrs",
" pydantic",
" msgspec",
" env",
" settings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "54bf5a2111134f1bbb0b84b7124a870ae039e4dfd2e126f7908f09226dd48b0c",
"md5": "c7cde197e6ebd144b6ded5a8637f6c3b",
"sha256": "a192c06ad8b9fcf31db421c7f21498b7c2e8a8258e78d5239a30f23d2079959a"
},
"downloads": -1,
"filename": "dataclass_settings-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7cde197e6ebd144b6ded5a8637f6c3b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 16309,
"upload_time": "2024-10-07T18:57:30",
"upload_time_iso_8601": "2024-10-07T18:57:30.158422Z",
"url": "https://files.pythonhosted.org/packages/54/bf/5a2111134f1bbb0b84b7124a870ae039e4dfd2e126f7908f09226dd48b0c/dataclass_settings-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2e455d61bfbe199ca8b02f47e4d9491a9c705fc3a14cc34b1fdc05cb8ea1e35",
"md5": "23d7926e106ebe8e9bd2804a345fe2c1",
"sha256": "ff3bf9c7e71f10057987b8667d2be246bdf758cbe63023ddb905fffaf8407b2c"
},
"downloads": -1,
"filename": "dataclass_settings-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "23d7926e106ebe8e9bd2804a345fe2c1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 15152,
"upload_time": "2024-10-07T18:57:32",
"upload_time_iso_8601": "2024-10-07T18:57:32.242800Z",
"url": "https://files.pythonhosted.org/packages/f2/e4/55d61bfbe199ca8b02f47e4d9491a9c705fc3a14cc34b1fdc05cb8ea1e35/dataclass_settings-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-07 18:57:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dancardin",
"github_project": "dataclass-settings",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "dataclass-settings"
}
JSON
