What?
===============================================================================
A simple tool for loading ``YAML`` and ``JSON`` configuration/settings using
``pydantic2``.
There is also a version for ``pydantic1``, see ``release/v1``. Major
versions of this package will match the major version of the respective
``pydantic`` release.
Why?
===============================================================================
This project can be helpful for projects that have large configuration files,
nested configuration files, or for those of us who don't like writing large ``.env``
files. It is also worth noting that due to the backwards compatability between
``YAML`` and ``JSON`` that this will also parse ``JSON`` configuration.
This can also be helpful when writing out application settings in kubernetes
/helm, where most configuration is written as ``YAML``. In such a case we may
want to validate/store our settings as ``YAML`` as writing ``JSON`` and
``JSON`` strings can be compersome due to syntax error in larger documents.
Installation
===============================================================================
Install using ``pip``:
.. code:: bash
pip install yaml-settings-pydantic
Examples
===============================================================================
Additional information
-------------------------------------------------------------------------------
First, it is worth reading the ``pydantic_settings`` docs about additional sources: https://docs.pydantic.dev/latest/usage/pydantic_settings/
Additionally see the example in ``./tests/examples/__init__.py``. It is gaurenteed to
work as its contents are tested. It contains information on how to write nested
configurations.
Tools
-------------------------------------------------------------------------------
There are three classes worth knowing about:
- ``YamlSettingsConfigDict`` -- ``pydantic_settings.SetttingsConfigDict``
extended to include the fields used by ``CreateYamlSettings``.
- ``CreateYamlSettings`` -- The pydantic ``PydanticBaseSettingsSource`` that
will analyze your class for the following class variables:
1. Files to be used -- under ``__env_yaml_files__`` or ``model_config.yaml_files``.
2. The reload settings -- under ``__env_yaml_reload__`` or ``model_config.yaml_reload``.
``CreateYamlSettings`` does not have to be used at all, but can be helpful if
you don't want to use ``BaseYamlSettings`` for any reason.
- ``BaseYamlSettings`` -- Use this directly as done in the example below. This
is 'the easy way'.
Minimal Examples
-------------------------------------------------------------------------------
The shortest possible example is as follows:
.. code:: python
from yaml_settings_pydantic import BaseYamlSettings
class MySettings(BaseYamlSettings):
__env_yaml_files__ = "settings.yaml"
setttingOne: str
settingTwo: str
...
...
Note that the above example can also be written like
.. code:: python
from yaml_settings_pydantic import BaseYamlSettings, YamlSettingsConfigDict
class MySettings(BaseYamlSettings):
model_config = YamlSettingsConfigDict(yaml_files="settings.yaml")
setttingOne: str
settingTwo: str
...
...
which is more like pydantic v2. The 'dunder' specifications will take priority
over their equivalent `model_config` specifications. These map as follows:
.. code:: text
+-----------------------+------------------+
| dunder | model_config |
+-----------------------+------------------+
| __env_yaml_files__ | yaml_files |
| __env_yaml_reload__ | yaml_reload |
+-----------------------+------------------+
Raw data
{
"_id": null,
"home_page": null,
"name": "yaml-settings-pydantic",
"maintainer": "Adrian Cederberg",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "adrn.cederberg123@gmail.com",
"keywords": "env, config, pydantic, settings, pydantic-settings, yaml, json, yaml-settings-pydantic",
"author": "Adrian Cederberg",
"author_email": "adrn.cederberg123@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/d3/958d75466277d73fffd7e685653dba4221dc637f4e8a23e2c18206b3c832/yaml_settings_pydantic-2.3.2.tar.gz",
"platform": null,
"description": "\nWhat?\n===============================================================================\n\nA simple tool for loading ``YAML`` and ``JSON`` configuration/settings using\n``pydantic2``.\n\nThere is also a version for ``pydantic1``, see ``release/v1``. Major\nversions of this package will match the major version of the respective\n``pydantic`` release.\n\n\nWhy?\n===============================================================================\n\nThis project can be helpful for projects that have large configuration files,\nnested configuration files, or for those of us who don't like writing large ``.env``\nfiles. It is also worth noting that due to the backwards compatability between\n``YAML`` and ``JSON`` that this will also parse ``JSON`` configuration.\n\nThis can also be helpful when writing out application settings in kubernetes\n/helm, where most configuration is written as ``YAML``. In such a case we may\nwant to validate/store our settings as ``YAML`` as writing ``JSON`` and\n``JSON`` strings can be compersome due to syntax error in larger documents.\n\n\nInstallation\n===============================================================================\n\n\nInstall using ``pip``:\n\n.. code:: bash\n\n pip install yaml-settings-pydantic\n\n\n\nExamples\n===============================================================================\n\nAdditional information\n-------------------------------------------------------------------------------\n\nFirst, it is worth reading the ``pydantic_settings`` docs about additional sources: https://docs.pydantic.dev/latest/usage/pydantic_settings/\n\nAdditionally see the example in ``./tests/examples/__init__.py``. It is gaurenteed to\nwork as its contents are tested. It contains information on how to write nested\nconfigurations.\n\n\nTools\n-------------------------------------------------------------------------------\n\nThere are three classes worth knowing about:\n\n- ``YamlSettingsConfigDict`` -- ``pydantic_settings.SetttingsConfigDict``\n extended to include the fields used by ``CreateYamlSettings``.\n- ``CreateYamlSettings`` -- The pydantic ``PydanticBaseSettingsSource`` that\n will analyze your class for the following class variables:\n\n 1. Files to be used -- under ``__env_yaml_files__`` or ``model_config.yaml_files``.\n 2. The reload settings -- under ``__env_yaml_reload__`` or ``model_config.yaml_reload``.\n\n ``CreateYamlSettings`` does not have to be used at all, but can be helpful if\n you don't want to use ``BaseYamlSettings`` for any reason.\n\n- ``BaseYamlSettings`` -- Use this directly as done in the example below. This\n is 'the easy way'.\n\n\nMinimal Examples\n-------------------------------------------------------------------------------\n\nThe shortest possible example is as follows:\n\n.. code:: python\n\n from yaml_settings_pydantic import BaseYamlSettings\n\n class MySettings(BaseYamlSettings):\n __env_yaml_files__ = \"settings.yaml\"\n\n setttingOne: str\n settingTwo: str\n ...\n\n ...\n\n\nNote that the above example can also be written like\n\n\n.. code:: python\n\n from yaml_settings_pydantic import BaseYamlSettings, YamlSettingsConfigDict\n\n class MySettings(BaseYamlSettings):\n model_config = YamlSettingsConfigDict(yaml_files=\"settings.yaml\")\n\n setttingOne: str\n settingTwo: str\n ...\n\n ...\n\n\nwhich is more like pydantic v2. The 'dunder' specifications will take priority\nover their equivalent `model_config` specifications. These map as follows:\n\n.. code:: text\n\n +-----------------------+------------------+\n | dunder | model_config |\n +-----------------------+------------------+\n | __env_yaml_files__ | yaml_files |\n | __env_yaml_reload__ | yaml_reload |\n +-----------------------+------------------+\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A tool to easily load (many) JSON/YAML files as pydantic settings.",
"version": "2.3.2",
"project_urls": null,
"split_keywords": [
"env",
" config",
" pydantic",
" settings",
" pydantic-settings",
" yaml",
" json",
" yaml-settings-pydantic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4793b8ad579aecf53d5805f7c4255a29ede935da4f78343176dc134506d7176a",
"md5": "eb7016c69a31ff60532959ec0dd171a0",
"sha256": "dd0e214d32ae7a8ca5cb9fe23d4be087bc63664a2fa076cea39b70e227b026a6"
},
"downloads": -1,
"filename": "yaml_settings_pydantic-2.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb7016c69a31ff60532959ec0dd171a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9105,
"upload_time": "2024-07-18T14:42:30",
"upload_time_iso_8601": "2024-07-18T14:42:30.235257Z",
"url": "https://files.pythonhosted.org/packages/47/93/b8ad579aecf53d5805f7c4255a29ede935da4f78343176dc134506d7176a/yaml_settings_pydantic-2.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fdd3958d75466277d73fffd7e685653dba4221dc637f4e8a23e2c18206b3c832",
"md5": "264b75717c12b8639ffa1b1407217486",
"sha256": "4dd8df300be4e5abc8a386843a197302c820d94e33e2e44be1fb22e2a5345df6"
},
"downloads": -1,
"filename": "yaml_settings_pydantic-2.3.2.tar.gz",
"has_sig": false,
"md5_digest": "264b75717c12b8639ffa1b1407217486",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 10682,
"upload_time": "2024-07-18T14:42:31",
"upload_time_iso_8601": "2024-07-18T14:42:31.761530Z",
"url": "https://files.pythonhosted.org/packages/fd/d3/958d75466277d73fffd7e685653dba4221dc637f4e8a23e2c18206b3c832/yaml_settings_pydantic-2.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-18 14:42:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "yaml-settings-pydantic"
}
JSON