pyspecification 2.0.2__tar.gz → 4.0.0__tar.gz

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

@@ -1,12 +1,13 @@
 Metadata-Version: 2.3
 Name: pyspecification
-Version: 2.0.2
+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,9 +66,10 @@ 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
+- `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 rule arguments and return types
+- JSON schema generation for single rules and for whole compilable expressions
 - Support for both logical and bitwise operator modes
 - Hidden rules and custom naming for internal/private rule registration
 
@@ -488,21 +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.
+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=(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
 
 
@@ -510,27 +521,72 @@ predicate = rules["datetime__gt"]("birthdate", "2001-06-01")
 print(predicate({"birthdate": datetime(2005, 1, 1)}))  # True
 ```
 
-The processor tuple format is:
-
-```python
-(default_processor, named_processors_map)
+`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
+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'
 ```
 
-For example:
-
-```python
-processors = (
-    int,
-    {"value": str},
-)
-```
-
-This means:
-
-- positional args are passed through `int`
-- keyword args with name `"value"` are passed through `str`
-
-If conversion fails, the library raises `ProcessArgumentError`.
+`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`.
 
 ---
 
@@ -693,7 +749,17 @@ not match a predicate or wrapper shape, it raises `TypeError`.
 
 ## JSON schema generation
 
-`get_rule_json_schema` inspects a rule function and returns JSON-schema-like metadata for parameters and return value.
+The generated schemas describe the exact shape accepted by `PredicateCompiler`,
+so they can be handed to a form builder, a validator, or an LLM that writes
+rules as JSON.
+
+### One rule
+
+`get_rule_json_schema(name, rule)` returns the schema of one predicate
+dictionary. Positional parameters are described under `args` (via
+`prefixItems`), keyword-capable parameters under `kwargs`, and the rule's
+docstring becomes the description. The object under test is not part of the
+schema; for subscriptable rules the `key` is the first parameter.
 
 ```python
 from dataclasses import dataclass
@@ -709,19 +775,99 @@ class User:
 
 
 @object_rule()
-def name__istartswith(user: User, value: str) -> bool:
-    return user.name.lower().startswith(value.lower())
+def age__between(user: User, min_age: int, max_age: int = 120) -> bool:
+    """Whether the age is within a range."""
+    return min_age <= user.age <= max_age
+
+
+print(get_rule_json_schema("age__between", age__between))
+# {
+#     "type": "object",
+#     "properties": {
+#         "name": {"const": "age__between"},
+#         "args": {
+#             "type": "array",
+#             "prefixItems": [{"type": "integer"}, {"type": "integer", "default": 120}],
+#             "items": False,
+#         },
+#         "kwargs": {
+#             "type": "object",
+#             "properties": {
+#                 "min_age": {"type": "integer"},
+#                 "max_age": {"type": "integer", "default": 120},
+#             },
+#             "required": [],
+#             "additionalProperties": False,
+#         },
+#         "inverse": {"type": "boolean"},
+#     },
+#     "required": ["name", "args", "kwargs", "inverse"],
+#     "additionalProperties": False,
+#     "description": "Whether the age is within a range.",
+# }
+```
+
+### A whole expression
 
+`get_expression_json_schema(rules)` returns the schema of everything
+`PredicateCompiler.compile` accepts: a predicate dictionary for each rule, or a
+nested `{"operator": "all" | "any", "expressions": [...]}` wrapper. Pass
+`registry.rules` (hidden rules are left out) or any name-to-rule mapping you
+give to the compiler.
+
+```python
+from pyspecification import ObjectRulesRegistry, get_expression_json_schema
+
+registry = ObjectRulesRegistry[User, bool](operator="logical")
 
