confkit 2.1.0__tar.gz → 2.2.0__tar.gz

confkit-2.2.0/.github/workflows/bump-version-by-labels.yml

@@ -0,0 +1,34 @@
+name: Bump Version By Labels
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+      - master
+
+jobs:
+  bump-version:
+    if: github.event.pull_request.merged == true && github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Bump by labels
+        uses: HEROgold/bump-by-label@v4.0.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          command: "uv version --bump"
+          validate: "uv version"
+          base_branch: ${{ github.event.pull_request.base.ref }}

confkit-2.2.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - uses: actions/configure-pages@v6
+      - run: uv sync --group docs
+      - run: uv run pdoc confkit -o docs/api
+      - run: uv run zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

{confkit-2.1.0 → confkit-2.2.0}/.github/workflows/test.yml

@@ -49,3 +49,19 @@ jobs:
         if: steps.cache-pytest.outputs.cache-hit != 'true'
         # Avoid executing examples in CI; they could run untrusted code from PRs
         run: uv run pytest . --ignore=tests/test_examples_run.py
+
+  # The test job runs with dev dependencies installed, which can hide a
+  # runtime import that isn't declared. Import the built wheel on its own.
+  clean-install:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build the wheel
+        run: uv build --wheel -o dist
+
+      - name: Import it with only its declared dependencies
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import confkit"

{confkit-2.1.0 → confkit-2.2.0}/.pre-commit-config.yaml

@@ -6,7 +6,7 @@ default_install_hook_types:
 
 repos:
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.26
+    rev: 0.13.5
     hooks:
       - id: uv-lock
         stages:
@@ -51,19 +51,19 @@ repos:
 
   # Security scanning
   - repo: https://github.com/gitleaks/gitleaks
-    rev: v8.24.2
+    rev: v8.30.0
     hooks:
       - id: gitleaks
 
   # Validate packaging metadata early
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.24.1
+    rev: v0.27
     hooks:
       - id: validate-pyproject
         stages: [pre-push, pre-commit]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.17.2
     hooks:
       - id: ruff
         name: ruff lint
@@ -97,7 +97,7 @@ repos:
 
   # Spell checking (global)
   - repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.11.0.1
+    rev: v0.11.0.1-1
     hooks:
       - id: shellcheck
         stages: [pre-push, pre-commit]

confkit-2.2.0/LICENSE

@@ -0,0 +1,16 @@
+License
+
+Copyright (c) 2026-Present HEROgold
+
+NON-COMMERCIAL USE PERMISSION:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, merge, and publish the Software for non-commercial purposes only, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+2. The Software may not be sublicensed, resold, or used to generate commercial revenue under this non-commercial permission.
+
+COMMERCIAL USE REQUIREMENT:
+Any use of the Software (in whole or in part) for commercial purposes, including but not limited to use within a company, corporate environment, commercial group, or by a commercial individual, is strictly prohibited without obtaining explicit written permission.
+
+Upon obtaining explicit written permission, the licensee (which may be an individual, a specified group, or an entire legal entity/company, depending on the terms of the purchased license) is granted the right to include, modify, and make use of the Software (in whole or in part) within their commercial operations according to the tier purchased.
+
+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.

{confkit-2.1.0 → confkit-2.2.0}/PKG-INFO

@@ -1,15 +1,17 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: confkit
-Version: 2.1.0
+Version: 2.2.0
 Summary: Lightweight and Easy to use configuration manager for Python projects
 Author: HEROgold
+License-File: LICENSE
 Requires-Python: >=3.11
+Requires-Dist: typing-extensions>=4.16.0
 Provides-Extra: msgspec
-Requires-Dist: msgspec>=0.20.0; extra == 'msgspec'
+Requires-Dist: msgspec>=0.22.0; extra == 'msgspec'
 Requires-Dist: pyyaml>=6.0.3; extra == 'msgspec'
 Requires-Dist: tomli-w>=1.2.0; extra == 'msgspec'
 Provides-Extra: pydantic
-Requires-Dist: pydantic>=2.12.5; extra == 'pydantic'
+Requires-Dist: pydantic>=2.14.2; extra == 'pydantic'
 Description-Content-Type: text/markdown
 
 # confkit
