infinity_pyscanf 0.1.0__tar.gz

infinity_pyscanf-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.3
+Name: infinity_pyscanf
+Version: 0.1.0
+Summary: Type-safe, scanf-style string parsing.
+Keywords: scanf,parsing,parser,regex,type-safe
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Dist: interrogate ; extra == 'dev'
+Requires-Dist: ruff ; extra == 'dev'
+Requires-Dist: pyright ; extra == 'dev'
+Requires-Dist: pre-commit ; extra == 'dev'
+Requires-Dist: infinity-pyscanf[test] ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'test'
+Requires-Dist: pytest-cov ; extra == 'test'
+Requires-Python: >=3.14
+Provides-Extra: dev
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# infinity_pyscanf
+
+Type-safe, `scanf`-style string parsing for Python 3.14+.
+Distributed as `infinity_pyscanf`; imported as `scanf`.
+
+Supply one converter type per `{}` placeholder as class type arguments, then
+the template and the input string as call arguments:
+
+```python
+from scanf import scanf
+
+a, b, c = scanf[int, float, str]("{} {} {}")("1 2.5 hello")
+# a=1 (int), b=2.5 (float), c="hello" (str)
+```
+
+Parsers are reusable:
+
+```python
+parse_pair = scanf[int, int]("{} {}")
+parse_pair("7 8")  # (7, 8)
+```
+
+## Built-in converters
+
+Built-in generic containers (`dict`, `list`, `tuple`, `set` and `frozenset`)
+are parsed as Python literals via `ast.literal_eval`, and `bool` accepts
+`true` / `false` / `1` / `0` (case-insensitive):
+
+```python
+from scanf import scanf
+
+scanf[bool]("{}")("true")  # (True,)
+scanf[list[int]]("{}")("[1, 2, 3]")  # ([1, 2, 3],)
+```
+
+For JSON-specific syntax (`true`, `false`, `null`) or any custom conversion,
+attach a `Converter` spec:
+
+```python
+import json
+from typing import Annotated
+
+from scanf import Converter, scanf
+
+parse_json = scanf[Annotated[dict[str, str], Converter(json.loads)]]("{}")
+parse_json('{"key": "value"}')  # ({"key": "value"},)
+```
+
+## Per-field configuration
+
+Per-field configuration rides along as `Converter` metadata inside a
+`typing.Annotated` converter: a conversion callable, a capture pattern, a
+strip flag, `re` flags and a label:
+
+```python
+from typing import Annotated
+
+from scanf import Converter, scanf
+
+parse = scanf[
+    Annotated[int, Converter(int, pattern=r"\d+", name="age")],
+    Annotated[str, Converter(str, pattern=r'"[^"]*"', name="name")],
+]("age={} name={}")
+parse('age=42 name="kim"')  # (42, '"kim"')
+```
+
+`typing.Annotated` wrappers around converters are stripped; their metadata is
+ignored unless it contains a `Converter` spec. Several specs on one field
+compete in declaration order: each branch carries its own pattern, the first
+branch whose pattern matches wins, and if its converter then fails the whole
+scan fails — a failing converter never falls back to a later branch.
+
+## Template semantics
+
+Each `{}` captures with the default `.+?` pattern:
+
+* non-empty: at least one character;
+* single-line: never matches a newline;
+* lazy: takes the shortest text that still lets the rest of the template match.
+
+A `Converter` spec can replace the pattern per field.
+
+Whitespace runs in the template match any whitespace run in the input, and
+surrounding whitespace of the input (and of each captured field) is ignored.
+Literal braces in a template are written `{{` and `}}`; a single brace is an
+error.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pre-commit install             # optional: run the gates on every commit
+uv run pre-commit run --all-files     # full local gate
+```
+
+The gate runs ruff (lint + format), pyright (strict), interrogate (docstring
+coverage), pytest with a coverage floor, and an `example/` smoke run. CI
+(GitHub Actions) runs the same gates plus a 3-OS test matrix.
+
+`example/example.py` contains worked examples: field customization, JSON
+parsing and a recursive scanner built with fixpoint / `alt` / `sep_by`
+combinators.

infinity_pyscanf-0.1.0/README.md

@@ -0,0 +1,102 @@
+# infinity_pyscanf
+
+Type-safe, `scanf`-style string parsing for Python 3.14+.
+Distributed as `infinity_pyscanf`; imported as `scanf`.
+
+Supply one converter type per `{}` placeholder as class type arguments, then
+the template and the input string as call arguments:
+
+```python
+from scanf import scanf
+
+a, b, c = scanf[int, float, str]("{} {} {}")("1 2.5 hello")
+# a=1 (int), b=2.5 (float), c="hello" (str)
+```
+
+Parsers are reusable:
+
+```python
+parse_pair = scanf[int, int]("{} {}")
+parse_pair("7 8")  # (7, 8)
+```
+
+## Built-in converters
+
+Built-in generic containers (`dict`, `list`, `tuple`, `set` and `frozenset`)
+are parsed as Python literals via `ast.literal_eval`, and `bool` accepts
+`true` / `false` / `1` / `0` (case-insensitive):
+
+```python
+from scanf import scanf
+
+scanf[bool]("{}")("true")  # (True,)
+scanf[list[int]]("{}")("[1, 2, 3]")  # ([1, 2, 3],)
+```
+
+For JSON-specific syntax (`true`, `false`, `null`) or any custom conversion,
+attach a `Converter` spec:
+
+```python
+import json
+from typing import Annotated
+
+from scanf import Converter, scanf
+
+parse_json = scanf[Annotated[dict[str, str], Converter(json.loads)]]("{}")
+parse_json('{"key": "value"}')  # ({"key": "value"},)
+```
+
+## Per-field configuration
+
+Per-field configuration rides along as `Converter` metadata inside a
+`typing.Annotated` converter: a conversion callable, a capture pattern, a
+strip flag, `re` flags and a label:
+
+```python
+from typing import Annotated
+
+from scanf import Converter, scanf
+
+parse = scanf[
+    Annotated[int, Converter(int, pattern=r"\d+", name="age")],
+    Annotated[str, Converter(str, pattern=r'"[^"]*"', name="name")],
+]("age={} name={}")
+parse('age=42 name="kim"')  # (42, '"kim"')
+```
+
+`typing.Annotated` wrappers around converters are stripped; their metadata is
+ignored unless it contains a `Converter` spec. Several specs on one field
+compete in declaration order: each branch carries its own pattern, the first
+branch whose pattern matches wins, and if its converter then fails the whole
+scan fails — a failing converter never falls back to a later branch.
+
+## Template semantics
+
+Each `{}` captures with the default `.+?` pattern:
+
+* non-empty: at least one character;
+* single-line: never matches a newline;
+* lazy: takes the shortest text that still lets the rest of the template match.
+
+A `Converter` spec can replace the pattern per field.
+
+Whitespace runs in the template match any whitespace run in the input, and
+surrounding whitespace of the input (and of each captured field) is ignored.
+Literal braces in a template are written `{{` and `}}`; a single brace is an
+error.
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pre-commit install             # optional: run the gates on every commit
+uv run pre-commit run --all-files     # full local gate
+```
+
+The gate runs ruff (lint + format), pyright (strict), interrogate (docstring
+coverage), pytest with a coverage floor, and an `example/` smoke run. CI
+(GitHub Actions) runs the same gates plus a 3-OS test matrix.
+
+`example/example.py` contains worked examples: field customization, JSON
+parsing and a recursive scanner built with fixpoint / `alt` / `sep_by`
+combinators.