-print(get_rule_json_schema(name__istartswith))
-# {'value': {'type': 'string'}, 'return': {'type': 'boolean'}}
+
+@registry.rule()
+def is_admin(user: User) -> bool:
+    return user.is_admin
+
+
+schema = get_expression_json_schema(registry.rules)
+print(schema["$schema"])  # https://json-schema.org/draft/2020-12/schema
 ```
 
+### Supported types
+
+`get_json_schema(annotation)` maps Python annotations to JSON Schema. Unknown or
+unannotated types map to `{}`, which accepts any value.
+
+| Python annotation | JSON Schema |
+| --- | --- |
+| `str`, `int`, `float`, `bool`, `None` | `string`, `integer`, `number`, `boolean`, `null` |
+| `Decimal` | `number` |
+| `datetime`, `date`, `time`, `UUID` | `string` with `date-time`, `date`, `time`, `uuid` format |
+| `list[T]`, `set[T]`, `frozenset[T]`, `tuple[T, ...]` | `array` of `T` |
+| `dict[K, V]` | `object` with `V` as `additionalProperties` |
+| `Literal[...]`, `Enum` subclasses | `enum` of the values (plus `string` type when all are strings) |
+| `A \| B`, `Optional[A]` | `anyOf` |
+| `TypedDict` | `object` with `properties` and `required` (`Required`/`NotRequired` honored) |
+| `Annotated[T, ...]`, `type` aliases | the schema of `T` / the aliased type |
+
+Fixed-size heterogeneous tuples such as `tuple[int, str]` are described by their
+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`
+> is now exported from the package root.
+
 This is useful for:
 
 - generating UIs for rule configuration
 - building admin tools and dashboards
-- describing rule inputs to other systems
+- validating rule payloads before compiling them
+- describing rule inputs to other systems and LLMs
 - documenting business rules programmatically
 
 ---
@@ -903,7 +1049,11 @@ The library raises explicit exceptions for rule issues:
 - `MissingArgumentError`
 - `UnexpectedKeywordArgumentError`
 - `TooManyArgumentsError`
+- `MultipleValuesArgumentError`
+- `PositionalOnlyArgumentError`
+- `InvalidRuleError`
 - `ProcessArgumentError`
+- `InvalidProcessorError`
 
 `ArgumentError` is the base class for failures involving arguments passed to a
 rule. Its specialized exceptions describe the problem:
@@ -914,8 +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.
+- `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-2.0.2 → pyspecification-4.0.0}/README.md

@@ -51,9 +51,10 @@ 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
+- `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 rule arguments and return types
+- JSON schema generation for single rules and for whole compilable expressions
 - Support for both logical and bitwise operator modes
 - Hidden rules and custom naming for internal/private rule registration
 