@@ -34,12 +36,12 @@ This ensures that confkit remains compatible with current Python versions while
 ## What is it?
 
 confkit is a Python library that provides type-safe configuration management with automatic type conversion and validation.
-It uses descriptors to define configuration values as class attributes that automatically read from and write to INI files.
+It uses descriptors to define configuration values as class attributes that automatically read from and write to configuration files.
 
 ## What does it do?
 
 - Type-safe configuration with automatic type conversion
-- Automatic INI file management
+- Automatic configuration file management
 - Default value handling with file persistence
 - Optional value support
 - Enum support (Enum, StrEnum, IntEnum, IntFlag)
@@ -92,11 +94,11 @@ uv sync --group docs
 # Generate API documentation with pdoc
 uv run pdoc confkit -o docs/api
 
-# Build documentation site with mkdocs
-uv run mkdocs build -d site
+# Build documentation site with zensical
+uv run zensical build --clean
 
 # Or serve locally for live preview (with auto-reload)
-uv run mkdocs serve
+uv run zensical serve
 ```
 
 Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `master` branch.
@@ -105,5 +107,5 @@ Documentation is automatically built and deployed to GitHub Pages when changes a
 
 1. Update relevant `.md` files in `docs/` directory (examples, reference, etc.)
 2. Run `uv run pdoc confkit -o docs/api` to regenerate API documentation
-3. Preview changes with `uv run mkdocs serve` and verify at `http://127.0.0.1:8000`
+3. Preview changes with `uv run zensical serve` and verify at `http://127.0.0.1:8000`
 4. Commit both code and documentation changes together

{confkit-2.1.0 → confkit-2.2.0}/README.md

@@ -20,12 +20,12 @@ This ensures that confkit remains compatible with current Python versions while
 ## What is it?
 
 confkit is a Python library that provides type-safe configuration management with automatic type conversion and validation.
-It uses descriptors to define configuration values as class attributes that automatically read from and write to INI files.
+It uses descriptors to define configuration values as class attributes that automatically read from and write to configuration files.
 
 ## What does it do?
 
 - Type-safe configuration with automatic type conversion
-- Automatic INI file management
+- Automatic configuration file management
 - Default value handling with file persistence
 - Optional value support
 - Enum support (Enum, StrEnum, IntEnum, IntFlag)
@@ -78,11 +78,11 @@ uv sync --group docs
 # Generate API documentation with pdoc
 uv run pdoc confkit -o docs/api
 
-# Build documentation site with mkdocs
-uv run mkdocs build -d site
+# Build documentation site with zensical
+uv run zensical build --clean
 
 # Or serve locally for live preview (with auto-reload)
