# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401

import builtins
import typing

__all__ = [
    "Cycle",
    "DotEdgeData",
    "DotGraph",
    "DotGraphBuilder",
    "DotHedgeData",
    "DotVertexData",
    "EdgeData",
    "EdgeIndex",
    "EdgeStatements",
    "Flow",
    "GlobalData",
    "GlobalStatements",
    "Hedge",
    "HedgeNode",
    "HedgePair",
    "NodeIndex",
    "NodeStatements",
    "Orientation",
    "OrientedCut",
    "Subgraph",
    "TraversalTree",
]

@typing.final
class Cycle:
    r"""
    Cycle represented as a subgraph and optional loop count.
    """
    @property
    def filter(self) -> Subgraph:
        r"""
        Subgraph filter for this cycle.
        """
    @property
    def loop_count(self) -> typing.Optional[builtins.int]:
        r"""
        Optional loop count for this cycle.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class DotEdgeData:
    r"""
    DOT edge data (attributes + optional edge id).
    """
    @property
    def statements(self) -> EdgeStatements:
        r"""
        Edge attributes as a dict-like proxy.
        """
    @property
    def local_statements(self) -> EdgeStatements:
        r"""
        Local edge attributes as a dict-like proxy.
        """
    @property
    def edge_id(self) -> typing.Optional[EdgeIndex]:
        r"""
        Optional edge id.
        """
    def __new__(cls, statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None, local_statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None, edge_id: typing.Optional[builtins.int] = None) -> DotEdgeData:
        r"""
        Create edge data from fields.
        """
    def add_statement(self, key: builtins.str, value: builtins.str) -> None:
        r"""
        Insert or update an attribute statement.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class DotGraph:
    r"""
    DOT-backed hedge graph.
    """
    @property
    def global_data(self) -> GlobalData:
        r"""
        Global graph attributes.
        """
    @global_data.setter
    def global_data(self, value: GlobalData) -> None: ...
    @classmethod
    def from_string(cls, s: builtins.str) -> DotGraph:
        r"""
        Parse a DOT string into a graph.
        """
    @classmethod
    def from_string_set(cls, s: builtins.str) -> builtins.list[DotGraph]:
        r"""
        Parse a DOT string into multiple graphs.
        """
    @classmethod
    def from_file(cls, path: builtins.str) -> DotGraph:
        r"""
        Parse a DOT file into a graph.
        """
    def debug_dot(self) -> builtins.str:
        r"""
        Serialize graph to DOT for debugging.
        """
    def dot(self) -> builtins.str:
        r"""
        Serialize the full graph to DOT.
        """
    def dot_of(self, subgraph: Subgraph) -> builtins.str:
        r"""
        Serialize a subgraph to DOT.
        """
    def n_nodes(self) -> builtins.int:
        r"""
        Number of nodes.
        """
    def n_edges(self) -> builtins.int:
        r"""
        Number of edges.
        """
    def n_hedges(self) -> builtins.int:
        r"""
        Number of hedges.
        """
    def n_externals(self) -> builtins.int:
        r"""
        Number of external hedges.
        """
    def n_internals(self) -> builtins.int:
        r"""
        Number of internal hedges.
        """
    def full_filter(self) -> Subgraph:
        r"""
        Subgraph including all hedges.
        """
    def empty_subgraph(self) -> Subgraph:
        r"""
        Empty subgraph of this graph.
        """
    def iter_edges(self) -> builtins.list[tuple[HedgePair, EdgeIndex, EdgeData]]:
        r"""
        Iterate edges in the full graph.
        """
    def iter_edges_of(self, subgraph: Subgraph) -> builtins.list[tuple[HedgePair, EdgeIndex, EdgeData]]:
        r"""
        Iterate edges within a subgraph.
        """
    def iter_nodes(self) -> builtins.list[tuple[NodeIndex, builtins.list[Hedge], DotVertexData]]:
        r"""
        Iterate nodes in the full graph.
        """
    def iter_nodes_of(self, subgraph: Subgraph) -> builtins.list[tuple[NodeIndex, builtins.list[Hedge], DotVertexData]]:
        r"""
        Iterate nodes within a subgraph.
        """
    def connected_components(self, subgraph: Subgraph) -> builtins.list[Subgraph]:
        r"""
        Connected components of a subgraph.
        """
    def count_connected_components(self, subgraph: Subgraph) -> builtins.int:
        r"""
        Count connected components.
        """
    def is_connected(self, subgraph: Subgraph) -> builtins.bool:
        r"""
        Whether a subgraph is connected.
        """
    def depth_first_traverse(self, subgraph: Subgraph, root_node: NodeIndex, include_hedge: typing.Optional[Hedge]) -> TraversalTree:
        r"""
        Depth-first traversal from a root node.
        """
    def breadth_first_traverse(self, subgraph: Subgraph, root_node: NodeIndex, include_hedge: typing.Optional[Hedge]) -> TraversalTree:
        r"""
        Breadth-first traversal from a root node.
        """
    def bridges(self) -> Subgraph:
        r"""
        Bridges in the full graph.
        """
    def bridges_of(self, subgraph: Subgraph) -> Subgraph:
        r"""
        Bridges within a subgraph.
        """
    def cycle_basis(self) -> tuple[builtins.list[Cycle], Subgraph]:
        r"""
        Cycle basis of the full graph.
        """
    def cycle_basis_of(self, subgraph: Subgraph) -> tuple[builtins.list[Cycle], Subgraph]:
        r"""
        Cycle basis of a subgraph.
        """
    def all_spanning_forests(self) -> builtins.list[Subgraph]:
        r"""
        All spanning forests of the full graph.
        """
    def all_spanning_forests_of(self, subgraph: Subgraph) -> builtins.list[Subgraph]:
        r"""
        All spanning forests of a subgraph.
        """
    def combine_to_single_hedgenode(self, nodes: typing.Sequence[NodeIndex]) -> HedgeNode:
        r"""
        Combine nodes into a single hedge node.
        """
    def all_cuts(self, source: HedgeNode, target: HedgeNode) -> builtins.list[tuple[Subgraph, OrientedCut, Subgraph]]:
        r"""
        All cuts between two hedge nodes.
        """
    def all_cuts_from_ids(self, source: typing.Sequence[NodeIndex], target: typing.Sequence[NodeIndex]) -> builtins.list[tuple[Subgraph, OrientedCut, Subgraph]]:
        r"""
        All cuts between two sets of node indices.
        """
    def contract_subgraph(self, subgraph: Subgraph, node_data_merge: typing.Optional[DotVertexData] = None) -> None:
        r"""
        Contract a subgraph into a single node, deleting its edges.
        """
    def join(self, other: DotGraph, matching_fn: typing.Any, merge_fn: typing.Any) -> DotGraph:
        r"""
        Join two graphs, matching dangling edges via a Python callback.
        """
    def join_mut(self, other: DotGraph, matching_fn: typing.Any, merge_fn: typing.Any) -> None:
        r"""
        In-place join, matching dangling edges via a Python callback.
        """
    def extract(self, subgraph: Subgraph, split_edge_fn: typing.Any, internal_data: typing.Any, split_node: typing.Any, owned_node: typing.Any) -> DotGraph:
        r"""
        Extract a subgraph with Python callbacks to transform edge/node data.
        """
    @typing.overload
    def __getitem__(self, key: Hedge) -> DotHedgeData: ...
    @typing.overload
    def __getitem__(self, key: NodeIndex) -> DotVertexData: ...
    @typing.overload
    def __getitem__(self, key: EdgeIndex) -> DotEdgeData: ...

@typing.final
class DotGraphBuilder:
    r"""
    Builder for constructing DOT graphs programmatically.
    """
    def __new__(cls) -> DotGraphBuilder:
        r"""
        Create a new, empty graph builder.
        """
    def add_node(self, data: typing.Optional[DotVertexData] = None) -> NodeIndex:
        r"""
        Add a node and return its index.
        """
    def add_edge(self, source: NodeIndex, sink: NodeIndex, data: typing.Optional[DotEdgeData] = None, orientation: typing.Optional[Orientation] = None, source_hedge: typing.Optional[DotHedgeData] = None, sink_hedge: typing.Optional[DotHedgeData] = None) -> None:
        r"""
        Add an edge between two nodes.
        """
    def add_external_edge(self, source: NodeIndex, data: typing.Optional[DotEdgeData] = None, orientation: typing.Optional[Orientation] = None, flow: typing.Optional[Flow] = None, hedge: typing.Optional[DotHedgeData] = None) -> None:
        r"""
        Add a dangling (external) edge incident to a node.
        """
    def build(self) -> DotGraph:
        r"""
        Build the graph and reset the builder.
        """

@typing.final
class DotHedgeData:
    r"""
    DOT hedge (half-edge) data.
    """
    @property
    def statement(self) -> typing.Optional[builtins.str]:
        r"""
        Optional statement string.
        """
    @property
    def id(self) -> typing.Optional[Hedge]:
        r"""
        Optional hedge id.
        """
    @property
    def port_label(self) -> typing.Optional[builtins.str]:
        r"""
        Optional port label.
        """
    @property
    def compasspt(self) -> typing.Optional[builtins.str]:
        r"""
        Optional compass point as a string.
        """
    def __new__(cls, statement: typing.Optional[builtins.str] = None, id: typing.Optional[builtins.int] = None, port_label: typing.Optional[builtins.str] = None, compasspt: typing.Optional[builtins.str] = None) -> DotHedgeData:
        r"""
        Create hedge data from fields.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class DotVertexData:
    r"""
    DOT vertex data (name, optional index, and attribute statements).
    """
    @property
    def name(self) -> typing.Optional[builtins.str]:
        r"""
        Optional vertex name.
        """
    @property
    def index(self) -> typing.Optional[NodeIndex]:
        r"""
        Optional node index.
        """
    @property
    def statements(self) -> NodeStatements:
        r"""
        Attribute statements as a dict-like proxy.
        """
    def __new__(cls, name: typing.Optional[builtins.str] = None, index: typing.Optional[builtins.int] = None, statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None) -> DotVertexData:
        r"""
        Create vertex data from fields.
        """
    def add_statement(self, key: builtins.str, value: builtins.str) -> None:
        r"""
        Insert or update an attribute statement.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class EdgeData:
    r"""
    Edge data with orientation.
    """
    @property
    def orientation(self) -> Orientation:
        r"""
        Orientation of this edge.
        """
    @property
    def data(self) -> DotEdgeData:
        r"""
        DOT edge data.
        """
    def __new__(cls, orientation: typing.Any, data: typing.Any) -> EdgeData:
        r"""
        Create edge data from orientation and DotEdgeData.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class EdgeIndex:
    r"""
    Edge index identifier.
    """
    @property
    def value(self) -> builtins.int:
        r"""
        Numeric value of this edge index.
        """
    def __new__(cls, value: builtins.int) -> EdgeIndex:
        r"""
        Create an edge index from a zero-based index.
        """
    def __int__(self) -> builtins.int:
        r"""
        Convert to int.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class EdgeStatements:
    r"""
    Dict-like proxy for edge attribute statements.
    """
    def __getitem__(self, key: builtins.str) -> builtins.str: ...
    def __setitem__(self, key: builtins.str, value: builtins.str) -> None: ...
    def __delitem__(self, key: builtins.str) -> None: ...
    def __contains__(self, key: builtins.str) -> builtins.bool: ...
    def __len__(self) -> builtins.int: ...
    def __iter__(self) -> typing.Iterator[builtins.str]: ...
    def get(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def keys(self) -> builtins.list[builtins.str]: ...
    def values(self) -> builtins.list[builtins.str]: ...
    def items(self) -> builtins.list[tuple[builtins.str, builtins.str]]: ...
    def clear(self) -> None: ...
    def update(self, other: typing.Mapping[builtins.str, builtins.str]) -> None: ...
    def pop(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def popitem(self) -> tuple[builtins.str, builtins.str]: ...
    def setdefault(self, key: builtins.str, default: typing.Optional[builtins.str] = None) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class Flow:
    r"""
    Flow direction (Source/Sink).
    """
    @staticmethod
    def source() -> Flow:
        r"""
        Flow::Source.
        """
    @staticmethod
    def sink() -> Flow:
        r"""
        Flow::Sink.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class GlobalData:
    r"""
    Global graph attributes (graph/node/edge statements).
    """
    @property
    def name(self) -> builtins.str:
        r"""
        Graph name.
        """
    @name.setter
    def name(self, value: builtins.str) -> None: ...
    @property
    def statements(self) -> GlobalStatements:
        r"""
        Graph-level statements.
        """
    @statements.setter
    def statements(self, value: builtins.dict[builtins.str, builtins.str]) -> None: ...
    @property
    def edge_statements(self) -> GlobalStatements:
        r"""
        Default edge statements.
        """
    @edge_statements.setter
    def edge_statements(self, value: builtins.dict[builtins.str, builtins.str]) -> None: ...
    @property
    def node_statements(self) -> GlobalStatements:
        r"""
        Default node statements.
        """
    @node_statements.setter
    def node_statements(self, value: builtins.dict[builtins.str, builtins.str]) -> None: ...
    def __new__(cls, name: typing.Optional[builtins.str] = None, statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None, edge_statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None, node_statements: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None) -> GlobalData:
        r"""
        Create global data from fields.
        """
    def add_statement(self, key: builtins.str, value: builtins.str) -> None:
        r"""
        Insert or update a graph-level statement.
        """
    def add_edge_statement(self, key: builtins.str, value: builtins.str) -> None:
        r"""
        Insert or update a default edge statement.
        """
    def add_node_statement(self, key: builtins.str, value: builtins.str) -> None:
        r"""
        Insert or update a default node statement.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class GlobalStatements:
    r"""
    Dict-like proxy for global statements.
    """
    def __getitem__(self, key: builtins.str) -> builtins.str: ...
    def __setitem__(self, key: builtins.str, value: builtins.str) -> None: ...
    def __delitem__(self, key: builtins.str) -> None: ...
    def __contains__(self, key: builtins.str) -> builtins.bool: ...
    def __len__(self) -> builtins.int: ...
    def __iter__(self) -> typing.Iterator[builtins.str]: ...
    def get(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def keys(self) -> builtins.list[builtins.str]: ...
    def values(self) -> builtins.list[builtins.str]: ...
    def items(self) -> builtins.list[tuple[builtins.str, builtins.str]]: ...
    def clear(self) -> None: ...
    def update(self, other: typing.Mapping[builtins.str, builtins.str]) -> None: ...
    def pop(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def popitem(self) -> tuple[builtins.str, builtins.str]: ...
    def setdefault(self, key: builtins.str, default: typing.Optional[builtins.str] = None) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class Hedge:
    r"""
    Half-edge identifier.
    """
    @property
    def value(self) -> builtins.int:
        r"""
        Numeric value of this hedge.
        """
    def __new__(cls, value: builtins.int) -> Hedge:
        r"""
        Create a hedge from a zero-based index.
        """
    def __int__(self) -> builtins.int:
        r"""
        Convert to int.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class HedgeNode:
    r"""
    Hedge node with internal graph and hairs.
    """
    @property
    def internal_graph(self) -> Subgraph:
        r"""
        Internal subgraph.
        """
    @property
    def hairs(self) -> Subgraph:
        r"""
        Hair subgraph.
        """
    def __new__(cls, internal_graph: Subgraph, hairs: Subgraph) -> HedgeNode:
        r"""
        Create a hedge node from internal graph and hairs subgraphs.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class HedgePair:
    r"""
    Hedge pairing (paired, unpaired, split).
    """
    @property
    def kind(self) -> builtins.str:
        r"""
        Kind of hedge pair: \"paired\", \"unpaired\", or \"split\".
        """
    @property
    def source(self) -> typing.Optional[Hedge]:
        r"""
        Source hedge (paired/split).
        """
    @property
    def sink(self) -> typing.Optional[Hedge]:
        r"""
        Sink hedge (paired/split).
        """
    @property
    def hedge(self) -> typing.Optional[Hedge]:
        r"""
        Hedge (unpaired only).
        """
    @property
    def flow(self) -> typing.Optional[Flow]:
        r"""
        Flow for unpaired hedge.
        """
    @property
    def split(self) -> typing.Optional[Flow]:
        r"""
        Which side is split for split edges.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class NodeIndex:
    r"""
    Node index identifier.
    """
    @property
    def value(self) -> builtins.int:
        r"""
        Numeric value of this node index.
        """
    def __new__(cls, value: builtins.int) -> NodeIndex:
        r"""
        Create a node index from a zero-based index.
        """
    def __int__(self) -> builtins.int:
        r"""
        Convert to int.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class NodeStatements:
    r"""
    Dict-like proxy for node attribute statements.
    """
    def __getitem__(self, key: builtins.str) -> builtins.str: ...
    def __setitem__(self, key: builtins.str, value: builtins.str) -> None: ...
    def __delitem__(self, key: builtins.str) -> None: ...
    def __contains__(self, key: builtins.str) -> builtins.bool: ...
    def __len__(self) -> builtins.int: ...
    def __iter__(self) -> typing.Iterator[builtins.str]: ...
    def get(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def keys(self) -> builtins.list[builtins.str]: ...
    def values(self) -> builtins.list[builtins.str]: ...
    def items(self) -> builtins.list[tuple[builtins.str, builtins.str]]: ...
    def clear(self) -> None: ...
    def update(self, other: typing.Mapping[builtins.str, builtins.str]) -> None: ...
    def pop(self, key: builtins.str, default: typing.Any = None) -> typing.Any: ...
    def popitem(self) -> tuple[builtins.str, builtins.str]: ...
    def setdefault(self, key: builtins.str, default: typing.Optional[builtins.str] = None) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class Orientation:
    r"""
    Edge orientation (Default/Reversed/Undirected).
    """
    @staticmethod
    def default() -> Orientation:
        r"""
        Orientation::Default.
        """
    @staticmethod
    def reversed() -> Orientation:
        r"""
        Orientation::Reversed.
        """
    @staticmethod
    def undirected() -> Orientation:
        r"""
        Orientation::Undirected.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class OrientedCut:
    r"""
    Oriented cut represented by left/right subgraphs.
    """
    @property
    def left(self) -> Subgraph:
        r"""
        Left side of the cut.
        """
    @property
    def right(self) -> Subgraph:
        r"""
        Right side of the cut.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class Subgraph:
    r"""
    Subgraph represented as a bitset of hedges.
    """
    @classmethod
    def empty(cls, size: builtins.int) -> Subgraph:
        r"""
        Create an empty subgraph of the given size (number of hedges).
        """
    @classmethod
    def full(cls, size: builtins.int) -> Subgraph:
        r"""
        Create a full subgraph including all hedges.
        """
    @classmethod
    def from_hedges(cls, size: builtins.int, hedges: typing.Sequence[Hedge]) -> Subgraph:
        r"""
        Create a subgraph from a list of hedges.
        """
    def to_hedges(self) -> builtins.list[Hedge]:
        r"""
        List included hedges.
        """
    def size(self) -> builtins.int:
        r"""
        Total number of hedges in the parent graph.
        """
    def n_included(self) -> builtins.int:
        r"""
        Number of included hedges.
        """
    def includes(self, hedge: typing.Any) -> builtins.bool:
        r"""
        Whether a hedge is included.
        """
    def union(self, other: Subgraph) -> Subgraph:
        r"""
        Union with another subgraph.
        """
    def intersection(self, other: Subgraph) -> Subgraph:
        r"""
        Intersection with another subgraph.
        """
    def sym_diff(self, other: Subgraph) -> Subgraph:
        r"""
        Symmetric difference with another subgraph.
        """
    def subtract(self, other: Subgraph) -> Subgraph:
        r"""
        Subtract another subgraph.
        """
    def __repr__(self) -> builtins.str:
        r"""
        Debug-style representation.
        """

@typing.final
class TraversalTree:
    r"""
    Traversal tree produced by DFS/BFS.
    """
    def tree_subgraph(self) -> Subgraph:
        r"""
        Subgraph corresponding to the tree edges.
        """
    def node_order(self) -> builtins.list[NodeIndex]:
        r"""
        Node order from traversal.
        """
    def covers(self, subgraph: Subgraph) -> Subgraph:
        r"""
        Covers a subgraph with the traversal tree.
        """
    def iter_hedges(self) -> builtins.list[tuple[Hedge, builtins.str, typing.Optional[Hedge]]]:
        r"""
        Iterate hedges as (hedge, kind, root_hedge).
        """