pydsettingsforge 1.0.0__tar.gz

pydsettingsforge-1.0.0/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.3
+Name: pydsettingsforge
+Version: 1.0.0
+Summary: Load and merge settings from pyproject.toml and .env files into validated Pydantic models
+Author: Ivan Shcherbenko
+Author-email: Ivan Shcherbenko <ivan_shcherbenko@outlook.com>
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pydantic-settings>=2.14.1
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# pydsettingsforge
+
+Load and merge application settings from `pyproject.toml` and `.env` files into validated Pydantic models.
+
+## Features
+
+- Read settings from `pyproject.toml` (`[project]` table + optional `[tool.<name>]` section)
+- Read and merge multiple `.env` files with explicit priority ordering
+- Nested configuration via `__` separator in `.env` keys (e.g., `DATABASE__HOST=localhost`)
+- Automatic coercion of `.env` list and dict values from Pydantic model hints
+- `.env` values override `pyproject.toml` values
+- Validate merged settings against a user-provided Pydantic model
+- Clear, specific error messages for missing files, sections, and validation failures
+
+## Installation
+
+```bash
+uv add pydsettingsforge
+```
+
+## Quick Start
+
+### 1. Define your settings model
+
+```python
+from pydantic import BaseModel
+
+class DatabaseConfig(BaseModel):
+    host: str
+    port: int
+
+class AppSettings(BaseModel):
+    name: str
+    version: str
+    debug: bool = False
+    log_level: str = "info"
+    database: DatabaseConfig | None = None
+```
+
+### 2. Add settings to `pyproject.toml`
+
+```toml
+[project]
+name = "myapp"
+version = "1.0.0"
+
+[tool.myapp]
+debug = false
+log_level = "info"
+
+[tool.myapp.database]
+host = "localhost"
+port = 5432
+```
+
+### 3. Create `.env` files (optional)
+
+```bash
+# .env
+DEBUG=true
+LOG_LEVEL=debug
+
+# .env.local (overrides .env)
+DATABASE__HOST=db.production.com
+DATABASE__PORT=3306
+```
+
+### 4. Load settings
+
+```python
+from pydsettingsforge import load_settings
+from myapp.config import AppSettings
+
+settings = load_settings(
+    AppSettings,
+    tool_section="myapp",
+    env_files=[".env", ".env.local"],
+)
+
+print(settings.name)            # "myapp"
+print(settings.debug)           # True (overridden by .env)
+print(settings.database.host)   # "db.production.com" (overridden by .env.local)
+```
+
+## Override Priority
+
+Settings are merged in this order (lowest to highest priority):
+
+1. `pyproject.toml` root section fields (default: `[project]`)
+2. `pyproject.toml` `[tool.<name>]` section
+3. `.env` files (in the order provided in the `env_files` list)
+4. OS environment variables (if your model inherits from `pydantic_settings.BaseSettings`)
+
+## Lists and Dicts in .env
+
+`.env` values are always strings, but your Pydantic model knows the target type. pydsettingsforge uses those hints to parse list-like and dict fields automatically:
+
+```python
+class AppSettings(BaseModel):
+    allowed_hosts: list[str]
+    ports: list[int]
+    features: dict[str, int]
+```
+
+```bash
+# .env
+ALLOWED_HOSTS=api.example.com,web.example.com
+PORTS=80,443,5432
+FEATURES={"timeout": 30, "retries": 3}
+```
+
+```python
+settings = load_settings(AppSettings, env_files=[".env"])
+settings.allowed_hosts  # ["api.example.com", "web.example.com"]
+settings.ports          # [80, 443, 5432]  (Pydantic coerces each element)
+settings.features       # {"timeout": 30, "retries": 3}
+```
+
+**Rules:**
+
+- **List-like fields** (`list`, `set`, `tuple`, `frozenset`): split on `,` by default, whitespace stripped, empty parts dropped. If the value starts with `[`, it is parsed as JSON instead; on invalid JSON the value is split as a fallback.
+- **Dict fields**: parsed as JSON.
+- **Per-element types** (e.g. `list[int]`, `list[bool]`): the list is split into strings, then Pydantic coerces each element during model validation.
+- **Optional list/dict fields** (`list[str] | None`) are detected. Multi-member unions like `list[str] | int | None` also detect the list member.
+- **Nested model lists** (`list[BaseModel]`, `set[BaseModel]`, `tuple[BaseModel, ...]`): the value must be a JSON list; each element is recursively coerced, so child `list` / `dict` fields inside the model are parsed the same way as top-level fields.
+- **Custom separator**: pass `list_separator=";"` to `load_settings` to split on a different character.
+- **Opt out**: pass `coerce_env=False` to keep raw string passthrough (the prior behavior).
+
+If a value cannot be parsed (e.g. malformed JSON for a dict field or a `list[BaseModel]` field), a `SettingsValidationError` is raised with the offending field name.
+
+```python
+class Server(BaseModel):
+    host: str
+    tags: list[str]
+
+class AppSettings(BaseModel):
+    servers: list[Server]
+```
+
+```bash
+SERVERS=[{"host": "a.example.com", "tags": "primary,public"}, {"host": "b.example.com", "tags": "backup"}]
+```
+
+```python
+settings.servers[0].host  # "a.example.com"
+settings.servers[0].tags  # ["primary", "public"]  (child list coerced too)
+```
+
+## Custom Root Section
+
+By default, pydsettingsforge reads from the `[project]` section (filtering to known metadata keys). You can specify a custom root section to read all keys from any TOML table:
+
+```toml
+[settings]
+host = "localhost"
+port = 8080
+debug = true
+```
+
+```python
+settings = load_settings(
+    ServerSettings,
+    root_section="settings",
+)
+```
+
+## Extra Fields
+
+By default, Pydantic ignores any fields in your configuration that aren't defined in your model:
+
+```python
+class AppSettings(BaseModel):
+    debug: bool
+
+# If pyproject.toml has extra fields like "name" or "version",
+# they are silently ignored
+```
+
+You can control this behavior using Pydantic's `model_config`:
+
+### Forbid Extra Fields (Strict Mode)
+
+Raise an error if unexpected fields are present:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+class StrictSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    debug: bool
+    log_level: str
+
+# Raises SettingsValidationError if pyproject.toml contains
+# fields not defined in the model
+```
+
+### Allow Extra Fields
+
+Accept and store extra fields dynamically:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+class FlexibleSettings(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    debug: bool
+
+# Extra fields are accessible via settings.model_extra
+```
+
+**Note**: This behavior is controlled by your Pydantic model configuration, not by pydsettingsforge.
+
+## API Reference
+
+### `load_settings()`
+
+```python
+def load_settings[T: BaseModel](
+    model_class: type[T],
+    *,
+    pyproject_path: Path | str | None = None,
+    env_files: list[Path | str] | None = None,
+    tool_section: str | None = None,
+    root_section: str = "project",
+    env_nesting_separator: str = "__",
+    coerce_env: bool = True,
+    list_separator: str = ",",
+) -> T
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_class` | `type[BaseModel]` | required | Pydantic model to validate against |
+| `pyproject_path` | `Path \| str \| None` | `./pyproject.toml` | Path to `pyproject.toml` |
+| `env_files` | `list[Path \| str] \| None` | `None` | Ordered list of `.env` files (later wins) |
+| `tool_section` | `str \| None` | `None` | `[tool.<name>]` section to read |
+| `root_section` | `str` | `"project"` | Root TOML section to read (custom sections include all keys) |
+| `env_nesting_separator` | `str` | `"__"` | Separator for nested `.env` keys |
+| `coerce_env` | `bool` | `True` | Parse list/dict string values via the model hints before validation |
+| `list_separator` | `str` | `","` | Separator for list-like fields when `coerce_env` is enabled |
+
+### `coerce_env_values()`
+
+```python
+def coerce_env_values(
+    model_class: type[BaseModel],
+    data: dict[str, Any],
+    *,
+    list_separator: str = ",",
+    coerce_env: bool = True,
+) -> dict[str, Any]
+```
+
+The same list/dict coercion that `load_settings` runs after merging, exposed as a standalone helper. Use it when you build the settings dict yourself (e.g. from a custom config source) and want the same string-to-typed-value behavior before handing the dict to Pydantic.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_class` | `type[BaseModel]` | required | Pydantic model used to interpret each leaf |
+| `data` | `dict[str, Any]` | required | The dict to coerce (not mutated) |
+| `list_separator` | `str` | `","` | Separator for list-like fields |
+| `coerce_env` | `bool` | `True` | Set to `False` to return a shallow copy with no coercion |
+
+### Exceptions
+
+| Exception | When |
+|-----------|------|
+| `PyprojectNotFoundError` | `pyproject.toml` not found |
+| `EnvFileNotFoundError` | A specified `.env` file doesn't exist |
+| `RootSectionNotFoundError` | Root section is missing |
+| `ToolSectionNotFoundError` | `[tool.<name>]` section is missing |
+| `SettingsValidationError` | Merged data fails Pydantic validation |
+
+## Development
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd pydsettingsforge
+uv sync --all-groups
+```
+
+### Commands
+
+```bash
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=pydsettingsforge
+
+# Lint
+uv run ruff check src/ tests/
+
+# Format
+uv run ruff format src/ tests/
+
+# Type check
+uv run ty check src/
+
+# All checks
+uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run ty check src/ && uv run pytest
+```
+
+## Project Structure
+
+```
+pydsettingsforge/
+├── pyproject.toml
+├── uv.lock
+├── README.md
+├── .gitignore
+├── src/
+│   └── pydsettingsforge/
+│       ├── __init__.py          # Public API: load_settings(), coerce_env_values()
+│       ├── constants.py         # Default constants
+│       ├── coercer.py           # List/dict coercion from Pydantic hints
+│       ├── env_reader.py        # .env file parsing and nesting
+│       ├── exceptions.py        # Custom exceptions
+│       ├── merger.py            # Deep-merge dictionaries
+│       ├── toml_reader.py       # pyproject.toml parsing
+│       └── validator.py         # Pydantic validation
+└── tests/
+    ├── conftest.py              # Shared fixtures
+    ├── test_coercer.py
+    ├── test_env_reader.py
+    ├── test_load_settings.py    # Integration tests
+    ├── test_merger.py
+    ├── test_toml_reader.py
+    └── test_validator.py
+```
+
+## License
+
+MIT

