{
  "module": "hexa.parse_yaml",
  "content": {
    "path": "hexa.parse_yaml",
    "docstring": "# Summary\n\nParse a hexa YAML spec into a :class:`PortNode` tree.\n\nThe YAML grammar uses a nested mapping format built from three member kinds:\n\n- **attribute**: a ``name: type`` scalar (e.g. ``source_type: str``)\n- **nested struct**: a ``name:`` mapping of sub-attributes (e.g. ``source:``)\n- **port**: a ``name:`` mapping whose single key is a class whose value is a\n  body, or a class key with a ``...`` body.  A port carries a class shape.\n\nDisambiguation of a mapping value:\n  A mapping with exactly one key whose value is a non-scalar body (a mapping,\n  ``...``, or a list) is a **port**.  Any other mapping (multiple keys, or all\n  scalar-typed values) is a **nested struct** of attributes.\n\n---\n# Examples\n\nParse a spec into a port tree:\n\n    ```python\n    from hexa import parse_yaml\n\n    node = parse_yaml(\"samples/minimal/sample.yaml\")\n    print(node)\n    ```\n\nThe YAML grammar:\n\n    ```yaml\n    RootClassName:\n      attr: type                 # scalar attribute\n      source:                    # nested struct (all scalar sub-attributes)\n        source_type: str\n        bank: str\n      methods:                   # reserved block of functions\n        run:\n          args: [a, b]\n      ingest:                    # port (single non-scalar class key)\n        IngestPort:\n          source_type: str\n          methods: {Method: ...}\n    ```\n\n---\n# Notes\n\n- See ``samples/minimal/sample.yaml`` and\n  ``samples/extraction_pipeline/extraction_pipeline.yaml`` for worked examples.",
    "objects": {
      "ConfigValue": {
        "name": "ConfigValue",
        "kind": "attribute",
        "path": "hexa.parse_yaml.ConfigValue",
        "signature": null,
        "docstring": null
      },
      "MethodSpec": {
        "name": "MethodSpec",
        "kind": "class",
        "path": "hexa.parse_yaml.MethodSpec",
        "signature": "MethodSpec(name: str, args: list[str] = list(), kwargs: dict[str, str] = dict())",
        "docstring": "Specification of a single abstract method.\n\nAttributes:\n    name (str):\n        Name of the method.\n\n    args (list[str]):\n        Positional parameter names.\n\n    kwargs (dict[str, str]):\n        Keyword-only parameter names mapped to their type expressions.",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "hexa.parse_yaml.MethodSpec.name",
            "signature": null,
            "docstring": null
          },
          "args": {
            "name": "args",
            "kind": "attribute",
            "path": "hexa.parse_yaml.MethodSpec.args",
            "signature": null,
            "docstring": null
          },
          "kwargs": {
            "name": "kwargs",
            "kind": "attribute",
            "path": "hexa.parse_yaml.MethodSpec.kwargs",
            "signature": null,
            "docstring": null
          }
        }
      },
      "PortNode": {
        "name": "PortNode",
        "kind": "class",
        "path": "hexa.parse_yaml.PortNode",
        "signature": "PortNode(name: str, port_cls: str, kind: str = 'leaf', attributes: dict[str, ConfigValue] = dict(), children: list[PortNode] = list(), methods: dict[str, MethodSpec] = dict())",
        "docstring": "A node in the hexa port tree.\n\nEach node is a leaf (no children), a port (has nested port slots), or the\nparent root of the tree. Every node carries a concrete typed shape derived\nfrom an ABC class name.\n\nAttributes:\n    name (str):\n        Slot name, e.g. ``\"parser\"``, ``\"amount_balance\"``.\n\n    port_cls (str):\n        ABC class name that gives this port its shape, e.g.\n        ``\"TransactionParserPort\"``.  Every port has a concrete typed shape.\n\n    kind (str):\n        One of ``\"leaf\"``, ``\"port\"``, or ``\"parent\"``.\n        - ``\"leaf\"``: no children (e.g. ``NumberPort``)\n        - ``\"port\"``: has children (e.g. ``TransactionParserPort``)\n        - ``\"parent\"``: the root of the tree (e.g. ``ExtractionPipeline``)\n\n    attributes (dict[str, ConfigValue]):\n        Annotated attributes: ``name -> type_expr`` for scalars, or a\n        nested ``dict`` of sub-attributes (a struct) for grouped values.\n\n    children (list[PortNode]):\n        Nested port slots.\n\n    methods (dict[str, MethodSpec]):\n        Abstract methods keyed by method name.",
        "members": {
          "name": {
            "name": "name",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.name",
            "signature": null,
            "docstring": null
          },
          "port_cls": {
            "name": "port_cls",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.port_cls",
            "signature": null,
            "docstring": null
          },
          "kind": {
            "name": "kind",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.kind",
            "signature": null,
            "docstring": null
          },
          "attributes": {
            "name": "attributes",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.attributes",
            "signature": null,
            "docstring": null
          },
          "children": {
            "name": "children",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.children",
            "signature": null,
            "docstring": null
          },
          "methods": {
            "name": "methods",
            "kind": "attribute",
            "path": "hexa.parse_yaml.PortNode.methods",
            "signature": null,
            "docstring": null
          },
          "find": {
            "name": "find",
            "kind": "function",
            "path": "hexa.parse_yaml.PortNode.find",
            "signature": "find(name: str)",
            "docstring": "Find a direct child by slot name.\n\nArgs:\n    name (str):\n        Slot name of the child to look up.\n\nReturns:\n    PortNode | None:\n        The matching child node, or ``None`` if no child has that name."
          },
          "walk": {
            "name": "walk",
            "kind": "function",
            "path": "hexa.parse_yaml.PortNode.walk",
            "signature": "walk()",
            "docstring": "Return all nodes in depth-first order (self first).\n\nReturns:\n    list[PortNode]:\n        All nodes of the tree, self first, depth-first."
          },
          "diff": {
            "name": "diff",
            "kind": "function",
            "path": "hexa.parse_yaml.PortNode.diff",
            "signature": "diff(other: PortNode, path: str = '')",
            "docstring": "Return a list of human-readable difference strings.\n\nAn empty list means the trees are equal.\n\nArgs:\n    other (PortNode):\n        Tree to compare against.\n\n    path (str):\n        Path prefix used when recursing into nested nodes; defaults to\n        the root path.\n\nReturns:\n    list[str]:\n        Human-readable difference strings, one per discrepancy."
          }
        }
      },
      "parse_yaml": {
        "name": "parse_yaml",
        "kind": "function",
        "path": "hexa.parse_yaml.parse_yaml",
        "signature": "parse_yaml(path: str | Path) -> PortNode",
        "docstring": "Parse a hexa YAML spec file into a :class:`PortNode` tree.\n\nArgs:\n    path (str | Path):\n        Path to the ``.yaml`` file.\n\nReturns:\n    PortNode:\n        The root node of the parsed tree.\n\nRaises:\n    ValueError:\n        On structural errors in the YAML."
      }
    }
  }
}