Speed up validate() with validator caching and optional schema-check fast path

Author: p1c2u

docs/contributing.rst

@@ -74,3 +74,22 @@ To run all checks on all files, enter:
    pre-commit run --all-files
 
 Pre-commit check results are also attached to your PR through integration with Github Action.
+
+Performance benchmark
+^^^^^^^^^^^^^^^^^^^^^
+
+To collect a local benchmark report for validation performance, run:
+
+.. code-block:: console
+
+   poetry run python benchmarks/run.py --output reports/benchmarks/current.json
+
+To compare two benchmark reports and optionally fail on regressions, run:
+
+.. code-block:: console
+
+   poetry run python benchmarks/compare.py \
+     --baseline reports/benchmarks/baseline.json \
+     --candidate reports/benchmarks/current.json \
+     --regression-threshold 5 \
+     --fail-on-regression

openapi_schema_validator/shortcuts.py

@@ -1,4 +1,10 @@
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+from threading import RLock
 from typing import Any
+from typing import Hashable
 from typing import Mapping
 from typing import cast
 
@@ -11,14 +17,79 @@
 from openapi_schema_validator.validators import OAS32Validator
 from openapi_schema_validator.validators import check_openapi_schema
 
+_VALIDATOR_CACHE_MAX_SIZE = 128
+
+
+@dataclass
+class _CachedValidator:
+    validator: Any
+    schema_checked: bool
+
+
+_validator_cache: OrderedDict[Hashable, _CachedValidator] = OrderedDict()
+_validator_cache_lock = RLock()
+_LOCAL_ONLY_REGISTRY = Registry()
+
+
+def _freeze_value(value: Any) -> Hashable:
+    if isinstance(value, dict):
+        return tuple(
+            sorted((str(k), _freeze_value(v)) for k, v in value.items())
+        )
+    if isinstance(value, list):
+        return tuple(_freeze_value(item) for item in value)
+    if isinstance(value, tuple):
+        return tuple(_freeze_value(item) for item in value)
+    if isinstance(value, set):
+        return tuple(
+            sorted(
+                (_freeze_value(item) for item in value),
+                key=repr,
+            )
+        )
+    if isinstance(value, (str, bytes, int, float, bool, type(None))):
+        return value
+    return ("id", id(value))
+
+
+def _schema_fingerprint(schema: Mapping[str, Any]) -> Hashable:
+    return _freeze_value(dict(schema))
+
+
+def _cache_key(
+    schema: Mapping[str, Any],
+    cls: type[Validator],
+    args: tuple[Any, ...],
+    kwargs: Mapping[str, Any],
+    allow_remote_references: bool,
+) -> Hashable:
+    return (
+        cls,
+        allow_remote_references,
+        _schema_fingerprint(schema),
+        _freeze_value(args),
+        _freeze_value(dict(kwargs)),
+    )
+
+
+def _prune_cache_if_needed() -> None:
+    while len(_validator_cache) > _VALIDATOR_CACHE_MAX_SIZE:
+        _validator_cache.popitem(last=False)
+
+
+def _clear_validate_cache() -> None:
+    with _validator_cache_lock:
+        _validator_cache.clear()
+
 
 def validate(
     instance: Any,
     schema: Mapping[str, Any],
     cls: type[Validator] = OAS32Validator,
     *args: Any,
     allow_remote_references: bool = False,
-    **kwargs: Any
+    check_schema: bool = True,
+    **kwargs: Any,
 ) -> None:
     """
     Validate an instance against a given schema using the specified
@@ -38,6 +109,9 @@ def validate(
         allow_remote_references: If ``True`` and no explicit ``registry`` is
             provided, allow jsonschema's default remote reference retrieval
             behavior.
+        check_schema: If ``True`` (default), validate the provided schema
+            before validating ``instance``. If ``False``, skip schema
+            validation and run instance validation directly.
         **kwargs: Keyword arguments forwarded to ``cls`` constructor
             (for example ``registry`` and ``format_checker``). If omitted,
             a local-only empty ``Registry`` is used to avoid implicit remote
@@ -49,25 +123,63 @@ def validate(
     """
     schema_dict = cast(dict[str, Any], schema)
 
-    meta_schema = getattr(cls, "META_SCHEMA", None)
-    # jsonschema's default check_schema path does not accept a custom
-    # registry, so for OAS dialects we use the package registry
-    # explicitly to keep metaschema resolution local and deterministic.
-    if isinstance(meta_schema, dict) and meta_schema.get("$id") in (
-        OAS31_BASE_DIALECT_ID,
-        OAS32_BASE_DIALECT_ID,
-    ):
-        check_openapi_schema(cls, schema_dict)
-    else:
-        cls.check_schema(schema_dict)
-
     validator_kwargs = kwargs.copy()
     if not allow_remote_references:
