minimal-magic 0.6.0__py3-none-any.whl

docs/api.md

@@ -0,0 +1,52 @@
+# API details
+
+## `alias()`
+
+Maps a config file key name to a Python attribute name. Useful for kebab-case TOML keys:
+
+```python
+import dataclasses
+from minimal_magic import load, alias
+
+@dataclasses.dataclass
+class RetryConfig:
+    retry_count: int = alias("retry-count", default=3)
+    connect_timeout: float = alias("connect-timeout", default=5.0)
+
+config = load("config.toml", type=RetryConfig)
+# reads "retry-count" and "connect-timeout" from the file,
+# exposes them as config.retry_count and config.connect_timeout
+```
+
+`alias()` is a thin wrapper around `dataclasses.field(metadata={"alias": ...})` and accepts all the same keyword arguments.
+
+## Error handling
+
+```python
+from minimal_magic import load, ParseError
+
+try:
+    config = load("config.yaml", type=ServerConfig)
+except ParseError as exc:
+    print(exc)           # "config.yaml:3:7: Expected `int`, got `str`"
+    print(exc.filename)  # "config.yaml" — always a str, never a Path
+    print(exc.line)      # 3
+    print(exc.column)    # 7
+```
+
+`ParseError` is re-exported from the `parse-errors` package (pinned to `>= 0.6.0, < 1.0`) so
+catching it doesn't need a second import. `ParseContext` and the source-map types
+(`Location`, `Entry`, `TSourceMap`) are `parse-errors`' own manual location-extraction
+building blocks — nothing here calls them, so import them from `parse_errors` directly
+if you need them.
+
+## CLI
+
+Validate a config file against a type without writing a wrapper script — handy in pre-commit or CI:
+
+```bash
+python -m minimal_magic validate config.toml --type mypkg.config:AppConfig
+# or, after install: minimal-magic validate config.toml --type mypkg.config:AppConfig
+```
+
+`--type` is `MODULE:ATTR` (dotted `ATTR` paths like `Outer.Inner` work too); `--format` and `--forbid-unknown-fields` are also accepted. Exits 0 and prints `<file>: OK` on success; exits 1 with the located error on stderr on failure.

docs/comparison.md

@@ -0,0 +1,28 @@
+# Shapes and alternate libraries
+
+msgspec decodes millions of records a second because its converter is a C extension driven by its own `Struct` types. pydantic validates through pydantic-core, a Rust extension, and does much more than type conversion — coercion policy, computed fields, JSON schema generation. minimal-magic does one thing, in Python, against the `dataclass` and `TypedDict` types you already declared, and spends the time it saves on ergonomics.
+
+| | minimal-magic | msgspec | pydantic |
+|---|---|---|---|
+| Target types | plain `dataclass`, `TypedDict` | `msgspec.Struct` | `BaseModel` |
+| 20k-item convert, converts/sec | ~150 | ~5,000 | ~2,700 |
+| Library size | ~1k lines pure Python | 2,400 lines Python + C extension | Python + Rust extension (pydantic-core) |
+| Syntax errors | filename, line, column | n/a | n/a |
+| Type errors | filename, line, column | field path only | field path only |
+| Field aliases | `alias("kebab-case")` | `rename=` on the Struct | `Field(alias=...)` |
+| Tagged unions | discriminator auto-detected | declared per Struct | declared via `discriminator=` |
+| Config cascade | `load_candidate()` with per-field merge | n/a | n/a |
+
+msgspec's "field path only" errors are still wrappable by `parse-errors`' `ParseContext` today, because msgspec happens to embed a JSONPath string in its message (`"... - at \`$.port\`"`) that `parse-errors` pattern-matches. pydantic's `ValidationError` carries the same kind of structured path — `exc.errors()` gives a `loc` tuple — but not embedded in the message text, so `ParseContext` can't extract it yet; that would need its own extraction branch in `parse-errors`, the same way JSON's and YAML's `lineno`/`colno` got one.
+
+All three convert the same already-parsed Python dict — `{"items": [0, 1, ..., 19999]}` — into a typed structure holding a `list[int]`: `minimal_magic.convert()`, `msgspec.convert()`, and `BaseModel.model_validate()`. No file I/O or text parsing in any of the three; that step is common to all of them and isn't what this table measures. Median of 11 runs after 2 warmup calls. Re-measure before quoting these; they move with the interpreter.
+
+The ratio moves with the data's shape, not just the interpreter: a flat homogeneous array is minimal-magic's worst case — it's the same compiled converter called 20,000 times with no branching, and msgspec's/pydantic's native code has nothing else to do either. A deeply nested, heterogeneous config (many small `dataclass`/`Struct`/`BaseModel` types, `Optional` fields, `dict[str, str]` maps) narrows the gap to roughly 8x vs. msgspec and 1.5x vs. pydantic, because msgspec's and pydantic's per-object construction cost stops being negligible too.
+
+None of the above hits a source map: it's the cost of a value that converts cleanly. A value that doesn't pays for one. `test_benchmark_large_list_load_validation_failure` / `test_benchmark_nested_envoy_config_load_validation_failure` measure exactly that against their clean-load counterparts. minimal-magic asks parse-errors' `locate_pointer()` for the one pointer that failed instead of mapping the whole document. `_FixedSource` stays lazy: nothing built on the common path, and only the failed pointer is located when something actually fails.
+
+That failure path is doing extra work on purpose: it turns "some nested value had the wrong type" into a filename, line, and column a person can fix. On current local runs with parse-errors 0.6.0, that richer error costs on the order of tens of milliseconds, not a whole-document source-map walk. Run the benchmark tests before quoting exact timings; they depend on the parser, Python, CPU, and where the bad value sits.
+
+See `tests/test_benchmark_loader.py` (flat) and `tests/test_benchmark_nested_loader.py` (deeply nested, Envoy-config-shaped) for the actual benchmarks this repo tracks, success and failure paths both.
+
+Use msgspec or pydantic when throughput or heavier validation is the point. Use minimal-magic when the data is a config file, the types are already dataclasses, and the person who has to fix a bad value is a human reading the error message.