infinity_pyscanf-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "infinity_pyscanf"
+version = "0.1.0"
+description = "Type-safe, scanf-style string parsing."
+readme = "README.md"
+keywords = [
+    "scanf",
+    "parsing",
+    "parser",
+    "regex",
+    "type-safe",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+dev = [
+    "interrogate",
+    "ruff",
+    "pyright",
+    "pre-commit",
+    "infinity_pyscanf[test]",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "RUF",
+    "SIM",
+    "UP",
+    "W",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["scanf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.interrogate]
+fail-under = 90
+ignore-init-method = true
+ignore-init-module = true
+ignore-magic = true
+ignore-private = true
+ignore-semiprivate = true
+ignore-nested-functions = true
+exclude = [
+    "tests",
+    "example",
+]
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "scanf"

infinity_pyscanf-0.1.0/pyproject.toml.orig

@@ -0,0 +1,83 @@
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[project]
+name = "infinity_pyscanf"
+version = "0.1.0"
+description = "Type-safe, scanf-style string parsing."
+readme = "README.md"
+keywords = [
+    "scanf",
+    "parsing",
+    "parser",
+    "regex",
+    "type-safe",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "pytest-cov",
+]
+dev = [
+    "interrogate",
+    "ruff",
+    "pyright",
+    "pre-commit",
+    "infinity_pyscanf[test]",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src"]
+
+[tool.ruff.lint]
+select = [
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "E",   # pycodestyle (errors)
+    "F",   # pyflakes
+    "I",   # isort
+    "RUF", # Ruff-specific rules
+    "SIM", # flake8-simplify
+    "UP",  # pyupgrade
+    "W",   # pycodestyle (warnings)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["scanf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.interrogate]
+fail-under = 90
+ignore-init-method = true
+ignore-init-module = true
+ignore-magic = true
+ignore-private = true
+ignore-semiprivate = true
+ignore-nested-functions = true
+exclude = ["tests", "example"]
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "scanf"

infinity_pyscanf-0.1.0/src/scanf/__init__.py

@@ -0,0 +1,5 @@
+"""Strictly typed, ``scanf``-style parsing for Python."""
+
+from scanf.scanf import Converter, ConvertError, MatchError, ScanError, scanf
+
+__all__ = ["ConvertError", "Converter", "MatchError", "ScanError", "scanf"]

infinity_pyscanf-0.1.0/src/scanf/engine.py

@@ -0,0 +1,301 @@
+"""Runtime engine for :mod:`scanf`: resolve field metas, then scan input.
+
+Two responsibilities, with no type-level semantics:
+
+* :func:`resolve_field` -- turn one field's meta (a bare declared converter
+  plus an optional :class:`Converter` spec) into a concrete converter configuration
+  (:class:`Field`);
+* :class:`Template` -- validate a configuration, compile the template regex
+  and ``scan`` input strings into tuples.
+"""
+
+import ast
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, get_origin
+
+# The default field pattern: non-empty, single-line (no DOTALL) and lazy.
+DEFAULT_PATTERN = r".+?"
+_PLACEHOLDER = "{}"
+_WHITESPACE = re.compile(r"\s+")
+
+
+class ScanError(ValueError):
+    """Base failure while scanning: a ``MatchError`` or a ``ConvertError``."""
+
+
+class MatchError(ScanError):
+    """Input did not match the template (a soft failure).
+
+    Ordered-choice combinators fall through to the next alternative on this
+    one. A branch that matched but failed to convert raises ``ConvertError``
+    instead, which aborts the choice so its diagnostics are never swallowed.
+    """
+
+
+class ConvertError(ScanError):
+    """A field matched but its converter failed (a hard failure).
+
+    The message carries the field number, the text and its offset; the
+    underlying error is chained through ``__cause__``.
+    """
+
+
+@dataclass(frozen=True)
+class Converter[T]:
+    """Per-field converter spec, passed as ``Annotated[T, Converter(...)]`` metadata.
+
+    ``fn`` converts the matched text; ``pattern`` is the regex used to capture
+    this field (inserted into the template regex as-is); ``strip`` strips the
+    matched text before conversion; ``name`` labels the field in error messages
+    (defaults to the callable's name); ``flags`` are ``re`` flags applied to
+    ``pattern``. Several specs on one field compete in declaration order: the
+    first branch whose pattern matches wins, and if its ``fn`` then raises, the
+    scan fails as a whole (no fallback to the remaining branches).
+    """
+
+    fn: Callable[[str], T]
+    pattern: str = DEFAULT_PATTERN
+    strip: bool = True
+    name: str | None = None
+    flags: int = 0
+
+
+@dataclass(frozen=True)
+class Field:
+    """One placeholder: converter branches competing in declaration order."""
+
+    converters: tuple[Converter[Any], ...]
+
+
+def _converter_name(converter: object) -> str | None:
+    """Return the display name of ``converter`` (used to label fields)."""
+    name = getattr(converter, "__name__", None)
+    if isinstance(name, str):
+        return name
+    origin = get_origin(converter)
+    if origin is not None:
+        name = getattr(origin, "__name__", None)
+        if isinstance(name, str):
+            return name
+    return None
+
+
+def _label(converter: Converter[Any]) -> str:
+    """Display name of one converter branch in error messages."""
+    return converter.name or _converter_name(converter.fn) or repr(converter.fn)
+
+
+def _literal_converter(origin: type[Any]) -> Callable[[str], Any]:
+    return lambda text: origin(ast.literal_eval(text))
+
+
+_BOOL_VALUES = {"true": True, "false": False, "1": True, "0": False}
+
+
+def _bool_converter(text: str) -> bool:
+    value = _BOOL_VALUES.get(text.casefold())
+    if value is None:
+        raise ValueError(f"cannot parse {text!r} as bool")
+    return value
+
+
+# Keyed by the origin *object* (not by name), so user classes that happen to be
+# named ``dict``, ``list``, ``bool``, ... never pick up a built-in default.
+_BUILTIN_CONVERTERS: dict[object, Callable[[str], Any]] = {
+    bool: _bool_converter,
+    dict: _literal_converter(dict),
+    frozenset: _literal_converter(frozenset),
+    list: _literal_converter(list),
+    set: _literal_converter(set),
+    tuple: _literal_converter(tuple),
+}
+
+
+def _default_converter(converter: object) -> Callable[[str], Any] | None:
+    """Return the built-in default converter for supported built-in types."""
+    origin = get_origin(converter)
+    return _BUILTIN_CONVERTERS.get(origin if origin is not None else converter)
+
+
+def resolve_field(declared: Any, convs: list[Converter[Any]]) -> Field:
+    """Resolve one field's meta into its converter branches (meta -> converters).
+
+    User-provided ``Converter`` specs become the branches, in order. Without
+    any, one branch is synthesized from the declared type: the built-in default
+    for supported containers, otherwise the declared type used as a callable.
+    """
+    if convs:
+        return Field(converters=tuple(convs))
+    branch: Converter[Any] = Converter(
+        fn=_default_converter(declared) or declared,
+        name=_converter_name(declared),
+    )
+    return Field(converters=(branch,))
+
+
+def _literal_to_pattern(text: str) -> str:
+    """Escape literal template text; whitespace runs become ``\\s+``."""
+    pieces: list[str] = []
+    position = 0
+    for match in _WHITESPACE.finditer(text):
+        pieces.append(re.escape(text[position : match.start()]))
+        pieces.append(r"\s+")
+        position = match.end()
+    pieces.append(re.escape(text[position:]))
+    return "".join(pieces)
+
+
+_INLINE_FLAGS: tuple[tuple[int, str], ...] = (
+    (re.IGNORECASE, "i"),
+    (re.MULTILINE, "m"),
+    (re.DOTALL, "s"),
+    (re.VERBOSE, "x"),
+    (re.ASCII, "a"),
+)
+_INLINE_FLAG_MASK = re.IGNORECASE | re.MULTILINE | re.DOTALL | re.VERBOSE | re.ASCII
+
+
+def _scoped(pattern: str, flags: int) -> str:
+    """Wrap ``pattern`` in scoped inline flags (e.g. ``(?i:...)``)."""
+    if not flags:
+        return pattern
+    if flags & ~_INLINE_FLAG_MASK:
+        raise ValueError(f"unsupported re flags for a field pattern: {flags:#x}")
+    letters = "".join(letter for bit, letter in _INLINE_FLAGS if flags & bit)
+    return f"(?{letters}:{pattern})"
+
+
+@lru_cache(maxsize=1024)
+def _segments(template: str) -> tuple[str | None, ...]:
+    """Split ``template`` into literal segments and ``None`` placeholders.
+
+    ``{{`` and ``}}`` escape literal braces; a single brace is an error.
+    """
+    segments: list[str | None] = []
+    literal: list[str] = []
+    text = template.strip()
+    position = 0
+    while position < len(text):
+        character = text[position]
+        if character == "{":
+            if text.startswith("{{", position):
+                literal.append("{")
+                position += 2
+            elif text.startswith(_PLACEHOLDER, position):
+                segments.append("".join(literal))
+                literal.clear()
+                segments.append(None)
+                position += 2
+            else:
+                raise ValueError(
+                    f"single '{{' in template {template!r}; escape literal "
+                    "braces as '{{' and '}}'"
+                )
+        elif character == "}":
+            if text.startswith("}}", position):
+                literal.append("}")
+                position += 2
+            else:
+                raise ValueError(
+                    f"single '}}' in template {template!r}; escape literal "
+                    "braces as '{{' and '}}'"
+                )
+        else:
+            literal.append(character)
+            position += 1
+    segments.append("".join(literal))
+    return tuple(segments)
+
+
+def _branch_group(index: int, branch: int) -> str:
+    """Regex group name capturing one branch's own match for a field."""
+    return f"s{index}b{branch}"
+
+
+def _field_chunk(index: int, field: Field) -> str:
+    """One field's regex: its converter branches as an ordered alternation."""
+    converters = field.converters
+    if len(converters) == 1:
+        single = converters[0]
+        return f"(?P<s{index}>{_scoped(single.pattern, single.flags)})"
+    branches = "|".join(
+        f"(?P<{_branch_group(index, branch)}>{_scoped(conv.pattern, conv.flags)})"
+        for branch, conv in enumerate(converters)
+    )
+    return f"(?P<s{index}>{branches})"
+
+
+@lru_cache(maxsize=1024)
+def _compile(template: str, fields: tuple[Field, ...]) -> re.Pattern[str]:
+    """Compile ``template`` into a regex with one named group per placeholder."""
+    chunks: list[str] = []
+    placeholder = 0
+    for segment in _segments(template):
+        if segment is None:
+            chunks.append(_field_chunk(placeholder, fields[placeholder]))
+            placeholder += 1
+        else:
+            chunks.append(_literal_to_pattern(segment))
+    return re.compile("".join(chunks))
+
+
+def _winner(match: re.Match[str], index: int, field: Field) -> int:
+    """Index of the branch whose pattern produced the field's match."""
+    if len(field.converters) == 1:
+        return 0
+    for branch, _ in enumerate(field.converters):
+        if match.group(_branch_group(index, branch)) is not None:
+            return branch
+    raise AssertionError(f"no converter branch matched field {index}")
+
+
+class Template:
+    """A validated, compiled template, ready to scan input."""
+
+    def __init__(self, template: str, fields: tuple[Field, ...]) -> None:
+        # Fail fast on converters that cannot go into the compile cache.
+        hash(fields)
+        for field in fields:
+            if not field.converters:
+                raise ValueError("each field requires at least one converter")
+            for converter in field.converters:
+                if not callable(converter.fn):
+                    raise TypeError(
+                        f"converters must be callable, got {converter.fn!r}"
+                    )
+        placeholders = sum(segment is None for segment in _segments(template))
+        if placeholders != len(fields):
+            raise ValueError(
+                f"template {template!r} has {placeholders} placeholder(s) "
+                f"but {len(fields)} converter type(s) were given"
+            )
+        self.template = template
+        self.fields = fields
+        self._pattern = _compile(template, fields)
+
+    def scan(self, input_value: str) -> tuple[Any, ...]:
+        """Scan ``input_value``: match the template and convert each field."""
+        match = self._pattern.fullmatch(input_value.strip())
+        if match is None:
+            raise MatchError(
+                f"input {input_value!r} does not match template {self.template!r}"
+            )
+        values: list[Any] = []
+        for index, field in enumerate(self.fields):
+            converter = field.converters[_winner(match, index, field)]
+            raw = match.group(f"s{index}")
+            text = raw.strip() if converter.strip else raw
+            try:
+                values.append(converter.fn(text))
+            except Exception as error:
+                # Report the offset within the original input, not the stripped one.
+                shift = len(input_value) - len(input_value.lstrip())
+                offset = shift + match.start(f"s{index}")
+                raise ConvertError(
+                    f"cannot convert field {index + 1} ({text!r}) at offset "
+                    f"{offset} using {_label(converter)}"
+                ) from error
+        return tuple(values)

infinity_pyscanf-0.1.0/src/scanf/scanf.py

@@ -0,0 +1,111 @@
+r"""Type-safe, ``scanf``-style string parsing.
+
+Supply one converter type per ``{}`` placeholder as class type arguments, then
+the template and the input string as call arguments::
+
+    from scanf import scanf
+
+    a, b, c = scanf[int, float, str]("{} {} {}")("1 2.5 hello")
+    # a=1 (int), b=2.5 (float), c="hello" (str)
+
+Parsers are reusable. Fields accept per-field ``Converter`` specs and built-in
+defaults (containers via ``ast.literal_eval``, ``bool`` literals); see the
+project README for the full guide -- usage, semantics and examples.
+"""
+
+import types
+from typing import Annotated, Any, cast, get_args, get_origin
+
+from scanf.engine import (
+    Converter,
+    ConvertError,
+    Field,
+    MatchError,
+    ScanError,
+    Template,
+    resolve_field,
+)
+
+__all__ = ["ConvertError", "Converter", "MatchError", "ScanError", "scanf"]
+
+
+def flatten_annotated(meta: Any) -> tuple[Any, list[Any]]:
+    """Flatten nested ``Annotated`` wrappers; metadata ordered deep to shallow
+    (which is also the order converter branches compete in)."""
+    if get_origin(meta) is not Annotated:
+        return meta, []
+    args = get_args(meta)
+    base, metadata = flatten_annotated(args[0])
+    return base, [*metadata, *args[1:]]
+
+
+def build_field(meta: Any) -> Field:
+    """Extract one declaration's Converter specs and resolve them via the engine."""
+    declared, metadata = flatten_annotated(meta)
+    converters: list[Converter[Any]] = [
+        cast(Converter[Any], item) for item in metadata if isinstance(item, Converter)
+    ]
+    return resolve_field(declared, converters)
+
+
+class scanf[*Meta]:
+    """Typed ``scanf``: ``scanf[Meta1, Meta2, ...](template)(input_value)``.
+
+    Each ``Meta`` declares one field -- a converter type, or
+    ``Annotated[converter, Converter(...)]`` for per-field configuration --
+    and determines the corresponding result element type. Several ``Converter``
+    specs on one field compete in order: the first matching branch wins. The
+    template and the input string are call arguments. Parsers are reusable.
+
+    The converter setup is validated eagerly when the parser is constructed:
+    non-callable converters and placeholder/converter-count mismatches raise
+    immediately.
+    """
+
+    _engine: Template
+
+    def __init__(self, template: str, _engine: Template | None = None) -> None:
+        # Parsers are built through ``scanf[...]`` (see _ScanfAlias), which
+        # passes the ready engine in; direct construction is a misuse.
+        if _engine is None:
+            raise TypeError(
+                "scanf requires at least one converter type, e.g. scanf[int]('{}')"
+            )
+        self._engine = _engine
+
+    @classmethod
+    def __class_getitem__(cls, item: Any) -> Any:
+        """Bind the field metas; see the class docstring.
+
+        Type checkers ignore this hook for generic classes and keep treating
+        ``scanf[int, float]`` as a specialization. At runtime it returns a
+        ``types.GenericAlias`` subclass carrying the metas; calling that alias
+        with the template is what validates and builds the parser.
+        """
+        metas = cast(tuple[Any, ...], item if isinstance(item, tuple) else (item,))
+        if not metas:
+            raise TypeError(
+                "scanf requires at least one converter type, e.g. scanf[int]('{}')"
+            )
+        return _ScanfAlias(cls, metas)
+
+    def __call__(self, input_value: str) -> tuple[*Meta]:
+        """Parse ``input_value``."""
+        return self._engine.scan(input_value)
+
+
+class _ScanfAlias(types.GenericAlias):
+    """Subclass of ``types.GenericAlias`` produced by ``scanf[...]``.
+
+    The field metas travel in the alias itself (``__args__``). Calling the
+    alias with the template is where both sides meet: it resolves each meta
+    into its converter, validates the configuration and constructs the parser,
+    setting ``__orig_class__`` the way typing would.
+    """
+
+    def __call__(self, template: str) -> Any:
+        origin = cast(Any, self.__origin__)
+        fields: tuple[Field, ...] = tuple(build_field(meta) for meta in self.__args__)
+        instance = origin(template, Template(template, fields))
+        instance.__orig_class__ = self
+        return instance