Add support for nested configuration (#52)

* Add support for nested configuration

* Update docs/examples/custom_data_type.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Fix docs: remove non-existent `Parser`/`set_parser` references (#53)

* Initial plan

* Fix documentation: remove non-existent Parser/set_parser references

Co-authored-by: HEROgold <21345384+HEROgold@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: HEROgold <21345384+HEROgold@users.noreply.github.com>

* mark as deprecation instead of private method

* Raise ConfigPathConflictError when trying to path through a scalar.

* fix ruff issue

* ignore line len on deprecation warning

* ruff fixes

* add missing .env parse detection

* Separate built-in parsers from msgspec optional dependency; fix MsgspecParser type handling and conflict detection (#54)

* Initial plan

* Move built-in parsers to confkit.parsers, fix type handling and conflict detection

Co-authored-by: HEROgold <21345384+HEROgold@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: HEROgold <21345384+HEROgold@users.noreply.github.com>

* fix docstr

* fix ruff

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: 3 people

.github/copilot-instructions.md

@@ -11,9 +11,10 @@ confkit is a Python library for type-safe configuration management using descrip
 - `Config` descriptor (`config.py`): The main descriptor class that handles getting/setting values in config files
 - `ConfigContainerMeta` (`config.py`): Metaclass that enables setting Config descriptors on class variables
 - `BaseDataType` and implementations (`data_types.py`): Type converters for different data types
-- `ConfkitParser` protocol (`ext/parsers.py`): Protocol defining the parser interface
-- `MsgspecParser` (`ext/parsers.py`): Parser for JSON, YAML, and TOML files
-- `EnvParser` (`ext/parsers.py`): Parser for environment variables and .env files
+- `ConfkitParser` protocol (`parsers.py`): Defines the unified parser interface for all configuration file formats (INI, JSON, YAML, TOML, .env)
+- `IniParser` (`parsers.py`): Adapter for Python's built-in ConfigParser (INI files)
+- `MsgspecParser` (`ext/parsers.py`): Adapter for JSON, YAML, and TOML files using msgspec
+- `EnvParser` (`parsers.py`): Adapter for environment variables and .env files
 - `sentinels.py`: Provides the `UNSET` sentinel value for representing unset values
 - `exceptions.py`: Custom exceptions for configuration errors
 - `watcher.py`: File watching functionality to detect config file changes
@@ -44,6 +45,8 @@ uv sync --group test
 ```bash
 # Run linting
 ruff check .
+# Fix issues using
+ruff check . --fix --unsafe-fixes
 # Update dependencies and run tests
 uv sync --upgrade --group dev; uv run pytest .
 ```
@@ -172,33 +175,26 @@ The `with_setting` approach is more type-safe as it references an actual descrip
 
 ### Required Initialization
 
-Always initialize Config with a file path before use. The parser can be set explicitly or will be auto-detected based on file extension:
+Always initialize Config with a file path before use. The parser is auto-detected based on file extension:
 
 ```python
 from pathlib import Path
 from confkit import Config
 
-# Option 1: Auto-detect parser based on file extension
-Config.set_file(Path("config.ini"))  # Uses ConfigParser
+# Parser is auto-detected based on file extension
+Config.set_file(Path("config.ini"))   # Uses IniParser
 Config.set_file(Path("config.json"))  # Uses MsgspecParser
 Config.set_file(Path("config.yaml"))  # Uses MsgspecParser
 Config.set_file(Path("config.toml"))  # Uses MsgspecParser
-Config.set_file(Path(".env"))  # Uses EnvParser
-
-# Option 2: Explicitly set parser (not recommended unless it's absolutely required.)
-from configparser import ConfigParser
-parser = ConfigParser()
-Config.set_parser(parser)
-Config.set_file(Path("config.ini"))
 ```
 
 ### Supported File Formats
 
-- **INI files** (`.ini`): Uses Python's `ConfigParser`, supports sections
+- **INI files** (`.ini`): Uses `IniParser`, supports sections
 - **JSON files** (`.json`): Uses `MsgspecParser`, requires `msgspec` extra
 - **YAML files** (`.yaml`, `.yml`): Uses `MsgspecParser`, requires `msgspec` extra
 - **TOML files** (`.toml`): Uses `MsgspecParser`, requires `msgspec` extra
-- **Environment files** (`.env`): Uses `EnvParser`, no sections (flat key-value pairs)
+- **Environment files** (`.env`): Uses `EnvParser`, no sections (flat key-value pairs) — not auto-detected by `set_file`
 
 ### List Type Handling
 

docs/examples/custom_data_type.md

@@ -11,14 +11,11 @@ Shows how to create and use a custom [`BaseDataType`](pdoc:confkit.BaseDataType)
 ## Implementation
 
 ```python
-from configparser import ConfigParser
 from pathlib import Path
 from confkit import Config
 from confkit.data_types import BaseDataType
 
-# Configure parser + file
-parser = ConfigParser()
-Config.set_parser(parser)
+# Configure config file (parser is automatically detected from extension)
 Config.set_file(Path("config.ini"))
 
 class UpperString(BaseDataType[str]):

docs/usage.md

@@ -9,13 +9,10 @@ This page explains how to work with confkit and how the documentation is generat
 ## Descriptor Quickstart
 
 ```python
-from configparser import ConfigParser
 from pathlib import Path
 from confkit import Config
 
-# 1. Configure confkit parser/file (normally app bootstrap)
-parser = ConfigParser()
-Config.set_parser(parser)
+# 1. Configure confkit file (parser is auto-detected)
 Config.set_file(Path("config.ini"))
 
 # 2. Define your (class)variables with their default values
@@ -36,14 +33,11 @@ print(AppConfig.port)
 4. Use via `Config(CustomType(default_value))`
 
 ```python
-from configparser import ConfigParser
 from pathlib import Path
 from confkit import Config
 from confkit.data_types import BaseDataType
 
-# 1. Configure confkit parser/file (normally app bootstrap)
-parser = ConfigParser()
-Config.set_parser(parser)
+# 1. Configure confkit file (parser is auto-detected)
 Config.set_file(Path("config.ini"))
 
 # 2. Define the custom converter, with a convert method (from str -> your_type)

examples/argparse_example.py

@@ -16,10 +16,8 @@
 from confkit.data_types import List
 
 # Setup a standard confkit config file (unrelated to argparse defaults file)
-parser_ini = ConfigParser()
 ini_path = Path("config.ini")
 Config.write_on_edit = False
-Config.set_parser(parser_ini)
 Config.set_file(ini_path)
 
 class AppConfig:

examples/basic.py

@@ -16,8 +16,6 @@
 from confkit import Config
 
 # Set up the parser and file
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 # Enable automatic writing when config values are changed (this is the default)

examples/custom_data_type.py

@@ -20,8 +20,6 @@
 from confkit import Config
 from confkit.data_types import BaseDataType
 
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 class UpperString(BaseDataType[str]):

examples/data_types.py

@@ -16,8 +16,6 @@
 from confkit import Config
 from confkit.data_types import Binary, Boolean, Float, Hex, Integer, Octal, String
 
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 

examples/decorators.py

@@ -5,8 +5,6 @@
 
 from confkit.config import Config
 
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 

examples/enums.py

@@ -20,8 +20,6 @@
 from confkit.data_types import IntFlag as ConfigIntFlag
 from confkit.data_types import Optional, StrEnum as ConfigStrEnum
 
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 

examples/file_change_event.py

@@ -11,8 +11,6 @@
 from confkit import Config
 
 # Set up the parser and file
-parser = ConfigParser()
-Config.set_parser(parser)
 Config.set_file(Path("config.ini"))
 
 # Enable automatic writing when config values are changed (this is the default)