jentic-openapi-traverse 1.0.0a23__tar.gz → 1.0.0a25__tar.gz

jentic_openapi_traverse-1.0.0a23/README.md → jentic_openapi_traverse-1.0.0a25/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.4
+Name: jentic-openapi-traverse
+Version: 1.0.0a25
+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.0a25
+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:
@@ -108,15 +123,42 @@ class PathInspector:
         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
+        # Ancestry (computed properties)
+        print(f"Parent: {path.parent.__class__.__name__}")
         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']
+        # Complete path formatting (RFC 6901 JSONPointer / RFC 9535 JSONPath)
+        print(f"JSONPointer: {path.format_path()}")
+        # Output: /paths/~1users/get
+
+        print(f"JSONPath: {path.format_path(path_format='jsonpath')}")
+        # Output: $['paths']['/users']['get']
 ```
 
+#### Path Reconstruction
+
+NodePath uses a linked chain structure (`parent_path`) internally to preserve complete path information from root to current node. This enables accurate JSONPointer and JSONPath reconstruction:
+
+```python
+class PathFormatter:
+    def visit_Response(self, path):
+        # Complete paths from root to current node
+        pointer = path.format_path()
+        # /paths/~1users/get/responses/200
+
+        jsonpath = path.format_path(path_format='jsonpath')
+        # $['paths']['/users']['get']['responses']['200']
+```
+
+**Special handling for patterned fields:**
+- Patterned fields like `Paths.paths` don't duplicate in paths: `/paths/{key}` (not `/paths/paths/{key}`)
+- Fixed dict fields like `webhooks`, `callbacks`, `schemas` include their field name: `/webhooks/{key}`, `/components/schemas/{key}`
+
+**Computed properties:**
+- `path.parent` - Returns parent node (computed from parent_path chain)
+- `path.ancestors` - Returns tuple of ancestor nodes from root to parent (computed on access)
+
 ### Enter/Leave Hooks
 
 Use enter/leave hooks for pre/post processing logic:

jentic_openapi_traverse-1.0.0a23/PKG-INFO → jentic_openapi_traverse-1.0.0a25/README.md

@@ -1,18 +1,3 @@
-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:
@@ -123,15 +108,42 @@ class PathInspector:
         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
+        # Ancestry (computed properties)
+        print(f"Parent: {path.parent.__class__.__name__}")
         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']
+        # Complete path formatting (RFC 6901 JSONPointer / RFC 9535 JSONPath)
+        print(f"JSONPointer: {path.format_path()}")
+        # Output: /paths/~1users/get
+
+        print(f"JSONPath: {path.format_path(path_format='jsonpath')}")
+        # Output: $['paths']['/users']['get']
 ```
 
+#### Path Reconstruction
+
+NodePath uses a linked chain structure (`parent_path`) internally to preserve complete path information from root to current node. This enables accurate JSONPointer and JSONPath reconstruction:
+
+```python
+class PathFormatter:
+    def visit_Response(self, path):
+        # Complete paths from root to current node
+        pointer = path.format_path()
+        # /paths/~1users/get/responses/200
+
+        jsonpath = path.format_path(path_format='jsonpath')
+        # $['paths']['/users']['get']['responses']['200']
+```
+
+**Special handling for patterned fields:**
+- Patterned fields like `Paths.paths` don't duplicate in paths: `/paths/{key}` (not `/paths/paths/{key}`)
+- Fixed dict fields like `webhooks`, `callbacks`, `schemas` include their field name: `/webhooks/{key}`, `/components/schemas/{key}`
+
+**Computed properties:**
+- `path.parent` - Returns parent node (computed from parent_path chain)
+- `path.ancestors` - Returns tuple of ancestor nodes from root to parent (computed on access)
+
 ### Enter/Leave Hooks
 
 Use enter/leave hooks for pre/post processing logic:

