subschema 0.0.1__py3-none-any.whl

subschema/__init__.py

@@ -0,0 +1,19 @@
+from subschema import api, exceptions
+from subschema.dialects import Dialect
+
+is_subschema = api.is_subschema
+meet_schemas = api.meet_schemas
+join_schemas = api.join_schemas
+is_equivalent = api.is_equivalent
+
+canonicalize_schema = api.canonicalize_schema
+
+__all__ = [
+    "Dialect",
+    "canonicalize_schema",
+    "exceptions",
+    "is_equivalent",
+    "is_subschema",
+    "join_schemas",
+    "meet_schemas",
+]

subschema/api.py

@@ -0,0 +1,172 @@
+"""
+Public API entrypoints.
+"""
+
+from copy import deepcopy
+
+from subschema.dialects import (
+    resolve_dialect,
+    strip_inactive_keywords_for_dialect,
+    validate_supported_keywords,
+)
+from subschema.kernel.contracts import ProofBudgets, ProofOptions
+from subschema.kernel.engine import ProofEngine
+from subschema.kernel.json_data import ensure_json_value
+from subschema.kernel.normalization import normalize_boolean_schemas
+from subschema.kernel.validation import validate_raw_schema_for_dialect
+
+
+def canonicalize_schema(s, *, dialect=None):
+    """Return a modern normalized schema without embedding removed checker objects."""
+    ensure_json_value(s, label="schema")
+    resolved_dialect = resolve_dialect(s, dialect=dialect)
+    _validate_public_schema(s, resolved_dialect)
+    schema = strip_inactive_keywords_for_dialect(
+        normalize_boolean_schemas(deepcopy(s)), resolved_dialect
+    )
+    validate_supported_keywords(schema, resolved_dialect)
+    return schema
+
+
+def _validate_public_schema(schema, dialect):
+    stripped = strip_inactive_keywords_for_dialect(schema, dialect)
+    validate_raw_schema_for_dialect(stripped, dialect)
+
+
+def _resolve_proof_options(
+    proof_options=None,
+    *,
+    endeavor=False,
+    max_work=None,
+    timeout_ms=None,
+):
+    if not isinstance(endeavor, bool):
+        raise TypeError("endeavor must be a boolean")
+    if proof_options is not None:
+        if not isinstance(proof_options, ProofOptions):
+            raise TypeError("proof_options must be a ProofOptions instance")
+        if endeavor or max_work is not None or timeout_ms is not None:
+            raise ValueError(
+                "proof_options cannot be combined with endeavor, max_work, or "
+                "timeout_ms"
+            )
+        return proof_options
+    if (max_work is not None or timeout_ms is not None) and not endeavor:
+        raise ValueError("max_work and timeout_ms require endeavor=True")
+    if endeavor:
+        return ProofOptions(
+            endeavor=endeavor,
+            budgets=ProofBudgets(
+                max_work=4096 if max_work is None else max_work,
+                timeout_ms=1000 if timeout_ms is None else timeout_ms,
+            ),
+        )
+    return None
+
+
+def is_subschema(
+    s1,
+    s2,
+    *,
+    dialect=None,
+    proof_options=None,
+    endeavor=False,
+    max_work=None,
+    timeout_ms=None,
+):
+    """Entry point for schema subtype checking."""
+    ensure_json_value(s1, label="lhs schema")
+    ensure_json_value(s2, label="rhs schema")
+    resolved_dialect = resolve_dialect(s1, s2, dialect=dialect)
+    _validate_public_schema(s1, resolved_dialect)
+    _validate_public_schema(s2, resolved_dialect)
+    options = _resolve_proof_options(
+        proof_options,
+        endeavor=endeavor,
+        max_work=max_work,
+        timeout_ms=timeout_ms,
+    )
+    return ProofEngine.for_schemas(
+        s1, s2, dialect=resolved_dialect, options=options
+    ).is_subschema_bool(s1, s2)
+
+
+def meet_schemas(
+    s1,
+    s2,
+    *,
+    dialect=None,
+    proof_options=None,
+    endeavor=False,
+    max_work=None,
+    timeout_ms=None,
+):
+    """Entry point for schema meet operation."""
+    ensure_json_value(s1, label="lhs schema")
+    ensure_json_value(s2, label="rhs schema")
+    resolved_dialect = resolve_dialect(s1, s2, dialect=dialect)
+    _validate_public_schema(s1, resolved_dialect)
+    _validate_public_schema(s2, resolved_dialect)
+    options = _resolve_proof_options(
+        proof_options,
+        endeavor=endeavor,
+        max_work=max_work,
+        timeout_ms=timeout_ms,
+    )
+    return ProofEngine.for_schemas(
+        s1, s2, dialect=resolved_dialect, options=options
+    ).meet(s1, s2)
+
+
+def join_schemas(
+    s1,
+    s2,
+    *,
+    dialect=None,
+    proof_options=None,
+    endeavor=False,
+    max_work=None,
+    timeout_ms=None,
+):
+    """Entry point for schema join operation."""
+    ensure_json_value(s1, label="lhs schema")
+    ensure_json_value(s2, label="rhs schema")
+    resolved_dialect = resolve_dialect(s1, s2, dialect=dialect)
+    _validate_public_schema(s1, resolved_dialect)
+    _validate_public_schema(s2, resolved_dialect)
+    options = _resolve_proof_options(
+        proof_options,
+        endeavor=endeavor,
+        max_work=max_work,
+        timeout_ms=timeout_ms,
+    )
+    return ProofEngine.for_schemas(
+        s1, s2, dialect=resolved_dialect, options=options
+    ).join(s1, s2)
+
+
+def is_equivalent(
+    s1,
+    s2,
+    *,
+    dialect=None,
+    proof_options=None,
+    endeavor=False,
+    max_work=None,
+    timeout_ms=None,
+):
+    """Entry point for schema equivalence check operation."""
+    options = _resolve_proof_options(
+        proof_options,
+        endeavor=endeavor,
+        max_work=max_work,
+        timeout_ms=timeout_ms,
+    )
+    return is_subschema(
+        s1, s2, dialect=dialect, proof_options=options
+    ) and is_subschema(
+        s2,
+        s1,
+        dialect=dialect,
+        proof_options=options,
+    )

subschema/cli.py

@@ -0,0 +1,75 @@
+import argparse
+
+from subschema.api import is_subschema
+from subschema.kernel import ProofBudgets, ProofOptions
+from subschema.kernel.json_data import strict_json_load
+
+
+def int_at_least_minus_one(value):
+    try:
+        parsed = int(value)
+    except ValueError as err:
+        raise argparse.ArgumentTypeError(f"{value!r} is not an integer") from err
+    if parsed < -1:
+        raise argparse.ArgumentTypeError("value must be -1 or greater")
+    return parsed
+
+
+def load_json_file(path, label):
+    with open(path) as fh:
+        try:
+            return strict_json_load(fh)
+        except Exception as err:
+            raise SystemExit(f"{label} {err}") from err
+
+
+def main():
+    """CLI entry point for subschema"""
+
+    parser = argparse.ArgumentParser(
+        description=(
+            "CLI for subschema tool which checks whether a LHS JSON "
+            "schema is a subschema (<:) of another RHS JSON schema."
+        )
+    )
+    parser.add_argument(
+        "--endeavor", action="store_true", help="enable finite expensive proof products"
+    )
+    parser.add_argument("--max-work", type=int_at_least_minus_one, default=None)
+    parser.add_argument("--timeout-ms", type=int_at_least_minus_one, default=None)
+    parser.add_argument(
+        "LHS",
+        metavar="lhs",
+        type=str,
+        help="Path to the JSON file which has the LHS JSON schema",
+    )
+    parser.add_argument(
+        "RHS",
+        metavar="rhs",
+        type=str,
+        help="Path to the JSON file which has the RHS JSON schema",
+    )
+
+    args = parser.parse_args()
+    if (args.max_work is not None or args.timeout_ms is not None) and not args.endeavor:
+        parser.error("--max-work and --timeout-ms require --endeavor")
+    s1_file_path = args.LHS
+    s2_file_path = args.RHS
+
+    s1 = load_json_file(s1_file_path, "LHS file:")
+    s2 = load_json_file(s2_file_path, "RHS file:")
+    proof_options = None
+    if args.endeavor:
+        proof_options = ProofOptions(
+            endeavor=args.endeavor,
+            budgets=ProofBudgets(
+                max_work=4096 if args.max_work is None else args.max_work,
+                timeout_ms=1000 if args.timeout_ms is None else args.timeout_ms,
+            ),
+        )
+
+    print("LHS <: RHS", is_subschema(s1, s2, proof_options=proof_options))
+
+
+if __name__ == "__main__":
+    main()