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

import builtins
import datetime
import enum
import typing
__all__ = [
    "ASTNode",
    "Cell",
    "CellRef",
    "EvaluationConfig",
    "EvaluationPlan",
    "ExcelError",
    "FormulaDialect",
    "LayerInfo",
    "LiteralValue",
    "NamedRangeRef",
    "Parser",
    "RangeAddress",
    "RangeRef",
    "RefWalker",
    "Sheet",
    "SheetPortSession",
    "TableRef",
    "Token",
    "TokenSubType",
    "TokenType",
    "Tokenizer",
    "TokenizerIter",
    "UnknownRef",
    "Workbook",
    "WorkbookConfig",
    "WorkbookMode",
    "load_workbook",
    "parse",
    "parse_formula",
    "recalculate_file",
    "tokenize",
]

@typing.final
class ASTNode:
    r"""
    An abstract syntax tree (AST) node representing a parsed formula.
    
    Use the top-level [`parse`] function to create an AST from a formula string.
    
    Example:
    ```python
        from formualizer import parse
    
        ast = parse("=SUM(A1:A3)")
        print(ast.pretty())
        print(ast.fingerprint())
        for ref in ast.walk_refs():
            print(ref)
    ```
    """
    def pretty(self) -> builtins.str:
        r"""
        Get the pretty-printed representation of this AST
        """
    def to_formula(self) -> builtins.str:
        r"""
        Round-trips the node back to canonical Excel formula (with leading '=').
        """
    def fingerprint(self) -> builtins.int:
        r"""
        Get a stable fingerprint hash of this AST structure
        """
    def children(self) -> builtins.list[ASTNode]:
        r"""
        Get immediate children of this AST node
        """
    def walk_refs(self) -> RefWalker:
        r"""
        Walk through all references in this AST
        """
    def to_dict(self) -> typing.Any:
        r"""
        Convert AST to a dictionary representation
        """
    def node_type(self) -> builtins.str:
        r"""
        Get the node type as a string
        """
    def get_literal_value(self) -> typing.Optional[typing.Any]:
        r"""
        Get the value for literal nodes
        """
    def get_reference_string(self) -> typing.Optional[builtins.str]:
        r"""
        Get the reference string for reference nodes
        """
    def get_reference(self) -> typing.Optional[CellRef  |  RangeRef  |  TableRef  |  NamedRangeRef  |  UnknownRef]:
        r"""
        Get the reference as a rich object for reference nodes
        """
    def get_operator(self) -> typing.Optional[builtins.str]:
        r"""
        Get the operator for unary/binary operation nodes
        """
    def get_function_name(self) -> typing.Optional[builtins.str]:
        r"""
        Get the function name for function nodes
        """
    def get_source_token(self) -> typing.Optional[Token]:
        r"""
        Get the source token if available
        """
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class Cell:
    @property
    def value(self) -> typing.Any: ...
    @property
    def formula(self) -> typing.Optional[builtins.str]: ...

