jentic-openapi-traverse 1.0.0a22__py3-none-any.whl → 1.0.0a23__py3-none-any.whl

jentic/apitools/openapi/traverse/datamodels/low/__init__.py

@@ -0,0 +1,14 @@
+"""Low-level OpenAPI datamodel traversal."""
+
+from .merge import merge_visitors
+from .path import NodePath
+from .traversal import BREAK, DataModelLowVisitor, traverse
+
+
+__all__ = [
+    "DataModelLowVisitor",
+    "traverse",
+    "BREAK",
+    "NodePath",
+    "merge_visitors",
+]

jentic/apitools/openapi/traverse/datamodels/low/introspection.py

@@ -0,0 +1,114 @@
+"""Utilities for introspecting datamodel fields."""
+
+from dataclasses import is_dataclass
+from typing import Any
+
+from jentic.apitools.openapi.datamodels.low.fields import fixed_fields, patterned_fields
+from jentic.apitools.openapi.datamodels.low.sources import (
+    FieldSource,
+    KeySource,
+    ValueSource,
+)
+
+
+__all__ = [
+    "get_traversable_fields",
+    "unwrap_value",
+    "is_datamodel_node",
+]
+
+
+# Cache of field names to check per class type
+# {Info: ["title", "description", "contact", ...], Operation: [...], ...}
+_FIELD_NAMES_CACHE: dict[type, list[str]] = {}
+
+
+def get_traversable_fields(node):
+    """
+    Get all fields that should be traversed in a datamodel node.
+
+    Uses field metadata (fixed_field, patterned_field) to identify OpenAPI
+    specification fields. This leverages the explicit field marking system
+    from the datamodels package.
+
+    Caches field names per class type for performance.
+
+    Args:
+        node: Datamodel node (dataclass instance)
+
+    Returns:
+        List of (field_name, field_value) tuples
+    """
+    if not is_dataclass(node):
+        return []
+
+    node_class = type(node)
+
+    # Get or compute field names for this class
+    if node_class not in _FIELD_NAMES_CACHE:
+        # Get all OpenAPI spec fields (fixed + patterned)
+        fixed = fixed_fields(node_class)
+        patterned = patterned_fields(node_class)
+        # Combine and extract field names
+        field_names = list(fixed.keys()) + list(patterned.keys())
+        _FIELD_NAMES_CACHE[node_class] = field_names
+
+    # Use cached field names
+    result = []
+    for field_name in _FIELD_NAMES_CACHE[node_class]:
+        value = getattr(node, field_name, None)
+
+        # Skip None values
+        if value is None:
+            continue
+
+        # Check if it's traversable
+        unwrapped = unwrap_value(value)
+
+        # Skip scalar primitives
+        if isinstance(unwrapped, (str, int, float, bool, type(None))):
+            continue
+
+        result.append((field_name, value))
+
+    return result
+
+
+def unwrap_value(value: Any) -> Any:
+    """
+    Unwrap FieldSource/ValueSource/KeySource to get actual value.
+
+    Wrapper types (FieldSource, ValueSource, KeySource) are used to preserve
+    source location information for field values. This function extracts the
+    actual value from these wrappers.
+
+    This excludes datamodel nodes like Example which may have .value field
+    but are not wrapper types.
+
+    Args:
+        value: Potentially wrapped value
+
+    Returns:
+        Unwrapped value, or original if not wrapped
+    """
+    # Check if it's a wrapper type
+    if isinstance(value, (FieldSource, ValueSource, KeySource)):
+        return value.value
+    return value
+
+
+def is_datamodel_node(value):
+    """
+    Check if value is a low-level datamodel object.
+
+    Low-level datamodels are distinguished by having a root_node field,
+    which contains the YAML source location information. This excludes
+    wrapper types (FieldSource, ValueSource, KeySource) and other dataclasses.
+
+    Args:
+        value: Value to check
+
+    Returns:
+        True if it's a low-level datamodel node, False otherwise
+    """
+    return is_dataclass(value) and hasattr(value, "root_node")

jentic/apitools/openapi/traverse/datamodels/low/merge.py

