pyspecification 3.0.0__tar.gz → 4.0.0__tar.gz

{pyspecification-3.0.0 → pyspecification-4.0.0}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.3
 Name: pyspecification
-Version: 3.0.0
+Version: 4.0.0
 Summary: A lightweight, typed Python library for composing business rules as reusable, executable predicates.
 Author: aaltatan
 Author-email: aaltatan <a.altatan@gmail.com>
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
+Requires-Dist: pyargprocessors>=0.1.0
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/aaltatan/pyspecification
 Project-URL: Issues, https://github.com/aaltatan/pyspecification/issues
@@ -65,7 +66,8 @@ This keeps your logic:
 - Subscriptable rules for dictionaries, lists, and generic lookup-based data
 - `Predicate` objects that support logical composition
 - Registry pattern for rule registration and lookup
-- Custom argument processors for coercion and normalization, validated when a rule is registered
+- `Process` markers (from [pyargprocessors](https://github.com/aaltatan/pyargprocessors)) that coerce and normalize raw arguments, such as strings from JSON or forms, into the objects a rule wants
+- Argument mistakes and failing processors reported while a rule is built, before anything is evaluated
 - `PredicateCompiler` for compiling structured rule dictionaries into executable predicates
 - JSON schema generation for single rules and for whole compilable expressions
 - Support for both logical and bitwise operator modes
@@ -488,24 +490,30 @@ This pattern is especially useful when you want:
 
 ---
 
-## Custom processors
+## Processing arguments with `Process`
 
-Rules can apply argument processors to coerce values before evaluation. This is
-most useful when rules come from JSON, where every value is a string, number,
-boolean, list, dict or null, and your rule functions expect richer types such as
-dates or decimals.
+Rules often come from JSON or a web form, where every value is a string, number,
+boolean, list, dict or null, while your rule functions want dates, decimals,
+enums, clean text or loaded data. Mark a parameter with `Process(fn)` inside
+`Annotated`, and `fn` is applied to the value when the rule is built. The marker
+comes from [pyargprocessors](https://github.com/aaltatan/pyargprocessors), a
+dependency of this package, and is re-exported here:
 
 ```python
 from datetime import datetime
+from typing import Annotated
 
-from pyspecification import SubscriptableRulesRegistry
-
+from pyspecification import Process, SubscriptableRulesRegistry
 
 rules = SubscriptableRulesRegistry[dict[str, object], str, bool](operator="logical")
 
 
-@rules.rule(processors={"value": lambda value: datetime.strptime(value, "%Y-%m-%d")})
-def datetime__gt(obj: dict[str, object], key: str, value: datetime) -> bool:
+def parse_date(text: str) -> datetime:
+    return datetime.strptime(text, "%Y-%m-%d")
+
+
+@rules.rule()
+def datetime__gt(obj: dict[str, object], key: str, value: Annotated[datetime, Process(parse_date)]) -> bool:
     return obj[key] > value
 
 
@@ -513,45 +521,72 @@ predicate = rules["datetime__gt"]("birthdate", "2001-06-01")
 print(predicate({"birthdate": datetime(2005, 1, 1)}))  # True
 ```
 
-The `processors` option accepts:
-
-- `None` (the default): arguments are passed through untouched.
-- a callable: applied to every argument, e.g. `processors=int`.
-- a mapping of parameter name to callable: applied to those arguments only,
-  e.g. `processors={"min_age": int}`. The key `...` (Ellipsis) means "every
-  argument not named here", e.g. `processors={"min_age": int, ...: str.strip}`.
-
-Processors are matched by parameter name, so they apply whether a value was
-passed positionally or by keyword. For `*args` the processor runs on each item,
-and for `**kwargs` each extra keyword name is looked up individually. Default
-values you did not pass are left as they are.
-
-The object under test and, for subscriptable rules, the `key` are not
-arguments: they are never processed and cannot be named in the mapping.
-
-Processors are validated when the rule is registered, so a typo fails
-immediately instead of silently never running:
-
-```python
-@rules.rule(processors={"valu": str})  # InvalidProcessorsError: unknown parameters ['valu']
-def string__eq(obj: dict[str, object], key: str, value: str) -> bool: ...
-```
-
-`InvalidProcessorsError` is raised when the option is not a callable or a
-mapping, when a mapping value is not callable, or when a key names no parameter
-of the rule (rules that accept `**kwargs` allow any key).
+`Process` works on `object_rule` and `subscriptable_rule` directly as well as
+through the registries. A few things worth knowing:
+
+- Name a processed type once with a `type` alias and reuse it in many rules, and
+  chain several markers (they run left to right):
+
+  ```python
+  type Text = Annotated[str, Process(str.strip), Process(str.lower)]
+  type Money = Annotated[Decimal, Process(Decimal)]
+  ```
+
+- A marker applies whether the value was passed positionally or by keyword. On
+  `*args` it runs on each item, and on `**kwargs` on each value.
+- Processing happens once, when the rule is built, so a bad value fails before the
+  predicate ever runs. Default values you did not pass are never processed.
+- The processor may take a different input than the rule: `Annotated[frozenset[str],
+  Process(load_names)]` lets the JSON send a file path while the rule receives the
+  loaded names. The JSON schema describes what the JSON must send (the processor's
+  first parameter annotation), see below.
+- The object under test and, for subscriptable rules, the key are not
+  arguments: a marker on them raises `InvalidProcessorError`.
+- `pyargprocessors` also provides `each` and `optional` to build a processor out
+  of another one (lists, nulls) and `process_value` to apply a processed type to
+  a single value; see its documentation.
 
 If a processor raises, the library raises `ProcessArgumentError` naming the
-parameter and value, with the original exception chained:
+argument and value, with the original exception chained. It also carries
+`argument`, `value` and `cause` attributes:
 
 ```text
 Argument 'value' with value '06-01-2001' failed to process, time data '06-01-2001' does not match format '%Y-%m-%d'
 ```
 
-> **Upgrading from 2.x:** processors used to be a `(default_processor,
-> named_processors_map)` tuple. Pass a callable instead of the tuple for the
-> old "process everything" behavior, or a mapping for named parameters. The
-> old tuple form is now rejected with `InvalidProcessorsError`.
+`InvalidProcessorError` (a `TypeError`) is raised as soon as the rule is defined
+when a `Process` is not callable, is placed on the object under test or the key,
+or is written as a default value instead of inside `Annotated`.
+
+### Argument errors
+
+Arguments are bound to the rule signature as soon as the rule is called, so
+mistakes surface while a predicate is being built (including by
+`PredicateCompiler.compile`), not when it is evaluated. They are reported in the
+order Python reports them for a call: keywords that cannot be passed by name,
+surplus or repeated arguments, then missing ones.
+
+| Mistake | Exception |
+| --- | --- |
+| a required argument is missing | `MissingArgumentError` |
+| too many positional arguments | `TooManyArgumentsError` |
+| a keyword the rule does not declare | `UnexpectedKeywordArgumentError` |
+| a value given both positionally and by keyword | `MultipleValuesArgumentError` |
+| a positional-only parameter passed by keyword | `PositionalOnlyArgumentError` |
+
+A `TypeError` raised from inside your rule function is yours and is never
+reclassified. A function that does not accept the object under test (and, for
+subscriptable rules, the key) positionally raises `InvalidRuleError`.
+
+> **Upgrading from 3.x:** the `processors=` option of `rule()` and
+> `register_rule()` is gone. Replace `processors=int` by annotating the
+> parameters (`value: Annotated[int, Process(int)]`), and a mapping such as
+> `processors={"age": int}` by marking just `age`. `ProcessArgumentError` and
+> `InvalidProcessorError` now come from pyargprocessors (re-exported by this
+> package) and derive from its `PyargprocessorsError` instead of
+> `PySpecificationError`. Argument errors are raised when a rule is built instead of when its predicate is
+> called, and a keyword-passed positional-only parameter (such as `key=` for a
+> rule declared `key, value, /`) is now a `PositionalOnlyArgumentError`.
 
 ---
 
@@ -817,6 +852,11 @@ first member only. String annotations are evaluated when possible, and fall back
 to `{}` when they cannot be resolved. Defaults are included when they are plain
 JSON values.
 
+A parameter marked with `Process` is described by what its processor accepts, since
+that is what the JSON has to send: with `Annotated[frozenset[str], Process(load_names)]`
+and `def load_names(path: str)`, the schema says `string`. A processor without a
+parameter annotation (such as `int` or `str.strip`) falls back to the annotated type.
+
 > **Upgrading from 2.x:** `get_rule_json_schema(rule)` used to return a flat
 > `{parameter: schema, "return": schema}` mapping. It now takes the rule name
 > too and returns the predicate dictionary schema shown above. `get_json_schema`
@@ -1009,8 +1049,11 @@ The library raises explicit exceptions for rule issues:
 - `MissingArgumentError`
 - `UnexpectedKeywordArgumentError`
 - `TooManyArgumentsError`
+- `MultipleValuesArgumentError`
+- `PositionalOnlyArgumentError`
+- `InvalidRuleError`
 - `ProcessArgumentError`
-- `InvalidProcessorsError`
+- `InvalidProcessorError`
 
 `ArgumentError` is the base class for failures involving arguments passed to a
 rule. Its specialized exceptions describe the problem:
@@ -1021,11 +1064,22 @@ rule. Its specialized exceptions describe the problem:
     rule's signature.
 - `TooManyArgumentsError` means more positional arguments were provided than
     the rule accepts.
-- `ProcessArgumentError` means an argument processor could not convert or
-    otherwise process a value.
-
-`InvalidProcessorsError` (a `TypeError`) is raised at registration when the
-`processors` option is malformed or names a parameter the rule does not have.
+- `MultipleValuesArgumentError` means a value was given both positionally and
+    by keyword.
+- `PositionalOnlyArgumentError` means a positional-only parameter was passed by
+    keyword.
+- `ProcessArgumentError` means a `Process` function could not convert a value.
+
+`InvalidProcessorError` and `InvalidRuleError` (both `TypeError`s) are raised when
+a rule is defined: a misplaced or non-callable `Process`, or a function that does
+not accept the object under test (and key) positionally.
+
+Every exception of this package derives from `PySpecificationError`, except
+`ProcessArgumentError` and `InvalidProcessorError`: they come from
+[pyargprocessors](https://github.com/aaltatan/pyargprocessors), derive from its
+`PyargprocessorsError`, and are re-exported here. Exceptions raised while
+compiling, including those two, carry a note with the JSON path of the offending
+expression, e.g. `at $.expressions[1]`.
 
 `RuleDoesNotExistError` includes the missing name and the available rule names,
 which is useful when rules are dynamically loaded. Malformed normalized

{pyspecification-3.0.0 → pyspecification-4.0.0}/README.md

@@ -51,7 +51,8 @@ This keeps your logic:
 - Subscriptable rules for dictionaries, lists, and generic lookup-based data
 - `Predicate` objects that support logical composition
 - Registry pattern for rule registration and lookup
-- Custom argument processors for coercion and normalization, validated when a rule is registered
+- `Process` markers (from [pyargprocessors](https://github.com/aaltatan/pyargprocessors)) that coerce and normalize raw arguments, such as strings from JSON or forms, into the objects a rule wants
+- Argument mistakes and failing processors reported while a rule is built, before anything is evaluated
 - `PredicateCompiler` for compiling structured rule dictionaries into executable predicates
 - JSON schema generation for single rules and for whole compilable expressions
 - Support for both logical and bitwise operator modes
@@ -474,24 +475,30 @@ This pattern is especially useful when you want:
 
 ---
 
-## Custom processors
+## Processing arguments with `Process`
 
-Rules can apply argument processors to coerce values before evaluation. This is
-most useful when rules come from JSON, where every value is a string, number,
-boolean, list, dict or null, and your rule functions expect richer types such as
-dates or decimals.
+Rules often come from JSON or a web form, where every value is a string, number,
+boolean, list, dict or null, while your rule functions want dates, decimals,
+enums, clean text or loaded data. Mark a parameter with `Process(fn)` inside
+`Annotated`, and `fn` is applied to the value when the rule is built. The marker
+comes from [pyargprocessors](https://github.com/aaltatan/pyargprocessors), a
+dependency of this package, and is re-exported here:
 
 ```python
 from datetime import datetime
+from typing import Annotated
 
-from pyspecification import SubscriptableRulesRegistry
-
+from pyspecification import Process, SubscriptableRulesRegistry
 
 rules = SubscriptableRulesRegistry[dict[str, object], str, bool](operator="logical")
 
 
-@rules.rule(processors={"value": lambda value: datetime.strptime(value, "%Y-%m-%d")})
-def datetime__gt(obj: dict[str, object], key: str, value: datetime) -> bool:
+def parse_date(text: str) -> datetime:
+    return datetime.strptime(text, "%Y-%m-%d")
+
+
+@rules.rule()
+def datetime__gt(obj: dict[str, object], key: str, value: Annotated[datetime, Process(parse_date)]) -> bool:
     return obj[key] > value
 
 
@@ -499,45 +506,72 @@ predicate = rules["datetime__gt"]("birthdate", "2001-06-01")
 print(predicate({"birthdate": datetime(2005, 1, 1)}))  # True
 ```
 
-The `processors` option accepts:
-
-- `None` (the default): arguments are passed through untouched.
-- a callable: applied to every argument, e.g. `processors=int`.
-- a mapping of parameter name to callable: applied to those arguments only,
-  e.g. `processors={"min_age": int}`. The key `...` (Ellipsis) means "every
-  argument not named here", e.g. `processors={"min_age": int, ...: str.strip}`.
-
-Processors are matched by parameter name, so they apply whether a value was
-passed positionally or by keyword. For `*args` the processor runs on each item,
-and for `**kwargs` each extra keyword name is looked up individually. Default
-values you did not pass are left as they are.
-
-The object under test and, for subscriptable rules, the `key` are not
-arguments: they are never processed and cannot be named in the mapping.
-
-Processors are validated when the rule is registered, so a typo fails
-immediately instead of silently never running:
-
-```python
-@rules.rule(processors={"valu": str})  # InvalidProcessorsError: unknown parameters ['valu']
-def string__eq(obj: dict[str, object], key: str, value: str) -> bool: ...
-```
-
-`InvalidProcessorsError` is raised when the option is not a callable or a
-mapping, when a mapping value is not callable, or when a key names no parameter
-of the rule (rules that accept `**kwargs` allow any key).
+`Process` works on `object_rule` and `subscriptable_rule` directly as well as
+through the registries. A few things worth knowing:
+
+- Name a processed type once with a `type` alias and reuse it in many rules, and
+  chain several markers (they run left to right):
+
+  ```python
+  type Text = Annotated[str, Process(str.strip), Process(str.lower)]
+  type Money = Annotated[Decimal, Process(Decimal)]
+  ```
+
+- A marker applies whether the value was passed positionally or by keyword. On
+  `*args` it runs on each item, and on `**kwargs` on each value.
+- Processing happens once, when the rule is built, so a bad value fails before the
+  predicate ever runs. Default values you did not pass are never processed.
+- The processor may take a different input than the rule: `Annotated[frozenset[str],
+  Process(load_names)]` lets the JSON send a file path while the rule receives the
+  loaded names. The JSON schema describes what the JSON must send (the processor's
+  first parameter annotation), see below.
+- The object under test and, for subscriptable rules, the key are not
+  arguments: a marker on them raises `InvalidProcessorError`.
+- `pyargprocessors` also provides `each` and `optional` to build a processor out
+  of another one (lists, nulls) and `process_value` to apply a processed type to
+  a single value; see its documentation.
 
 If a processor raises, the library raises `ProcessArgumentError` naming the
-parameter and value, with the original exception chained:
+argument and value, with the original exception chained. It also carries
+`argument`, `value` and `cause` attributes:
 
 ```text
 Argument 'value' with value '06-01-2001' failed to process, time data '06-01-2001' does not match format '%Y-%m-%d'
 ```
 
-> **Upgrading from 2.x:** processors used to be a `(default_processor,
-> named_processors_map)` tuple. Pass a callable instead of the tuple for the
-> old "process everything" behavior, or a mapping for named parameters. The
-> old tuple form is now rejected with `InvalidProcessorsError`.
+`InvalidProcessorError` (a `TypeError`) is raised as soon as the rule is defined
+when a `Process` is not callable, is placed on the object under test or the key,
+or is written as a default value instead of inside `Annotated`.
+
+### Argument errors
+
+Arguments are bound to the rule signature as soon as the rule is called, so
+mistakes surface while a predicate is being built (including by
+`PredicateCompiler.compile`), not when it is evaluated. They are reported in the
+order Python reports them for a call: keywords that cannot be passed by name,
+surplus or repeated arguments, then missing ones.
+
+| Mistake | Exception |
+| --- | --- |
+| a required argument is missing | `MissingArgumentError` |
+| too many positional arguments | `TooManyArgumentsError` |
+| a keyword the rule does not declare | `UnexpectedKeywordArgumentError` |
+| a value given both positionally and by keyword | `MultipleValuesArgumentError` |
+| a positional-only parameter passed by keyword | `PositionalOnlyArgumentError` |
+
+A `TypeError` raised from inside your rule function is yours and is never
+reclassified. A function that does not accept the object under test (and, for
+subscriptable rules, the key) positionally raises `InvalidRuleError`.
+
+> **Upgrading from 3.x:** the `processors=` option of `rule()` and
+> `register_rule()` is gone. Replace `processors=int` by annotating the
+> parameters (`value: Annotated[int, Process(int)]`), and a mapping such as
+> `processors={"age": int}` by marking just `age`. `ProcessArgumentError` and
+> `InvalidProcessorError` now come from pyargprocessors (re-exported by this
+> package) and derive from its `PyargprocessorsError` instead of
+> `PySpecificationError`. Argument errors are raised when a rule is built instead of when its predicate is
+> called, and a keyword-passed positional-only parameter (such as `key=` for a
+> rule declared `key, value, /`) is now a `PositionalOnlyArgumentError`.
 
 ---
 
@@ -803,6 +837,11 @@ first member only. String annotations are evaluated when possible, and fall back
 to `{}` when they cannot be resolved. Defaults are included when they are plain
 JSON values.
 
+A parameter marked with `Process` is described by what its processor accepts, since
+that is what the JSON has to send: with `Annotated[frozenset[str], Process(load_names)]`
+and `def load_names(path: str)`, the schema says `string`. A processor without a
+parameter annotation (such as `int` or `str.strip`) falls back to the annotated type.
+
 > **Upgrading from 2.x:** `get_rule_json_schema(rule)` used to return a flat
 > `{parameter: schema, "return": schema}` mapping. It now takes the rule name
 > too and returns the predicate dictionary schema shown above. `get_json_schema`
@@ -995,8 +1034,11 @@ The library raises explicit exceptions for rule issues:
 - `MissingArgumentError`
 - `UnexpectedKeywordArgumentError`
 - `TooManyArgumentsError`
+- `MultipleValuesArgumentError`
+- `PositionalOnlyArgumentError`
+- `InvalidRuleError`
 - `ProcessArgumentError`
-- `InvalidProcessorsError`
+- `InvalidProcessorError`
 
 `ArgumentError` is the base class for failures involving arguments passed to a
 rule. Its specialized exceptions describe the problem:
@@ -1007,11 +1049,22 @@ rule. Its specialized exceptions describe the problem:
     rule's signature.
 - `TooManyArgumentsError` means more positional arguments were provided than
     the rule accepts.
-- `ProcessArgumentError` means an argument processor could not convert or
-    otherwise process a value.
-
-`InvalidProcessorsError` (a `TypeError`) is raised at registration when the
-`processors` option is malformed or names a parameter the rule does not have.
+- `MultipleValuesArgumentError` means a value was given both positionally and
+    by keyword.
+- `PositionalOnlyArgumentError` means a positional-only parameter was passed by
+    keyword.
+- `ProcessArgumentError` means a `Process` function could not convert a value.
+
+`InvalidProcessorError` and `InvalidRuleError` (both `TypeError`s) are raised when
+a rule is defined: a misplaced or non-callable `Process`, or a function that does
+not accept the object under test (and key) positionally.
+
+Every exception of this package derives from `PySpecificationError`, except
+`ProcessArgumentError` and `InvalidProcessorError`: they come from
+[pyargprocessors](https://github.com/aaltatan/pyargprocessors), derive from its
+`PyargprocessorsError`, and are re-exported here. Exceptions raised while
+compiling, including those two, carry a note with the JSON path of the offending
+expression, e.g. `at $.expressions[1]`.
 
 `RuleDoesNotExistError` includes the missing name and the available rule names,
 which is useful when rules are dynamically loaded. Malformed normalized

{pyspecification-3.0.0 → pyspecification-4.0.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "pyspecification"
-version = "3.0.0"
+version = "4.0.0"
 description = "A lightweight, typed Python library for composing business rules as reusable, executable predicates."
 readme = "README.md"
 requires-python = ">=3.12"
-dependencies = []
+dependencies = ["pyargprocessors>=0.1.0"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",

{pyspecification-3.0.0 → pyspecification-4.0.0}/pyproject.toml.orig

@@ -1,11 +1,13 @@
 [project]
 name = "pyspecification"
-version = "3.0.0"
+version = "4.0.0"
 description = "A lightweight, typed Python library for composing business rules as reusable, executable predicates."
 readme = "README.md"
 authors = [{ name = "aaltatan", email = "a.altatan@gmail.com" }]
 requires-python = ">=3.12"
-dependencies = []
+dependencies = [
+    "pyargprocessors>=0.1.0",
+]
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",

{pyspecification-3.0.0 → pyspecification-4.0.0}/src/pyspecification/__init__.py

@@ -4,13 +4,16 @@ A lightweight, typed Python library for composing business rules as reusable, ex
 This project was inspired by the work and ideas shared by [ArjanCodes](https://github.com/arjancodes), especially the concepts demonstrated in his video: ["The Most Overengineered Python Pattern I've Ever Built"](https://youtu.be/KqfMiuL3cx4?si=WAn01N2I0OO3KOgc).
 """  # noqa: E501
 
+from pyargprocessors import InvalidProcessorError, Process, ProcessArgumentError
+
 from .compilers import ExpressionWrapperDict, PredicateCompiler, PredicateDict
 from .exceptions import (
     ArgumentError,
-    InvalidProcessorsError,
+    InvalidRuleError,
     MissingArgumentError,
+    MultipleValuesArgumentError,
     PositionalOnlyArgumentError,
-    ProcessArgumentError,
+    PySpecificationError,
     RuleAlreadyRegisteredError,
     RuleDoesNotExistError,
     RuleKeyDoesNotExistError,
@@ -25,15 +28,19 @@ from .rules import object_rule, subscriptable_rule
 __all__ = [
     "ArgumentError",
     "ExpressionWrapperDict",
-    "InvalidProcessorsError",
+    "InvalidProcessorError",
+    "InvalidRuleError",
     "MissingArgumentError",
+    "MultipleValuesArgumentError",
     "ObjectRulesRegistry",
     "OperatorType",
+    "Process",
+    "ProcessArgumentError",
     "PositionalOnlyArgumentError",
     "Predicate",
     "PredicateCompiler",
     "PredicateDict",
-    "ProcessArgumentError",
+    "PySpecificationError",
     "RuleAlreadyRegisteredError",
     "RuleDoesNotExistError",
     "RuleKeyDoesNotExistError",

{pyspecification-3.0.0 → pyspecification-4.0.0}/src/pyspecification/compilers.py

@@ -3,7 +3,9 @@ from collections.abc import Callable
 from pprint import pformat
 from typing import Any, Literal, TypedDict, TypeGuard
 
-from .exceptions import MissingArgumentError, RuleDoesNotExistError, is_missing_argument_exception
+from pyargprocessors import PyargprocessorsError
+
+from .exceptions import PySpecificationError, RuleDoesNotExistError
 from .json_schema import get_json_schema
 from .predicate import Predicate, ReturnType
 
@@ -133,7 +135,13 @@ class PredicateCompiler[T, R: ReturnType]:
         self._initial_predicate_factory = initial_predicate_factory
 
     def compile(self, expression: ExpressionDict) -> Predicate[T, R]:
-        """Compiles an expression into a predicate."""
+        """Compiles an expression into a predicate.
+
+        Every problem is reported while compiling, before any object is evaluated:
+        unknown rules, bad arguments and failing `Process` functions. Errors raised
+        by this library carry a note with the JSON path of the offending
+        expression, e.g. `at $.expressions[1]`.
+        """
         return self._compile(expression, path="$")
 
     def _compile(self, expression: ExpressionDict, path: str) -> Predicate[T, R]:
@@ -141,19 +149,18 @@ class PredicateCompiler[T, R: ReturnType]:
             return self._compile_wrapper(expression, path)
 
         if is_predicate_dict(expression):
-            return self._compile_single(expression)
+            return self._compile_single(expression, path)
 
         raise TypeError(_invalid_expression_message(expression, path))
 
-    def _compile_single(self, single: PredicateDict) -> Predicate[T, R]:
-        if single["name"] not in self._rules:
-            raise RuleDoesNotExistError(single["name"], self._rules.keys())
-
+    def _compile_single(self, single: PredicateDict, path: str) -> Predicate[T, R]:
         try:
+            if single["name"] not in self._rules:
+                raise RuleDoesNotExistError(single["name"], self._rules.keys())
+
             predicate = self._rules[single["name"]](*single["args"], **single["kwargs"])
-        except TypeError as e:
-            if is_missing_argument_exception(e):
-                raise MissingArgumentError(str(e)) from e
+        except (PySpecificationError, PyargprocessorsError) as error:
+            error.add_note(f"at {path}")
             raise
 
         if single["inverse"]: