feat: add TOML support to serdes and improve docs

- Add TOML read support via stdlib tomllib (Python 3.11+) with tomli backport for Python 3.10
- Add TOML write support via optional tomli-w, guarded by TOML_WRITE_AVAILABLE flag
- Extend loads() and dumps() to accept 'toml' as a format hint/type
- Reject top-level lists in toml_dumps() with a clear ValidationError message
- Rewrite all serdes docstrings with full Args/Returns/Raises sections and format constraints
- Update docs/development.md with correct Python version, full project structure, and Optional Dependencies table
- Add tomli and tomli_w to mypy ignore_missing_imports overrides

Author: Peter Sprygada

docs/development.md

@@ -80,14 +80,49 @@ asyncgateway/
 │   ├── client.py           # Client class with service/resource discovery
 │   ├── exceptions.py       # Exception hierarchy (AsyncGatewayError, ValidationError)
 │   ├── logging.py          # Logging with sensitive data filtering
-│   ├── serdes.py           # JSON/YAML serialization
+│   ├── serdes.py           # JSON / YAML / TOML serialization utilities
 │   ├── services/           # 23 thin async wrappers, one per IAG API tag group
 │   └── resources/          # 22 declarative resource abstractions
 ├── tests/                  # Test files (mock ipsdk, no live IAG needed)
 ├── docs/                   # Documentation
 └── pyproject.toml          # Project configuration and tool settings
 ```
 
+## Optional Dependencies
+
+The core library requires only `ipsdk`.  Additional serialization formats can
+be unlocked by installing optional packages:
+
+| Format | Operation | Package | Python version |
+|--------|-----------|---------|----------------|
+| YAML   | read & write | `PyYAML` | any |
+| TOML   | read | *(stdlib `tomllib`)* | 3.11+ |
+| TOML   | read | `tomli` | 3.10 only |
+| TOML   | write | `tomli-w` | any |
+
+Install a single optional format:
+
+```bash
+uv add PyYAML          # YAML support
+uv add tomli           # TOML read on Python 3.10
+uv add tomli-w         # TOML write (any version)
+```
+
+Install all optional serialization extras at once:
+
+```bash
+uv add PyYAML tomli-w  # tomli only needed on Python 3.10
+```
+
+You can inspect runtime availability from Python:
+
+```python
+from asyncgateway.serdes import YAML_AVAILABLE, TOML_AVAILABLE, TOML_WRITE_AVAILABLE
+```
+
+Calling a function whose dependency is absent raises `ValidationError` (not
+`ImportError`), so callers do not need to guard imports.
+
 ## Development Notes
 
 - Services and resources are filesystem-discovered at client init. Adding a file with a `Service` or `Resource` class and a `name` attribute is sufficient for registration — no other wiring required.
@@ -114,3 +149,4 @@ asyncgateway/
 - For test failures, run with `-v` for more detailed output.
 - If tests mock `os.listdir`, note that `Client.__init__` calls it **twice** — once for `services/` and once for `resources/`. Use `side_effect=[service_files, resource_files]`.
 - YAML support is optional. If `PyYAML` is not installed, YAML paths raise `ValidationError` rather than `ImportError`.
+- TOML read support is optional on Python 3.10 (install `tomli`); on 3.11+ it uses the stdlib `tomllib`. TOML write always requires `tomli-w`.

pyproject.toml

@@ -118,7 +118,7 @@ python_version = "3.11"
 warn_unused_configs = true
 
 [[tool.mypy.overrides]]
-module = ["ipsdk.*", "yaml"]
+module = ["ipsdk.*", "yaml", "tomli", "tomli_w"]
 ignore_missing_imports = true
 
 [tool.bandit]