@@ -0,0 +1,111 @@
+"""Visitor merging utilities (ApiDOM pattern)."""
+
+from .path import NodePath
+from .traversal import BREAK
+
+
+__all__ = ["merge_visitors"]
+
+
+def merge_visitors(*visitors) -> object:
+    """
+    Merge multiple visitors into one composite visitor (ApiDOM semantics).
+
+    Each visitor maintains independent state:
+    - If visitor[i] returns False, only that visitor skips children (resumes when leaving)
+    - If visitor[i] returns BREAK, only that visitor stops permanently
+    - Other visitors continue normally
+
+    This matches ApiDOM's per-visitor control model where each visitor can
+    independently skip subtrees or stop without affecting other visitors.
+
+    Args:
+        *visitors: Visitor objects (with visit_* methods)
+
+    Returns:
+        A new visitor object that runs all visitors with independent state
+
+    Example:
+        security_check = SecurityCheckVisitor()
+        counter = OperationCounterVisitor()
+        validator = SchemaValidatorVisitor()
+
+        # Each visitor can skip/break independently
+        merged = merge_visitors(security_check, counter, validator)
+        traverse(doc, merged)
+
+        # If security_check.visit_PathItem returns False:
+        # - security_check skips PathItem's children
+        # - counter and validator still visit children normally
+    """
+
+    class MergedVisitor:
+        """Composite visitor with per-visitor state tracking (ApiDOM pattern)."""
+
+        def __init__(self, visitors):
+            self.visitors = visitors
+            # State per visitor: None = active, NodePath = skipping, BREAK = stopped
+            self._skipping_state: list[NodePath | object | None] = [None] * len(visitors)
+
+        def _is_active(self, visitor_idx):
+            """Check if visitor is active (not skipping or stopped)."""
+            return self._skipping_state[visitor_idx] is None
+
+        def _is_skipping_node(self, visitor_idx, path):
+            """Check if we're leaving the exact node this visitor skipped."""
+            state = self._skipping_state[visitor_idx]
+            if state is None or state is BREAK:
+                return False
+            # At this point, state must be a NodePath
+            # Compare node identity (not equality)
+            assert isinstance(state, NodePath)
+            return state.node is path.node
+
+        def __getattr__(self, name):
+            """
+            Dynamically handle visit_* method calls.
+
+            Maintains per-visitor state for skip/break control.
+
+            Args:
+                name: Method name being called
+
+            Returns:
+                Callable that merges visitor results with state tracking
+
+            Raises:
+                AttributeError: If not a visit_* method
+            """
+            if not name.startswith("visit"):
+                raise AttributeError(f"'{self.__class__.__name__}' has no attribute '{name}'")
+
+            # Determine if this is a leave hook
+            is_leave_hook = name.startswith("visit_leave")
+
+            def merged_visit_method(path: NodePath):
+                for i, visitor in enumerate(self.visitors):
+                    if is_leave_hook:
+                        # Leave hook: only call if visitor is active
+                        if self._is_active(i) and hasattr(visitor, name):
+                            result = getattr(visitor, name)(path)
+                            if result is BREAK:
+                                self._skipping_state[i] = BREAK  # Stop this visitor
+                        # Resume visitor if leaving the skipped node (don't call leave hook)
+                        elif self._is_skipping_node(i, path):
+                            self._skipping_state[i] = None  # Resume for next nodes
+                    else:
+                        # Enter/visit hook: only call if visitor is active
+                        if self._is_active(i) and hasattr(visitor, name):
+                            result = getattr(visitor, name)(path)
+
+                            if result is BREAK:
+                                self._skipping_state[i] = BREAK  # Stop this visitor
+                            elif result is False:
+                                self._skipping_state[i] = path  # Skip descendants
+
+                # Never return BREAK or False - let traversal continue for all visitors
+                return None
+
+            return merged_visit_method
+
+    return MergedVisitor(visitors)

jentic/apitools/openapi/traverse/datamodels/low/path.py

@@ -0,0 +1,145 @@
+"""NodePath context for traversal."""
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from jsonpointer import JsonPointer
+
+
+__all__ = ["NodePath"]
+
+
+@dataclass(frozen=True, slots=True)
+class NodePath:
+    """
+    Context for a node during traversal.
+
+    Provides access to node, parent, ancestry, and path formatting.
+    Supports Babel-style sub-traversal via traverse() method.
+    """
+
+    node: Any  # Current datamodel object
+    parent: Any | None  # Parent datamodel object
+    parent_field: str | None  # Field name in parent
+    parent_key: str | int | None  # Key if parent field is list/dict
+    ancestors: tuple[Any, ...]  # Tuple of ancestor nodes (root first)
+
+    def create_child(
+        self, node: Any, parent_field: str, parent_key: str | int | None
+    ) -> "NodePath":
+        """
+        Create a child NodePath from this path.
+
+        Helper for creating child paths during traversal.
+
+        Args:
+            node: Child node
+            parent_field: Field name in current node
+            parent_key: Key if field is list/dict
+
+        Returns:
+            New NodePath for the child
+        """
+        return NodePath(
+            node=node,
+            parent=self.node,
+            parent_field=parent_field,
+            parent_key=parent_key,
+            ancestors=self.ancestors + (self.node,),
+        )
+
+    def traverse(self, visitor) -> None:
+        """
+        Traverse from this node as root (Babel pattern).
+
+        Allows convenient sub-traversal with a different visitor.
+
+        Args:
+            visitor: Visitor object with visit_* methods
+
+        Example:
+            class PathItemVisitor:
+                def visit_PathItem(self, path):
+                    # Only traverse GET operations
+                    if path.node.get:
+                        operation_visitor = OperationOnlyVisitor()
+                        get_path = path.create_child(
+                            node=path.node.get.value,
+                            parent_field="get",
+                            parent_key=None
+                        )
+                        get_path.traverse(operation_visitor)
+                    return False  # Skip automatic traversal
+        """
+        from .traversal import traverse
+
+        traverse(self.node, visitor)
+
+    def format_path(
+        self, *, path_format: Literal["jsonpointer", "jsonpath"] = "jsonpointer"
+    ) -> str:
+        """
+        Format path as RFC 6901 JSON Pointer or RFC 9535 Normalized JSONPath.
+
+        Args:
+            path_format: Output format - "jsonpointer" (default) or "jsonpath"
+
+        Returns:
+            JSONPointer string like "/paths/~1pets/get/responses/200"
+            or Normalized JSONPath like "$['paths']['/pets']['get']['responses']['200']"
+
+        Examples (jsonpointer):
+            "" (root)
+            "/info"
+            "/paths/~1pets/get"
+            "/paths/~1users~1{id}/parameters/0"
+            "/components/schemas/User/properties/name"
+
+        Examples (jsonpath):
+            "$" (root)
+            "$['info']"
+            "$['paths']['/pets']['get']"
+            "$['paths']['/users/{id}']['parameters'][0]"
+            "$['components']['schemas']['User']['properties']['name']"
+        """
+        # Root node
+        if not self.ancestors and self.parent_field is None:
+            return "$" if path_format == "jsonpath" else ""
+
+        # Build parts list
+        parts: list[str | int] = []
+
+        # This is a simplified implementation that only captures one level
+        # A full implementation would need to walk back through ancestors
+        if self.parent_field:
+            parts.append(self.parent_field)
+
+        if self.parent_key is not None:
+            # Both int (array index) and str (object key) work with from_parts
+            parts.append(self.parent_key)
+
+        if path_format == "jsonpath":
+            # RFC 9535 Normalized JSONPath: $['field'][index]['key']
+            segments = ["$"]
+            for part in parts:
+                if isinstance(part, int):
+                    # Array index: $[0]
+                    segments.append(f"[{part}]")
+                else:
+                    # Member name: $['field']
+                    # Escape single quotes in the string
+                    escaped = str(part).replace("'", "\\'")
+                    segments.append(f"['{escaped}']")
+            return "".join(segments)
+
+        # RFC 6901 JSON Pointer
+        return JsonPointer.from_parts(parts).path
+
+    def get_root(self) -> Any:
+        """
+        Get the root node of the tree.
+
+        Returns:
+            Root datamodel object
+        """
+        return self.ancestors[0] if self.ancestors else self.node

jentic/apitools/openapi/traverse/datamodels/low/traversal.py

@@ -0,0 +1,235 @@
+"""Core traversal functionality for low-level OpenAPI datamodels."""
+
+from .introspection import get_traversable_fields, is_datamodel_node, unwrap_value
+from .path import NodePath
+
+
+__all__ = ["DataModelLowVisitor", "traverse", "BREAK"]
+
+
+class _BreakType: ...
+
+
+BREAK = _BreakType()
+
+
+class DataModelLowVisitor:
+    """
+    Optional base class for OpenAPI datamodel visitors.
+
+    You don't need to inherit from this class - just implement visit_* methods.
+    Inheritance is optional and provides no functionality - use for organizational purposes only.
+
+    Visitor Method Signatures:
+        Generic hooks (fire for ALL nodes):
+        - visit_enter(path: NodePath) -> None | False | BREAK
+        - visit_leave(path: NodePath) -> None | False | BREAK
+
+        Class-specific hooks (fire for matching node types):
+        - visit_ClassName(path: NodePath) -> None | False | BREAK
+        - visit_enter_ClassName(path: NodePath) -> None | False | BREAK
+        - visit_leave_ClassName(path: NodePath) -> None | False | BREAK
+
+    Dispatch Order:
+        1. visit_enter(path) - generic enter
+        2. visit_enter_ClassName(path) - specific enter
+        3. visit_ClassName(path) - main visitor
+        4. [child traversal - automatic unless False returned]
+        5. visit_leave_ClassName(path) - specific leave
+        6. visit_leave(path) - generic leave
+
+    Return Values:
+        - None: Continue traversal normally (children visited automatically)
+        - False: Skip visiting children of this node
+        - BREAK: Stop entire traversal immediately
+
+    Example (with enter/leave hooks):
+        class MyVisitor(DataModelLowVisitor):  # Optional inheritance
+            def visit_enter_Operation(self, path):
+                print(f"Entering: {path.format_path()}")
+
+            def visit_leave_Operation(self, path):
+                print(f"Leaving: {path.format_path()}")
+
+        class SimpleVisitor:  # No inheritance (duck typing works too)
+            def visit_Operation(self, path):
+                print(f"Found: {path.format_path()}")
+                # Children automatically visited
+    """
+
+    pass
+
+
+def traverse(root, visitor) -> None:
+    """
+    Traverse OpenAPI datamodel tree using visitor pattern.
+
+    The visitor can be any object with visit_* methods (duck typing).
+    Optionally inherit from DataModelLowVisitor for organizational purposes.
+
+    Children are automatically traversed unless a visitor method returns False.
+    Use enter/leave hooks for pre/post traversal logic.
+
+    Args:
+        root: Root datamodel object (OpenAPI30, OpenAPI31, or any datamodel node)
+        visitor: Object with visit_* methods
+
+    Example:
+        # Using enter/leave hooks
+        class MyVisitor(DataModelLowVisitor):
+            def visit_enter_Operation(self, path):
+                print(f"Entering operation: {path.format_path()}")
+
+            def visit_leave_Operation(self, path):
+                print(f"Leaving operation: {path.format_path()}")
+
+        # Simple visitor (duck typing - no inheritance needed)
+        class SimpleVisitor:
+            def visit_Operation(self, path):
+                print(f"Found operation: {path.format_path()}")
+                # Children automatically visited
+
+        doc = parser.parse(..., return_type=DataModelLow)
+        traverse(doc, MyVisitor())
+        traverse(doc, SimpleVisitor())
+    """
+    # Create initial root path
+    initial_path = NodePath(
+        node=root,
+        parent=None,
+        parent_field=None,
+        parent_key=None,
+        ancestors=(),
+    )
+
+    # Start traversal
+    _visit_node(visitor, initial_path)
+
+
+def _default_traverse_children(visitor, path: NodePath) -> _BreakType | None:
+    """
+    Internal child traversal logic.
+
+    Iterates through traversable fields and visits datamodel children.
+    Called automatically during traversal.
+
+    Args:
+        visitor: Visitor object with visit_* methods
+        path: Current node path
+
+    Returns:
+        BREAK to stop traversal, None otherwise
+    """
+    # Get all traversable fields
+    for field_name, field_value in get_traversable_fields(path.node):
+        unwrapped = unwrap_value(field_value)
+
+        # Handle single datamodel nodes
+        if is_datamodel_node(unwrapped):
+            child_path = path.create_child(node=unwrapped, parent_field=field_name, parent_key=None)
+            result = _visit_node(visitor, child_path)
+            if result is BREAK:
+                return BREAK
+
+        # Handle lists
+        elif isinstance(unwrapped, list):
+            for idx, item in enumerate(unwrapped):
+                if is_datamodel_node(item):
+                    child_path = path.create_child(
+                        node=item, parent_field=field_name, parent_key=idx
+                    )
+                    result = _visit_node(visitor, child_path)
+                    if result is BREAK:
+                        return BREAK
+
+        # Handle dicts
+        elif isinstance(unwrapped, dict):
+            for key, value in unwrapped.items():
+                unwrapped_key = unwrap_value(key)
+                unwrapped_value = unwrap_value(value)
+
+                if is_datamodel_node(unwrapped_value):
+                    # Dict keys should be str after unwrapping (field names, paths, status codes, etc.)
+                    assert isinstance(unwrapped_key, (str, int)), (
+                        f"Expected str or int key, got {type(unwrapped_key)}"
+                    )
+                    child_path = path.create_child(
+                        node=unwrapped_value,
+                        parent_field=field_name,
+                        parent_key=unwrapped_key,
+                    )
+                    result = _visit_node(visitor, child_path)
+                    if result is BREAK:
+                        return BREAK
+
+    return None
+
+
+def _visit_node(visitor, path: NodePath) -> _BreakType | None:
+    """
+    Visit a single node with the visitor.
+
+    Handles enter/main/leave dispatch and control flow.
+    Duck typed - works with any object that has visit_* methods.
+
+    Args:
+        visitor: Visitor object with visit_* methods
+        path: Current node path
+
+    Returns:
+        BREAK to stop traversal, None otherwise
+    """
+    node_class = path.node.__class__.__name__
+
+    # Generic enter hook: visit_enter (fires for ALL nodes)
+    if hasattr(visitor, "visit_enter"):
+        result = visitor.visit_enter(path)
+        if result is BREAK:
+            return BREAK
+        if result is False:
+            return None  # Skip children, but continue traversal
+
+    # Try enter hook: visit_enter_ClassName
+    enter_method = f"visit_enter_{node_class}"
+    if hasattr(visitor, enter_method):
+        result = getattr(visitor, enter_method)(path)
+        if result is BREAK:
+            return BREAK
+        if result is False:
+            return None  # Skip children, but continue traversal
+
+    # Try main visitor: visit_ClassName
+    visit_method = f"visit_{node_class}"
+    skip_auto_traverse = False
+
+    if hasattr(visitor, visit_method):
+        result = getattr(visitor, visit_method)(path)
+        # Only care about BREAK and False:
+        # - BREAK: stop entire traversal
+        # - False: skip children of this node
+        # - Any other value (None, True, etc.): continue normally
+        if result is BREAK:
+            return BREAK
+        if result is False:
+            skip_auto_traverse = True
+
+    # Automatic child traversal (unless explicitly skipped)
+    if not skip_auto_traverse:
+        result = _default_traverse_children(visitor, path)
+        if result is BREAK:
+            return BREAK
+
+    # Try leave hook: visit_leave_ClassName
+    leave_method = f"visit_leave_{node_class}"
+    if hasattr(visitor, leave_method):
+        result = getattr(visitor, leave_method)(path)
+        if result is BREAK:
+            return BREAK
+
+    # Generic leave hook: visit_leave (fires for ALL nodes)
+    if hasattr(visitor, "visit_leave"):
+        result = visitor.visit_leave(path)
+        if result is BREAK:
+            return BREAK
+
+    return None

