pytest-httpchain 0.8.0__tar.gz → 0.9.0__tar.gz

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-httpchain
-Version: 0.8.0
+Version: 0.9.0
 Summary: pytest plugin for HTTP testing using JSON files
 Keywords: testing,pytest,httpx,http,api,integration-testing
 Author: Alexander Eresov
@@ -14,21 +14,21 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Testing
+Requires-Dist: deepmerge>=2.0
+Requires-Dist: graphql-core>=3.0.0
 Requires-Dist: httpx[http2]>=0.27.0
 Requires-Dist: jmespath>=1.0.0
 Requires-Dist: jsonschema>=4.0.0
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: pyrate-limiter>=4.0.0
 Requires-Dist: pytest>=8.4
-Requires-Dist: pytest-httpchain-core
-Requires-Dist: pytest-httpchain-jsonref
-Requires-Dist: pytest-httpchain-models
-Requires-Dist: pytest-httpchain-templates
-Requires-Dist: pytest-httpchain-userfunc
 Requires-Dist: pytest-order>=1.3.0
 Requires-Dist: simpleeval>=1.0.3
 Requires-Dist: typer>=0.16.0
 Requires-Python: >=3.13
+Project-URL: Changelog, https://github.com/aeresov/pytest-httpchain/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://aeresov.github.io/pytest-httpchain/
+Project-URL: Repository, https://github.com/aeresov/pytest-httpchain
 Description-Content-Type: text/markdown
 
 [![image](https://img.shields.io/pypi/v/pytest-httpchain)](https://pypi.python.org/pypi/pytest-httpchain)

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/pyproject.toml

@@ -1,22 +1,19 @@
 [project]
 name = "pytest-httpchain"
-version = "0.8.0"
+version = "0.9.0"
 description = "pytest plugin for HTTP testing using JSON files"
 readme = "README.md"
 requires-python = ">=3.13"
 authors = [{ name = "Alexander Eresov", email = "aeresov@gmail.com" }]
 dependencies = [
+    "deepmerge>=2.0",
+    "graphql-core>=3.0.0",
     "httpx[http2]>=0.27.0",
     "jmespath>=1.0.0",
     "jsonschema>=4.0.0",
     "pydantic>=2.11.7",
     "pyrate-limiter>=4.0.0",
     "pytest>=8.4",
-    "pytest-httpchain-core",
-    "pytest-httpchain-jsonref",
-    "pytest-httpchain-models",
-    "pytest-httpchain-templates",
-    "pytest-httpchain-userfunc",
     "pytest-order>=1.3.0",
     "simpleeval>=1.0.3",
     "typer>=0.16.0",
@@ -34,10 +31,16 @@ classifiers = [
     "Topic :: Software Development :: Testing",
 ]
 
+[project.urls]
+Repository = "https://github.com/aeresov/pytest-httpchain"
+Documentation = "https://aeresov.github.io/pytest-httpchain/"
+Changelog = "https://github.com/aeresov/pytest-httpchain/blob/main/CHANGELOG.md"
+
 [dependency-groups]
 dev = [
     "flask-httpauth>=4.8.0",
     "http-server-mock>=1.7",
+    "import-linter>=2.0",
     "ruff>=0.12.1",
     "pytest-cov>=6.0.0",
     "coverage[toml]>=7.0",
@@ -51,20 +54,13 @@ docs = [
 [tool.uv]
 default-groups = ["dev", "docs"]
 
-[tool.uv.workspace]
-members = ["packages/*"]
-
-[tool.uv.sources]
-pytest-httpchain-core = { workspace = true }
-pytest-httpchain-jsonref = { workspace = true }
-pytest-httpchain-templates = { workspace = true }
-pytest-httpchain-models = { workspace = true }
-pytest-httpchain-userfunc = { workspace = true }
-
 [build-system]
 requires = ["uv_build>=0.7.21,<0.8.0"]
 build-backend = "uv_build"
 
+[tool.uv.build-backend]
+source-exclude = ["src/pytest_httpchain/**/CLAUDE.md"]
+
 [project.scripts]
 pytest-httpchain = "pytest_httpchain.cli:app"
 
@@ -94,6 +90,26 @@ ignore = []
 [tool.ruff.lint.isort]
 known-first-party = ["tests", "utils"]
 
+[tool.ty.environment]
+python-version = "3.13"
+
+[tool.ty.terminal]
+error-on-warning = true
+
+# Test suites (especially the models package) deliberately construct models with
+# invalid types to assert ValidationError, and access attributes on unions/mocks
+# the checker can't narrow. Relax those specific rules for test code only; src/
+# stays strict and uses pinpoint `# ty: ignore[...]` comments instead.
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+unknown-argument = "ignore"
+unresolved-attribute = "ignore"
+not-subscriptable = "ignore"
+missing-argument = "ignore"
+
 [tool.pytest]
 minversion = "9.0"
 log_cli = true
@@ -103,26 +119,43 @@ pytester_example_dir = "tests/integration/examples"
 addopts = ["--log-disable=werkzeug", "--import-mode=importlib"]
 pythonpath = [
     ".",
-    "packages/pytest-httpchain-core/src",
-    "packages/pytest-httpchain-jsonref/src",
-    "packages/pytest-httpchain-templates/src",
-    "packages/pytest-httpchain-models/src",
-    "packages/pytest-httpchain-userfunc/src",
 ]
-testpaths = ["tests", "packages/*/tests"]
+testpaths = ["tests"]
 
 [tool.coverage.run]
-source = [
-    "src",
-    "packages/pytest-httpchain-core/src",
-    "packages/pytest-httpchain-jsonref/src",
-    "packages/pytest-httpchain-templates/src",
-    "packages/pytest-httpchain-models/src",
-    "packages/pytest-httpchain-userfunc/src",
-]
+source = ["src"]
 branch = true
 
 [tool.coverage.report]
 precision = 2
 show_missing = true
 skip_covered = false
+
+[tool.importlinter]
+root_package = "pytest_httpchain"
+
+# Exhaustive vertical layering: every top-level module must appear in exactly one
+# layer; a new module fails lint-imports until it is placed. Modules on the same
+# layer (separated by ":") are additionally kept mutually independent.
+[[tool.importlinter.contracts]]
+name = "package layering"
+type = "layers"
+containers = ["pytest_httpchain"]
+exhaustive = true
+layers = [
+    "plugin : cli",
+    "carrier : dataflow : schema",
+    "validation : har_writer : report_formatter",
+    "utils",
+    "models",
+    "templates : jsonref : userfunc",
+    "errors : constants : warnings",
+]
+
+# Horizontal refinement the layers contract cannot express: models sits above the
+# domain trio and may import templates/userfunc, but must never import jsonref.
+[[tool.importlinter.contracts]]
+name = "models does not import jsonref"
+type = "forbidden"
+source_modules = ["pytest_httpchain.models"]
+forbidden_modules = ["pytest_httpchain.jsonref"]

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/src/pytest_httpchain/__init__.py

@@ -22,9 +22,9 @@ Example test file (test_api.http.json):
     }
 """
 
-# Re-export the user-facing warning so consumers can filter it without reaching
-# into the plugin module. The definition stays in plugin.py because the pytest11
-# entry point and the collection hook reference it there directly.
-from pytest_httpchain.plugin import ScenarioValidationWarning
+# Re-export the user-facing warning so consumers can filter it from the package
+# root. It lives in the leaf module ``warnings`` so this import (which runs on
+# any subpackage import) does not load the plugin/execution machinery.
+from pytest_httpchain.warnings import ScenarioValidationWarning
 
 __all__ = ["ScenarioValidationWarning"]

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/src/pytest_httpchain/carrier.py

@@ -1,7 +1,7 @@
 """Test execution engine for pytest-httpchain scenarios.
 
-``create_test_class`` turns a validated :class:`Scenario` into a dynamic pytest
-test class (a subclass of :class:`Carrier`), one ``test_NN - <stage name>``
+``create_test_class`` turns a validated `Scenario` into a dynamic pytest
+test class (a subclass of `Carrier`), one ``test_NN - <stage name>``
 method per stage, ordered by the ``order(i)`` marker so the stages run as a
 chain. Each scenario gets its own subclass; the per-scenario mutable state
 (``client``, ``global_context``, ``aborted``, ``last_request``/``last_response``,
@@ -10,7 +10,7 @@ subclass dict, so the stage methods — which are classmethods operating on
 ``cls`` — share one running context across the chain while different scenarios
 stay isolated from each other.
 
-Per stage, :meth:`Carrier.execute_stage` gates on the abort/``always_run`` flow,
+Per stage, `Carrier.execute_stage` gates on the abort/``always_run`` flow,
 layers fixtures and substitutions over the global context, expands any
 ``parallel`` config into iterations (sequential or thread-pooled, optionally
 rate limited), executes the HTTP request via httpx, runs the response
@@ -41,7 +41,8 @@ import jsonschema
 import pytest
 from pydantic import ValidationError
 from pyrate_limiter import Duration, Limiter, Rate
-from pytest_httpchain_models import (
+
+from pytest_httpchain.models import (
     Base64Body,
     BinaryBody,
     CombinationsParameter,
@@ -67,10 +68,10 @@ from pytest_httpchain_models import (
     XmlBody,
     check_json_schema,
 )
-from pytest_httpchain_templates import TemplatesError, walk
-from pytest_httpchain_userfunc import UserFunctionError
+from pytest_httpchain.templates import TemplatesError, walk
+from pytest_httpchain.userfunc import UserFunctionError
 
-from .exceptions import RequestError, SaveError, StageExecutionError, VerificationError
+from .errors import RequestError, SaveError, StageExecutionError, VerificationError
 from .utils import call_user_function, make_marker, process_substitutions
 
 logger = logging.getLogger(__name__)
@@ -98,6 +99,13 @@ class Carrier:
     It manages the shared state, context, and execution flow for all stages in a test scenario.
     """
 
+    # These ClassVars are placeholders: create_test_class() overrides every one of
+    # them in each per-scenario subclass dict (see the bottom of this module), so
+    # the values here are never the ones used at runtime — do NOT rely on the
+    # ChainMap()/None/[] defaults, and do NOT move this state to instance
+    # attributes: the stage methods are classmethods that share one running context
+    # across the chain via `cls`, while distinct scenarios stay isolated because
+    # each gets its own subclass.
     client: ClassVar[httpx.Client | None] = None
     aborted: ClassVar[bool] = False
     last_request: ClassVar[httpx.Request | None] = None
@@ -222,8 +230,11 @@ class Carrier:
     def _build_iteration_substitutions(parallel_config: Any) -> list[dict[str, Any]]:
         """Expand the (already template-resolved) parallel config into per-iteration
         substitution dicts: non-parallel -> a single empty dict; ``repeat`` -> N
-        empties; ``foreach`` -> the cross-product of its parameter steps (the same
-        algorithm pytest uses for the ``parametrize`` marker)."""
+        empties; ``foreach`` -> the cross-product of its parameter steps.
+
+        Like pytest's stacked ``parametrize`` marker this is a cross-product, but the
+        resulting iteration ORDER is the *reverse* of pytest's — do not assume the
+        two orders match."""
         iteration_substitutions: list[dict[str, Any]] = [{}]
         match parallel_config:
             case None:
@@ -232,13 +243,17 @@ class Carrier:
                 iteration_substitutions = [{} for _ in range(repeat_count)]
             case ParallelForeachConfig(foreach=foreach_steps):
                 for step in foreach_steps:
+                    # Comprehension clause order is load-bearing: the new values are the
+                    # OUTER loop and the accumulated dicts the INNER loop, which is what
+                    # produces the (reverse-of-pytest) ordering noted above. Swapping the
+                    # two `for` clauses silently changes the iteration order.
                     match step:
                         case IndividualParameter(individual=individual):
                             param_name = next(iter(individual.keys()))
                             values = individual[param_name]
                             iteration_substitutions = [{**existing, param_name: val} for val in values for existing in iteration_substitutions]
                         case CombinationsParameter(combinations=combinations):
-                            combos: list[dict[str, Any] | SimpleNamespace] = [vars(item) if isinstance(item, SimpleNamespace) else item for item in combinations]
+                            combos: list[dict[str, Any]] = [vars(item) if isinstance(item, SimpleNamespace) else item for item in combinations]
                             iteration_substitutions = [{**existing, **combo} for combo in combos for existing in iteration_substitutions]
         return iteration_substitutions
 
@@ -353,7 +368,7 @@ class Carrier:
     @classmethod
     def _execute_http_request(cls, request_kwargs: dict[str, Any]) -> httpx.Response:
         try:
-            return cls.client.request(**request_kwargs)
+            return cls.client.request(**request_kwargs)  # ty: ignore[unresolved-attribute]
         except httpx.TimeoutException as e:
             raise RequestError(f"HTTP request timed out: {e}") from e
         except httpx.ConnectError as e:
@@ -396,7 +411,7 @@ class Carrier:
                         if not isinstance(func_result, dict):
                             raise SaveError(f"Save function must return dict, got {type(func_result).__name__}")
 
-                        step_saved.update(func_result)
+                        step_saved.update(func_result)  # ty: ignore[no-matching-overload]
                     except SaveError:
                         raise
                     except UserFunctionError as e:
@@ -518,6 +533,15 @@ class Carrier:
 
     @classmethod
     def _wrap_factory_fixture(cls, fixture: Callable) -> Callable:
+        """Wrap a callable fixture so context-manager results are entered and tracked.
+
+        Not a pure pass-through: each call invokes ``fixture`` and, if the result is
+        a context manager, calls ``__enter__()`` and registers it on
+        ``cls.active_context_managers`` for LIFO teardown in ``teardown_class``.
+        Consequence: calling the wrapped value twice opens two resources (two
+        ``__enter__`` calls, two teardowns) — invoke it once per needed instance.
+        """
+
         def wrapped(*args, **kwargs):
             result = fixture(*args, **kwargs)
 
@@ -594,7 +618,9 @@ def create_test_class(scenario: Scenario, class_name: str, max_parallel_iteratio
     padding_width = len(str(total_stages - 1)) if total_stages > 0 else 1
 
     for i, stage in enumerate(scenario.stages):
-
+        # Factory captures `stage` by value (as stage_template) per iteration. Do NOT
+        # inline this into a closure over the loop variable `stage`: Python closes over
+        # the variable, not its value, so every stage method would run the LAST stage.
         def make_stage_method(stage_template: Stage) -> Callable:
             def call_execute_stage(self, **kwargs):
                 type(self).execute_stage(stage_template, kwargs)
@@ -636,7 +662,7 @@ def create_test_class(scenario: Scenario, class_name: str, max_parallel_iteratio
                         stage_method = parametrize_marker(stage_method)
 
         all_fixtures = ["self"] + list(dict.fromkeys(all_param_names + stage.fixtures + scenario.fixtures))
-        stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])  # type: ignore[assignment]
+        stage_method.__signature__ = inspect.Signature([inspect.Parameter(name, inspect.Parameter.POSITIONAL_OR_KEYWORD) for name in all_fixtures])  # ty: ignore[unresolved-attribute]
 
         all_marks = [f"order({i})"] + stage.marks
         for mark_str in all_marks:

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/src/pytest_httpchain/cli.py

@@ -1,14 +1,16 @@
 import enum
 import json
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated
+from typing import Annotated
 
 import typer
+from pydantic import ValidationError
 
-if TYPE_CHECKING:
-    from pytest_httpchain_models import Scenario
-
-    from pytest_httpchain.dataflow import DataFlow
+from pytest_httpchain.dataflow import DataFlow, analyze_dataflow
+from pytest_httpchain.jsonref import ReferenceResolverError, load_json
+from pytest_httpchain.models import Scenario
+from pytest_httpchain.schema import build_schema
+from pytest_httpchain.validation import ValidateResult, load_scenario, resolve_root_path, validate_scenario
 
 app = typer.Typer()
 
@@ -49,8 +51,6 @@ def validate(
     per file and exits non-zero if any file is invalid (or, with --strict, has any
     warnings).
     """
-    from pytest_httpchain.validation import ValidateResult, validate_scenario
-
     results = [
         (path, validate_scenario(path, ref_parent_traversal_depth=ref_parent_traversal_depth, root_path=root_path, deep=deep, syspaths=list(syspath or []))) for path in paths
     ]
@@ -87,8 +87,6 @@ def schema() -> None:
 
     Writes to stdout; redirect to a file (``pytest-httpchain schema > scenario.schema.json``).
     """
-    from pytest_httpchain.schema import build_schema
-
     typer.echo(json.dumps(build_schema(), indent=2, default=str))
 
 
@@ -99,10 +97,6 @@ def resolve(
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> None:
     """Resolve $ref/$include/$merge and print the merged scenario JSON to stdout."""
-    from pytest_httpchain_jsonref import ReferenceResolverError, load_json
-
-    from pytest_httpchain.validation import resolve_root_path
-
     try:
         data = load_json(
             scenario,
@@ -116,13 +110,8 @@ def resolve(
     typer.echo(json.dumps(data, indent=2, default=str))
 
 
-def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None) -> tuple["Scenario", dict]:
+def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None) -> tuple[Scenario, dict]:
     """Load + validate a scenario for show/graph, mapping failures to Exit(1)."""
-    from pydantic import ValidationError
-    from pytest_httpchain_jsonref import ReferenceResolverError
-
-    from pytest_httpchain.validation import load_scenario
-
     try:
         return load_scenario(path, root_path=root_path, ref_parent_traversal_depth=depth)
     except (ReferenceResolverError, json.JSONDecodeError, OSError) as e:
@@ -133,7 +122,7 @@ def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None)
         raise typer.Exit(1) from None
 
 
-def _render_show_text(path: Path, scenario: "Scenario", flow: "DataFlow") -> list[str]:
+def _render_show_text(path: Path, scenario: Scenario, flow: DataFlow) -> list[str]:
     producer_of: dict[tuple[int, str], int] = {}
     for edge in flow.edges:
         for var_name in edge.vars:
@@ -177,8 +166,6 @@ def show(
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> None:
     """Summarize a scenario's stages and variable data-flow."""
-    from pytest_httpchain.dataflow import analyze_dataflow
-
     sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth, root_path)
     flow = analyze_dataflow(sc, test_data)
 
@@ -195,7 +182,7 @@ def _mermaid_label(text: str) -> str:
     return text.replace('"', "'").replace("\n", " ")
 
 
-def _to_mermaid(flow: "DataFlow", direction: str = "TD") -> str:
+def _to_mermaid(flow: DataFlow, direction: str = "TD") -> str:
     lines = [f"flowchart {direction}"]
     if not flow.stages:
         lines.append("    %% (no stages)")
@@ -216,8 +203,6 @@ def graph(
     root_path: Annotated[Path | None, typer.Option("--root-path", help="Directory that constrains $ref resolution (default: nearest tests/ ancestor).")] = None,
 ) -> None:
     """Emit a Mermaid flowchart of the stage data-flow."""
-    from pytest_httpchain.dataflow import analyze_dataflow
-
     sc, test_data = _load_for_inspection(scenario, ref_parent_traversal_depth, root_path)
     flow = analyze_dataflow(sc, test_data)
     typer.echo(_to_mermaid(flow, direction.value))

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/src/pytest_httpchain/dataflow.py

@@ -9,11 +9,11 @@ stages, and the producer -> consumer edges between stages.
 from typing import Any
 
 from pydantic import BaseModel
-from pytest_httpchain_models import Scenario
 
+from pytest_httpchain.models import Scenario
 from pytest_httpchain.validation import (
-    _parameter_names,
     extract_template_variables,
+    parameter_names,
     raw_stages,
     saved_in_stage,
     stage_defined_names,
@@ -90,7 +90,7 @@ def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
         # always_run resolves before stage substitutions exist, so only fixtures
         # and parametrize parameters shadow an earlier save there.
         always_run_refs = extract_template_variables(raw.get("always_run"))
-        always_run_local = set(stage.fixtures) | _parameter_names(stage.parametrize) | scenario_fixture_names
+        always_run_local = set(stage.fixtures) | parameter_names(stage.parametrize) | scenario_fixture_names
         consumes |= {name for name in always_run_refs if name in cumulative_saves and name not in always_run_local}
 
         by_producer: dict[int, list[str]] = {}

pytest_httpchain-0.8.0/src/pytest_httpchain/exceptions.py → pytest_httpchain-0.9.0/src/pytest_httpchain/errors.py

@@ -1,5 +1,8 @@
 import httpx
-from pytest_httpchain_core import HttpChainError
+
+
+class HttpChainError(Exception):
+    """Base exception for all pytest-httpchain errors."""
 
 
 class StageExecutionError(HttpChainError):

{pytest_httpchain-0.8.0 → pytest_httpchain-0.9.0}/src/pytest_httpchain/har_writer.py

@@ -4,8 +4,10 @@ This module converts httpx Request/Response objects to HAR 1.2 format
 and writes them to files for external analysis.
 """
 
+import base64
 import json
 from datetime import UTC, datetime
+from importlib.metadata import version
 from pathlib import Path
 from typing import Any
 from urllib.parse import parse_qs, urlparse
@@ -16,14 +18,12 @@ import httpx
 def _get_version() -> str:
     """Get pytest-httpchain version for HAR creator info."""
     try:
-        from importlib.metadata import version
-
         return version("pytest-httpchain")
     except Exception:
         return "unknown"
 
 
-def _format_cookies(cookies: httpx.Cookies) -> list[dict[str, Any]]:
+def _format_cookies(cookies: httpx.Cookies) -> list[dict[str, str]]:
     """Convert httpx Cookies to HAR cookie format."""
     result = []
     for name, value in cookies.items():
@@ -71,8 +71,6 @@ def _format_post_data(request: httpx.Request) -> dict[str, Any] | None:
     try:
         text = request.content.decode("utf-8")
     except UnicodeDecodeError:
-        import base64
-
         text = base64.b64encode(request.content).decode("ascii")
         return {
             "mimeType": mime_type,
@@ -106,8 +104,6 @@ def _format_response_content(response: httpx.Response) -> dict[str, Any]:
         try:
             content["text"] = response.content.decode("utf-8")
         except UnicodeDecodeError:
-            import base64
-
             content["text"] = base64.b64encode(response.content).decode("ascii")
             content["encoding"] = "base64"
 
@@ -118,7 +114,7 @@ def _calculate_headers_size(headers: httpx.Headers) -> int:
     """Calculate approximate size of headers in bytes."""
     size = 0
     for name, value in headers.items():
-        size += len(name) + len(value) + 4
+        size += len(name) + len(value) + 4  # ": " (2) + CRLF (2) per header line
     return size
 
 
@@ -194,7 +190,7 @@ def request_response_to_har_entry(
 
     post_data = _format_post_data(request)
     if post_data:
-        entry["request"]["postData"] = post_data
+        entry["request"]["postData"] = post_data  # ty: ignore[invalid-assignment]
 
     return entry
 

pytest_httpchain-0.9.0/src/pytest_httpchain/jsonref/__init__.py

@@ -0,0 +1,24 @@
+"""JSON reference resolution for pytest-httpchain.
+
+This package provides JSON loading with reference resolution and deep merging
+support. References use the ``$include``/``$merge`` directives (preferred, they
+avoid conflicts with VS Code's JSON Schema validation) or the legacy ``$ref``;
+all three behave identically. References can point to other local files or to
+JSON pointers within the same document, with security controls for parent
+directory traversal.
+
+Example:
+    >>> from pathlib import Path
+    >>> from pytest_httpchain.jsonref import load_json
+    >>> # base.json contains {"timeout": 30}; the scenario merges it in:
+    >>> #   {"$include": "base.json", "url": "https://example.com"}
+    >>> data = load_json(Path("test_scenario.http.json"))
+"""
+
+from .exceptions import ReferenceResolverError
+from .loader import load_json
+
+__all__ = [
+    "load_json",
+    "ReferenceResolverError",
+]

pytest_httpchain-0.9.0/src/pytest_httpchain/jsonref/exceptions.py

@@ -0,0 +1,5 @@
+from pytest_httpchain.errors import HttpChainError
+
+
+class ReferenceResolverError(HttpChainError):
+    """Exception for reference resolution errors."""

pytest_httpchain-0.9.0/src/pytest_httpchain/jsonref/loader.py

@@ -0,0 +1,30 @@
+"""JSON file loading with reference resolution."""
+
+from pathlib import Path
+from typing import Any
+
+from pytest_httpchain.jsonref.plumbing.reference import ReferenceResolver
+
+
+def load_json(path: Path, max_parent_traversal_depth: int = 3, root_path: Path | None = None) -> dict[str, Any]:
+    """Load JSON from file and resolve all $include/$merge/$ref statements with circular reference protection.
+
+    All three directives ($include, $merge, $ref) work identically. $include and $merge are preferred
+    as they avoid conflicts with VS Code's JSON Schema validation (which treats $ref specially).
+
+    "$schema" keys pass through untouched — whether and where to tolerate them
+    is the consumer's decision (pytest-httpchain's models drop them during validation).
+
+    Args:
+        path: Path to the JSON file to load
+        max_parent_traversal_depth: Maximum number of parent directory traversals allowed in reference paths
+        root_path: Optional root directory for resolving references (e.g., pytest's rootdir)
+
+    Returns:
+        Dictionary with all $include/$ref statements resolved
+
+    Raises:
+        ReferenceResolverError: If the file cannot be loaded or parsed, if merge conflicts occur, or if circular references are detected
+    """
+    resolver = ReferenceResolver(max_parent_traversal_depth, root_path)
+    return resolver.resolve_file(path)