nested-config 2.1.3__tar.gz

nested_config-2.1.3/.gitignore

@@ -0,0 +1,5 @@
+.venv
+dist
+__pycache__
+test_envs
+.env

nested_config-2.1.3/.gitlab-ci.yml

@@ -0,0 +1,77 @@
+# This file is a template, and might need editing before it works on your project.
+# This is a sample GitLab CI/CD configuration file that should run without any modifications.
+# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
+# it uses echo commands to simulate the pipeline execution.
+#
+# A pipeline is composed of independent jobs that run scripts, grouped into stages.
+# Stages run in sequential order, but jobs within stages run in parallel.
+#
+# For more information, see: https://docs.gitlab.com/ee/ci/yaml/index.html#stages
+#
+# You can copy and paste this template into a new `.gitlab-ci.yml` file.
+# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
+#
+# To contribute improvements to CI/CD templates, please follow the Development guide at:
+# https://docs.gitlab.com/ee/development/cicd/templates.html
+# This specific template is located at:
+# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Getting-Started.gitlab-ci.yml
+
+variables:
+  UV_VERSION: 0.5.20
+  BASE_LAYER: bookworm-slim
+  UV_RUN_NS: uv run --no-sync
+
+
+stages:
+  - test
+
+default:
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python3.12-$BASE_LAYER
+
+before_script:
+  - echo "UV_RUN_NS means '$UV_RUN_NS'"
+  - uv venv
+  - uv sync --all-extras
+
+
+pytest_38_oldest_pyd18:
+  stage: test
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python3.8-$BASE_LAYER
+  script:
+    # backtrack to all older versions
+    - uv pip install typing_extensions==4.6 pydantic==1.8 tomli==2.0.0 pyyaml==5.1
+    - $UV_RUN_NS mypy --always-true PYDANTIC_1 ./
+    - $UV_RUN_NS pytest
+
+
+pytest_38_all_latest:
+  stage: test
+  image: ghcr.io/astral-sh/uv:$UV_VERSION-python3.8-$BASE_LAYER
+  script:
+    - $UV_RUN_NS mypy --always-false PYDANTIC_1 ./
+    - $UV_RUN_NS pytest
+
+
+pytest_312_pyd18:
+  stage: test
+  script:
+    # backtrack to older pydantic
+    - uv pip install pydantic==1.8
+    - $UV_RUN_NS mypy --always-true PYDANTIC_1 ./
+    - $UV_RUN_NS pytest
+
+
+pytest_312_pyd110:
+  stage: test
+  script:
+    # backtrack to older pydantic
+    - uv pip install pydantic==1.10
+    - $UV_RUN_NS mypy --always-true PYDANTIC_1 ./
+    - $UV_RUN_NS pytest
+
+
+pytest_312_all_latest:
+  stage: test
+  script:
+    - $UV_RUN_NS mypy --always-false PYDANTIC_1 ./
+    - $UV_RUN_NS pytest