jentic_openapi_traverse-1.0.0a23.dist-info/METADATA

@@ -0,0 +1,491 @@
+Metadata-Version: 2.4
+Name: jentic-openapi-traverse
+Version: 1.0.0a23
+Summary: Jentic OpenAPI Traversal Utilities
+Author: Jentic
+Author-email: Jentic <hello@jentic.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: jentic-openapi-datamodels~=1.0.0a23
+Requires-Dist: jsonpointer~=3.0.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/jentic/jentic-openapi-tools
+Description-Content-Type: text/markdown
+
+# jentic-openapi-traverse
+
+A Python library for traversing OpenAPI documents. This package is part of the Jentic OpenAPI Tools ecosystem and provides two types of traversal:
+
+1. **Datamodel Traversal** - OpenAPI-aware semantic traversal with visitor pattern
+2. **JSON Traversal** - Generic depth-first traversal of JSON-like structures
+
+## Installation
+
+```bash
+pip install jentic-openapi-traverse
+```
+
+**Prerequisites:**
+- Python 3.11+
+
+---
+
+## Datamodel Traversal
+
+OpenAPI-aware semantic traversal using the visitor pattern. Works with low-level datamodels from `jentic-openapi-datamodels` package, preserving source location information and providing structured access to OpenAPI nodes.
+
+### Quick Start
+
+```python
+from jentic.apitools.openapi.parser.core import OpenAPIParser
+from jentic.apitools.openapi.traverse.datamodels.low import traverse, DataModelLowVisitor
+
+# Parse OpenAPI document
+parser = OpenAPIParser("datamodel-low")
+doc = parser.parse("file:///path/to/openapi.yaml")
+
+# Create visitor
+class OperationCollector(DataModelLowVisitor):
+    def __init__(self):
+        self.operations = []
+
+    def visit_Operation(self, path):
+        self.operations.append({
+            "path": path.format_path(path_format="jsonpointer"),
+            "operation_id": path.node.operation_id.value if path.node.operation_id else None
+        })
+
+# Traverse
+visitor = OperationCollector()
+traverse(doc, visitor)
+
+print(f"Found {len(visitor.operations)} operations")
+```
+
+### Visitor Pattern
+
+The datamodel traversal uses a flexible visitor pattern with multiple hook types:
+
+#### Hook Methods
+
+**Generic hooks** (fire for ALL nodes):
+- `visit_enter(path)` - Called before processing any node
+- `visit_leave(path)` - Called after processing any node and its children
+
+**Class-specific hooks** (fire for matching node types):
+- `visit_ClassName(path)` - Main visitor for specific node type
+- `visit_enter_ClassName(path)` - Called before visit_ClassName
+- `visit_leave_ClassName(path)` - Called after children are visited
+
+#### Dispatch Order
+
+For each node, hooks are called in this order:
+1. `visit_enter(path)` - generic enter
+2. `visit_enter_ClassName(path)` - specific enter
+3. `visit_ClassName(path)` - main visitor
+4. [child traversal - automatic unless skipped]
+5. `visit_leave_ClassName(path)` - specific leave
+6. `visit_leave(path)` - generic leave
+
+#### Control Flow
+
+Visitor methods control traversal by their return value:
+
+- `None` (or no return) - **Continue normally** (children visited automatically)
+- `False` - **Skip children** of this node (but continue to siblings)
+- `BREAK` - **Stop entire traversal** immediately
+
+```python
+from jentic.apitools.openapi.traverse.datamodels.low import traverse, BREAK
+
+class ControlFlowExample:
+    def visit_PathItem(self, path):
+        if path.parent_key == "/internal":
+            return False  # Skip internal paths and their children
+
+    def visit_Operation(self, path):
+        if some_error_condition:
+            return BREAK  # Stop entire traversal
+```
+
+### NodePath Context
+
+Every visitor method receives a `NodePath` object with context about the current node:
+
+```python
+class PathInspector:
+    def visit_Operation(self, path):
+        # Current node
+        print(f"Node: {path.node.__class__.__name__}")
+
+        # Parent information
+        print(f"Parent field: {path.parent_field}")  # e.g., "get", "post"
+        print(f"Parent key: {path.parent_key}")      # e.g., "/users" (for path items)
+
+        # Ancestry
+        print(f"Ancestors: {len(path.ancestors)}")
+        root = path.get_root()
+
+        # Path formatting
+        print(f"JSONPointer: {path.format_path()}")                      # /paths/~1users/get
+        print(f"JSONPath: {path.format_path(path_format='jsonpath')}")   # $['paths']['/users']['get']
+```
+
+### Enter/Leave Hooks
+
+Use enter/leave hooks for pre/post processing logic:
+
+```python
+class DepthTracker(DataModelLowVisitor):
+    def __init__(self):
+        self.current_depth = 0
+        self.max_depth = 0
+
+    def visit_enter(self, path):
+        self.current_depth += 1
+        self.max_depth = max(self.max_depth, self.current_depth)
+        print("  " * self.current_depth + f"Entering {path.node.__class__.__name__}")
+
+    def visit_leave(self, path):
+        print("  " * self.current_depth + f"Leaving {path.node.__class__.__name__}")
+        self.current_depth -= 1
+```
+
+### Examples
+
+#### Collecting All Schemas
+
+```python
+class SchemaCollector(DataModelLowVisitor):
+    def __init__(self):
+        self.schemas = {}
+
+    def visit_Schema(self, path):
+        schema_name = path.parent_key if path.parent_field == "schemas" else None
+        if schema_name:
+            self.schemas[schema_name] = path.node
+
+visitor = SchemaCollector()
+traverse(doc, visitor)
+print(f"Found {len(visitor.schemas)} schemas")
+```
+
+#### Validating Security Requirements
+
+```python
+class SecurityValidator(DataModelLowVisitor):
+    def __init__(self):
+        self.errors = []
+
+    def visit_Operation(self, path):
+        if not path.node.security:
+            self.errors.append(f"Missing security at {path.format_path()}")
+
+    def visit_SecurityRequirement(self, path):
+        # Validate security requirement
+        if not path.node.schemes:
+            self.errors.append(f"Empty security requirement at {path.format_path()}")
+
+visitor = SecurityValidator()
+traverse(doc, visitor)
+if visitor.errors:
+    for error in visitor.errors:
+        print(f"Security error: {error}")
+```
+
+#### Finding Deprecated Operations
+
+```python
+class DeprecatedFinder:
+    def __init__(self):
+        self.deprecated_ops = []
+
+    def visit_Operation(self, path):
+        if path.node.deprecated and path.node.deprecated.value:
+            self.deprecated_ops.append({
+                "path": path.format_path(),
+                "operation_id": path.node.operation_id.value if path.node.operation_id else None,
+                "method": path.parent_field
+            })
+        return False  # Skip children (we don't need to go deeper)
+
+visitor = DeprecatedFinder()
+traverse(doc, visitor)
+```
+
+#### Early Exit on Error
+
+```python
+class ErrorDetector(DataModelLowVisitor):
+    def __init__(self):
+        self.error_found = False
+        self.error_location = None
+
+    def visit_Operation(self, path):
+        if not path.node.responses:
+            self.error_found = True
+            self.error_location = path.format_path()
+            return BREAK  # Stop traversal immediately
+```
+
+### Merging Multiple Visitors
+
+Run multiple visitors in a single traversal pass (parallel visitation) using `merge_visitors`:
+
+```python
+from jentic.apitools.openapi.traverse.datamodels.low import merge_visitors
+
+# Create separate visitors
+schema_collector = SchemaCollector()
+security_validator = SecurityValidator()
+deprecated_finder = DeprecatedFinder()
+
+# Merge and traverse once
+merged = merge_visitors(schema_collector, security_validator, deprecated_finder)
+traverse(doc, merged)
+
+# Each visitor maintains independent state
+print(f"Schemas: {len(schema_collector.schemas)}")
+print(f"Security errors: {len(security_validator.errors)}")
+print(f"Deprecated: {len(deprecated_finder.deprecated_ops)}")
+```
+
+**Per-Visitor Control Flow:**
+- Each visitor can independently skip subtrees or break
+- If `visitor1` returns `False`, only `visitor1` skips children
+- Other visitors continue normally
+- This follows ApiDOM's per-visitor semantics
+
+### Duck Typing
+
+You don't need to inherit from `DataModelLowVisitor` - duck typing works:
+
+```python
+class SimpleCounter:  # No inheritance
+    def __init__(self):
+        self.count = 0
+
+    def visit_Operation(self, path):
+        self.count += 1
+
+visitor = SimpleCounter()
+traverse(doc, visitor)
+```
+
+The `DataModelLowVisitor` base class is optional and provides no functionality - it's purely for organizational purposes.
+
+### API Reference
+
+#### `traverse(root, visitor) -> None`
+
+Traverse OpenAPI datamodel tree using visitor pattern.
+
+**Parameters:**
+- `root` - Root datamodel object (OpenAPI30, OpenAPI31, or any datamodel node)
+- `visitor` - Object with `visit_*` methods (duck typing)
+
+**Returns:**
+- None (traversal is side-effect based)
+
+#### `BREAK`
+
+Sentinel value to stop traversal immediately. Return this from any visitor method.
+
+```python
+from jentic.apitools.openapi.traverse.datamodels.low import BREAK
+
+def visit_Operation(self, path):
+    if should_stop:
+        return BREAK
+```
+
+#### `merge_visitors(*visitors) -> object`
+
+Merge multiple visitors into one composite visitor.
+
+**Parameters:**
+- `*visitors` - Variable number of visitor objects
+
+**Returns:**
+- Composite visitor object with per-visitor state tracking
+
+
+## JSON Traversal
+
+Generic depth-first traversal of any JSON-like structure (dicts, lists, scalars).
+Works with raw parsed OpenAPI documents or any other JSON data.
+
+### Quick Start
+
+```python
+from jentic.apitools.openapi.traverse.json import traverse
+
+# Traverse a nested structure
+data = {
+    "openapi": "3.1.0",
+    "info": {"title": "My API", "version": "1.0.0"},
+    "paths": {
+        "/users": {
+            "get": {"summary": "List users"}
+        }
+    }
+}
+
+# Walk all nodes
+for node in traverse(data):
+    print(f"{node.format_path()}: {node.value}")
+```
+
+Output:
+```
+openapi: 3.1.0
+info: {'title': 'My API', 'version': '1.0.0'}
+info.title: My API
+info.version: 1.0.0
+paths: {'/users': {'get': {'summary': 'List users'}}}
+paths./users: {'get': {'summary': 'List users'}}
+paths./users.get: {'summary': 'List users'}
+paths./users.get.summary: List users
+```
+
+### Working with Paths
+
+```python
+from jentic.apitools.openapi.traverse.json import traverse
+
+data = {
+    "users": [
+        {"name": "Alice", "email": "alice@example.com"},
+        {"name": "Bob", "email": "bob@example.com"}
+    ]
+}
+
+for node in traverse(data):
+    # Access path information
+    print(f"Path: {node.path}")
+    print(f"Segment: {node.segment}")
+    print(f"Full path: {node.full_path}")
+    print(f"Formatted: {node.format_path()}")
+    print(f"Depth: {len(node.ancestors)}")
+    print()
+```
+
+### Custom Path Formatting
+
+```python
+for node in traverse(data):
+    # Default dot separator
+    print(node.format_path())  # e.g., "paths./users.get.summary"
+
+    # Custom separator
+    print(node.format_path(separator="/"))  # e.g., "paths//users/get/summary"
+```
+
+### Finding Specific Nodes
+
+```python
+# Find all $ref references in a document
+refs = [
+    node.value["$ref"]
+    for node in traverse(openapi_doc)
+    if isinstance(node.value, dict) and "$ref" in node.value
+]
+
+# Find all nodes at a specific path segment
+schemas = [
+    node.value
+    for node in traverse(openapi_doc)
+    if node.segment == "schema"
+]
+
+# Find deeply nested values
+response_descriptions = [
+    node.value
+    for node in traverse(openapi_doc)
+    if node.segment == "description" and "responses" in node.path
+]
+```
+
+### API Reference
+
+#### `traverse(root: JSONValue) -> Iterator[TraversalNode]`
+
+Performs depth-first traversal of a JSON-like structure.
+
+**Parameters:**
+- `root`: The data structure to traverse (dict, list, or scalar)
+
+**Returns:**
+- Iterator of `TraversalNode` objects
+
+**Yields:**
+- For dicts: one node per key-value pair
+- For lists: one node per index-item pair
+- Scalars at root don't yield nodes (but are accessible via parent nodes)
+
+#### `TraversalNode`
+
+Immutable dataclass representing a node encountered during traversal.
+
+**Attributes:**
+- `path: JSONPath` - Path from root to the parent container (tuple of segments)
+- `parent: JSONContainer` - The parent container (dict or list)
+- `segment: PathSeg` - The key (for dicts) or index (for lists) within parent
+- `value: JSONValue` - The actual value at `parent[segment]`
+- `ancestors: tuple[JSONValue, ...]` - Ordered tuple of values from root down to (but not including) parent
+
+**Properties:**
+- `full_path: JSONPath` - Complete path from root to this value (`path + (segment,)`)
+
+**Methods:**
+- `format_path(separator: str = ".") -> str` - Format the full path as a human-readable string
+
+### Usage Examples
+
+#### Collecting All Schemas
+
+```python
+from jentic.apitools.openapi.traverse.json import traverse
+
+def collect_schemas(openapi_doc):
+    """Collect all schema objects from an OpenAPI document."""
+    schemas = []
+
+    for node in traverse(openapi_doc):
+        if node.segment == "schema" and isinstance(node.value, dict):
+            schemas.append({
+                "path": node.format_path(),
+                "schema": node.value
+            })
+
+    return schemas
+```
+
+
+#### Analyzing Document Structure
+
+```python
+def analyze_depth(data):
+    """Analyze the depth distribution of a document."""
+    max_depth = 0
+    depth_counts = {}
+
+    for node in traverse(data):
+        depth = len(node.ancestors)
+        max_depth = max(max_depth, depth)
+        depth_counts[depth] = depth_counts.get(depth, 0) + 1
+
+    return {
+        "max_depth": max_depth,
+        "depth_distribution": depth_counts
+    }
+```
+
+### Testing
+
+The package includes comprehensive test coverage for JSON traversal:
+
+```bash
+uv run --package jentic-openapi-traverse pytest packages/jentic-openapi-traverse/tests -v
+```

