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": "",
"name": "yaml-settings-pydantic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "env,config,pydantic,settings,pydantic-settings,yaml,json,yaml-settings-pydantic",
"author": "",
"author_email": "Adrian Cederberg <adrn.cederberg123@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/10/c7/5183195c7f695520d8ceb1a0e62b9be904acb4beea88a062777ae61081e3/yaml-settings-pydantic-2.0.1.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",
"bugtrack_url": null,
"license": "",
"summary": "A tool to easily load (many) JSON/YAML files as pydantic settings.",
"version": "2.0.1",
"project_urls": null,
"split_keywords": [
"env",
"config",
"pydantic",
"settings",
"pydantic-settings",
"yaml",
"json",
"yaml-settings-pydantic"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4f3252ed83f78e52bec981d18c561e1c99792799b5bda190bda3f368a94500f2",
"md5": "62ae8bf01a14a9ed2dfec1d470641776",
"sha256": "80deee2bdfb2147fdf88618395bff61ca3c96999e1ab71e53bfcccaeee73be8f"
},
"downloads": -1,
"filename": "yaml_settings_pydantic-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62ae8bf01a14a9ed2dfec1d470641776",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7170,
"upload_time": "2023-10-20T15:59:43",
"upload_time_iso_8601": "2023-10-20T15:59:43.885362Z",
"url": "https://files.pythonhosted.org/packages/4f/32/52ed83f78e52bec981d18c561e1c99792799b5bda190bda3f368a94500f2/yaml_settings_pydantic-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "10c75183195c7f695520d8ceb1a0e62b9be904acb4beea88a062777ae61081e3",
"md5": "b7442a50580f5bd1af0217b0efea6f49",
"sha256": "13fb946b94ac0f68447cd30933a5ed211f93fb1023301726737ee4103d838f62"
},
"downloads": -1,
"filename": "yaml-settings-pydantic-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "b7442a50580f5bd1af0217b0efea6f49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11219,
"upload_time": "2023-10-20T15:59:45",
"upload_time_iso_8601": "2023-10-20T15:59:45.323606Z",
"url": "https://files.pythonhosted.org/packages/10/c7/5183195c7f695520d8ceb1a0e62b9be904acb4beea88a062777ae61081e3/yaml-settings-pydantic-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-20 15:59:45",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "yaml-settings-pydantic"
}