pydsettingsforge-1.0.0/README.md

@@ -0,0 +1,340 @@
+# pydsettingsforge
+
+Load and merge application settings from `pyproject.toml` and `.env` files into validated Pydantic models.
+
+## Features
+
+- Read settings from `pyproject.toml` (`[project]` table + optional `[tool.<name>]` section)
+- Read and merge multiple `.env` files with explicit priority ordering
+- Nested configuration via `__` separator in `.env` keys (e.g., `DATABASE__HOST=localhost`)
+- Automatic coercion of `.env` list and dict values from Pydantic model hints
+- `.env` values override `pyproject.toml` values
+- Validate merged settings against a user-provided Pydantic model
+- Clear, specific error messages for missing files, sections, and validation failures
+
+## Installation
+
+```bash
+uv add pydsettingsforge
+```
+
+## Quick Start
+
+### 1. Define your settings model
+
+```python
+from pydantic import BaseModel
+
+class DatabaseConfig(BaseModel):
+    host: str
+    port: int
+
+class AppSettings(BaseModel):
+    name: str
+    version: str
+    debug: bool = False
+    log_level: str = "info"
+    database: DatabaseConfig | None = None
+```
+
+### 2. Add settings to `pyproject.toml`
+
+```toml
+[project]
+name = "myapp"
+version = "1.0.0"
+
+[tool.myapp]
+debug = false
+log_level = "info"
+
+[tool.myapp.database]
+host = "localhost"
+port = 5432
+```
+
+### 3. Create `.env` files (optional)
+
+```bash
+# .env
+DEBUG=true
+LOG_LEVEL=debug
+
+# .env.local (overrides .env)
+DATABASE__HOST=db.production.com
+DATABASE__PORT=3306
+```
+
+### 4. Load settings
+
+```python
+from pydsettingsforge import load_settings
+from myapp.config import AppSettings
+
+settings = load_settings(
+    AppSettings,
+    tool_section="myapp",
+    env_files=[".env", ".env.local"],
+)
+
+print(settings.name)            # "myapp"
+print(settings.debug)           # True (overridden by .env)
+print(settings.database.host)   # "db.production.com" (overridden by .env.local)
+```
+
+## Override Priority
+
+Settings are merged in this order (lowest to highest priority):
+
+1. `pyproject.toml` root section fields (default: `[project]`)
+2. `pyproject.toml` `[tool.<name>]` section
+3. `.env` files (in the order provided in the `env_files` list)
+4. OS environment variables (if your model inherits from `pydantic_settings.BaseSettings`)
+
+## Lists and Dicts in .env
+
+`.env` values are always strings, but your Pydantic model knows the target type. pydsettingsforge uses those hints to parse list-like and dict fields automatically:
+
+```python
+class AppSettings(BaseModel):
+    allowed_hosts: list[str]
+    ports: list[int]
+    features: dict[str, int]
+```
+
+```bash
+# .env
+ALLOWED_HOSTS=api.example.com,web.example.com
+PORTS=80,443,5432
+FEATURES={"timeout": 30, "retries": 3}
+```
+
+```python
+settings = load_settings(AppSettings, env_files=[".env"])
+settings.allowed_hosts  # ["api.example.com", "web.example.com"]
+settings.ports          # [80, 443, 5432]  (Pydantic coerces each element)
+settings.features       # {"timeout": 30, "retries": 3}
+```
+
+**Rules:**
+
+- **List-like fields** (`list`, `set`, `tuple`, `frozenset`): split on `,` by default, whitespace stripped, empty parts dropped. If the value starts with `[`, it is parsed as JSON instead; on invalid JSON the value is split as a fallback.
+- **Dict fields**: parsed as JSON.
+- **Per-element types** (e.g. `list[int]`, `list[bool]`): the list is split into strings, then Pydantic coerces each element during model validation.
+- **Optional list/dict fields** (`list[str] | None`) are detected. Multi-member unions like `list[str] | int | None` also detect the list member.
+- **Nested model lists** (`list[BaseModel]`, `set[BaseModel]`, `tuple[BaseModel, ...]`): the value must be a JSON list; each element is recursively coerced, so child `list` / `dict` fields inside the model are parsed the same way as top-level fields.
+- **Custom separator**: pass `list_separator=";"` to `load_settings` to split on a different character.
+- **Opt out**: pass `coerce_env=False` to keep raw string passthrough (the prior behavior).
+
+If a value cannot be parsed (e.g. malformed JSON for a dict field or a `list[BaseModel]` field), a `SettingsValidationError` is raised with the offending field name.
+
+```python
+class Server(BaseModel):
+    host: str
+    tags: list[str]
+
+class AppSettings(BaseModel):
+    servers: list[Server]
+```
+
+```bash
+SERVERS=[{"host": "a.example.com", "tags": "primary,public"}, {"host": "b.example.com", "tags": "backup"}]
+```
+
+```python
+settings.servers[0].host  # "a.example.com"
+settings.servers[0].tags  # ["primary", "public"]  (child list coerced too)
+```
+
+## Custom Root Section
+
+By default, pydsettingsforge reads from the `[project]` section (filtering to known metadata keys). You can specify a custom root section to read all keys from any TOML table:
+
+```toml
+[settings]
+host = "localhost"
+port = 8080
+debug = true
+```
+
+```python
+settings = load_settings(
+    ServerSettings,
+    root_section="settings",
+)
+```
+
+## Extra Fields
+
+By default, Pydantic ignores any fields in your configuration that aren't defined in your model:
+
+```python
+class AppSettings(BaseModel):
+    debug: bool
+
+# If pyproject.toml has extra fields like "name" or "version",
+# they are silently ignored
+```
+
+You can control this behavior using Pydantic's `model_config`:
+
+### Forbid Extra Fields (Strict Mode)
+
+Raise an error if unexpected fields are present:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+class StrictSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    debug: bool
+    log_level: str
+
+# Raises SettingsValidationError if pyproject.toml contains
+# fields not defined in the model
+```
+
+### Allow Extra Fields
+
+Accept and store extra fields dynamically:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+class FlexibleSettings(BaseModel):
+    model_config = ConfigDict(extra="allow")
+    debug: bool
+
+# Extra fields are accessible via settings.model_extra
+```
+
+**Note**: This behavior is controlled by your Pydantic model configuration, not by pydsettingsforge.
+
+## API Reference
+
+### `load_settings()`
+
+```python
+def load_settings[T: BaseModel](
+    model_class: type[T],
+    *,
+    pyproject_path: Path | str | None = None,
+    env_files: list[Path | str] | None = None,
+    tool_section: str | None = None,
+    root_section: str = "project",
+    env_nesting_separator: str = "__",
+    coerce_env: bool = True,
+    list_separator: str = ",",
+) -> T
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_class` | `type[BaseModel]` | required | Pydantic model to validate against |
+| `pyproject_path` | `Path \| str \| None` | `./pyproject.toml` | Path to `pyproject.toml` |
+| `env_files` | `list[Path \| str] \| None` | `None` | Ordered list of `.env` files (later wins) |
+| `tool_section` | `str \| None` | `None` | `[tool.<name>]` section to read |
+| `root_section` | `str` | `"project"` | Root TOML section to read (custom sections include all keys) |
+| `env_nesting_separator` | `str` | `"__"` | Separator for nested `.env` keys |
+| `coerce_env` | `bool` | `True` | Parse list/dict string values via the model hints before validation |
+| `list_separator` | `str` | `","` | Separator for list-like fields when `coerce_env` is enabled |
+
+### `coerce_env_values()`
+
+```python
+def coerce_env_values(
+    model_class: type[BaseModel],
+    data: dict[str, Any],
+    *,
+    list_separator: str = ",",
+    coerce_env: bool = True,
+) -> dict[str, Any]
+```
+
+The same list/dict coercion that `load_settings` runs after merging, exposed as a standalone helper. Use it when you build the settings dict yourself (e.g. from a custom config source) and want the same string-to-typed-value behavior before handing the dict to Pydantic.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_class` | `type[BaseModel]` | required | Pydantic model used to interpret each leaf |
+| `data` | `dict[str, Any]` | required | The dict to coerce (not mutated) |
+| `list_separator` | `str` | `","` | Separator for list-like fields |
+| `coerce_env` | `bool` | `True` | Set to `False` to return a shallow copy with no coercion |
+
+### Exceptions
+
+| Exception | When |
+|-----------|------|
+| `PyprojectNotFoundError` | `pyproject.toml` not found |
+| `EnvFileNotFoundError` | A specified `.env` file doesn't exist |
+| `RootSectionNotFoundError` | Root section is missing |
+| `ToolSectionNotFoundError` | `[tool.<name>]` section is missing |
+| `SettingsValidationError` | Merged data fails Pydantic validation |
+
+## Development
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/)
+
+### Setup
+
+```bash
+git clone <repo-url>
+cd pydsettingsforge
+uv sync --all-groups
+```
+
+### Commands
+
+```bash
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=pydsettingsforge
+
+# Lint
+uv run ruff check src/ tests/
+
+# Format
+uv run ruff format src/ tests/
+
+# Type check
+uv run ty check src/
+
+# All checks
+uv run ruff check src/ tests/ && uv run ruff format --check src/ tests/ && uv run ty check src/ && uv run pytest
+```
+
+## Project Structure
+
+```
+pydsettingsforge/
+├── pyproject.toml
+├── uv.lock
+├── README.md
+├── .gitignore
+├── src/
+│   └── pydsettingsforge/
+│       ├── __init__.py          # Public API: load_settings(), coerce_env_values()
+│       ├── constants.py         # Default constants
+│       ├── coercer.py           # List/dict coercion from Pydantic hints
+│       ├── env_reader.py        # .env file parsing and nesting
+│       ├── exceptions.py        # Custom exceptions
+│       ├── merger.py            # Deep-merge dictionaries
+│       ├── toml_reader.py       # pyproject.toml parsing
+│       └── validator.py         # Pydantic validation
+└── tests/
+    ├── conftest.py              # Shared fixtures
+    ├── test_coercer.py
+    ├── test_env_reader.py
+    ├── test_load_settings.py    # Integration tests
+    ├── test_merger.py
+    ├── test_toml_reader.py
+    └── test_validator.py
+```
+
+## License
+
+MIT

pydsettingsforge-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "pydsettingsforge"
+version = "1.0.0"
+description = "Load and merge settings from pyproject.toml and .env files into validated Pydantic models"
+readme = "README.md"
+authors = [
+    { name = "Ivan Shcherbenko", email = "ivan_shcherbenko@outlook.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "pydantic>=2.13.4",
+    "pydantic-settings>=2.14.1",
+    "python-dotenv>=1.2.2",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.15",
+    "ty>=0.0.42",
+]
+
+[tool.ruff]
+target-version = "py313"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "TCH"]
+
+[tool.ty]
+
+[tool.ty.environment]
+python-version = "3.13"
+python = ".venv/bin/python3"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/pydsettingsforge/__init__.py:__version__"]
+changelog_file = "CHANGELOG.md"
+upload_to_pypi = false
+upload_to_release = true
+commit_message = "chore(release): {version}"
+branch = "main"
+commit_parser = "conventional"
+major_on_zero = true
+tag_format = "v{version}"

pydsettingsforge-1.0.0/src/pydsettingsforge/__init__.py

@@ -0,0 +1,109 @@
+"""pydsettingsforge — Load and merge settings from pyproject.toml and .env files."""
+
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+__version__ = "1.0.0"
+
+from pydsettingsforge.coercer import coerce_env_values
+from pydsettingsforge.constants import DEFAULT_ROOT_SECTION, ENV_NESTING_SEPARATOR
+from pydsettingsforge.env_reader import expand_nested_keys, read_env_files
+from pydsettingsforge.exceptions import (
+    EnvFileNotFoundError,
+    PyprojectNotFoundError,
+    RootSectionNotFoundError,
+    SettingsForgeError,
+    SettingsValidationError,
+    ToolSectionNotFoundError,
+)
+from pydsettingsforge.merger import deep_merge
+from pydsettingsforge.toml_reader import (
+    extract_settings,
+    read_pyproject,
+    resolve_pyproject_path,
+)
+from pydsettingsforge.validator import validate_settings
+
+__all__ = [
+    "EnvFileNotFoundError",
+    "PyprojectNotFoundError",
+    "RootSectionNotFoundError",
+    "SettingsForgeError",
+    "SettingsValidationError",
+    "ToolSectionNotFoundError",
+    "coerce_env_values",
+    "load_settings",
+]
+
+
+def load_settings[T: BaseModel](
+    model_class: type[T],
+    *,
+    pyproject_path: Path | str | None = None,
+    env_files: list[Path | str] | None = None,
+    tool_section: str | None = None,
+    root_section: str = DEFAULT_ROOT_SECTION,
+    env_nesting_separator: str = ENV_NESTING_SEPARATOR,
+    coerce_env: bool = True,
+    list_separator: str = ",",
+) -> T:
+    """Load, merge, and validate application settings.
+
+    Reads settings from pyproject.toml (root section + optional [tool.<name>] section),
+    merges with .env files (later files override earlier ones), and validates
+    the result against a user-provided Pydantic model.
+
+    Override priority (lowest to highest):
+        1. pyproject.toml root section fields
+        2. pyproject.toml [tool.<name>] section
+        3. .env files (in list order)
+        4. OS environment variables (handled by pydantic-settings if the model
+           inherits from BaseSettings)
+
+    Args:
+        model_class: A Pydantic BaseModel subclass defining the expected settings.
+        pyproject_path: Path to pyproject.toml. Defaults to ./pyproject.toml.
+        env_files: Ordered list of .env file paths. Later files override earlier.
+        tool_section: Name of the [tool.<name>] section to read from pyproject.toml.
+        root_section: Root TOML section to read (default: "project").
+            When "project", only known metadata keys are included.
+            Custom sections include all keys unfiltered.
+        env_nesting_separator: Separator for nested keys in .env files (default: "__").
+        coerce_env: When True (default), string values for list, set, tuple, and
+            dict fields are parsed before Pydantic validation: list-like fields
+            are split on ``list_separator`` (or parsed as JSON if the value starts
+            with ``[`` or ``{``), and dict fields are parsed as JSON. Set to False
+            to keep raw string passthrough.
+        list_separator: Separator used to split string values for list-like
+            fields when ``coerce_env`` is True (default: ``,``).
+
+    Returns:
+        A validated instance of model_class.
+
+    Raises:
+        PyprojectNotFoundError: If pyproject.toml is not found.
+        EnvFileNotFoundError: If a specified .env file does not exist.
+        RootSectionNotFoundError: If the root section is missing.
+        ToolSectionNotFoundError: If the [tool.<name>] section is missing.
+        SettingsValidationError: If the merged data fails Pydantic validation.
+    """
+    resolved_pyproject = resolve_pyproject_path(
+        Path(pyproject_path) if pyproject_path else None
+    )
+    pyproject_data = read_pyproject(resolved_pyproject)
+    toml_settings = extract_settings(pyproject_data, tool_section, root_section)
+
+    env_settings: dict[str, Any] = {}
+    if env_files:
+        resolved_env_paths = [Path(p) for p in env_files]
+        flat_env = read_env_files(resolved_env_paths)
+        env_settings = expand_nested_keys(flat_env, env_nesting_separator)
+
+    merged = deep_merge(toml_settings, env_settings)
+
+    if coerce_env:
+        merged = coerce_env_values(model_class, merged, list_separator=list_separator)
+
+    return validate_settings(model_class, merged)

pydsettingsforge-1.0.0/src/pydsettingsforge/coercer.py

@@ -0,0 +1,171 @@
+"""Coerce env-string values into typed Python objects using a Pydantic model."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+
+from pydsettingsforge.exceptions import SettingsValidationError
+
+_CONTAINER_ORIGINS = (list, set, frozenset, tuple)
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    args = get_args(annotation)
+    if not args or type(None) not in args:
+        return annotation
+    for a in args:
+        if a is not type(None) and get_origin(a) in _CONTAINER_ORIGINS + (dict,):
+            return a
+    non_none = [a for a in args if a is not type(None)]
+    if len(non_none) == 1:
+        return non_none[0]
+    return annotation
+
+
+def _split_list(value: str, separator: str) -> list[str]:
+    return [item.strip() for item in value.split(separator) if item.strip()]
+
+
+def _is_list_like(annotation: Any) -> bool:
+    return get_origin(_unwrap_optional(annotation)) in _CONTAINER_ORIGINS
+
+
+def _is_dict(annotation: Any) -> bool:
+    return get_origin(_unwrap_optional(annotation)) is dict
+
+
+def _coerce_list_value(
+    value: str,
+    list_separator: str,
+    field_name: str,
+) -> Any:
+    stripped = value.strip()
+    if stripped.startswith("["):
+        try:
+            parsed = json.loads(stripped)
+        except json.JSONDecodeError:
+            return _split_list(stripped, list_separator)
+        if isinstance(parsed, list):
+            return parsed
+    return _split_list(stripped, list_separator)
+
+
+def _coerce_dict_value(
+    value: str,
+    field_name: str,
+) -> Any:
+    try:
+        return json.loads(value.strip())
+    except json.JSONDecodeError as exc:
+        raise SettingsValidationError(
+            f"Failed to coerce env value for field '{field_name}' "
+            f"to dict: invalid JSON: {exc}"
+        ) from exc
+
+
+def _coerce_list_of_models(
+    value: str,
+    inner_model: type[BaseModel],
+    list_separator: str,
+    field_name: str,
+) -> list[dict[str, Any]]:
+    try:
+        parsed = json.loads(value.strip())
+    except json.JSONDecodeError as exc:
+        raise SettingsValidationError(
+            f"Failed to coerce env value for field '{field_name}' "
+            f"to list[{inner_model.__name__}]: invalid JSON: {exc}"
+        ) from exc
+    if not isinstance(parsed, list):
+        raise SettingsValidationError(
+            f"Failed to coerce env value for field '{field_name}': expected JSON list"
+        )
+    return [
+        coerce_env_values(inner_model, item, list_separator=list_separator)
+        for item in parsed
+    ]
+
+
+def _coerce_field(
+    value: Any,
+    annotation: Any,
+    list_separator: str,
+    field_name: str,
+) -> Any:
+    inner = _unwrap_optional(annotation)
+    origin = get_origin(inner)
+    args = get_args(inner)
+
+    if (
+        isinstance(inner, type)
+        and issubclass(inner, BaseModel)
+        and isinstance(value, dict)
+    ):
+        return coerce_env_values(inner, value, list_separator=list_separator)
+
+    if (
+        origin in _CONTAINER_ORIGINS
+        and args
+        and isinstance(args[0], type)
+        and issubclass(args[0], BaseModel)
+    ):
+        if isinstance(value, str):
+            return _coerce_list_of_models(value, args[0], list_separator, field_name)
+        return value
+
+    if _is_list_like(annotation):
+        if isinstance(value, str):
+            return _coerce_list_value(value, list_separator, field_name)
+        return value
+
+    if _is_dict(annotation):
+        if isinstance(value, str):
+            return _coerce_dict_value(value, field_name)
+        return value
+
+    return value
+
+
+def coerce_env_values(
+    model_class: type[BaseModel],
+    data: dict[str, Any],
+    *,
+    list_separator: str = ",",
+    coerce_env: bool = True,
+) -> dict[str, Any]:
+    """Pre-process a merged settings dict so list/dict leaf strings become typed values.
+
+    Uses ``model_class.model_fields`` to decide how to interpret each string leaf.
+    String values whose target field is a list/set/tuple are split on
+    ``list_separator`` (whitespace stripped, empties dropped), or parsed as JSON if
+    the value starts with ``[`` (falls back to split on invalid JSON). String
+    values whose target field is a ``dict`` are parsed as JSON. String values for
+    ``list[BaseModel]`` (or ``set[BaseModel]`` / ``tuple[BaseModel, ...]``) fields
+    are parsed as JSON and each element is recursively coerced. Primitive types
+    (``int``/``bool``/``float``/``str``) are left untouched — Pydantic handles
+    their coercion in ``model_validate``. Optional list/dict fields
+    (``list[str] | None``) are detected, including multi-member unions like
+    ``list[str] | int | None``. When ``coerce_env`` is False, ``data`` is returned
+    as a shallow copy with no coercion applied.
+
+    Extra fields not declared on the model are passed through unchanged.
+    """
+    if not coerce_env:
+        return dict(data)
+
+    result: dict[str, Any] = {}
+    known_fields = model_class.model_fields
+
+    for name, field in known_fields.items():
+        if name not in data:
+            continue
+        result[name] = _coerce_field(data[name], field.annotation, list_separator, name)
+
+    for name, value in data.items():
+        if name not in known_fields:
+            result[name] = value
+
+    return result

pydsettingsforge-1.0.0/src/pydsettingsforge/constants.py

@@ -0,0 +1,9 @@
+"""Default constants for pydsettingsforge."""
+
+DEFAULT_PYPROJECT_FILENAME: str = "pyproject.toml"
+
+ENV_NESTING_SEPARATOR: str = "__"
+
+TOOL_SECTION_PREFIX: str = "tool"
+
+DEFAULT_ROOT_SECTION: str = "project"

pydsettingsforge-1.0.0/src/pydsettingsforge/env_reader.py

@@ -0,0 +1,58 @@
+"""Read and parse .env files."""
+
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+
+from pydsettingsforge.constants import ENV_NESTING_SEPARATOR
+from pydsettingsforge.exceptions import EnvFileNotFoundError
+
+
+def read_env_file(path: Path) -> dict[str, str]:
+    """Parse a single .env file and return key-value pairs.
+
+    Raises EnvFileNotFoundError if the file does not exist.
+    """
+    if not path.is_file():
+        raise EnvFileNotFoundError(str(path))
+
+    values = dotenv_values(path)
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def read_env_files(paths: list[Path]) -> dict[str, str]:
+    """Read multiple .env files and merge them.
+
+    Files are processed in order; later files override earlier ones.
+    """
+    merged: dict[str, str] = {}
+    for path in paths:
+        merged.update(read_env_file(path))
+    return merged
+
+
+def expand_nested_keys(
+    flat: dict[str, str],
+    separator: str = ENV_NESTING_SEPARATOR,
+) -> dict[str, Any]:
+    """Convert flat keys with a nesting separator into a nested dictionary.
+
+    Example: {"DB__HOST": "localhost"} -> {"db": {"host": "localhost"}}
+
+    Keys are lowercased to match typical Pydantic field naming conventions.
+    """
+    result: dict[str, Any] = {}
+
+    for key, value in flat.items():
+        parts = key.lower().split(separator)
+        current = result
+
+        for part in parts[:-1]:
+            if part not in current or not isinstance(current[part], dict):
+                current[part] = {}
+            current = current[part]
+
+        current[parts[-1]] = value
+
+    return result

pydsettingsforge-1.0.0/src/pydsettingsforge/exceptions.py

@@ -0,0 +1,40 @@
+"""Custom exceptions for pydsettingsforge."""
+
+
+class SettingsForgeError(Exception):
+    """Base exception for all pydsettingsforge errors."""
+
+
+class PyprojectNotFoundError(SettingsForgeError):
+    """Raised when pyproject.toml cannot be found at the specified path."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f"pyproject.toml not found at: {path}")
+
+
+class EnvFileNotFoundError(SettingsForgeError):
+    """Raised when a specified .env file does not exist."""
+
+    def __init__(self, path: str) -> None:
+        super().__init__(f".env file not found: {path}")
+
+
+class ToolSectionNotFoundError(SettingsForgeError):
+    """Raised when [tool.<name>] section is missing from pyproject.toml."""
+
+    def __init__(self, section: str) -> None:
+        super().__init__(f"[tool.{section}] section not found in pyproject.toml")
+
+
+class RootSectionNotFoundError(SettingsForgeError):
+    """Raised when the specified root section is missing from pyproject.toml."""
+
+    def __init__(self, section: str) -> None:
+        super().__init__(f"[{section}] section not found in pyproject.toml")
+
+
+class SettingsValidationError(SettingsForgeError):
+    """Raised when the merged settings dictionary fails Pydantic validation."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Settings validation failed: {message}")

pydsettingsforge-1.0.0/src/pydsettingsforge/merger.py

@@ -0,0 +1,23 @@
+"""Deep-merge dictionaries with override semantics."""
+
+from typing import Any
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge two dictionaries. Values from `override` win on conflict.
+
+    Nested dicts are merged recursively; all other types (including lists)
+    are replaced entirely by the override value.
+    Returns a new dictionary without mutating inputs.
+    """
+    result: dict[str, Any] = {**base}
+
+    for key, override_value in override.items():
+        base_value = result.get(key)
+
+        if isinstance(base_value, dict) and isinstance(override_value, dict):
+            result[key] = deep_merge(base_value, override_value)
+        else:
+            result[key] = override_value
+
+    return result

pydsettingsforge-1.0.0/src/pydsettingsforge/toml_reader.py

@@ -0,0 +1,78 @@
+"""Read and extract settings from pyproject.toml."""
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydsettingsforge.constants import (
+    DEFAULT_PYPROJECT_FILENAME,
+    DEFAULT_ROOT_SECTION,
+    TOOL_SECTION_PREFIX,
+)
+from pydsettingsforge.exceptions import (
+    PyprojectNotFoundError,
+    RootSectionNotFoundError,
+    ToolSectionNotFoundError,
+)
+
+TOP_LEVEL_KEYS: frozenset[str] = frozenset(
+    {
+        "name",
+        "version",
+        "description",
+        "requires-python",
+        "readme",
+        "authors",
+    }
+)
+
+
+def resolve_pyproject_path(path: Path | None = None) -> Path:
+    """Resolve the path to pyproject.toml.
+
+    If no path is given, looks in the current working directory.
+    """
+    if path is None:
+        return Path.cwd() / DEFAULT_PYPROJECT_FILENAME
+    return path.resolve()
+
+
+def read_pyproject(path: Path) -> dict[str, Any]:
+    """Parse pyproject.toml and return its contents as a dictionary."""
+    if not path.is_file():
+        raise PyprojectNotFoundError(str(path))
+
+    with path.open("rb") as f:
+        return tomllib.load(f)
+
+
+def extract_settings(
+    pyproject_data: dict[str, Any],
+    tool_section: str | None = None,
+    root_section: str = DEFAULT_ROOT_SECTION,
+) -> dict[str, Any]:
+    """Extract settings from parsed pyproject.toml data.
+
+    Returns fields from the root section merged with an optional [tool.<name>] section.
+    When root_section is "project" (default), only known metadata keys are included.
+    For custom root sections, all keys are included without filtering.
+    """
+    if root_section not in pyproject_data:
+        raise RootSectionNotFoundError(root_section)
+
+    root_table: dict[str, Any] = pyproject_data[root_section]
+
+    if root_section == DEFAULT_ROOT_SECTION:
+        top_level = {k: v for k, v in root_table.items() if k in TOP_LEVEL_KEYS}
+    else:
+        top_level = dict(root_table)
+
+    if tool_section is None:
+        return top_level
+
+    tool_table = pyproject_data.get(TOOL_SECTION_PREFIX, {})
+    if tool_section not in tool_table:
+        raise ToolSectionNotFoundError(tool_section)
+
+    section_data = tool_table[tool_section]
+    return {**top_level, **section_data}

pydsettingsforge-1.0.0/src/pydsettingsforge/validator.py

@@ -0,0 +1,22 @@
+"""Validate merged settings against a user-provided Pydantic model."""
+
+from typing import Any
+
+from pydantic import BaseModel, ValidationError
+
+from pydsettingsforge.exceptions import SettingsValidationError
+
+
+def validate_settings[T: BaseModel](
+    model_class: type[T],
+    data: dict[str, Any],
+) -> T:
+    """Validate a settings dictionary against a Pydantic model.
+
+    Returns an instance of the model if validation passes.
+    Raises SettingsValidationError with details on failure.
+    """
+    try:
+        return model_class.model_validate(data)
+    except ValidationError as exc:
+        raise SettingsValidationError(str(exc)) from exc