jentic_openapi_traverse-1.0.0a23.dist-info/RECORD

@@ -0,0 +1,14 @@
+jentic/apitools/openapi/traverse/datamodels/low/__init__.py,sha256=M0xRiYA2ErksACo8bKSVIu6PVx9aiYTDCHEkcTnmXAA,277
+jentic/apitools/openapi/traverse/datamodels/low/introspection.py,sha256=_QzvTnxrSlyRc_QIajyEkaKEwyng7t1y_qx9dEXxwg8,3216
+jentic/apitools/openapi/traverse/datamodels/low/merge.py,sha256=Z7OpX14y740oC2ML_ylTE0TTh-ZbrEaliMU9s1bDFfM,4411
+jentic/apitools/openapi/traverse/datamodels/low/path.py,sha256=MUqqxzEjOQGzt-TPlhWyh40xXG5B3ABYKvMWxmKgU1Q,4715
+jentic/apitools/openapi/traverse/datamodels/low/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jentic/apitools/openapi/traverse/datamodels/low/traversal.py,sha256=aAObD_JFRnD2I6EqLgZo3KFL3jkoRxarMcnUqZeMpm0,8090
+jentic/apitools/openapi/traverse/json/__init__.py,sha256=1euUmpZviE_ECtpXYchpO8hZito2BINPjfSHMNqAU8k,326
+jentic/apitools/openapi/traverse/json/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jentic/apitools/openapi/traverse/json/traversal.py,sha256=1ouszn4S29X0iJaMxxb1neyClbWXqIKwFGhHROcpBSI,3524
+jentic_openapi_traverse-1.0.0a23.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+jentic_openapi_traverse-1.0.0a23.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
+jentic_openapi_traverse-1.0.0a23.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+jentic_openapi_traverse-1.0.0a23.dist-info/METADATA,sha256=mR38IoYfZFJ7_V-sswXIbQyxUbFypNK6V6q4lrge5EI,13572
+jentic_openapi_traverse-1.0.0a23.dist-info/RECORD,,

