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

import builtins
from raygeo import ops
import typing
__all__ = [
    "LinkStrategy",
    "find_pass_entry",
    "find_pass_exit",
    "link_passes",
]

@typing.final
class LinkStrategy:
    RETRACT: builtins.str = 'retract'
    STAY_DOWN: builtins.str = 'stay_down'

def find_pass_entry(ops: ops.Ops) -> tuple[float, float, float] | None:
    r"""
    Find the entry point of an Ops sequence.
    
    Scans for the first travel (MoveTo) endpoint, falling back to
    the first moving command endpoint.
    
    :param ops: An :class:`~raygeo.ops.Ops` container.
    :returns: ``(x, y, z)`` or ``None`` if no moving commands exist.
    :complexity: O(n) where n = number of commands
    """

def find_pass_exit(ops: ops.Ops) -> tuple[float, float, float] | None:
    r"""
    Find the exit point of an Ops sequence.
    
    Scans backwards for the last moving command endpoint.
    
    :param ops: An :class:`~raygeo.ops.Ops` container.
    :returns: ``(x, y, z)`` or ``None`` if no moving commands exist.
    :complexity: O(n) where n = number of commands
    """

def link_passes(passes: list[ops.Ops], safe_z: float, strategy: str | LinkStrategy) -> ops.Ops:
    r"""
    Join ordered machining passes into a single Ops sequence.
    
    The first pass is emitted as-is; subsequent passes are prefixed
    with travel moves according to *strategy*:
    
    * ``"retract"`` / ``LinkStrategy.RETRACT`` — retract to
      *safe_z*, move XY at that height, then descend to the next
      pass start Z.
    * ``"stay_down"`` / ``LinkStrategy.STAY_DOWN`` — move directly
      from the previous pass end to the next pass start without
      retracting.
    
    :param passes: Ordered list of :class:`~raygeo.ops.Ops` passes.
    :param safe_z: Z height for retract moves (mm).
    :param strategy: Linking strategy.
    :returns: A single :class:`~raygeo.ops.Ops` container.
    :complexity: O(n) where n = total commands across all passes
    """