@@ -474,21 +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.
+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=(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
 
 
@@ -496,27 +506,72 @@ predicate = rules["datetime__gt"]("birthdate", "2001-06-01")
 print(predicate({"birthdate": datetime(2005, 1, 1)}))  # True
 ```
 
-The processor tuple format is:
-
-```python
-(default_processor, named_processors_map)
+`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
+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'
 ```
 
-For example:
-
-```python
-processors = (
-    int,
-    {"value": str},
-)
-```
-
-This means:
-
-- positional args are passed through `int`
-- keyword args with name `"value"` are passed through `str`
-
-If conversion fails, the library raises `ProcessArgumentError`.
+`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`.
 
 ---
 
@@ -679,7 +734,17 @@ not match a predicate or wrapper shape, it raises `TypeError`.
 
 ## JSON schema generation
 
-`get_rule_json_schema` inspects a rule function and returns JSON-schema-like metadata for parameters and return value.
+The generated schemas describe the exact shape accepted by `PredicateCompiler`,
+so they can be handed to a form builder, a validator, or an LLM that writes
+rules as JSON.
+
+### One rule
+
+`get_rule_json_schema(name, rule)` returns the schema of one predicate
+dictionary. Positional parameters are described under `args` (via
+`prefixItems`), keyword-capable parameters under `kwargs`, and the rule's
+docstring becomes the description. The object under test is not part of the
+schema; for subscriptable rules the `key` is the first parameter.
 
 ```python
 from dataclasses import dataclass
@@ -695,19 +760,99 @@ class User:
 
 
 @object_rule()
-def name__istartswith(user: User, value: str) -> bool:
-    return user.name.lower().startswith(value.lower())
+def age__between(user: User, min_age: int, max_age: int = 120) -> bool:
+    """Whether the age is within a range."""
+    return min_age <= user.age <= max_age
+
+
+print(get_rule_json_schema("age__between", age__between))
+# {
+#     "type": "object",
+#     "properties": {
+#         "name": {"const": "age__between"},
+#         "args": {
+#             "type": "array",
+#             "prefixItems": [{"type": "integer"}, {"type": "integer", "default": 120}],
+#             "items": False,
+#         },
+#         "kwargs": {
+#             "type": "object",
+#             "properties": {
+#                 "min_age": {"type": "integer"},
+#                 "max_age": {"type": "integer", "default": 120},
+#             },
+#             "required": [],
+#             "additionalProperties": False,
+#         },
+#         "inverse": {"type": "boolean"},
+#     },
+#     "required": ["name", "args", "kwargs", "inverse"],
+#     "additionalProperties": False,
+#     "description": "Whether the age is within a range.",
+# }
+```
+
+### A whole expression
 
+`get_expression_json_schema(rules)` returns the schema of everything
+`PredicateCompiler.compile` accepts: a predicate dictionary for each rule, or a
+nested `{"operator": "all" | "any", "expressions": [...]}` wrapper. Pass
+`registry.rules` (hidden rules are left out) or any name-to-rule mapping you
+give to the compiler.
+
+```python
+from pyspecification import ObjectRulesRegistry, get_expression_json_schema
+
+registry = ObjectRulesRegistry[User, bool](operator="logical")
 
-print(get_rule_json_schema(name__istartswith))
-# {'value': {'type': 'string'}, 'return': {'type': 'boolean'}}
+
+@registry.rule()
+def is_admin(user: User) -> bool:
+    return user.is_admin
+
+
+schema = get_expression_json_schema(registry.rules)
+print(schema["$schema"])  # https://json-schema.org/draft/2020-12/schema
 ```
 
+### Supported types
+
+`get_json_schema(annotation)` maps Python annotations to JSON Schema. Unknown or
+unannotated types map to `{}`, which accepts any value.
+
+| Python annotation | JSON Schema |
+| --- | --- |
+| `str`, `int`, `float`, `bool`, `None` | `string`, `integer`, `number`, `boolean`, `null` |
+| `Decimal` | `number` |
+| `datetime`, `date`, `time`, `UUID` | `string` with `date-time`, `date`, `time`, `uuid` format |
+| `list[T]`, `set[T]`, `frozenset[T]`, `tuple[T, ...]` | `array` of `T` |
+| `dict[K, V]` | `object` with `V` as `additionalProperties` |
+| `Literal[...]`, `Enum` subclasses | `enum` of the values (plus `string` type when all are strings) |
+| `A \| B`, `Optional[A]` | `anyOf` |
+| `TypedDict` | `object` with `properties` and `required` (`Required`/`NotRequired` honored) |
+| `Annotated[T, ...]`, `type` aliases | the schema of `T` / the aliased type |
+
+Fixed-size heterogeneous tuples such as `tuple[int, str]` are described by their
+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`
+> is now exported from the package root.
+
 This is useful for:
 
 - generating UIs for rule configuration
 - building admin tools and dashboards
-- describing rule inputs to other systems
+- validating rule payloads before compiling them
+- describing rule inputs to other systems and LLMs
 - documenting business rules programmatically
 
 ---
@@ -889,7 +1034,11 @@ The library raises explicit exceptions for rule issues:
 - `MissingArgumentError`
 - `UnexpectedKeywordArgumentError`
 - `TooManyArgumentsError`
+- `MultipleValuesArgumentError`
+- `PositionalOnlyArgumentError`
+- `InvalidRuleError`
 - `ProcessArgumentError`
+- `InvalidProcessorError`
 
 `ArgumentError` is the base class for failures involving arguments passed to a
 rule. Its specialized exceptions describe the problem:
@@ -900,8 +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.
+- `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-2.0.2 → pyspecification-4.0.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "pyspecification"
-version = "2.0.2"
+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-2.0.2 → pyspecification-4.0.0}/pyproject.toml.orig

@@ -1,11 +1,13 @@
 [project]
 name = "pyspecification"
-version = "2.0.2"
+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)",