{jentic_openapi_traverse-1.0.0a23 → jentic_openapi_traverse-1.0.0a25}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jentic-openapi-traverse"
-version = "1.0.0-alpha.23"
+version = "1.0.0-alpha.25"
 description = "Jentic OpenAPI Traversal Utilities"
 readme = "README.md"
 authors = [{ name = "Jentic", email = "hello@jentic.com" }]
@@ -8,7 +8,7 @@ license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
 requires-python = ">=3.11"
 dependencies = [
-    "jentic-openapi-datamodels~=1.0.0-alpha.23",
+    "jentic-openapi-datamodels~=1.0.0-alpha.25",
     "jsonpointer~=3.0.0"
 ]
 

{jentic_openapi_traverse-1.0.0a23 → jentic_openapi_traverse-1.0.0a25}/src/jentic/apitools/openapi/traverse/datamodels/low/introspection.py

@@ -15,9 +15,33 @@ __all__ = [
     "get_traversable_fields",
     "unwrap_value",
     "is_datamodel_node",
+    "get_yaml_field_name",
 ]
 
 
+def get_yaml_field_name(node_class: type, python_field_name: str) -> str:
+    """
+    Convert Python field name to YAML field name using metadata.
+
+    Args:
+        node_class: Datamodel class type
+        python_field_name: Python attribute name (e.g., "external_docs")
+
+    Returns:
+        YAML field name from metadata, or python_field_name if not found
+        (e.g., "externalDocs")
+    """
+    fixed = fixed_fields(node_class)
+    patterned = patterned_fields(node_class)
+
+    # Try fixed fields first, then patterned
+    field_obj = fixed.get(python_field_name) or patterned.get(python_field_name)
+    if field_obj:
+        return field_obj.metadata.get("yaml_name", python_field_name)
+
+    return python_field_name
+
+
 # Cache of field names to check per class type
 # {Info: ["title", "description", "contact", ...], Operation: [...], ...}
 _FIELD_NAMES_CACHE: dict[type, list[str]] = {}

{jentic_openapi_traverse-1.0.0a23 → jentic_openapi_traverse-1.0.0a25}/src/jentic/apitools/openapi/traverse/datamodels/low/path.py

@@ -5,6 +5,8 @@ from typing import Any, Literal
 
 from jsonpointer import JsonPointer
 
+from .introspection import get_yaml_field_name
+
 
 __all__ = ["NodePath"]
 
@@ -19,13 +21,28 @@ class NodePath:
     """
 
     node: Any  # Current datamodel object
-    parent: Any | None  # Parent datamodel object
+    parent_path: "NodePath | None"  # Reference to parent's NodePath (chain)
     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)
+
+    @property
+    def parent(self) -> Any | None:
+        """Get parent node. Computed from parent_path for convenience."""
+        return self.parent_path.node if self.parent_path else None
+
+    @property
+    def ancestors(self) -> tuple[Any, ...]:
+        """Get ancestor nodes from root to parent. Computed for convenience."""
+        result = []
+        current = self.parent_path
+        while current is not None:
+            result.append(current.node)
+            current = current.parent_path
+        result.reverse()  # Root first
+        return tuple(result)
 
     def create_child(
-        self, node: Any, parent_field: str, parent_key: str | int | None
+        self, node: Any, parent_field: str | None, parent_key: str | int | None
     ) -> "NodePath":
         """
         Create a child NodePath from this path.
@@ -34,7 +51,7 @@ class NodePath:
 
         Args:
             node: Child node
-            parent_field: Field name in current node
+            parent_field: Field name in current node (None for dict items to avoid duplicates)
             parent_key: Key if field is list/dict
 
         Returns:
@@ -42,10 +59,9 @@ class NodePath:
         """
         return NodePath(
             node=node,
-            parent=self.node,
+            parent_path=self,
             parent_field=parent_field,
             parent_key=parent_key,
-            ancestors=self.ancestors + (self.node,),
         )
 
     def traverse(self, visitor) -> None:
@@ -103,37 +119,42 @@ class NodePath:
             "$['components']['schemas']['User']['properties']['name']"
         """
         # Root node
-        if not self.ancestors and self.parent_field is None:
+        if self.parent_path 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)
+        # Walk back collecting all segments
+        segments: list[str | int] = []
+        current = self
+        while current.parent_path is not None:
+            # Add in reverse order (key first, then field) because we'll reverse the list
+            # This ensures field comes before key in the final path
+            if current.parent_key is not None:
+                segments.append(current.parent_key)
+            if current.parent_field:
+                # Convert Python field name to YAML name for output
+                parent_class = type(current.parent_path.node)
+                yaml_name = get_yaml_field_name(parent_class, current.parent_field)
+                segments.append(yaml_name)
+            current = current.parent_path
+
+        segments.reverse()  # Root to leaf order
 
         if path_format == "jsonpath":
             # RFC 9535 Normalized JSONPath: $['field'][index]['key']
-            segments = ["$"]
-            for part in parts:
-                if isinstance(part, int):
+            result = ["$"]
+            for segment in segments:
+                if isinstance(segment, int):
                     # Array index: $[0]
-                    segments.append(f"[{part}]")
+                    result.append(f"[{segment}]")
                 else:
                     # Member name: $['field']
                     # Escape single quotes in the string
-                    escaped = str(part).replace("'", "\\'")
-                    segments.append(f"['{escaped}']")
-            return "".join(segments)
+                    escaped = str(segment).replace("'", "\\'")
+                    result.append(f"['{escaped}']")
+            return "".join(result)
 
         # RFC 6901 JSON Pointer
-        return JsonPointer.from_parts(parts).path
+        return JsonPointer.from_parts(segments).path
 
     def get_root(self) -> Any:
         """
@@ -142,4 +163,7 @@ class NodePath:
         Returns:
             Root datamodel object
         """
-        return self.ancestors[0] if self.ancestors else self.node
+        current = self
+        while current.parent_path is not None:
+            current = current.parent_path
+        return current.node

{jentic_openapi_traverse-1.0.0a23 → jentic_openapi_traverse-1.0.0a25}/src/jentic/apitools/openapi/traverse/datamodels/low/traversal.py

@@ -1,5 +1,7 @@
 """Core traversal functionality for low-level OpenAPI datamodels."""
 
+from jentic.apitools.openapi.datamodels.low.fields import patterned_fields
+
 from .introspection import get_traversable_fields, is_datamodel_node, unwrap_value
 from .path import NodePath
 
@@ -96,10 +98,9 @@ def traverse(root, visitor) -> None:
     # Create initial root path
     initial_path = NodePath(
         node=root,
-        parent=None,
+        parent_path=None,
         parent_field=None,
         parent_key=None,
-        ancestors=(),
     )
 
     # Start traversal
@@ -144,6 +145,12 @@ def _default_traverse_children(visitor, path: NodePath) -> _BreakType | None:
 
         # Handle dicts
         elif isinstance(unwrapped, dict):
+            # Check if this field is a patterned field
+            # Patterned fields (like Paths.paths, Components.schemas) should not
+            # add their field name to the path when iterating dict items
+            patterned_field_names = patterned_fields(type(path.node))
+            is_patterned = field_name in patterned_field_names
+
             for key, value in unwrapped.items():
                 unwrapped_key = unwrap_value(key)
                 unwrapped_value = unwrap_value(value)
@@ -153,9 +160,12 @@ def _default_traverse_children(visitor, path: NodePath) -> _BreakType | None:
                     assert isinstance(unwrapped_key, (str, int)), (
                         f"Expected str or int key, got {type(unwrapped_key)}"
                     )
+                    # For patterned fields, don't include the field name in the path
+                    # (e.g., Paths.paths is patterned, so /paths/{path-key} not /paths/paths/{path-key})
+                    dict_field_name: str | None = None if is_patterned else field_name
                     child_path = path.create_child(
                         node=unwrapped_value,
-                        parent_field=field_name,
+                        parent_field=dict_field_name,
                         parent_key=unwrapped_key,
                     )
                     result = _visit_node(visitor, child_path)