@typing.final
class CellRef:
    @property
    def sheet(self) -> typing.Optional[builtins.str]: ...
    @property
    def row(self) -> builtins.int: ...
    @property
    def col(self) -> builtins.int: ...
    @property
    def abs_row(self) -> builtins.bool: ...
    @property
    def abs_col(self) -> builtins.bool: ...
    @property
    def str_col(self) -> builtins.str: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, sheet: typing.Optional[builtins.str], row: builtins.int, col: builtins.int | builtins.str, abs_row: builtins.bool = True, abs_col: builtins.bool = True) -> CellRef: ...
    @classmethod
    def from_string(cls, reference: builtins.str, default_sheet: typing.Optional[builtins.str] = None) -> CellRef: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class EvaluationConfig:
    r"""
    Configuration for workbook-backed evaluation.
    
    You typically pass this via `WorkbookConfig(eval_config=...)`.
    
    Example:
    ```python
        import formualizer as fz
    
        eval_cfg = fz.EvaluationConfig()
        eval_cfg.enable_parallel = True
    
        wb = fz.Workbook(config=fz.WorkbookConfig(eval_config=eval_cfg))
    ```
    """
    @property
    def enable_parallel(self) -> builtins.bool: ...
    @enable_parallel.setter
    def enable_parallel(self, value: builtins.bool) -> None:
        r"""
        Enable parallel evaluation
        """
    @property
    def max_threads(self) -> typing.Optional[builtins.int]: ...
    @max_threads.setter
    def max_threads(self, value: typing.Optional[builtins.int]) -> None:
        r"""
        Set maximum threads for parallel evaluation
        """
    @property
    def range_expansion_limit(self) -> builtins.int: ...
    @range_expansion_limit.setter
    def range_expansion_limit(self, value: builtins.int) -> None:
        r"""
        Set range expansion limit
        """
    @property
    def workbook_seed(self) -> builtins.int: ...
    @workbook_seed.setter
    def workbook_seed(self, value: builtins.int) -> None:
        r"""
        Set workbook seed for random functions
        """
    @property
    def case_sensitive_names(self) -> builtins.bool: ...
    @case_sensitive_names.setter
    def case_sensitive_names(self, value: builtins.bool) -> None:
        r"""
        Enable case-sensitive defined-name resolution.
        """
    @property
    def case_sensitive_tables(self) -> builtins.bool: ...
    @case_sensitive_tables.setter
    def case_sensitive_tables(self, value: builtins.bool) -> None:
        r"""
        Enable case-sensitive table-name resolution.
        """
    @property
    def warmup_enabled(self) -> builtins.bool: ...
    @warmup_enabled.setter
    def warmup_enabled(self, value: builtins.bool) -> None:
        r"""
        Enable or disable global warmup (pre-build flats/masks/indexes before evaluation)
        """
    @property
    def warmup_time_budget_ms(self) -> builtins.int: ...
    @warmup_time_budget_ms.setter
    def warmup_time_budget_ms(self, value: builtins.int) -> None:
        r"""
        Warmup time budget in milliseconds per evaluation invocation
        """
    @property
    def warmup_parallelism_cap(self) -> builtins.int: ...
    @warmup_parallelism_cap.setter
    def warmup_parallelism_cap(self, value: builtins.int) -> None:
        r"""
        Maximum parallelism for warmup building
        """
    @property
    def warmup_topk_refs(self) -> builtins.int: ...
    @warmup_topk_refs.setter
    def warmup_topk_refs(self, value: builtins.int) -> None:
        r"""
        Maximum top-K references to consider for flattening during warmup
        """
    @property
    def min_flat_cells(self) -> builtins.int: ...
    @min_flat_cells.setter
    def min_flat_cells(self, value: builtins.int) -> None:
        r"""
        Minimum number of cells in a range to consider flattening during warmup
        """
    @property
    def flat_cache_mb_cap(self) -> builtins.int: ...
    @flat_cache_mb_cap.setter
    def flat_cache_mb_cap(self, value: builtins.int) -> None:
        r"""
        Memory budget (MB) for pass-scoped flat cache during warmup
        """
    @property
    def date_system(self) -> builtins.str: ...
    @date_system.setter
    def date_system(self, value: builtins.str) -> None: ...
    def __new__(cls) -> EvaluationConfig:
        r"""
        Create a new evaluation configuration
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class EvaluationPlan:
    r"""
    Evaluation plan showing how cells would be evaluated
    """
    @property
    def total_vertices_to_evaluate(self) -> builtins.int: ...
    @property
    def layers(self) -> builtins.list[LayerInfo]: ...
    @property
    def cycles_detected(self) -> builtins.int: ...
    @property
    def dirty_count(self) -> builtins.int: ...
    @property
    def volatile_count(self) -> builtins.int: ...
    @property
    def parallel_enabled(self) -> builtins.bool: ...
    @property
    def estimated_parallel_layers(self) -> builtins.int: ...
    @property
    def target_cells(self) -> builtins.list[builtins.str]: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class ExcelError:
    r"""
    Python representation of Excel domain errors
    """
    @property
    def kind(self) -> builtins.str:
        r"""
        Get the error kind
        """
    @property
    def message(self) -> typing.Optional[builtins.str]:
        r"""
        Get the error message
        """
    @property
    def row(self) -> typing.Optional[builtins.int]:
        r"""
        Get error row (if set)
        """
    @property
    def col(self) -> typing.Optional[builtins.int]:
        r"""
        Get error column (if set)
        """
    @property
    def extra(self) -> typing.Optional[typing.Any]:
        r"""
        Get extra error data
        """
    @property
    def is_div(self) -> builtins.bool:
        r"""
        Check if this is a #DIV/0! error
        """
    @property
    def is_ref(self) -> builtins.bool:
        r"""
        Check if this is a #REF! error
        """
    @property
    def is_name(self) -> builtins.bool:
        r"""
        Check if this is a #NAME? error
        """
    @property
    def is_value(self) -> builtins.bool:
        r"""
        Check if this is a #VALUE! error
        """
    @property
    def is_num(self) -> builtins.bool:
        r"""
        Check if this is a #NUM! error
        """
    @property
    def is_null(self) -> builtins.bool:
        r"""
        Check if this is a #NULL! error
        """
    @property
    def is_na(self) -> builtins.bool:
        r"""
        Check if this is a #N/A error
        """
    @property
    def is_spill(self) -> builtins.bool:
        r"""
        Check if this is a #SPILL! error
        """
    @property
    def is_calc(self) -> builtins.bool:
        r"""
        Check if this is a #CALC! error
        """
    @property
    def is_circ(self) -> builtins.bool:
        r"""
        Check if this is a circular reference error
        """
    @property
    def is_cancelled(self) -> builtins.bool:
        r"""
        Check if this is a cancellation error
        """
    @property
    def is_error(self) -> builtins.bool:
        r"""
        Check if this is a #ERROR! error
        """
    @property
    def is_nimpl(self) -> builtins.bool:
        r"""
        Check if this is a #N/IMPL! error
        """
    def __new__(cls, kind: builtins.str, message: typing.Optional[builtins.str], row: typing.Optional[builtins.int], col: typing.Optional[builtins.int], spill_rows: typing.Optional[builtins.int], spill_cols: typing.Optional[builtins.int]) -> ExcelError:
        r"""
        Create a new Excel error
        """
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class LayerInfo:
    r"""
    Information about a single evaluation layer
    """
    @property
    def vertex_count(self) -> builtins.int: ...
    @property
    def parallel_eligible(self) -> builtins.bool: ...
    @property
    def sample_cells(self) -> builtins.list[builtins.str]: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class LiteralValue:
    r"""
    A typed scalar or array value understood by the formula engine.
    
    You can construct `LiteralValue` instances explicitly (e.g. `LiteralValue.number(1.23)`),
    but most APIs also accept Python primitives and will convert them automatically.
    
    Example:
    ```python
        import formualizer as fz
    
        v1 = fz.LiteralValue.number(1.5)
        v2 = fz.LiteralValue.text("hello")
    
        wb = fz.Workbook()
        s = wb.sheet("Data")
        s.set_value(1, 1, v1)
        s.set_value(1, 2, v2)
    ```
    """
    @property
    def is_int(self) -> builtins.bool:
        r"""
        Check if value is an Int
        """
    @property
    def is_number(self) -> builtins.bool:
        r"""
        Check if value is a Number
        """
    @property
    def is_boolean(self) -> builtins.bool:
        r"""
        Check if value is Boolean
        """
    @property
    def is_text(self) -> builtins.bool:
        r"""
        Check if value is Text
        """
    @property
    def is_empty(self) -> builtins.bool:
        r"""
        Check if value is Empty
        """
    @property
    def is_date(self) -> builtins.bool:
        r"""
        Check if value is Date
        """
    @property
    def is_time(self) -> builtins.bool:
        r"""
        Check if value is Time
        """
    @property
    def is_datetime(self) -> builtins.bool:
        r"""
        Check if value is DateTime
        """
    @property
    def is_duration(self) -> builtins.bool:
        r"""
        Check if value is Duration
        """
    @property
    def is_array(self) -> builtins.bool:
        r"""
        Check if value is Array
        """
    @property
    def is_error(self) -> builtins.bool:
        r"""
        Check if value is Error
        """
    @property
    def is_pending(self) -> builtins.bool:
        r"""
        Check if value is Pending
        """
    @property
    def type_name(self) -> builtins.str:
        r"""
        Get the type name of the value
        """
    @property
    def error_kind(self) -> typing.Optional[builtins.str]:
        r"""
        If this is an error, return the error kind string; otherwise None
        """
    @property
    def error_message(self) -> typing.Optional[builtins.str]:
        r"""
        If this is an error, return the error message; otherwise None
        """
    @property
    def error_location(self) -> typing.Optional[tuple[builtins.int, builtins.int]]:
        r"""
        If this is an error and has location, return (row, col); otherwise None
        """
    @property
    def error_origin(self) -> typing.Optional[tuple[typing.Optional[builtins.str], builtins.int, builtins.int]]:
        r"""
        If this is an error and has an origin location, return (sheet, row, col); otherwise None
        """
    def as_int(self) -> builtins.int:
        r"""
        Extract as Python int; errors if not an Int
        """
    def as_number(self) -> builtins.float:
        r"""
        Extract as Python float; errors if not a Number/Int/Boolean
        """
    @staticmethod
    def int(value: builtins.int) -> LiteralValue:
        r"""
        Create an Int value
        """
    @staticmethod
    def number(value: builtins.float) -> LiteralValue:
        r"""
        Create a Number (float) value
        """
    @staticmethod
    def boolean(value: builtins.bool) -> LiteralValue:
        r"""
        Create a Boolean value
        """
    @staticmethod
    def text(value: builtins.str) -> LiteralValue:
        r"""
        Create a Text value
        """
    @staticmethod
    def empty() -> LiteralValue:
        r"""
        Create an Empty value
        """
    @staticmethod
    def date(year: builtins.int, month: builtins.int, day: builtins.int) -> LiteralValue:
        r"""
        Create a Date value
        """
    @staticmethod
    def time(hour: builtins.int, minute: builtins.int, second: builtins.int) -> LiteralValue:
        r"""
        Create a Time value
        """
    @staticmethod
    def datetime(year: builtins.int, month: builtins.int, day: builtins.int, hour: builtins.int, minute: builtins.int, second: builtins.int) -> LiteralValue:
        r"""
        Create a DateTime value
        """
    @staticmethod
    def duration(seconds: builtins.int) -> LiteralValue:
        r"""
        Create a Duration value
        """
    @staticmethod
    def array(values: typing.Sequence[typing.Sequence[LiteralValue]]) -> LiteralValue:
        r"""
        Create an Array value from a 2D list
        """
    @staticmethod
    def error(kind: builtins.str, message: typing.Optional[builtins.str]) -> LiteralValue:
        r"""
        Create an Error value
        """
    def to_python(self) -> typing.Any:
        r"""
        Convert to a Python object
        """
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class NamedRangeRef:
    @property
    def name(self) -> builtins.str: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, name: builtins.str) -> NamedRangeRef: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class Parser:
    r"""
    Stateful formula parser.
    
    Most users can use the top-level [`parse`] function, but `Parser` is useful
    if you want to parse multiple formulas with the same instance.
    
    Example:
    ```python
        import formualizer as fz
    
        p = fz.Parser()
        ast = p.parse_string("=1+2")
        print(ast.pretty())
    ```
    """
    def __new__(cls) -> Parser: ...
    def parse_string(self, formula: builtins.str, dialect: typing.Optional[FormulaDialect] = None) -> ASTNode:
        r"""
        Parse a formula string into an AST
        """
    def parse_tokens(self, tokenizer: Tokenizer, include_whitespace: builtins.bool = False, dialect: typing.Optional[FormulaDialect] = None) -> ASTNode:
        r"""
        Parse from a tokenizer
        """

@typing.final
class RangeAddress:
    @property
    def sheet(self) -> builtins.str: ...
    @property
    def start_row(self) -> builtins.int: ...
    @property
    def start_col(self) -> builtins.int: ...
    @property
    def end_row(self) -> builtins.int: ...
    @property
    def end_col(self) -> builtins.int: ...
    def __new__(cls, sheet: builtins.str, start_row: builtins.int, start_col: builtins.int, end_row: builtins.int, end_col: builtins.int) -> RangeAddress: ...

@typing.final
class RangeRef:
    @property
    def sheet(self) -> typing.Optional[builtins.str]: ...
    @property
    def start(self) -> typing.Optional[CellRef]: ...
    @property
    def end(self) -> typing.Optional[CellRef]: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, sheet: typing.Optional[builtins.str], start: typing.Optional[CellRef], end: typing.Optional[CellRef]) -> RangeRef: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class RefWalker:
    r"""
    Iterator over reference-like objects found in an AST.
    
    Constructed via `ASTNode.walk_refs()`.
    
    Example:
    ```python
        from formualizer import parse
    
        ast = parse("=SUM(A1, Sheet2!B3)")
        for r in ast.walk_refs():
            print(r)
    ```
    """
    def __iter__(self) -> RefWalker: ...
    def __next__(self) -> typing.Optional[typing.Any]: ...

@typing.final
class Sheet:
    r"""
    A per-sheet facade for interacting with a [`Workbook`].
    
    Rows and columns are **1-based**.
    
    In most cases you obtain a `Sheet` by calling `Workbook.sheet(name)`.
    
    Example:
    ```python
        import formualizer as fz
    
        wb = fz.Workbook()
        s = wb.sheet("Data")
        s.set_value(1, 1, 10)
        s.set_value(2, 1, 20)
        s.set_formula(3, 1, "=SUM(A1:A2)")
        print(wb.evaluate_cell("Data", 3, 1))
    ```
    """
    @property
    def name(self) -> builtins.str: ...
    def set_value(self, row: builtins.int, col: builtins.int, value: typing.Any) -> None:
        r"""
        Set a single value (stores in workbook, doesn't evaluate).
        
        The `value` may be a Python primitive (int/float/bool/str/None) or a
        [`LiteralValue`].
        """
    def set_formula(self, row: builtins.int, col: builtins.int, formula: builtins.str) -> None:
        r"""
        Set a single formula (stores in workbook, doesn't evaluate).
        
        Formulas should be Excel-style and typically start with `=`.
        """
    def get_cell(self, row: builtins.int, col: builtins.int) -> Cell:
        r"""
        Get a single cell's stored data (no evaluation)
        """
    def set_values_batch(self, start_row: builtins.int, start_col: builtins.int, rows: builtins.int, _cols: builtins.int, data: list) -> None:
        r"""
        Batch set values into a rectangle
        """
    def set_formulas_batch(self, start_row: builtins.int, start_col: builtins.int, rows: builtins.int, _cols: builtins.int, formulas: list) -> None:
        r"""
        Batch set formulas into a rectangle
        """
    def get_values(self, range: RangeAddress) -> builtins.list[builtins.list[typing.Any]]:
        r"""
        Get values from a range (no evaluation, just stored values)
        """
    def get_formulas(self, range: RangeAddress) -> builtins.list[builtins.list[builtins.str]]:
        r"""
        Get formulas from a range (returns formula strings, empty strings for non-formula cells)
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class SheetPortSession:
    r"""
    Bind a SheetPort manifest to a workbook and evaluate it like a typed function.
    
    A SheetPort manifest describes "ports" (typed inputs and outputs) and how they
    map to cell ranges in a spreadsheet.
    
    This makes a spreadsheet behave like an API:
    - validate inputs against schema/constraints
    - write inputs into the workbook
    - evaluate once (optionally deterministically)
    - read outputs back into Python
    
    Example:
    ```python
        from formualizer import SheetPortSession, Workbook
    
        manifest_yaml = (
            "spec: fio\n"
            "spec_version: \"0.3.0\"\n"
            "manifest:\n"
            "  id: pricing-model\n"
            "  name: Pricing Model\n"
            "  workbook:\n"
            "    uri: memory://pricing.xlsx\n"
            "    locale: en-US\n"
            "    date_system: 1900\n"
            "ports:\n"
            "  - id: base_price\n"
            "    dir: in\n"
            "    shape: scalar\n"
            "    location: { a1: Inputs!A1 }\n"
            "    schema: { type: number }\n"
            "  - id: final_price\n"
            "    dir: out\n"
            "    shape: scalar\n"
            "    location: { a1: Outputs!A1 }\n"
            "    schema: { type: number }\n"
        )
    
        wb = Workbook()
        wb.add_sheet("Inputs")
        wb.add_sheet("Outputs")
        wb.set_formula("Outputs", 1, 1, "=Inputs!A1*1.2")
    
        session = SheetPortSession.from_manifest_yaml(manifest_yaml, wb)
        session.write_inputs({"base_price": 100.0})
        out = session.evaluate_once(freeze_volatile=True)
        print(out["final_price"])
    ```
    """
    @property
    def manifest(self) -> typing.Any:
        r"""
        Manifest metadata as a Python dictionary (mirrors the YAML structure).
        """
    @classmethod
    def from_manifest_path(cls, manifest_path: builtins.str, workbook_path: builtins.str, backend: typing.Optional[builtins.str] = None) -> SheetPortSession: ...
    @classmethod
    def from_manifest_yaml(cls, _cls: type, manifest_yaml: builtins.str, workbook: Workbook) -> SheetPortSession: ...
    def describe_ports(self) -> typing.Any:
        r"""
        Describe each port with direction, shape, constraints, and resolved defaults.
        """
    def read_inputs(self) -> typing.Any: ...
    def read_outputs(self) -> typing.Any: ...
    def write_inputs(self, update: typing.Any) -> None:
        r"""
        Write input values into the bound workbook.
        
        Args:
            update: A Python `dict` mapping port IDs to values.
        
        Values are validated and converted based on the manifest schema.
        
        Example:
        ```python
            session.write_inputs({"base_price": 100.0, "qty": 2})
        ```
        """
    def evaluate_once(self, *, freeze_volatile: builtins.bool = False, rng_seed: typing.Optional[builtins.int] = None, deterministic_timestamp_utc: typing.Optional[datetime.datetime] = None, deterministic_timezone: typing.Optional[typing.Any] = None) -> typing.Any:
        r"""
        Evaluate the workbook once and return the output snapshot.
        
        This performs a single end-to-end SheetPort evaluation:
        - applies deterministic options (optional)
        - evaluates the workbook
        - reads port outputs and returns them as a Python dict
        
        Determinism:
        - `freeze_volatile=True` freezes volatile functions (e.g. `NOW()`, `RAND()`) within the evaluation.
        - `rng_seed` sets a seed used by random functions.
        - `deterministic_timestamp_utc` + `deterministic_timezone` control time and timezone.
        
        Example:
        ```python
            import datetime
            from formualizer import SheetPortSession
        
            out = session.evaluate_once(
                freeze_volatile=True,
                rng_seed=123,
                deterministic_timestamp_utc=datetime.datetime(2024, 1, 1, tzinfo=datetime.timezone.utc),
                deterministic_timezone="utc",
            )
            print(out)
        ```
        """

@typing.final
class TableRef:
    @property
    def name(self) -> builtins.str: ...
    @property
    def spec(self) -> typing.Optional[builtins.str]: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, name: builtins.str, spec: typing.Optional[builtins.str]) -> TableRef: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class Token:
    r"""
    A single token produced by [`Tokenizer`].
    
    Tokens include the raw `value` string, a `token_type` and `subtype`, and
    byte offsets (`start`, `end`) pointing into the original formula string.
    
    Example:
    ```python
        import formualizer as fz
    
        tok = fz.tokenize("=A1+1")[0]
        print(tok.value)
        print(tok.token_type, tok.subtype)
        print(tok.start, tok.end)
    ```
    """
    @property
    def value(self) -> builtins.str: ...
    @property
    def token_type(self) -> TokenType: ...
    @property
    def subtype(self) -> TokenSubType: ...
    @property
    def start(self) -> builtins.int: ...
    @property
    def end(self) -> builtins.int: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...
    def to_dict(self) -> typing.Any: ...
    def is_operator(self) -> builtins.bool:
        r"""
        Check if this token is an operator
        """
    def get_precedence(self) -> typing.Optional[tuple[builtins.int, builtins.str]]:
        r"""
        Get the precedence of this token (if it's an operator)
        """

@typing.final
class Tokenizer:
    r"""
    Tokenize a formula string into a sequence of [`Token`] objects.
    
    The tokenizer is iterable and supports indexing.
    
    Example:
    ```python
        import formualizer as fz
    
        t = fz.Tokenizer("=SUM(A1:A3)")
        print(len(t))
        print(t.render())
        print([tok.value for tok in t.tokens()])
    ```
    """
    @property
    def dialect(self) -> FormulaDialect: ...
    def __new__(cls, formula: builtins.str, dialect: typing.Optional[FormulaDialect] = None) -> Tokenizer: ...
    def tokens(self) -> builtins.list[Token]:
        r"""
        Get all tokens as a list
        """
    def render(self) -> builtins.str:
        r"""
        Reconstruct the original formula from tokens
        """
    def __iter__(self) -> TokenizerIter:
        r"""
        Make the tokenizer iterable
        """
    def __len__(self) -> builtins.int: ...
    def __getitem__(self, index: builtins.int) -> Token: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class TokenizerIter:
    r"""
    Iterator returned from `iter(Tokenizer)`.
    
    Most users won't instantiate this directly.
    """
    def __iter__(self) -> TokenizerIter: ...
    def __next__(self) -> typing.Optional[Token]: ...

@typing.final
class UnknownRef:
    @property
    def raw(self) -> builtins.str: ...
    def __eq__(self, other: builtins.object) -> builtins.bool: ...
    def __hash__(self) -> builtins.int: ...
    def __new__(cls, raw: builtins.str) -> UnknownRef: ...
    def __repr__(self) -> builtins.str: ...
    def __str__(self) -> builtins.str: ...

@typing.final
class Workbook:
    r"""
    An in-memory Excel-like workbook which can store values and formulas and evaluate them.
    
    Rows and columns are **1-based** (as in Excel).
    
    The workbook supports setting values and formulas, evaluating individual cells,
    and (optionally) tracking a changelog for undo/redo.
    
    Quick start:
    ```python
        import formualizer as fz
    
        wb = fz.Workbook()
        s = wb.sheet("Sheet1")
    
        s.set_value(1, 1, fz.LiteralValue.number(1000.0))  # A1
        s.set_value(2, 1, fz.LiteralValue.number(0.05))    # A2
        s.set_value(3, 1, fz.LiteralValue.number(12.0))    # A3
    
        s.set_formula(1, 2, "=PMT(A2/12, A3, -A1)")
        print(wb.evaluate_cell("Sheet1", 1, 2))
    ```
    """
    @property
    def sheet_names(self) -> builtins.list[builtins.str]: ...
    def __new__(cls, *, mode: typing.Optional[WorkbookMode] = None, config: typing.Optional[WorkbookConfig] = None) -> Workbook: ...
    @classmethod
    def load_path(cls, path: builtins.str, strategy: typing.Optional[builtins.str] = None, backend: typing.Optional[builtins.str] = None, *, mode: typing.Optional[WorkbookMode] = None, config: typing.Optional[WorkbookConfig] = None) -> Workbook:
        r"""
        Class method: load an XLSX workbook from a file path.
        
        This is equivalent to the top-level `formualizer.load_workbook(...)`.
        
        Args:
            path: Path to the `.xlsx` file.
            backend: Backend name (currently defaults to `calamine`).
            mode/config: Optional workbook configuration.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook.load_path("model.xlsx")
            print(wb.sheet_names)
        ```
        """
    def sheet(self, name: builtins.str) -> Sheet:
        r"""
        Get or create a sheet by name.
        
        This returns a lightweight handle which forwards operations to the parent workbook.
        
        Notes:
        - Sheet names are case-sensitive.
        - The sheet is created if it doesn't exist.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook()
            s = wb.sheet("Data")
            s.set_value(1, 1, 123)
        ```
        """
    @classmethod
    def from_path(cls, path: builtins.str, backend: typing.Optional[builtins.str] = None, *, mode: typing.Optional[WorkbookMode] = None, config: typing.Optional[WorkbookConfig] = None) -> Workbook: ...
    def add_sheet(self, name: builtins.str) -> None:
        r"""
        Add a sheet to the workbook.
        
        This is idempotent: adding an existing sheet name is a no-op.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook()
            wb.add_sheet("Inputs")
            wb.add_sheet("Outputs")
        ```
        """
    def register_function(self, name: builtins.str, callback: typing.Any, *, min_args: builtins.int = 0, max_args: typing.Optional[builtins.int] = None, volatile: builtins.bool = False, thread_safe: builtins.bool = False, deterministic: builtins.bool = True, allow_override_builtin: builtins.bool = False) -> None:
        r"""
        Register a workbook-local custom function backed by a Python callable.
        """
    def unregister_function(self, name: builtins.str) -> None:
        r"""
        Unregister a previously registered workbook-local custom function.
        """
    def list_functions(self) -> typing.Any:
        r"""
        List registered workbook-local custom functions and their options.
        """
    def get_named_ranges(self, sheet: typing.Optional[builtins.str] = None) -> typing.Any:
        r"""
        Return named ranges visible to the workbook or a specific sheet.
        
        Args:
            sheet: Optional sheet name. When provided, returns workbook-scoped names plus
                sheet-scoped names visible on that sheet.
        
        Returns:
            A list of dictionaries with keys:
            - `name`
            - `scope` (`"workbook" | "sheet"`)
            - `scope_sheet` (optional)
            - `kind` (`"cell" | "range" | "literal" | "formula"`)
            - address fields for `cell`/`range` kinds
        """
    def set_value(self, sheet: builtins.str, row: builtins.int, col: builtins.int, value: typing.Any) -> None:
        r"""
        Set a single cell value.
        
        Rows and columns are **1-based**.
        
        The `value` may be a Python primitive (int/float/bool/str/None), a
        `datetime/date/time/timedelta`, or a [`LiteralValue`].
        
        Example:
        ```python
            import datetime
            import formualizer as fz
        
            wb = fz.Workbook()
            wb.add_sheet("Sheet1")
        
            wb.set_value("Sheet1", 1, 1, 123)
            wb.set_value("Sheet1", 2, 1, 3.14)
            wb.set_value("Sheet1", 3, 1, datetime.date(2024, 1, 1))
            wb.set_value("Sheet1", 4, 1, fz.LiteralValue.text("hello"))
        ```
        """
    def set_formula(self, sheet: builtins.str, row: builtins.int, col: builtins.int, formula: builtins.str) -> None:
        r"""
        Set a single cell formula.
        
        Rows and columns are **1-based**. Formulas should be Excel-style and typically
        begin with `=`.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook()
            s = wb.sheet("Sheet1")
            s.set_value(1, 1, 10)
            s.set_value(2, 1, 20)
            s.set_formula(3, 1, "=SUM(A1:A2)")
            print(wb.evaluate_cell("Sheet1", 3, 1))
        ```
        """
    def evaluate_cell(self, sheet: builtins.str, row: builtins.int, col: builtins.int) -> typing.Any:
        r"""
        Evaluate a single cell and return the computed value.
        
        Rows and columns are **1-based**.
        
        Returns:
            A Python value converted from the engine's internal [`LiteralValue`].
            For example: `float`, `int`, `str`, `bool`, `datetime.*`, `None`, or
            nested lists for arrays.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook()
            s = wb.sheet("Data")
            s.set_value(1, 1, 100)
            s.set_value(2, 1, 200)
            s.set_formula(3, 1, "=SUM(A1:A2)")
            print(wb.evaluate_cell("Data", 3, 1))
        ```
        """
    def evaluate_all(self) -> None: ...
    def evaluate_cells(self, targets: list) -> typing.Any: ...
    def get_eval_plan(self, targets: list) -> EvaluationPlan: ...
    def cancel(self) -> None: ...
    def reset_cancel(self) -> None: ...
    def get_value(self, sheet: builtins.str, row: builtins.int, col: builtins.int) -> typing.Optional[typing.Any]: ...
    def get_formula(self, sheet: builtins.str, row: builtins.int, col: builtins.int) -> typing.Optional[builtins.str]: ...
    def set_changelog_enabled(self, enabled: builtins.bool) -> None: ...
    def set_actor_id(self, actor_id: typing.Optional[builtins.str] = None) -> None: ...
    def set_correlation_id(self, correlation_id: typing.Optional[builtins.str] = None) -> None: ...
    def set_reason(self, reason: typing.Optional[builtins.str] = None) -> None: ...
    def begin_action(self, description: builtins.str) -> None:
        r"""
        Begin grouping multiple edits into a single undo/redo action.
        
        This is only relevant when the changelog is enabled.
        
        Example:
        ```python
            import formualizer as fz
        
            wb = fz.Workbook()
            wb.set_changelog_enabled(True)
            s = wb.sheet("Data")
        
            wb.begin_action("update prices")
            s.set_value(1, 1, 100)
            s.set_value(2, 1, 200)
            wb.end_action()
        
            wb.undo()  # reverts both values at once
        ```
        """
    def end_action(self) -> None:
        r"""
        End the current grouped undo/redo action.
        """
    def undo(self) -> None:
        r"""
        Undo the most recent workbook edit.
        """
    def redo(self) -> None:
        r"""
        Redo the most recently undone edit.
        """
    def set_values_batch(self, sheet: builtins.str, start_row: builtins.int, start_col: builtins.int, data: list) -> None: ...
    def set_formulas_batch(self, sheet: builtins.str, start_row: builtins.int, start_col: builtins.int, formulas: list) -> None: ...
    def __getitem__(self, name: builtins.str) -> Sheet:
        r"""
        Indexing to get a Sheet view (compatibility)
        """

@typing.final
class WorkbookConfig:
    r"""
    Configuration for creating a [`Workbook`].
    
    You typically pass this into `Workbook(config=...)`.
    
    Example:
    ```python
        import formualizer as fz
    
        cfg = fz.WorkbookConfig(
            mode=fz.WorkbookMode.Interactive,
            enable_changelog=True,
            eval_config=fz.EvaluationConfig(),
        )
        wb = fz.Workbook(config=cfg)
    ```
    """
    def __new__(cls, *, mode: WorkbookMode = ..., eval_config: typing.Optional[EvaluationConfig] = None, enable_changelog: typing.Optional[builtins.bool] = None) -> WorkbookConfig: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class FormulaDialect(enum.Enum):
    r"""
    Formula dialect enum exposed to Python
    """
    Excel = ...
    OpenFormula = ...

    def __str__(self) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class TokenSubType(enum.Enum):
    r"""
    Python-exposed token subtype enum
    """
    None_ = ...
    Text = ...
    Number = ...
    Logical = ...
    Error = ...
    Range = ...
    Open = ...
    Close = ...
    Arg = ...
    Row = ...

    def __str__(self) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class TokenType(enum.Enum):
    r"""
    Python-exposed token type enum
    """
    Literal = ...
    Operand = ...
    Func = ...
    Array = ...
    Paren = ...
    Sep = ...
    OpPrefix = ...
    OpInfix = ...
    OpPostfix = ...
    Whitespace = ...

    def __str__(self) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

@typing.final
class WorkbookMode(enum.Enum):
    r"""
    Workbook mode enum exposed to Python.
    """
    Ephemeral = ...
    Interactive = ...

    def __str__(self) -> builtins.str: ...
    def __repr__(self) -> builtins.str: ...

def load_workbook(path: builtins.str, strategy: typing.Optional[builtins.str] = None) -> Workbook:
    r"""
    Load an XLSX workbook from a filesystem path.
    
    This is a convenience wrapper around `Workbook.from_path(...)`.
    
    Args:
        path: Path to an `.xlsx` file.
        strategy: Currently accepted for backward compatibility.
            (The backend/strategy is currently fixed to `calamine` + eager load.)
    
    Example:
    ```python
        import formualizer as fz
    
        wb = fz.load_workbook("financial_model.xlsx")
        print(wb.evaluate_cell("Summary", 1, 2))
    ```
    """

def parse(formula: builtins.str, dialect: typing.Optional[FormulaDialect] = None) -> ASTNode:
    r"""
    Parse a formula string into an [`ASTNode`].
    
    The returned AST supports analysis helpers like `.pretty()`, `.to_formula()`,
    `.fingerprint()`, `.walk_refs()`, and reference extraction.
    
    Args:
        formula: The formula string. It may optionally start with `=`.
        dialect: Optional dialect hint.
    
    Example:
    ```python
        from formualizer import parse
        from formualizer.visitor import collect_references, collect_function_names
    
        ast = parse("=SUMIFS(Revenue,Region,A1,Year,B1)")
        print(ast.pretty())
        print(ast.to_formula())
        print(collect_references(ast))
        print(collect_function_names(ast))
    ```
    """

def parse_formula(formula: builtins.str, dialect: typing.Optional[FormulaDialect] = None) -> ASTNode:
    r"""
    Convenience function to parse a formula string directly
    """

def recalculate_file(path: builtins.str, output: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    Recalculate an XLSX workbook and write formula cached values back to file.
    
    Args:
        path: Input `.xlsx` path.
        output: Optional output path. If omitted, updates `path` in-place.
    
    Returns:
        A summary dictionary containing total/per-sheet evaluated counts and errors.
    
    Note:
        Formula text is preserved. Cached-value typing follows the active
        `umya-spreadsheet` implementation.
    """

def tokenize(formula: builtins.str, dialect: typing.Optional[FormulaDialect] = None) -> Tokenizer:
    r"""
    Tokenize a formula string into a structured [`Tokenizer`].
    
    This is a convenience wrapper around `Tokenizer(formula, dialect=...)`.
    
    Args:
        formula: The formula string. It may optionally start with `=`.
        dialect: Optional dialect hint (`FormulaDialect.Excel` or `FormulaDialect.OpenFormula`).
    
    Returns:
        A [`Tokenizer`] which can be iterated to yield [`Token`] objects.
    
    Example:
    ```python
        import formualizer as fz
    
        t = fz.tokenize("=SUM(A1:A3)")
        print(t.render())
    
        for tok in t:
            print(tok.value, tok.token_type, tok.subtype, tok.start, tok.end)
    ```
    """



# Backwards compatible Py* aliases
#
# Historically this package exported most symbols with a `Py...` prefix.
# Keep these aliases so older code continues to type-check.
PyToken = Token
PyTokenizer = Tokenizer
PyTokenizerIter = TokenizerIter
PyRefWalker = RefWalker
PyTokenType = TokenType
PyTokenSubType = TokenSubType
PyFormulaDialect = FormulaDialect
