# This file is automatically generated by pyo3_stub_gen
# ruff: noqa: E501, F401, F403, F405
r"""
Binary trace-file reader and shared move-type classification.

MoveKind — standard move-type classification shared by all operations.
TraceFile — read a .bin trace file with span/event access.
Span — one span record from a trace file.
Event — one event record from a trace file.
ToolSnapshot — tool position and heading snapshot.
ProgressSnapshot — step progress snapshot.
"""

import builtins
import typing
__all__ = [
    "Event",
    "MoveKind",
    "ProgressSnapshot",
    "Span",
    "ToolSnapshot",
    "TraceFile",
    "get_route_detail_name",
]

@typing.final
class Event:
    r"""
    One trace event (init / move / resume / exit).
    """
    @property
    def kind(self) -> builtins.str: ...
    @property
    def seq(self) -> builtins.int: ...
    @property
    def span(self) -> builtins.int: ...
    @property
    def source(self) -> builtins.str: ...
    @property
    def move_kind(self) -> typing.Optional[builtins.str]: ...
    @property
    def tool(self) -> typing.Optional[ToolSnapshot]: ...
    @property
    def progress(self) -> typing.Optional[ProgressSnapshot]: ...
    @property
    def meta(self) -> typing.Any: ...

@typing.final
class MoveKind:
    r"""
    Standard move-type classification shared by all operations.
    
    Every toolpath point is tagged with one of these so that renderers
    can colour and categorise moves generically.
    """
    CUT: MoveKind = MoveKind.CUT
    TRAVEL: MoveKind = MoveKind.TRAVEL
    PLUNGE: MoveKind = MoveKind.PLUNGE
    LEAD_IN: MoveKind = MoveKind.LEAD_IN
    LEAD_OUT: MoveKind = MoveKind.LEAD_OUT
    LINK: MoveKind = MoveKind.LINK
    RESUME: MoveKind = MoveKind.RESUME
    ROUTE: MoveKind = MoveKind.ROUTE
    @property
    def value(self) -> builtins.int: ...
    @property
    def name(self) -> builtins.str: ...
    def __eq__(self, other: builtins.object, /) -> builtins.bool: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class ProgressSnapshot:
    r"""
    Snapshot of step progress during trace execution.
    """
    @property
    def step_idx(self) -> builtins.int: ...
    @property
    def ops_len(self) -> builtins.int: ...
    @property
    def status(self) -> builtins.int: ...

@typing.final
class Span:
    r"""
    One span record from a trace file.
    """
    @property
    def id(self) -> builtins.int: ...
    @property
    def parent(self) -> builtins.int: ...
    @property
    def source(self) -> builtins.str: ...
    @property
    def label(self) -> builtins.str: ...
    @property
    def attrs(self) -> typing.Any: ...
    @property
    def children(self) -> builtins.list[Span]: ...
    @property
    def events(self) -> builtins.list[Event]: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class ToolSnapshot:
    r"""
    Snapshot of tool position and heading at a trace event.
    """
    @property
    def pos_x(self) -> builtins.float: ...
    @property
    def pos_y(self) -> builtins.float: ...
    @property
    def pos_z(self) -> builtins.float: ...
    @property
    def heading(self) -> builtins.float: ...
    @property
    def prev_x(self) -> builtins.float: ...
    @property
    def prev_y(self) -> builtins.float: ...
    @property
    def prev_z(self) -> builtins.float: ...

@typing.final
class TraceFile:
    r"""
    Binary trace file with span/event access.
    
    Usage::
    
    ```python
    >>> from raygeo.trace import TraceFile
    >>> t = TraceFile("path/to/trace.bin")
    >>> t.ver
    3
    >>> t.root
    Span(id=1, parent=0, source='workplan', label='Workplan')
    >>> len(t.events)
    42
    ```
    """
    @property
    def ver(self) -> builtins.int: ...
    @property
    def spans(self) -> builtins.list[Span]: ...
    @property
    def events(self) -> builtins.list[Event]: ...
    @property
    def root(self) -> typing.Optional[Span]:
        r"""
        The root span (first span with parent == 0), or None.
        """
    @property
    def sources(self) -> typing.Any:
        r"""
        Distinct source strings across all spans and events.
        """
    def __new__(cls, path: builtins.str) -> TraceFile: ...
    def toolpath(self, span: typing.Optional[typing.Any] = None) -> builtins.list[tuple[builtins.float, builtins.float, builtins.str]]:
        r"""
        Toolpath points from Move events.
        
        Returns a list of ``(x, y, move_kind_name)`` tuples.
        If *span* is given (an int span id or a Span object), restrict
        to events belonging to that span.
        """
    def __len__(self) -> builtins.int: ...
    def __getitem__(self, idx: builtins.int) -> Event: ...
    def __repr__(self) -> builtins.str: ...

def get_route_detail_name(detail: int) -> str:
    r"""
    Return a human-readable label for a route-strategy detail code.
    """