docs/merging.md

@@ -0,0 +1,82 @@
+# Merge rules
+
+
+For each key that appears in both the accumulated base and the incoming candidate:
+
+1. **Field merge callable** — if the dataclass field declares `metadata={"merge": fn}`,
+   `fn(base_value, override_value)` is called and its return value is used. This takes
+   priority over all other rules, including dict recursion.
+2. **Both values are dicts** — the dicts are merged recursively by the same rules,
+   propagating the field's type so nested merge callables are respected.
+3. **Everything else** — the override value replaces the base value entirely.
+   This includes lists, sets, scalars, `None`, and type changes (e.g. dict → scalar).
+
+Keys present only in the base are kept; keys present only in the override are added.
+
+```python
+import dataclasses
+from minimal_magic import load_candidate
+
+@dataclasses.dataclass
+class AppConfig:
+    host: str
+    port: int
+    # concatenate tags from all config files instead of replacing
+    tags: list[str] = dataclasses.field(
+        default_factory=list,
+        metadata={"merge": lambda base, override: base + override},
+    )
+```
+
+### Example: `extend-ignore`
+
+A common config pattern is `ignore` (replace) paired with `extend-ignore` (append). The merge callable accumulates `extend-ignore` across candidates; `__post_init__` folds it into `ignore` at the end:
+
+```python
+import dataclasses
+from minimal_magic import load_candidate
+
+@dataclasses.dataclass
+class LinterConfig:
+    ignore: list[str] = dataclasses.field(default_factory=list)
+    extend_ignore: list[str] = dataclasses.field(
+        default_factory=list,
+        metadata={"alias": "extend-ignore", "merge": lambda base, override: base + override},
+    )
+
+    def __post_init__(self):
+        self.ignore = self.ignore + self.extend_ignore
+
+config = load_candidate([
+    "defaults.toml",          # extend-ignore = ["E001"]
+    "pyproject.toml",         # extend-ignore = ["E501"]
+    "local.toml",             # extend-ignore = ["W503"]
+], type=LinterConfig)
+# config.ignore == base_ignore + ["E001", "E501", "W503"]
+```
+
+Without the merge callable, `extend-ignore` would have last-wins semantics and only `["W503"]` would survive the merge phase.
+
+### Notes on merge callables
+
+**Merge is only called when a key appears in two or more candidates.** If a key
+appears in only one candidate (or comes from a `default_factory`), the merge
+callable is never invoked — the value is used as-is.
+
+**Avoid `base or override` in merge callables.** If `base` is truthy and
+`override` is falsy, `base or override` short-circuits and returns `base`,
+silently ignoring the override. For example, `['x'] or []` returns `['x']`
+even though the override explicitly set an empty list. Prefer explicit
+operations: `base + override` for concatenation, `base | override` for sets and
+dicts, or `base if base is not None else override` for null-coalescing.
+
+**Merge callables receive and return raw values** (dicts, lists, scalars) as they
+appear in the config files, before type conversion. A `list[LinterConfig]` field's
+merge callable receives a list of dicts, not `LinterConfig` objects. If your
+callable constructs a typed instance internally — even temporarily — be aware that
+its `__post_init__` fires at that point, and then `_convert` constructs another
+instance from the returned raw value, firing `__post_init__` a second time on a
+different object.
+
+**Exceptions raised inside a merge callable** are caught and re-raised as
+`ParseError` pointing to the override value's location in the candidate file.

