pyvocabulary 0.1.0__tar.gz

pyvocabulary-0.1.0/PKG-INFO

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: pyvocabulary
+Version: 0.1.0
+Summary: The shared core of composable, JSON-definable building blocks: named registries, JSON Schemas from signatures and JSON-path errors.
+Keywords: registry,vocabulary,json-schema,dsl,composition
+Author: aaltatan
+Author-email: aaltatan <a.altatan@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pyargprocessors>=0.1.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/aaltatan/pyvocabulary
+Project-URL: Repository, https://github.com/aaltatan/pyvocabulary
+Project-URL: Issues, https://github.com/aaltatan/pyvocabulary/issues
+Description-Content-Type: text/markdown
+
+# pyvocabulary
+
+The shared core of composable, JSON-definable building blocks, used by
+[pyspecification](https://github.com/aaltatan/pyspecification),
+[pyflowstep](https://github.com/aaltatan/pyflowstep) and
+[pyruleset](https://github.com/aaltatan/pyruleset).
+
+```python
+>>> from pyvocabulary import Vocabulary, call_json_schema, located
+>>> steps = Vocabulary[str]("step")
+>>> steps.add("click", "click()")
+'click()'
+>>> steps["fill"]
+Traceback (most recent call last):
+...
+pyvocabulary.exceptions.NameDoesNotExistError: Step 'fill' does not exist. Available steps: click
+```
+
+| Piece | What it does |
+| --- | --- |
+| `Vocabulary[F]` | Named entries, hidden entries, lookups with "Available ..." errors; packages inject their own error classes |
+| `validate_name` | ASCII identifier check for names used in JSON |
+| `bind_problem` | Classifies `Signature.bind` errors so each package raises its own `ArgumentError` subclass |
+| `json_schema_of`, `call_json_schema` | JSON Schema of a type annotation, and of a `{"name", "args", "kwargs"}` call from a signature |
+| `located`, `index_path`, `key_path` | Adds `at $.path` notes to errors, prefixing paths across nested compilers |
+
+Python 3.12+. Licensed GPL-3.0-only.

pyvocabulary-0.1.0/README.md

@@ -0,0 +1,27 @@
+# pyvocabulary
+
+The shared core of composable, JSON-definable building blocks, used by
+[pyspecification](https://github.com/aaltatan/pyspecification),
+[pyflowstep](https://github.com/aaltatan/pyflowstep) and
+[pyruleset](https://github.com/aaltatan/pyruleset).
+
+```python
+>>> from pyvocabulary import Vocabulary, call_json_schema, located
+>>> steps = Vocabulary[str]("step")
+>>> steps.add("click", "click()")
+'click()'
+>>> steps["fill"]
+Traceback (most recent call last):
+...
+pyvocabulary.exceptions.NameDoesNotExistError: Step 'fill' does not exist. Available steps: click
+```
+
+| Piece | What it does |
+| --- | --- |
+| `Vocabulary[F]` | Named entries, hidden entries, lookups with "Available ..." errors; packages inject their own error classes |
+| `validate_name` | ASCII identifier check for names used in JSON |
+| `bind_problem` | Classifies `Signature.bind` errors so each package raises its own `ArgumentError` subclass |
+| `json_schema_of`, `call_json_schema` | JSON Schema of a type annotation, and of a `{"name", "args", "kwargs"}` call from a signature |
+| `located`, `index_path`, `key_path` | Adds `at $.path` notes to errors, prefixing paths across nested compilers |
+
+Python 3.12+. Licensed GPL-3.0-only.

pyvocabulary-0.1.0/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "pyvocabulary"
+version = "0.1.0"
+description = "The shared core of composable, JSON-definable building blocks: named registries, JSON Schemas from signatures and JSON-path errors."
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.12"
+dependencies = ["pyargprocessors>=0.1.0"]
+keywords = [
+    "registry",
+    "vocabulary",
+    "json-schema",
+    "dsl",
+    "composition",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "aaltatan"
+email = "a.altatan@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/aaltatan/pyvocabulary"
+Repository = "https://github.com/aaltatan/pyvocabulary"
+Issues = "https://github.com/aaltatan/pyvocabulary/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "src",
+]
+pythonpath = ["."]
+addopts = [
+    "--doctest-modules",
+    "--strict-markers",
+]
+doctest_optionflags = [
+    "ELLIPSIS",
+    "NORMALIZE_WHITESPACE",
+]
+
+[tool.coverage.run]
+source = ["pyvocabulary"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+    "@overload",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "CPY001",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D107",
+    "D203",
+    "D213",
+    "ANN401",
+    "PLR0911",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "ANN",
+    "ARG",
+    "INP001",
+    "E501",
+]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"

pyvocabulary-0.1.0/pyproject.toml.orig

@@ -0,0 +1,75 @@
+[project]
+name = "pyvocabulary"
+version = "0.1.0"
+description = "The shared core of composable, JSON-definable building blocks: named registries, JSON Schemas from signatures and JSON-path errors."
+readme = "README.md"
+authors = [
+    { name = "aaltatan", email = "a.altatan@gmail.com" }
+]
+license = "GPL-3.0-only"
+requires-python = ">=3.12"
+dependencies = [
+    "pyargprocessors>=0.1.0",
+]
+keywords = ["registry", "vocabulary", "json-schema", "dsl", "composition"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/aaltatan/pyvocabulary"
+Repository = "https://github.com/aaltatan/pyvocabulary"
+Issues = "https://github.com/aaltatan/pyvocabulary/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+pythonpath = ["."]
+addopts = ["--doctest-modules", "--strict-markers"]
+doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
+
+[tool.coverage.run]
+source = ["pyvocabulary"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ["@overload", "if TYPE_CHECKING:"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # conflicts with the formatter
+    "CPY001",  # no per-file copyright headers
+    "D100", "D101", "D102", "D103", "D104", "D105", "D107", "D203", "D213",
+    "ANN401",  # JSON values and registry entries genuinely are `Any`
+    "PLR0911",  # guard-clause style dispatch returns early on purpose
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004", "ANN", "ARG", "INP001", "E501"]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"

pyvocabulary-0.1.0/src/pyvocabulary/__init__.py

@@ -0,0 +1,35 @@
+"""pyvocabulary: the shared core of composable, JSON-definable building blocks.
+
+Used by pyspecification, pyflowstep and pyruleset for the parts every such
+package needs: a registry of named entries, JSON Schemas generated from
+signatures, errors that point at a JSON path, and early argument checks.
+"""
+
+from .arguments import BindProblem, bind_problem
+from .exceptions import (
+    InvalidNameError,
+    NameAlreadyRegisteredError,
+    NameDoesNotExistError,
+    PyvocabularyError,
+)
+from .json_schema import JSON_SCHEMA_DIALECT, call_json_schema, json_schema_of
+from .names import validate_name
+from .paths import index_path, key_path, located
+from .vocabulary import Vocabulary
+
+__all__ = [
+    "JSON_SCHEMA_DIALECT",
+    "BindProblem",
+    "InvalidNameError",
+    "NameAlreadyRegisteredError",
+    "NameDoesNotExistError",
+    "PyvocabularyError",
+    "Vocabulary",
+    "bind_problem",
+    "call_json_schema",
+    "index_path",
+    "json_schema_of",
+    "key_path",
+    "located",
+    "validate_name",
+]

pyvocabulary-0.1.0/src/pyvocabulary/arguments.py

@@ -0,0 +1,43 @@
+"""Classify the `TypeError` raised by `inspect.Signature.bind`.
+
+Building blocks bind their arguments when they are built, so a wrong argument
+fails early. Each package maps the problem to its own exception class.
+"""
+
+import re
+from typing import Literal
+
+type BindProblem = Literal[
+    "positional_only",
+    "missing",
+    "too_many",
+    "unexpected_keyword",
+    "multiple_values",
+]
+
+_PATTERNS: tuple[tuple[str, BindProblem], ...] = (
+    (r"positional.only.*passed as (a )?keyword", "positional_only"),
+    (r"missing a required", "missing"),
+    (r"too many positional arguments", "too_many"),
+    (r"got an unexpected keyword argument", "unexpected_keyword"),
+    (r"multiple values for argument", "multiple_values"),
+)
+
+
+def bind_problem(error: TypeError, /) -> BindProblem | None:
+    """Return what went wrong in a failed `Signature.bind`, or `None` if unknown.
+
+    Example:
+    ```python
+    >>> bind_problem(TypeError("too many positional arguments"))
+    'too_many'
+    >>> bind_problem(TypeError("missing a required argument: 'value'"))
+    'missing'
+    >>> bind_problem(TypeError("something else")) is None
+    True
+
+    ```
+
+    """
+    message = str(error)
+    return next((problem for pattern, problem in _PATTERNS if re.search(pattern, message)), None)

pyvocabulary-0.1.0/src/pyvocabulary/exceptions.py

@@ -0,0 +1,48 @@
+"""Exceptions raised by pyvocabulary.
+
+Packages built on pyvocabulary usually inject their own error classes into a
+`Vocabulary` (e.g. `RuleDoesNotExistError`), so these defaults are what callers
+see only when nothing is injected.
+"""
+
+from collections.abc import Iterable
+
+
+class PyvocabularyError(Exception):
+    """Base class for every exception raised by pyvocabulary."""
+
+
+class NameDoesNotExistError(PyvocabularyError, LookupError):
+    """Raised when a name is not in a vocabulary.
+
+    Example:
+    ```python
+    >>> str(NameDoesNotExistError("stepz", ["click", "fill"], kind="step"))
+    "Step 'stepz' does not exist. Available steps: click, fill"
+
+    ```
+
+    """
+
+    def __init__(self, name: str, available: Iterable[str], /, *, kind: str = "name") -> None:
+        names = ", ".join(available) or "(none)"
+        super().__init__(f"{kind.capitalize()} '{name}' does not exist. Available {kind}s: {names}")
+
+
+class NameAlreadyRegisteredError(PyvocabularyError):
+    """Raised when a name is registered twice in the same vocabulary."""
+
+    def __init__(self, name: str, /, *, kind: str = "name") -> None:
+        super().__init__(f"{kind.capitalize()} '{name}' is already registered.")
+
+
+class InvalidNameError(PyvocabularyError, ValueError):
+    """Raised when a name is not a valid ASCII Python identifier."""
+
+    def __init__(self, name: object, /, *, kind: str = "name") -> None:
+        label = "name" if kind == "name" else f"{kind} name"
+        super().__init__(
+            f"Invalid {label}: {name!r}, "
+            "you should follow the python variable naming convention: "
+            "name must start with a letter and can only contain letters, numbers and underscores"
+        )

pyvocabulary-0.1.0/src/pyvocabulary/json_schema.py

@@ -0,0 +1,242 @@
+"""Generate JSON Schemas from Python type annotations and building-block signatures.
+
+A building block (a rule, a step, a formula variable) is called from JSON as
+`{"name": ..., "args": [...], "kwargs": {...}}`. Its signature already says what
+those may contain, so the schema is derived from it instead of written by hand.
+"""
+
+from collections.abc import Callable, Mapping
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+from inspect import Parameter, get_annotations, signature
+from types import NoneType, UnionType
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    NotRequired,
+    Required,
+    TypeAliasType,
+    Union,
+    get_args,
+    get_origin,
+    is_typeddict,
+)
+from uuid import UUID
+
+from pyargprocessors import Process, annotated_metadata, input_annotation, resolved_annotations
+
+JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+_SCALAR_SCHEMAS: dict[Any, dict[str, Any]] = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    Decimal: {"type": "number"},
+    bool: {"type": "boolean"},
+    None: {"type": "null"},
+    NoneType: {"type": "null"},
+    datetime: {"type": "string", "format": "date-time"},
+    date: {"type": "string", "format": "date"},
+    time: {"type": "string", "format": "time"},
+    UUID: {"type": "string", "format": "uuid"},
+}
+
+_ARRAY_TYPES = (list, tuple, set, frozenset)
+_WRAPPER_ORIGINS = (Annotated, Required, NotRequired)
+_POSITIONAL_KINDS = (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
+_KEYWORD_KINDS = (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY)
+
+
+def json_schema_of(annotation: Any) -> dict[str, Any]:
+    """Return the JSON Schema of a Python type annotation.
+
+    Unknown or unannotated types map to `{}`, which accepts any value. A type
+    marked with `Process(fn)` is described by what `fn` accepts, because that is
+    what the JSON has to send.
+
+    Example:
+    ```python
+    >>> json_schema_of(int)
+    {'type': 'integer'}
+    >>> json_schema_of(list[str])
+    {'type': 'array', 'items': {'type': 'string'}}
+    >>> json_schema_of(Literal["active", "pending"])
+    {'enum': ['active', 'pending'], 'type': 'string'}
+    >>> json_schema_of(int | None)
+    {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}
+
+    ```
+
+    """
+    origin = get_origin(annotation)
+
+    if is_typeddict(annotation):
+        return _typeddict_schema(annotation)
+
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return _enum_schema([member.value for member in annotation])
+
+    if isinstance(annotation, TypeAliasType):
+        return json_schema_of(annotation.__value__)
+
+    if origin in _WRAPPER_ORIGINS:
+        return json_schema_of(_sent_annotation(annotation))
+
+    if origin is Literal:
+        return _enum_schema(list(get_args(annotation)))
+
+    if origin in (Union, UnionType):
+        return {"anyOf": [json_schema_of(arg) for arg in get_args(annotation)]}
+
+    if (origin or annotation) in _ARRAY_TYPES:
+        return _array_schema(get_args(annotation))
+
+    if (origin or annotation) is dict:
+        return _dict_schema(get_args(annotation))
+
+    return dict(_SCALAR_SCHEMAS.get(annotation, {}))
+
+
+def call_json_schema(
+    name: str,
+    factory: Callable[..., Any],
+    /,
+    *,
+    extra_properties: Mapping[str, dict[str, Any]] | None = None,
+    required: tuple[str, ...] = ("name",),
+) -> dict[str, Any]:
+    """Return the JSON Schema of one call: `{"name": ..., "args": [...], "kwargs": {...}}`.
+
+    `factory` is a building-block factory whose signature excludes the subject.
+    Positional parameters are described under `args` (via `prefixItems`),
+    keyword-capable ones under `kwargs`, and the docstring becomes the description.
+
+    Args:
+        name: The registered name, fixed with `const`.
+        factory: The factory whose signature describes the arguments.
+        extra_properties: More keys a package adds to its call shape,
+            e.g. `{"inverse": {"type": "boolean"}}` for rules.
+        required: The keys that must be present.
+
+    Example:
+    ```python
+    >>> def age__between(min_age: int, max_age: int = 120) -> bool:
+    ...     '''Whether the age is within a range.'''
+    ...     return True
+    >>> schema = call_json_schema("age__between", age__between)
+    >>> schema["properties"]["name"]
+    {'const': 'age__between'}
+    >>> schema["properties"]["args"]["prefixItems"]
+    [{'type': 'integer'}, {'type': 'integer', 'default': 120}]
+    >>> schema["description"], schema["required"]
+    ('Whether the age is within a range.', ['name'])
+
+    ```
+
+    """
+    parameters = list(signature(factory).parameters.values())
+    annotations = resolved_annotations(factory)
+
+    def parameter_schema(parameter: Parameter) -> dict[str, Any]:
+        schema = json_schema_of(annotations.get(parameter.name, Any))
+        if parameter.default is not Parameter.empty and _is_json_value(parameter.default):
+            schema["default"] = parameter.default
+        return schema
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "name": {"const": name},
+            "args": _args_schema(parameters, parameter_schema),
+            "kwargs": _kwargs_schema(parameters, parameter_schema),
+            **(extra_properties or {}),
+        },
+        "required": list(required),
+        "additionalProperties": False,
+    }
+
+    if factory.__doc__:
+        schema["description"] = factory.__doc__.strip()
+
+    return schema
+
+
+# -----------------------
+# helpers
+# -----------------------
+
+
+def _args_schema(
+    parameters: list[Parameter],
+    parameter_schema: Callable[[Parameter], dict[str, Any]],
+) -> dict[str, Any]:
+    positional = [parameter for parameter in parameters if parameter.kind in _POSITIONAL_KINDS]
+    var_positional = next(
+        (parameter for parameter in parameters if parameter.kind is Parameter.VAR_POSITIONAL),
+        None,
+    )
+    return {
+        "type": "array",
+        "prefixItems": [parameter_schema(parameter) for parameter in positional],
+        "items": parameter_schema(var_positional) if var_positional else False,
+    }
+
+
+def _kwargs_schema(
+    parameters: list[Parameter],
+    parameter_schema: Callable[[Parameter], dict[str, Any]],
+) -> dict[str, Any]:
+    keyword = [parameter for parameter in parameters if parameter.kind in _KEYWORD_KINDS]
+    var_keyword = next(
+        (parameter for parameter in parameters if parameter.kind is Parameter.VAR_KEYWORD),
+        None,
+    )
+    return {
+        "type": "object",
+        "properties": {parameter.name: parameter_schema(parameter) for parameter in keyword},
+        "required": [
+            parameter.name
+            for parameter in keyword
+            if parameter.kind is Parameter.KEYWORD_ONLY and parameter.default is Parameter.empty
+        ],
+        "additionalProperties": parameter_schema(var_keyword) if var_keyword else False,
+    }
+
+
+def _enum_schema(values: list[Any]) -> dict[str, Any]:
+    schema: dict[str, Any] = {"enum": values}
+    if values and all(isinstance(value, str) for value in values):
+        schema["type"] = "string"
+    return schema
+
+
+def _array_schema(args: tuple[Any, ...]) -> dict[str, Any]:
+    return {"type": "array", "items": json_schema_of(args[0]) if args else {}}
+
+
+def _dict_schema(args: tuple[Any, ...]) -> dict[str, Any]:
+    return {"type": "object", "additionalProperties": json_schema_of(args[1]) if args else {}}
+
+
+def _typeddict_schema(annotation: Any) -> dict[str, Any]:
+    annotations = get_annotations(annotation)
+    return {
+        "type": "object",
+        "properties": {name: json_schema_of(typ) for name, typ in annotations.items()},
+        "required": [name for name in annotations if name in annotation.__required_keys__],
+    }
+
+
+def _sent_annotation(annotation: Any) -> Any:
+    """Return the type the JSON must send for an `Annotated`/`Required`/`NotRequired` type."""
+    processor = next(
+        (item for item in annotated_metadata(annotation) if isinstance(item, Process)), None
+    )
+    sent = input_annotation(processor) if processor else None
+    return get_args(annotation)[0] if sent is None else sent
+
+
+def _is_json_value(value: Any) -> bool:
+    return value is None or isinstance(value, str | int | float | bool | list | dict)

pyvocabulary-0.1.0/src/pyvocabulary/names.py

@@ -0,0 +1,51 @@
+"""Validate the names of building blocks.
+
+A name ends up in JSON definitions, error messages and reprs, so it is kept to
+an ASCII Python identifier: `age__between`, `add_milk`.
+"""
+
+import re
+from collections.abc import Callable
+
+from .exceptions import InvalidNameError
+
+type InvalidNameErrorFactory = Callable[[object], Exception]
+
+# `fullmatch`, not `match` with `$`: `$` also matches before a trailing newline
+_IDENTIFIER = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*")
+
+
+def validate_name(
+    name: object,
+    /,
+    *,
+    kind: str = "name",
+    error: InvalidNameErrorFactory | None = None,
+) -> str:
+    """Return `name` unchanged if it is a valid ASCII Python identifier.
+
+    Args:
+        name: The candidate name.
+        kind: What is being named, used in the default error message.
+        error: Builds the exception to raise for an invalid name. Defaults to
+            `InvalidNameError`, which is also a `ValueError`.
+
+    Raises:
+        InvalidNameError: If `name` is invalid and no `error` factory is given.
+
+    Example:
+    ```python
+    >>> validate_name("add_milk")
+    'add_milk'
+    >>> validate_name("add-milk", kind="step")
+    Traceback (most recent call last):
+    ...
+    pyvocabulary.exceptions.InvalidNameError: Invalid step name: 'add-milk', ...
+
+    ```
+
+    """
+    if isinstance(name, str) and _IDENTIFIER.fullmatch(name):
+        return name
+
+    raise (error or (lambda value: InvalidNameError(value, kind=kind)))(name)

pyvocabulary-0.1.0/src/pyvocabulary/paths.py

@@ -0,0 +1,74 @@
+"""Point errors at the part of a JSON definition that caused them.
+
+Compilers walk nested definitions; an error deep inside should say where it
+happened, e.g. `at $.expressions[1]`. The location is added as an exception
+note, so the original message and type stay unchanged.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+def index_path(path: str, index: int, /) -> str:
+    """Return the JSON path of an item in a list.
+
+    Example:
+    ```python
+    >>> index_path("$.branches", 2)
+    '$.branches[2]'
+
+    ```
+
+    """
+    return f"{path}[{index}]"
+
+
+def key_path(path: str, key: str, /) -> str:
+    """Return the JSON path of a key in an object.
+
+    Example:
+    ```python
+    >>> key_path(index_path("$.branches", 0), "when")
+    '$.branches[0].when'
+
+    ```
+
+    """
+    return f"{path}.{key}"
+
+
+@contextmanager
+def located(path: str, /, *errors: type[Exception]) -> Iterator[None]:
+    """Add an `at <path>` note to errors of the given types raised inside the block.
+
+    Paths nest: when the error already carries a location from an inner block,
+    or from another compiler that reports paths relative to its own root (`$`),
+    the outer path is prefixed to it. So a rule compiled inside a decision
+    reports its full path in the outer document.
+
+    Example:
+    ```python
+    >>> try:
+    ...     with located("$.branches[1].when", KeyError):
+    ...         with located("$.expressions[0]", KeyError):
+    ...             raise KeyError("itemz__ge")
+    ... except KeyError as error:
+    ...     error.__notes__
+    ['at $.branches[1].when.expressions[0]']
+
+    ```
+
+    """
+    try:
+        yield
+    except errors as error:
+        notes = getattr(error, "__notes__", [])
+        index = next((i for i, note in enumerate(notes) if note.startswith(_PREFIX)), None)
+        if index is None:
+            error.add_note(f"at {path}")
+        else:
+            notes[index] = f"at {path}{notes[index].removeprefix(_PREFIX)}"
+        raise
+
+
+_PREFIX = "at $"

pyvocabulary-0.1.0/src/pyvocabulary/vocabulary.py

@@ -0,0 +1,133 @@
+"""A vocabulary: the named building blocks a JSON-definable language understands.
+
+A rules registry, a steps registry and a formulas registry are all the same
+thing underneath: names mapped to entries, some of them hidden from lookups.
+`Vocabulary` is that shared part. Packages keep their own decorators on top.
+"""
+
+from collections.abc import Callable, Iterable, Iterator, Mapping
+
+from .exceptions import NameAlreadyRegisteredError, NameDoesNotExistError
+from .names import InvalidNameErrorFactory, validate_name
+
+type DoesNotExistErrorFactory = Callable[[str, Iterable[str]], Exception]
+type AlreadyRegisteredErrorFactory = Callable[[str], Exception]
+
+
+class Vocabulary[F](Mapping[str, F]):
+    """A read-only mapping of visible names to entries, filled with `add`.
+
+    Hidden entries are kept, so a name cannot be reused, but they are left out of
+    lookups, iteration and length. That keeps them out of compilers and JSON
+    Schemas while the objects stay usable from Python.
+
+    Args:
+        kind: What the entries are ("rule", "step"), used in default error messages.
+        does_not_exist: Builds the error for an unknown name from the name and
+            the visible names. Defaults to `NameDoesNotExistError`.
+        already_registered: Builds the error for a duplicate name. Defaults to
+            `NameAlreadyRegisteredError`.
+        invalid_name: Builds the error for a name that is not an identifier.
+            Defaults to `InvalidNameError`.
+
+    Example:
+    ```python
+    >>> steps = Vocabulary[str]("step")
+    >>> steps.add("click", "click()")
+    'click()'
+    >>> steps.add("debug", "debug()", hidden=True)
+    'debug()'
+    >>> list(steps), "debug" in steps, len(steps)
+    (['click'], False, 1)
+    >>> steps["fill"]
+    Traceback (most recent call last):
+    ...
+    pyvocabulary.exceptions.NameDoesNotExistError: Step 'fill' does not exist. ...
+
+    ```
+
+    """
+
+    __slots__ = (
+        "_already_registered",
+        "_does_not_exist",
+        "_entries",
+        "_hidden",
+        "_invalid_name",
+        "_kind",
+    )
+
+    def __init__(
+        self,
+        kind: str = "name",
+        /,
+        *,
+        does_not_exist: DoesNotExistErrorFactory | None = None,
+        already_registered: AlreadyRegisteredErrorFactory | None = None,
+        invalid_name: InvalidNameErrorFactory | None = None,
+    ) -> None:
+        self._kind = kind
+        self._entries: dict[str, F] = {}
+        self._hidden: set[str] = set()
+        self._does_not_exist = does_not_exist or (
+            lambda name, available: NameDoesNotExistError(name, available, kind=kind)
+        )
+        self._already_registered = already_registered or (
+            lambda name: NameAlreadyRegisteredError(name, kind=kind)
+        )
+        self._invalid_name = invalid_name
+
+    def add(self, name: str, entry: F, /, *, hidden: bool = False) -> F:
+        """Register `entry` under `name` and return the entry.
+
+        Raises:
+            InvalidNameError: If `name` is not a valid identifier (or the injected error).
+            NameAlreadyRegisteredError: If `name` is taken, hidden or not (or the injected error).
+
+        """
+        validate_name(name, kind=self._kind, error=self._invalid_name)
+
+        if name in self._entries:
+            raise self._already_registered(name)
+
+        self._entries[name] = entry
+        if hidden:
+            self._hidden.add(name)
+
+        return entry
+
+    def is_registered(self, name: str, /) -> bool:
+        """Whether `name` is taken, including hidden entries.
+
+        Example:
+        ```python
+        >>> vocabulary = Vocabulary[int]()
+        >>> _ = vocabulary.add("secret", 1, hidden=True)
+        >>> vocabulary.is_registered("secret"), "secret" in vocabulary
+        (True, False)
+
+        ```
+
+        """
+        return name in self._entries
+
+    def __getitem__(self, name: str, /) -> F:
+        if name not in self:
+            raise self._does_not_exist(name, list(self))
+        return self._entries[name]
+
+    def get(self, name: str, default: F | None = None, /) -> F | None:  # type: ignore[override]
+        # `Mapping.get` only catches `KeyError`; injected errors may be any `LookupError`.
+        return self._entries[name] if name in self else default
+
+    def __contains__(self, name: object, /) -> bool:
+        return name in self._entries and name not in self._hidden
+
+    def __iter__(self) -> Iterator[str]:
+        return (name for name in self._entries if name not in self._hidden)
+
+    def __len__(self) -> int:
+        return len(self._entries) - len(self._hidden)
+
+    def __repr__(self) -> str:
+        return f"Vocabulary[{self._kind}]({', '.join(self)})"