jentic_openapi_traverse-1.0.0a22.dist-info/METADATA

@@ -1,209 +0,0 @@
-Metadata-Version: 2.4
-Name: jentic-openapi-traverse
-Version: 1.0.0a22
-Summary: Jentic OpenAPI Traversal Utilities
-Author: Jentic
-Author-email: Jentic <hello@jentic.com>
-License-Expression: Apache-2.0
-License-File: LICENSE
-License-File: NOTICE
-Requires-Python: >=3.11
-Project-URL: Homepage, https://github.com/jentic/jentic-openapi-tools
-Description-Content-Type: text/markdown
-
-# jentic-openapi-traverse
-
-A Python library for traversing OpenAPI documents. This package is part of the Jentic OpenAPI Tools ecosystem and provides two types of traversal:
-
-1. **JSON Traversal** (current) - Generic depth-first traversal of JSON-like structures
-2. **Datamodel Traversal** (planned) - OpenAPI-aware semantic traversal with visitor pattern
-
-## Installation
-
-```bash
-pip install jentic-openapi-traverse
-```
-
-**Prerequisites:**
-- Python 3.11+
-
----
-
-## JSON Traversal (Current Implementation)
-
-Generic depth-first traversal of any JSON-like structure (dicts, lists, scalars).
-Works with raw parsed OpenAPI documents or any other JSON data.
-
-### Quick Start
-
-```python
-from jentic.apitools.openapi.traverse.json import traverse
-
-# Traverse a nested structure
-data = {
-    "openapi": "3.1.0",
-    "info": {"title": "My API", "version": "1.0.0"},
-    "paths": {
-        "/users": {
-            "get": {"summary": "List users"}
-        }
-    }
-}
-
-# Walk all nodes
-for node in traverse(data):
-    print(f"{node.format_path()}: {node.value}")
-```
-
-Output:
-```
-openapi: 3.1.0
-info: {'title': 'My API', 'version': '1.0.0'}
-info.title: My API
-info.version: 1.0.0
-paths: {'/users': {'get': {'summary': 'List users'}}}
-paths./users: {'get': {'summary': 'List users'}}
-paths./users.get: {'summary': 'List users'}
-paths./users.get.summary: List users
-```
-
-### Working with Paths
-
-```python
-from jentic.apitools.openapi.traverse.json import traverse
-
-data = {
-    "users": [
-        {"name": "Alice", "email": "alice@example.com"},
-        {"name": "Bob", "email": "bob@example.com"}
-    ]
-}
-
-for node in traverse(data):
-    # Access path information
-    print(f"Path: {node.path}")
-    print(f"Segment: {node.segment}")
-    print(f"Full path: {node.full_path}")
-    print(f"Formatted: {node.format_path()}")
-    print(f"Depth: {len(node.ancestors)}")
-    print()
-```
-
-### Custom Path Formatting
-
-```python
-for node in traverse(data):
-    # Default dot separator
-    print(node.format_path())  # e.g., "paths./users.get.summary"
-
-    # Custom separator
-    print(node.format_path(separator="/"))  # e.g., "paths//users/get/summary"
-```
-
-### Finding Specific Nodes
-
-```python
-# Find all $ref references in a document
-refs = [
-    node.value["$ref"]
-    for node in traverse(openapi_doc)
-    if isinstance(node.value, dict) and "$ref" in node.value
-]
-
-# Find all nodes at a specific path segment
-schemas = [
-    node.value
-    for node in traverse(openapi_doc)
-    if node.segment == "schema"
-]
-
-# Find deeply nested values
-response_descriptions = [
-    node.value
-    for node in traverse(openapi_doc)
-    if node.segment == "description" and "responses" in node.path
-]
-```
-
-### API Reference
-
-#### `traverse(root: JSONValue) -> Iterator[TraversalNode]`
-
-Performs depth-first traversal of a JSON-like structure.
-
-**Parameters:**
-- `root`: The data structure to traverse (dict, list, or scalar)
-
-**Returns:**
-- Iterator of `TraversalNode` objects
-
-**Yields:**
-- For dicts: one node per key-value pair
-- For lists: one node per index-item pair
-- Scalars at root don't yield nodes (but are accessible via parent nodes)
-
-#### `TraversalNode`
-
-Immutable dataclass representing a node encountered during traversal.
-
-**Attributes:**
-- `path: JSONPath` - Path from root to the parent container (tuple of segments)
-- `parent: JSONContainer` - The parent container (dict or list)
-- `segment: PathSeg` - The key (for dicts) or index (for lists) within parent
-- `value: JSONValue` - The actual value at `parent[segment]`
-- `ancestors: tuple[JSONValue, ...]` - Ordered tuple of values from root down to (but not including) parent
-
-**Properties:**
-- `full_path: JSONPath` - Complete path from root to this value (`path + (segment,)`)
-
-**Methods:**
-- `format_path(separator: str = ".") -> str` - Format the full path as a human-readable string
-
-### Usage Examples
-
-#### Collecting All Schemas
-
-```python
-from jentic.apitools.openapi.traverse.json import traverse
-
-def collect_schemas(openapi_doc):
-    """Collect all schema objects from an OpenAPI document."""
-    schemas = []
-
-    for node in traverse(openapi_doc):
-        if node.segment == "schema" and isinstance(node.value, dict):
-            schemas.append({
-                "path": node.format_path(),
-                "schema": node.value
-            })
-
-    return schemas
-```
-
-
-#### Analyzing Document Structure
-
-```python
-def analyze_depth(data):
-    """Analyze the depth distribution of a document."""
-    max_depth = 0
-    depth_counts = {}
-
-    for node in traverse(data):
-        depth = len(node.ancestors)
-        max_depth = max(max_depth, depth)
-        depth_counts[depth] = depth_counts.get(depth, 0) + 1
-
-    return {
-        "max_depth": max_depth,
-        "depth_distribution": depth_counts
-    }
-```
-
-### Testing
-
-The package includes comprehensive test coverage for JSON traversal:
-
-```bash
-uv run --package jentic-openapi-traverse pytest packages/jentic-openapi-traverse/tests -v
-```

jentic_openapi_traverse-1.0.0a22.dist-info/RECORD

@@ -1,8 +0,0 @@
-jentic/apitools/openapi/traverse/json/__init__.py,sha256=1euUmpZviE_ECtpXYchpO8hZito2BINPjfSHMNqAU8k,326
-jentic/apitools/openapi/traverse/json/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-jentic/apitools/openapi/traverse/json/traversal.py,sha256=1ouszn4S29X0iJaMxxb1neyClbWXqIKwFGhHROcpBSI,3524
-jentic_openapi_traverse-1.0.0a22.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-jentic_openapi_traverse-1.0.0a22.dist-info/licenses/NOTICE,sha256=pAOGW-rGw9KNc2cuuLWZkfx0GSTV4TicbgBKZSLPMIs,168
-jentic_openapi_traverse-1.0.0a22.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-jentic_openapi_traverse-1.0.0a22.dist-info/METADATA,sha256=5-XpBl4fy2yjMwJVJM6Qn0qwPzfA9wZHWuKjRkKosAY,5322
-jentic_openapi_traverse-1.0.0a22.dist-info/RECORD,,