nested_config-2.1.3/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.1.3] - 2025-01-16
+
+- README updated.
+- Switch from poetry/poetry-core to uv/hatchling, including in CI/CI.
+- Replace `setuptools` dependency with `packaging`, since we're using it to get the
+  vendored `packaging` anyway.
+
+## [2.1.2] - 2024-04-19
+
+- Fixed problem where `expand_config` didn't work with PEP 563 stringized annotations. Now
+  using `typing.get_type_hints` rather than directly querying `__annotations__`.
+- Added test with `from __future__ import annotations`
+
+## [2.1.1] - 2024-04-19
+
+- Export ConfigExpansionError in `__init__.py`
+- Fix/update docstrings
+
+## [2.1.0] - 2024-04-18
+
+### Added
+
+- `nested_config.expand_config` - Recursively read in any config file(s) into a dict based
+  on model class(es). This is now the primary functionality, superseeding
+  `validate_config`, which will be deprecated.
+
+### Changed
+
+- Pydantic is now an extra (optional) dependency, only needed to use the below [deprecated
+  syntax](#2.1.0-deprecated). All Pydantic stuff has been merged into a single module and
+  emits deprecation warnings when used.
+- Improved deb build and test scripts
+
+### Deprecated <a name="2.1.0-deprecated"></a>
+
+- Pydantic PurePath validator and JSON encoder -- Doesn't need to be part of this project
+  and not needed in Pydantic 2+
+- Pydantic validation integration -- This project started out as being specifically for
+  working with Pydantic models and was tightly integrated with Pydantic, but that is no
+  longer necessary. Use with Pydantic or attrs or whatever is better left to the user.
+
+## [2.0.3] - 2024-04-15
+
+- Fix typing issue regression for Pydantic < 2.0 introduced in last release
+- Move package to `src` directory
+
+## [2.0.2] - 2024-04-12
+
+- Generalize handling of lists and dicts such that if the source config value and the
+  model annotation are both lists, recursively evaluate each item. This addresses the
+  situation where there may be a dict in the source config that corresponds to a Pydantic
+  model and that dict contains paths to other configs.
+
+## [2.0.1] - 2024-04-10
+
+- Make dependency specifications more generous
+- Use `yaml.safe_load`
+- Test minimum dependency versions in CI
+
+## [2.0.0] - 2024-04-09
+
+### Changed
+
+- Project renamed from **pydantic-plus** to **nested-config**
+
+### Added
+
+- Can find paths to other config files and parse them using their respective Pydantic
+  models using `validate_config` or `BaseModel` (this is the main functionality now).
+- Pydantic 2.0 compatibility.
+- Can validate any config file. TOML and JSON built in, YAML optional, others can be
+  added.
+- Validators for `PurePath` and `PureWindowsPath`
+- Simplify JSON encoder specification to work for all `PurePaths`
+- pytest and mypy checks, checked with GitLab CI/CD
+
+## [1.1.3] - 2021-07-30
+
+- Add README
+- Simplify PurePosixPath validator
+- Export `TomlParsingError` from rtoml for downstream exception handling (without needing to explicitly
+  import rtoml).
+
+[Unreleased]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.1.3...master
+[2.1.3]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.1.1...v2.1.3
+[2.1.2]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.1.1...v2.1.2
+[2.1.1]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.1.0...v2.1.1
+[2.1.0]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.0.3...v2.1.0
+[2.0.3]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.0.2...v2.0.3
+[2.0.2]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.0.1...v2.0.2
+[2.0.1]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v2.0.0...v2.0.1
+[2.0.0]: https://gitlab.com/osu-nrsg/nested-config/-/compare/v1.1.3...v2.0.0
+[1.1.3]: https://gitlab.com/osu-nrsg/nested-config/-/tags/v1.1.3

nested_config-2.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Randall Pittman, Oregon State University
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nested_config-2.1.3/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: nested-config
+Version: 2.1.3
+Summary: Parse configuration files that include paths to other config files into a single configuration object
+Project-URL: Repository, https://gitlab.com/osu-nrsg/nested-config
+Project-URL: Issues, https://gitlab.com/osu-nrsg/nested-config/-/issues
+Project-URL: Changelog, https://gitlab.com/osu-nrsg/nested-config/-/blob/master/CHANGELOG.md
+Project-URL: GitHub Mirror, https://github.com/RandallPittmanOrSt/nested-config
+Author-email: Randall Pittman <pittmara@oregonstate.edu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: config,configuration files
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: packaging>=24.2
+Requires-Dist: pydantic<3.0.0,>=1.8
+Requires-Dist: single-version>=1.6.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: typing-extensions>=4.6.0
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=1.8; extra == 'pydantic'
+Provides-Extra: pyyaml
+Requires-Dist: pyyaml>=5.1.0; extra == 'pyyaml'
+Description-Content-Type: text/markdown
+
+# nested-config <!-- omit in toc -->
+
+[![PyPI package](https://img.shields.io/pypi/v/nested-config.svg)](http://python.org/pypi/nested-config)&nbsp;&nbsp;
+[GitLab repository](https://gitlab.com/osu-nrsg/nested-config)&nbsp;&nbsp;
+[GitHub mirror](https://github.com/RandallPittmanOrSt/nested-config)
+
+<span style="font-size: larger">If you've ever wanted to have the option of replacing part
+ of a configuration file with a path to another configuration file that contains those
+sub-parameters, then _nested-config_ might be for you.</span>
+
+_nested-config_ allows you to parse configuration files that contain references to other
+configuration files using a series of [models](#model). If a model includes a [nested
+model](#nested-model) as one of its attributes and _nested-config_ finds a string value
+for that parameter in the configuration file instead of an associative
+array[^assoc-array], then it assumes that this string is a path to another configuration
+file that should be parsed and whose contents should replace the string in the main
+configuration file. If the string appears to be a relative path, it is assumed to be
+relative to the path of its parent configuration file.
+
+## Contents
+
+- [Contents](#contents)
+- [Basic Usage](#basic-usage)
+- [Nomenclature](#nomenclature)
+  - [loader](#loader)
+  - [model](#model)
+  - [nested model](#nested-model)
+  - [config dict](#config-dict)
+- [API](#api)
+  - [`nested_config.expand_config(config_path, model, *, default_suffix = None)`](#nested_configexpand_configconfig_path-model--default_suffix--none)
+  - [`nested_config.config_dict_loaders`](#nested_configconfig_dict_loaders)
+    - [Included loaders](#included-loaders)
+    - [Adding loaders](#adding-loaders)
+  - [_Deprecated features in v2.1.0, to be removed in v3.0.0_](#deprecated-features-in-v210-to-be-removed-in-v300)
+- [Pydantic 1.0/2.0 Compatibility](#pydantic-1020-compatibility)
+- [Footnotes](#footnotes)
+
+## Basic Usage
+
+Given the following configuration files `/tmp/house.toml` and `/tmp/tmp2/dimensions.toml`:
+
+<figure>
+<figcaption>Figure 1: /tmp/house.toml</figcaption>
+
+```toml
+name = "my house"
+dimensions = "tmp2/dimensions.toml"
+```
+
+</figure>
+
+<figure>
+<figcaption>Figure 2: /tmp/tmp2/dimensions.toml</figcaption>
+
+```toml
+length = 10
+width = 20
+```
+
+</figure>
+
+You can expand these into a single dict with the following:
+
+<figure>
+<figcaption>Figure 3: Expand /tmp/house.toml</figcaption>
+
+```python
+import nested_config
+
+class Dimensions:
+    length: int
+    width: int
+
+
+class House:
+    name: str
+    dimensions: Dimensions
+
+
+house_dict = nested_config.expand_config("/tmp/house.toml", House)
+print(house_dict)
+# {'name': 'my house', 'dimensions': {'length': 10, 'width': 20}}
+```
+
+Note that in `/tmp/house.toml`, `dimensions` is not a mapping but is a path to another
+toml file at a path relative to `house.toml`.
+
+See [tests](https://gitlab.com/osu-nrsg/nested-config/-/tree/master/tests) for more
+detailed use-cases, such as where the root model contains lists or dicts of other models
+and when those may be included in the root config file or specified as paths to sub-config
+files.
+
+## Nomenclature
+
+### loader
+
+A _loader_ is a function that reads a config file and returns a `dict` containing the
+key-value pairs from the file. _nested-config_ includes loaders for JSON, TOML, and (if
+PyYAML is installed) YAML. For example, the JSON loader looks like this:
+
+```python
+import json
+
+def json_load(path):
+    with open(path, "rb") as fobj:
+        return json.load(fobj)
+```
+
+### model
+
+_nested-config_ uses the term _model_ to refer to a class definition that includes
+annotated attributes. For example, this model, `Dimensions`, includes three attributes,
+each of float type, `x`, `y`, and `z`:
+
+```python
+class Dimensions:
+    x: float
+    y: float
+    z: float
+```
+
+A model can be decorated as a [dataclass][dataclasses] or using [`attrs.define`][attrs] or
+can subclass [`pydantic.BaseModel`][pydantic] to provide some method for instantiating an
+object instance of the model but they aren't necessary to use _nested-config_.
+
+The only criterion for a type to be a model is that is has a `__dict__` attribute that
+includes an `__annotations__` member. _Note: This does **not** mean that **instances** of
+the model must have a `__dict__` attribute. For example, instances of classes with
+`__slots__` and `NamedTuple` instances may not have a `__dict__` attribute._
+
+### nested model
+
+A _nested model_ is a model that is included within another model as one of its class
+attributes. For example, the below model `House` includes an `name` of string type, and an
+attribute `dimensions` of `Dimensions` type (defined above). Since `Dimensions` is a
+_model_ type, this is an example of a _nested model_.
+
+```python
+class House:
+    name: str
+    dimensions: Dimensions
+```
+
+### config dict
+
+A _config dict_ is simply a `dict` with string keys such as may be obtained by reading in
+configuration text. For example reading in a string of TOML text with `tomllib.loads`
+returns a _config dict_.
+
+```python
+import tomllib
+
+config = "x = 2\ny = 3"
+print(tomllib.loads(config))
+# {'x': 2, 'y': 3}
+```
+
+## API
+
+### `nested_config.expand_config(config_path, model, *, default_suffix = None)`
+
+This function first loads the config file at `config_path` into a [config
+dict](#config-dict) using the appropriate [loader](#loader). It then uses the attribute
+annotations of [`model`](#model) and/or any [nested models](#nested-model) within `model`
+to see if any of the string values in the configuration file correspond to a nested model.
+For each such case, the string is assumed to be a path and is loaded into another config
+dict which replaces the string value in the parent config dict. This continues until all
+paths are converted and then the fully-expanded config dict is returned.
+
+Note that all non-absolute string paths are assumed to be relative to the path of their
+parent config file.
+
+The loader for a given config file is determined by file extension (AKA suffix). If
+`default_suffix` is specified, any config file with an unknown suffix or no suffix will be
+assumed to be of that type, e.g. `".toml"`. (Otherwise this is an error.) It is possible
+for one config file to include a path to a config file of a different format, so long as
+each file has the appropriate suffix and there is a loader for that suffix.
+
+### `nested_config.config_dict_loaders`
+
+`config_dict_loaders` is a `dict` that maps file suffixes to [loaders](#loader).
+
+#### Included loaders
+
+_nested-config_ automatically loads the following files based on extension:
+
+| Format | Extensions(s) | Library                                    |
+| ------ | ------------- | ------------------------------------------ |
+| JSON   | .json         | `json` (stdlib)                            |
+| TOML   | .toml         | `tomllib` (Python 3.11+ stdlib) or `tomli` |
+| YAML   | .yaml, .yml   | `pyyaml` (extra dependency[^yaml-extra])   |
+
+#### Adding loaders
+
+To add a loader for another file extension, simply update `config_dict_loaders`:
+
+```python
+import nested_config
+from nested_config import ConfigDict  # alias for dict[str, Any]
+
+def dummy_loader(config_path: Path | str) -> ConfigDict:
+    return {"a": 1, "b": 2}
+
+nested_config.config_dict_loaders[".dmy"] = dummy_loader
+
+# or add another extension for an existing loader
+nested_config.config_dict_loaders[".jsn"] = nested_config.config_dict_loaders[".json"]
+
+# or use a different library to replace an existing loader
+import rtoml
+
+def rtoml_load(path) -> ConfigDict:
+    with open(path, "rb") as fobj:
+        return rtoml.load(fobj)
+
+nested_config.config_dict_loaders[".toml"] = rtoml_load
+```
+
+### _Deprecated features in v2.1.0, to be removed in v3.0.0_
+
+The following functionality is available only if Pydantic is installed:
+
+- `nested_config.validate_config()` expands a configuration file according to a Pydantic
+  model and then validates the config dictionary into an instance of the Pydantic model.
+- `nested_config.BaseModel` can be used as a replacement for `pydantic.BaseModel` to
+  include a `from_config()` classmethod on all models that uses
+  `nested_config.validate_config()` to create an instance of the model.
+- By importing `nested_config`, `PurePath` validators and JSON encoders are added to
+  `pydantic` in Pydantic 1.8-1.10 (they are included in Pydantic 2.0+)
+
+## Pydantic 1.0/2.0 Compatibility
+
+The [pydantic functionality](#deprecated-features-in-v210-to-be-removed-in-v300) in
+nested-config is runtime compatible with Pydantic 1.8+ and Pydantic 2.0.
+
+The follow table gives info on how to configure the [mypy](https://www.mypy-lang.org/) and
+[Pyright](https://microsoft.github.io/pyright) type checkers to properly work, depending
+on the version of Pydantic you are using.
+
+| Pydantic Version | [mypy config][1]            | mypy cli                    | [Pyright config][2]                         |
+|------------------|-----------------------------|-----------------------------|---------------------------------------------|
+| 2.0+             | `always_false = PYDANTIC_1` | `--always-false PYDANTIC_1` | `defineConstant = { "PYDANTIC_1" = false }` |
+| 1.8-1.10         | `always_true = PYDANTIC_1`  | `--always-true PYDANTIC_1`  | `defineConstant = { "PYDANTIC_1" = true }`  |
+
+## Footnotes
+
+[^yaml-extra]: Install `pyyaml` separately with `pip` or install _nested-config_ with
+               `pip install nested-config[yaml]`.
+
+[^assoc-array]: Each language uses one or more names for an associative arrays. JSON calls
+                it an _object_, YAML calls is a _mapping_, and TOML calls is a _table_.
+                Any of course in Python it's a _dictionary_, or `dict`.
+
+[1]: https://mypy.readthedocs.io/en/latest/config_file.html
+[2]: https://microsoft.github.io/pyright/#/configuration
+[dataclasses]: https://docs.python.org/3/library/dataclasses.html
+[attrs]: https://www.attrs.org
+[pydantic]: https://pydantic.dev