cbpr-usage-rules 0.2.0__tar.gz → 0.4.0__tar.gz

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0]
+
+### Added
+- List only the **enforceable** rules for a year + message type:
+  `list_rules(year, msgtype, enforced_only=True)` in the API and
+  `cbpr-validate --enforced --year … --type …` on the CLI (advisory rules omitted;
+  composes with `--json`).
+
+## [0.3.0]
+
+### Added
+- Bundled **example messages**: a minimum and a maximum variant for every
+  supported message type, each pre-verified to pass the usage rules and the
+  CBPR+ XSDs. New API `example_message(year, msgtype, variant="max",
+  wrapper="Envelope")` and `example_variants(year, msgtype)`, and CLI
+  `--example {min,max}` (with `--wrapper TAG`). Data is fictitious/anonymised.
+
 ## [0.2.0]
 
 ### Added

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/MANIFEST.in

@@ -2,3 +2,4 @@ include LICENSE
 include README.md
 include CHANGELOG.md
 recursive-include src/cbpr_rules py.typed
+recursive-include src/cbpr_rules/examples *.xml

{cbpr_usage_rules-0.2.0/src/cbpr_usage_rules.egg-info → cbpr_usage_rules-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cbpr-usage-rules
-Version: 0.2.0
+Version: 0.4.0
 Summary: Validate ISO 20022 CBPR+ XML messages against SWIFT usage (business) rules.
 Author: Pete Houghton
 License: MIT License
@@ -148,6 +148,35 @@ Advisory rules are summarised as a count by default; pass `--advisory` to list t
 
 ---
 
+## Example messages
+
+For every supported message type the package bundles a **minimum** and a
+**maximum** example message — both pre-verified to pass the usage rules *and* the
+CBPR+ XSDs:
+
+- **min** — only the mandatory fields (smallest valid message);
+- **max** — every XSD-visible field populated (one representative occurrence; the
+  richest single legal combination, since some fields are mutually exclusive).
+
+```bash
+# Print to stdout (full AppHdr + Document, wrapped in <Envelope>)
+cbpr-validate --example max --year 2025 --type pacs.008
+cbpr-validate --example min --year 2026 --type pacs.009_cov > template.xml
+
+# Override the wrapper tag (default: Envelope)
+cbpr-validate --example max --year 2025 --type pacs.008 --wrapper BusinessMessage
+```
+```python
+import cbpr_rules
+xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults to "max"
+cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
+```
+
+The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+not reproduce any real sample — use them as starting templates, not real payments.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:
@@ -229,11 +258,13 @@ matching is by local name, so namespace prefixes never matter.
 ```python
 cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
 cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
+cbpr_rules.list_rules(2025, "pacs.008", enforced_only=True)  # only the enforceable rules
 ```
 
 ```bash
 cbpr-validate --year 2025 --list-types
-cbpr-validate --year 2025 --type pacs.008 --list
+cbpr-validate --year 2025 --type pacs.008 --list               # all rules
+cbpr-validate --year 2025 --type pacs.008 --enforced           # enforceable rules only
 ```
 
 ### Algorithmic field validation

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/README.md

@@ -93,6 +93,35 @@ Advisory rules are summarised as a count by default; pass `--advisory` to list t
 
 ---
 
+## Example messages
+
+For every supported message type the package bundles a **minimum** and a
+**maximum** example message — both pre-verified to pass the usage rules *and* the
+CBPR+ XSDs:
+
+- **min** — only the mandatory fields (smallest valid message);
+- **max** — every XSD-visible field populated (one representative occurrence; the
+  richest single legal combination, since some fields are mutually exclusive).
+
+```bash
+# Print to stdout (full AppHdr + Document, wrapped in <Envelope>)
+cbpr-validate --example max --year 2025 --type pacs.008
+cbpr-validate --example min --year 2026 --type pacs.009_cov > template.xml
+
+# Override the wrapper tag (default: Envelope)
+cbpr-validate --example max --year 2025 --type pacs.008 --wrapper BusinessMessage
+```
+```python
+import cbpr_rules
+xml = cbpr_rules.example_message(2025, "pacs.008", "max")   # variant defaults to "max"
+cbpr_rules.example_variants(2025, "pacs.008")               # ['min', 'max']
+```
+
+The data is **fictitious** (synthetic BICs/IBANs/LEIs, `EXAMPLE` names) and does
+not reproduce any real sample — use them as starting templates, not real payments.
+
+---
+
 ## The result object
 
 Both `validate_file` and `validate_string` return a dictionary:
@@ -174,11 +203,13 @@ matching is by local name, so namespace prefixes never matter.
 ```python
 cbpr_rules.available(2025)              # -> ['camt.052', 'pacs.008', ...]
 cbpr_rules.list_rules(2025, "pacs.008") # -> [{rule_number, name, description, severity, enforced}, ...]
+cbpr_rules.list_rules(2025, "pacs.008", enforced_only=True)  # only the enforceable rules
 ```
 
 ```bash
 cbpr-validate --year 2025 --list-types
-cbpr-validate --year 2025 --type pacs.008 --list
+cbpr-validate --year 2025 --type pacs.008 --list               # all rules
+cbpr-validate --year 2025 --type pacs.008 --enforced           # enforceable rules only
 ```
 
 ### Algorithmic field validation

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/pyproject.toml

@@ -50,7 +50,7 @@ version = { attr = "cbpr_rules.__version__" }
 where = ["src"]
 
 [tool.setuptools.package-data]
-cbpr_rules = ["py.typed"]
+cbpr_rules = ["py.typed", "examples/**/*.xml"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/src/cbpr_rules/__init__.py

@@ -4,10 +4,17 @@ This package is AI generated. See the README for details and caveats.
 """
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 from .models import Rule, Severity, Violation
-from .engine import validate_file, validate_string, list_rules, available
+from .engine import (
+    validate_file,
+    validate_string,
+    list_rules,
+    available,
+    example_message,
+    example_variants,
+)
 
 __all__ = [
     "__version__",
@@ -18,4 +25,6 @@ __all__ = [
     "validate_string",
     "list_rules",
     "available",
+    "example_message",
+    "example_variants",
 ]

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/src/cbpr_rules/cli.py

@@ -9,7 +9,14 @@ import textwrap
 from typing import List, Optional
 
 from . import __version__
-from .engine import ValidationError, available, list_rules, validate_file, validate_string
+from .engine import (
+    ValidationError,
+    available,
+    example_message,
+    list_rules,
+    validate_file,
+    validate_string,
+)
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -51,11 +58,31 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Also list the advisory (non-enforced) rules in full.",
     )
+    p.add_argument(
+        "--example",
+        choices=("min", "max"),
+        help="Print a bundled example message for --year/--type instead of validating: "
+        "min (mandatory fields only) or max (every field populated). Both are XSD- and "
+        "usage-rule-valid.",
+    )
+    p.add_argument(
+        "--wrapper",
+        default="Envelope",
+        metavar="TAG",
+        help="Root element tag wrapping the AppHdr+Document in --example output "
+        "(default: Envelope).",
+    )
     p.add_argument(
         "--list",
         action="store_true",
         help="List the rules for --year/--type instead of validating.",
     )
+    p.add_argument(
+        "--enforced",
+        action="store_true",
+        help="List only the enforceable (mechanically-checked) rules for --year/--type; "
+        "advisory rules are omitted. Implies --list.",
+    )
     p.add_argument(
         "--list-types", action="store_true", help="List message types available for --year."
     )
@@ -184,11 +211,22 @@ def main(argv: Optional[List[str]] = None) -> int:
         print(json.dumps(types) if args.json else "\n".join(types))
         return 0
 
-    if args.list:
+    if args.example:
+        if args.year is None or args.msgtype is None:
+            print("error: --example requires --year and --type", file=sys.stderr)
+            return 2
+        try:
+            print(example_message(args.year, args.msgtype, args.example, wrapper=args.wrapper))
+        except ValidationError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        return 0
+
+    if args.list or args.enforced:
         if args.year is None or args.msgtype is None:
             print("error: --year and --type are required for --list", file=sys.stderr)
             return 2
-        rules = list_rules(args.year, args.msgtype)
+        rules = list_rules(args.year, args.msgtype, enforced_only=args.enforced)
         if args.json:
             print(json.dumps(rules, indent=2))
         else:

{cbpr_usage_rules-0.2.0 → cbpr_usage_rules-0.4.0}/src/cbpr_rules/engine.py

@@ -1,14 +1,19 @@
 """Validation engine and public API."""
 from __future__ import annotations
 
+from importlib import resources
 from typing import List, Optional
 
+from lxml import etree
+
 from . import loader
 from . import schema as _schema
 from .message import ParsedMessage
 from .models import Rule, Severity
 from .registry import available_message_types, load_rules
 
+_VARIANTS = ("min", "max")
+
 
 class ValidationError(Exception):
     """Raised when a message cannot be validated (parse error, unknown type)."""
@@ -90,11 +95,61 @@ def validate_string(xml: str, year: int, msgtype: Optional[str] = None, xsd=None
     return _validate_tree(tree, year, msgtype, xsd)
 
 
-def list_rules(year: int, msgtype: str) -> List[dict]:
-    """Return metadata for every rule registered for a (year, message type)."""
-    return [r.to_dict() for r in load_rules(year, msgtype)]
+def list_rules(year: int, msgtype: str, enforced_only: bool = False) -> List[dict]:
+    """Return metadata for the rules registered for a (year, message type).
+
+    With ``enforced_only=True`` only the enforceable (mechanically-checked) rules
+    are returned, omitting advisory/catalogue-only ones.
+    """
+    rules = [r.to_dict() for r in load_rules(year, msgtype)]
+    if enforced_only:
+        rules = [r for r in rules if r["enforced"]]
+    return rules
 
 
 def available(year: int) -> List[str]:
     """Message types with rules available for a given year."""
     return available_message_types(year)
+
+
+def _example_resource(year: int, msgtype: str, variant: str):
+    return (
+        resources.files("cbpr_rules")
+        .joinpath("examples", f"y{int(year)}", f"{msgtype}.{variant}.xml")
+    )
+
+
+def example_variants(year: int, msgtype: str) -> List[str]:
+    """Which example variants ('min'/'max') are bundled for a (year, message type)."""
+    return [v for v in _VARIANTS if _example_resource(year, msgtype, v).is_file()]
+
+
+def example_message(
+    year: int, msgtype: str, variant: str = "max", wrapper: str = "Envelope"
+) -> str:
+    """Return a bundled, pre-verified example message for a (year, message type).
+
+    ``variant`` is 'min' (mandatory fields only) or 'max' (every field populated).
+    Both are guaranteed to pass the usage rules (and the CBPR+ XSDs). ``wrapper``
+    overrides the single root element tag (default ``Envelope``) that holds the
+    ``AppHdr`` and ``Document``. Raises ``ValidationError`` if no such example.
+    """
+    if variant not in _VARIANTS:
+        raise ValidationError(
+            f"Unknown variant '{variant}'; choose one of {', '.join(_VARIANTS)}."
+        )
+    res = _example_resource(year, msgtype, variant)
+    if not res.is_file():
+        types = ", ".join(available(year)) or "(none)"
+        raise ValidationError(
+            f"No {variant} example for '{msgtype}' in {int(year)}. "
+            f"Available message types: {types}."
+        )
+    text = res.read_text(encoding="utf-8")
+    if wrapper and wrapper != "Envelope":
+        root = etree.fromstring(text.encode("utf-8"))
+        root.tag = wrapper
+        text = etree.tostring(
+            root, xml_declaration=True, encoding="UTF-8", pretty_print=True
+        ).decode("utf-8")
+    return text