-        validator_kwargs.setdefault("registry", Registry())
+        validator_kwargs.setdefault("registry", _LOCAL_ONLY_REGISTRY)
+
+    key = _cache_key(
+        schema=schema_dict,
+        cls=cls,
+        args=args,
+        kwargs=validator_kwargs,
+        allow_remote_references=allow_remote_references,
+    )
+
+    with _validator_cache_lock:
+        cached = _validator_cache.get(key)
+
+    if cached is None:
+        if check_schema:
+            meta_schema = getattr(cls, "META_SCHEMA", None)
+            # jsonschema's default check_schema path does not accept a custom
+            # registry, so for OAS dialects we use the package registry
+            # explicitly to keep metaschema resolution local and deterministic.
+            if isinstance(meta_schema, dict) and meta_schema.get("$id") in (
+                OAS31_BASE_DIALECT_ID,
+                OAS32_BASE_DIALECT_ID,
+            ):
+                check_openapi_schema(cls, schema_dict)
+            else:
+                cls.check_schema(schema_dict)
+
+        validator = cls(schema_dict, *args, **validator_kwargs)
+        cached = _CachedValidator(
+            validator=validator,
+            schema_checked=check_schema,
+        )
+        with _validator_cache_lock:
+            _validator_cache[key] = cached
+            _validator_cache.move_to_end(key)
+            _prune_cache_if_needed()
+    elif check_schema and not cached.schema_checked:
+        meta_schema = getattr(cls, "META_SCHEMA", None)
+        if isinstance(meta_schema, dict) and meta_schema.get("$id") in (
+            OAS31_BASE_DIALECT_ID,
+            OAS32_BASE_DIALECT_ID,
+        ):
+            check_openapi_schema(cls, schema_dict)
+        else:
+            cls.check_schema(schema_dict)
+
+        with _validator_cache_lock:
+            cached.schema_checked = True
+            _validator_cache.move_to_end(key)
+    else:
+        with _validator_cache_lock:
+            _validator_cache.move_to_end(key)
 
-    validator = cls(schema_dict, *args, **validator_kwargs)
     error = best_match(
-        validator.evolve(schema=schema_dict).iter_errors(instance)
+        cached.validator.evolve(schema=schema_dict).iter_errors(instance)
     )
     if error is not None:
         raise error

tests/unit/test_shortcut.py

@@ -1,12 +1,16 @@
 import inspect
+import re
 from unittest.mock import patch
 
 import pytest
+from jsonschema.exceptions import SchemaError
 from referencing import Registry
 from referencing import Resource
 
 from openapi_schema_validator import OAS32Validator
 from openapi_schema_validator import validate
+from openapi_schema_validator._regex import has_ecma_regex
+from openapi_schema_validator.shortcuts import _clear_validate_cache
 
 
 @pytest.fixture(scope="function")
@@ -23,6 +27,13 @@ def schema():
     }
 
 
+@pytest.fixture(autouse=True)
+def clear_validate_cache_fixture():
+    _clear_validate_cache()
+    yield
+    _clear_validate_cache()
+
+
 def test_validate_does_not_add_nullable_to_schema(schema):
     """
     Verify that calling validate does not add the 'nullable' key to the schema
@@ -118,3 +129,43 @@ def test_validate_can_allow_implicit_remote_references():
             validate({}, schema, allow_remote_references=True)
 
     assert urlopen.called
+
+
+def test_validate_skip_schema_check():
+    schema = {"type": "string", "pattern": "["}
+
+    with pytest.raises(SchemaError, match="is not a 'regex'"):
+        validate("foo", schema)
+
+    if has_ecma_regex():
+        with pytest.raises(Exception):
+            validate("foo", schema, check_schema=False)
+    else:
+        with pytest.raises(re.error):
+            validate("foo", schema, check_schema=False)
+
+
+def test_validate_cache_avoids_rechecking_schema(schema):
+    with patch(
+        "openapi_schema_validator.shortcuts.check_openapi_schema"
+    ) as check_schema_mock:
+        validate({"email": "foo@bar.com"}, schema, cls=OAS32Validator)
+        validate({"email": "foo@bar.com"}, schema, cls=OAS32Validator)
+
+    check_schema_mock.assert_called_once()
+
+
+def test_validate_cache_promotes_unchecked_validator(schema):
+    with patch(
+        "openapi_schema_validator.shortcuts.check_openapi_schema"
+    ) as check_schema_mock:
+        validate(
+            {"email": "foo@bar.com"},
+            schema,
+            cls=OAS32Validator,
+            check_schema=False,
+        )
+        validate({"email": "foo@bar.com"}, schema, cls=OAS32Validator)
+        validate({"email": "foo@bar.com"}, schema, cls=OAS32Validator)
+
+    check_schema_mock.assert_called_once()