docs/types.md

@@ -0,0 +1,15 @@
+# Supported types
+
+
+| Category | Types |
+|---|---|
+| Structured | `dataclass`, `TypedDict` |
+| Collections | `list`, `tuple`, `dict`, `set`, `frozenset`, `Sequence`, `Mapping`, `AbstractSet` |
+| Unions | `Optional[T]`, `Union[A, B]`, `A \| B`, tagged unions (discriminator auto-detected) |
+| Scalars | `str`, `int`, `float`, `bool`, `Literal[...]`, `Enum` |
+| Rich scalars | `Path`, `Decimal`, `date`, `datetime`, `time` |
+| Unchecked | `Any` (passed through), `Annotated[T, ...]`, `Required[T]`, `NotRequired[T]` (unwrapped, then `T` is checked) |
+
+`bool` is rejected for `int` fields. Bare `int` is coerced to `float` when a `float` field is expected.
+
+A collection type used bare, with no type argument (`dict` rather than `dict[str, int]`), is checked no more than `Any` is: only that the value is a `dict`. Parameterize it if you want its contents checked too.

minimal_magic/__init__.py

@@ -0,0 +1,7 @@
+"""minimal_magic — msgspec-style typed conversion for plain dataclasses and TypedDicts."""
+
+from parse_errors import ParseError
+
+from .api import alias, Candidate, convert, load, load_candidate
+
+__all__ = ["ParseError", "convert", "load", "load_candidate", "alias", "Candidate"]

minimal_magic/__main__.py

@@ -0,0 +1,68 @@
+"""``python -m minimal_magic`` — validate a config file against a type from the command line."""
+
+import argparse
+import importlib
+import sys
+
+from . import load, ParseError
+
+
+def _resolve_type(spec: str) -> type:
+    if ":" not in spec:
+        raise ValueError(f"--type must look like MODULE:ATTR, got {spec!r}")
+    module_name, _, attr_path = spec.partition(":")
+    module = importlib.import_module(module_name)
+    obj = module
+    for part in attr_path.split("."):
+        obj = getattr(obj, part)
+    return obj
+
+
+def _validate(args: argparse.Namespace) -> int:
+    try:
+        target_type = _resolve_type(args.type)
+    except Exception as exc:
+        print(f"Cannot resolve --type {args.type!r}: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        load(
+            args.file,
+            type=target_type,
+            format=args.format,
+            forbid_unknown_fields=args.forbid_unknown_fields,
+        )
+    except ParseError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    print(f"{args.file}: OK")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="minimal-magic")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser("validate", help="validate a config file against a type")
+    validate.add_argument("file", help="path to the config file")
+    validate.add_argument(
+        "--type",
+        required=True,
+        help="MODULE:ATTR of the type to validate against, e.g. mypkg.config:AppConfig",
+    )
+    validate.add_argument("--format", choices=["json", "yaml", "toml"], default=None)
+    validate.add_argument("--forbid-unknown-fields", action="store_true")
+    validate.set_defaults(func=_validate)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()