-uv run mkdocs serve
+uv run zensical serve
 ```
 
 Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `master` branch.
@@ -91,5 +91,5 @@ Documentation is automatically built and deployed to GitHub Pages when changes a
 
 1. Update relevant `.md` files in `docs/` directory (examples, reference, etc.)
 2. Run `uv run pdoc confkit -o docs/api` to regenerate API documentation
-3. Preview changes with `uv run mkdocs serve` and verify at `http://127.0.0.1:8000`
+3. Preview changes with `uv run zensical serve` and verify at `http://127.0.0.1:8000`
 4. Commit both code and documentation changes together

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/custom_data_type.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Shows how to create and use a custom [`BaseDataType`](pdoc:confkit.BaseDataType) implementation.
+Shows how to create and use a custom [BaseDataType](/confkit/api/confkit.html#BaseDataType) implementation.
 
 - Normalize and persist a value in a consistent representation
 - Demonstrate the required `convert` method
@@ -20,7 +20,7 @@ Config.set_file(Path("config.ini"))
 
 class UpperString(BaseDataType[str]):
     """String that is always stored / returned in UPPER CASE."""
-    def convert(self, value: str) -> str:  # raw INI -> normalized
+    def convert(self, value: str) -> str:  # raw configuration -> normalized
         return str(value).upper()
 
     def __str__(self, value: str):  # normalized -> persisted string

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/data_types.md

@@ -5,9 +5,9 @@
 Showcases the breadth of built-in and helper data types:
 
 - Explicit vs implicit (auto-detected) types
-- Numeric formatting ([Hex](pdoc:confkit.Hex), [Octal](pdoc:confkit.Octal), [Binary](pdoc:confkit.Binary))
+- Numeric formatting ([Hex](/confkit/api/confkit.html#Hex), [Octal](/confkit/api/confkit.html#Octal), [Binary](/confkit/api/confkit.html#Binary))
 - Custom base integers (encoded as `<base>c<value>` in the file)
-- Bytes → integer conversion via [`Binary`](pdoc:confkit.Binary)
+- Bytes → integer conversion via [Binary](/confkit/api/confkit.html#Binary)
 
 ## Running
 

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/decorators.md

@@ -4,8 +4,8 @@
 
 Shows how to inject configuration values into functions using decorators:
 
-- [`@Config.with_setting(descriptor)`](pdoc:confkit.Config.with_setting) — injects kwarg named after descriptor
-- [`@Config.with_kwarg(section, option, kwarg_name, default)`](pdoc:confkit.Config.with_kwarg) — inject by strings + custom kwarg name
+- [@Config.with_setting(descriptor)](/confkit/api/confkit.html#Config.with_setting) — injects kwarg named after descriptor
+- [@Config.with_kwarg(section, option, kwarg_name, default)](/confkit/api/confkit.html#Config.with_kwarg) — inject by strings + custom kwarg name
 
 ## Running
 

confkit-2.2.0/docs/examples/delegate.md

@@ -0,0 +1,67 @@
+# Delegate Example ([`delegate.py`](https://github.com/HEROgold/confkit/blob/master/examples/delegate.py))
+
+## Purpose
+
+Shows how one setting can read and write a setting in another config file, so that file holds the only copy of the value.
+
+## Key Concepts
+
+- `Delegate(Settings.dashboard_url)` passes reads and writes through to `Settings.dashboard_url`
+- The delegate stores nothing, so its own file gets no key for it
+- Type checkers see the delegate with the target's type
+
+## Running
+
+```bash
+uv run python examples/delegate.py
+```
+
+## Code
+
+The bot and the dashboard both read `app.ini`. Only the dashboard reads `dashboard.ini`. The dashboard's public address lives in `app.ini`, and `dashboard.ini` refers to it:
+
+```python
+from pathlib import Path
+from typing import TypeVar
+
+from confkit.config import Config
+from confkit.ext.delegate import Delegate
+
+T = TypeVar("T")
+class AppConfig(Config[T]): ...
+class DashboardConfig(Config[T]): ...
+
+AppConfig.set_file(Path("app.ini"))
+DashboardConfig.set_file(Path("dashboard.ini"))
+
+class Settings:
+    dashboard_url = AppConfig("http://localhost:8001")
+
+class DashboardSettings:
+    session_key = DashboardConfig("change-me")
+    public_url = Delegate(Settings.dashboard_url)
+```
+
+## Generated Files
+
+`app.ini` holds the value:
+
+```ini
+[Settings]
+dashboard_url = http://localhost:8001
+```
+
+`dashboard.ini` has no `public_url` key:
+
+```ini
+[DashboardSettings]
+session_key = change-me
+```
+
+## Notes
+
+- Reading `DashboardSettings.public_url` reads the `dashboard_url` key in `app.ini`.
+- `DashboardSettings().public_url = "https://dashboard.example.com"` writes the `dashboard_url` key in `app.ini`.
+- A delegate can point at another delegate. Both read and write the same key.
+- Pass a plain attribute read of a `Config` setting, like `Settings.dashboard_url` or `module.Settings.dashboard_url`. A literal or a computed value such as `Settings.dashboard_url + "/callback"` raises `TypeError`.
+- `Delegate` finds the target by reading the caller's bytecode, so it runs on CPython only.

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/enums.md

@@ -4,7 +4,7 @@
 
 Demonstrates enum support:
 
-- [`StrEnum`](pdoc:confkit.StrEnum), [`IntEnum`](pdoc:confkit.IntEnum), [`IntFlag`](pdoc:confkit.IntFlag), usage via dedicated data types
+- [StrEnum](/confkit/api/confkit.html#StrEnum), [IntEnum](/confkit/api/confkit.html#IntEnum), [IntFlag](/confkit/api/confkit.html#IntFlag), usage via dedicated data types
 - Optional enum values
 - Bitwise flag composition (`Permission`)
 - **Self-documenting config files** with inline comments showing all allowed enum values

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/index.md

@@ -16,7 +16,7 @@ All examples assume you are in the project root and have dependencies installed
 uv run python examples/basic.py
 ```
 
-> If you are editing examples and want immediate persistence, remember that [`Config.write_on_edit`](pdoc:confkit.Config.write_on_edit) defaults to `True` unless explicitly disabled.
+> If you are editing examples and want immediate persistence, remember that [Config.write_on_edit](/confkit/api/confkit.html#Config.write_on_edit) defaults to `True` unless explicitly disabled.
 
 ## Example Categories
 
@@ -29,5 +29,6 @@ uv run python examples/basic.py
 | Enums | [Enums](enums.md) | StrEnum, IntEnum, IntFlag, optional enum values |
 | Decorators | [Decorators](decorators.md) | Injecting config into functions |
 | argparse Integration | [Argparse](argparse.md) | CLI defaults + config separation |
+| Delegates | [Delegate](delegate.md) | Reading and writing a setting in another file |
 
 Select an example in the navigation to dive in.

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/list_types.md

@@ -30,7 +30,7 @@ empty_list =
 
 ## Notes
 
-- See [`List.separator`](pdoc:confkit.List.separator) and [`List.escape_char`](pdoc:confkit.List.escape_char) for their default values (explicitly set in the example for clarity).
+- See [List.separator](/confkit/api/confkit.html#List.separator) and [List.escape_char](/confkit/api/confkit.html#List.escape_char) for their default values (explicitly set in the example for clarity).
 - Items containing the separator are escaped when written, then unescaped on read.
 - An explicit empty list with a declared data type stays as a blank line after the equals sign.
 

{confkit-2.1.0 → confkit-2.2.0}/docs/examples/optional_values.md

@@ -4,7 +4,7 @@
 
 Demonstrates nullable / optional configuration patterns:
 
-- `optional=True` shorthand vs [`Optional(...)`](pdoc:confkit.Optional) wrapper
+- `optional=True` shorthand vs [Optional(...)](/confkit/api/confkit.html#Optional) wrapper
 - Optional enums, strings, integers
 - Empty string vs None semantics
 - Cascading defaults & fallback logic

{confkit-2.1.0 → confkit-2.2.0}/docs/index.md

@@ -10,7 +10,7 @@ This landing page orients you quickly:
 | Create a custom data type | Usage Guide: [Adding a New Data Type](usage.md#adding-a-new-data-type) |
 | See all data type converters | [Reference: Data Types](reference/data_types.md) |
 | Decorator utilities | [Usage: Decorators Overview](usage.md#decorators-overview) |
-| API by symbol | [Generated API (pdoc)](pdoc:confkit) |
+| API by symbol | [Generated API (pdoc)](/confkit/api/confkit.html) |
 | Contribute / issues | GitHub Repo: [HEROgold/confkit](https://github.com/HEROgold/confkit) |
 
 ---
@@ -49,7 +49,7 @@ uv run pytest -q
 uv run ruff check .
 uv sync --group docs
 uv run pdoc confkit -o docs/api
-uv run mkdocs build -d site
+uv run zensical build --clean
 ```
 
 Before opening a PR, ensure:
@@ -82,13 +82,13 @@ Two complementary views:
 
 ### Full symbol index (pdoc)
 
-[confkit API](pdoc:confkit)
+[confkit API](/confkit/api/confkit.html)
 
 Use `(pdoc:qual.name)` style links inside docs for deep, stable symbol links
 
 ```md
-The [MyClass](pdoc:mypackage.MyClass) class is awesome.
-The [do_something](pdoc:mypackage.MyClass.do_something) method is awesome.
+The [MyClass](/confkit/api/confkit.html#mypackage.MyClass) class is awesome.
+The [do_something](/confkit/api/confkit.html#mypackage.MyClass.do_something) method is awesome.
 The [](mypackage.MyClass) class is awesome.
 ```
 

confkit-2.2.0/docs/markdown.md

@@ -0,0 +1,111 @@
+---
+icon: simple/markdown
+---
+
+# Markdown in 5min
+
+## Headers
+
+```
+# H1 Header
+## H2 Header
+### H3 Header
+#### H4 Header
+##### H5 Header
+###### H6 Header
+```
+
+## Text formatting
+
+```
+**bold text**
+*italic text*
+***bold and italic***
+~~strikethrough~~
+`inline code`
+```
+
+## Links and images
+
+```
+[Link text](https://example.com)
+[Link with title](https://example.com "Hover title")
+![Alt text](image.jpg)
+![Image with title](image.jpg "Image title")
+```
+
+## Lists
+
+```
+Unordered:
+
+- Item 1
+- Item 2
+  - Nested item
+
+Ordered:
+
+1. First item
+2. Second item
+3. Third item
+```
+
+## Blockquotes
+
+```
+> This is a blockquote
+> Multiple lines
+>> Nested quote
+```
+
+## Code blocks
+
+````
+```javascript
+function hello() {
+  console.log("Hello, world!");
+}
+```
+````
+
+## Tables
+
+```
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Row 1    | Data     | Data     |
+| Row 2    | Data     | Data     |
+```
+
+## Horizontal rule
+
+```
+---
+or
+***
+or
+___
+```
+
+## Task lists
+
+```
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+## Escaping characters
+
+```
+Use backslash to escape: \* \_ \# \`
+```
+
+## Line breaks
+
+```
+End a line with two spaces  
+to create a line break.
+
+Or use a blank line for a new paragraph.
+```

{confkit-2.1.0 → confkit-2.2.0}/docs/reference/config.md

@@ -8,31 +8,31 @@ This section provides curated guidance around the core `Config` descriptor and i
 
 ## Core Class
 
-- [`Config`](pdoc:confkit.Config) – Descriptor managing reading/writing typed values.
+- [Config](/confkit/api/confkit.html#Config) – Descriptor managing reading/writing typed values.
 
 ## Lifecycle / Initialization Helpers
 
-- [`Config.set_parser`](pdoc:confkit.Config.set_parser)
-- [`Config.set_file`](pdoc:confkit.Config.set_file)
-- [`Config.write`](pdoc:confkit.Config.write)
+- [Config.set_parser](/confkit/api/confkit.html#Config.set_parser)
+- [Config.set_file](/confkit/api/confkit.html#Config.set_file)
+- [Config.write](/confkit/api/confkit.html#Config.write)
 
 ## Runtime Flags
 
-- [`Config.validate_types`](pdoc:confkit.Config.validate_types)
-- [`Config.write_on_edit`](pdoc:confkit.Config.write_on_edit)
+- [Config.validate_types](/confkit/api/confkit.html#Config.validate_types)
+- [Config.write_on_edit](/confkit/api/confkit.html#Config.write_on_edit)
 
 ## Decorators
 
-- [`Config.set`](pdoc:confkit.Config.set) – Always set a value before calling a function.
-- [`Config.default`](pdoc:confkit.Config.default) – Set only when unset.
-- [`Config.with_setting`](pdoc:confkit.Config.with_setting) – Inject an existing descriptor value as a kwarg.
-- [`Config.with_kwarg`](pdoc:confkit.Config.with_kwarg) – (Named `with_kwarg` in code; often described as `with_kwarg`) inject by section/setting with optional rename & default.
+- [Config.set](/confkit/api/confkit.html#Config.set) – Always set a value before calling a function.
+- [Config.default](/confkit/api/confkit.html#Config.default) – Set only when unset.
+- [Config.with_setting](/confkit/api/confkit.html#Config.with_setting) – Inject an existing descriptor value as a kwarg.
+- [Config.with_kwarg](/confkit/api/confkit.html#Config.with_kwarg) – (Named `with_kwarg` in code; often described as `with_kwarg`) inject by section/setting with optional rename & default.
 
 ## Internal Validation (Selected)
 
-- [`Config.validate_file`](pdoc:confkit.Config.validate_file)
-- [`Config.validate_parser`](pdoc:confkit.Config.validate_parser)
-- [`Config.validate_strict_type`](pdoc:confkit.Config.validate_strict_type)
+- [Config.validate_file](/confkit/api/confkit.html#Config.validate_file)
+- [Config.validate_parser](/confkit/api/confkit.html#Config.validate_parser)
+- [Config.validate_strict_type](/confkit/api/confkit.html#Config.validate_strict_type)
 
 > Tip: Use the decorators for imperative flows and prefer descriptor attributes for normal configuration access.
 >

confkit-2.2.0/docs/reference/data_types.md

@@ -0,0 +1,77 @@
+---
+title: Data Types
+---
+
+# Data Types
+
+confkit uses a family of small converter classes to provide type safety and round‑trip serialization.
+
+## Base Type
+
+- [BaseDataType](/confkit/api/confkit.html#BaseDataType)
+  - [BaseDataType.convert](/confkit/api/confkit.html#BaseDataType.convert)
+  - [BaseDataType.validate](/confkit/api/confkit.html#BaseDataType.validate)
+  - [BaseDataType.cast](/confkit/api/confkit.html#BaseDataType.cast)
+  - [BaseDataType.cast_optional](/confkit/api/confkit.html#BaseDataType.cast_optional)
+
+## Primitive Converters
+
+- [String](/confkit/api/confkit.html#String)
+- [Integer](/confkit/api/confkit.html#Integer)
+- [Float](/confkit/api/confkit.html#Float)
+- [Boolean](/confkit/api/confkit.html#Boolean)
+- [NoneType](/confkit/api/confkit.html#NoneType)
+
+## Enum Converters
+
+- [Enum](/confkit/api/confkit.html#Enum)
+- [StrEnum](/confkit/api/confkit.html#StrEnum)
+- [IntEnum](/confkit/api/confkit.html#IntEnum)
+- [IntFlag](/confkit/api/confkit.html#IntFlag)
+
+All enum types automatically display allowed values as inline comments in the config file, making them self-documenting for end-users. For example:
+
+```ini
+log_level = info  # allowed: debug, info, warning, error
+```
+
+The format varies by enum type:
+- **StrEnum**: Shows member values (e.g., `debug, info, warning, error`)
+- **IntEnum/IntFlag**: Shows member names with integer values (e.g., `LOW(0), MEDIUM(5), HIGH(10)`)
+- **Enum**: Shows member names (e.g., `DEBUG, INFO, WARNING, ERROR`)
+
+Comments are automatically stripped when reading values, ensuring they don't interfere with parsing.
+
+## Number Representation Helpers
+
+- [Hex](/confkit/api/confkit.html#Hex)
+- [Octal](/confkit/api/confkit.html#Octal)
+- [Binary](/confkit/api/confkit.html#Binary)
+
+## Optional & Composite
+
+- [Optional](/confkit/api/confkit.html#Optional)
+- [List](/confkit/api/confkit.html#List)
+
+> Design note: `Optional` wraps another `BaseDataType` and returns `None` when a null sentinel is parsed.
+
+## Collections
+
+- [Tuple](/confkit/api/confkit.html#Tuple)
+- [Set](/confkit/api/confkit.html#Set)
+- [Dict](/confkit/api/confkit.html#Dict)
+
+`Tuple`, `Set`, and `Dict` mirror their built‑in counterparts. Allowing for collections to be stored in configuration files.
+
+## Date & Time
+
+- [DateTime](/confkit/api/confkit.html#DateTime)
+- [Date](/confkit/api/confkit.html#Date)
+- [Time](/confkit/api/confkit.html#Time)
+- [TimeDelta](/confkit/api/confkit.html#TimeDelta)
+
+`DateTime`, `Date`, `Time` and `TimeDelta` mirror their built-in counterparts. Allowing to store date information in configuration files.
+
+## Custom Type Example
+
+- [BaseDataType](/confkit/api/confkit.html#BaseDataType)