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

import builtins
import typing
__all__ = [
    "PyEngine",
    "PyEngineConfig",
    "PySubscription",
    "enable_sdk_logging",
    "ext_build_corporate_bonds_query",
    "ext_build_earning_header_rename",
    "ext_build_etf_holdings_query",
    "ext_build_futures_ticker",
    "ext_build_fx_pair",
    "ext_build_preferreds_query",
    "ext_build_yas_overrides",
    "ext_calculate_level_percentages",
    "ext_cdx_gen_to_specific",
    "ext_clear_exchange_override",
    "ext_contract_index",
    "ext_currencies_needing_conversion",
    "ext_default_bqr_datetimes",
    "ext_default_turnover_dates",
    "ext_derive_sessions",
    "ext_filter_candidates_by_cycle",
    "ext_filter_equity_tickers",
    "ext_filter_valid_contracts",
    "ext_fmt_date",
    "ext_generate_futures_candidates",
    "ext_get_dvd_type",
    "ext_get_dvd_types",
    "ext_get_exchange_override",
    "ext_get_futures_months",
    "ext_get_market_rule",
    "ext_get_month_code",
    "ext_get_month_name",
    "ext_infer_timezone",
    "ext_is_long_format",
    "ext_is_specific_contract",
    "ext_list_exchange_overrides",
    "ext_normalize_tickers",
    "ext_parse_cdx_ticker",
    "ext_parse_date",
    "ext_parse_ticker",
    "ext_pivot_to_wide",
    "ext_previous_cdx_series",
    "ext_rename_dividend_columns",
    "ext_rename_etf_columns",
    "ext_same_currency",
    "ext_session_times_to_utc",
    "ext_set_exchange_override",
    "ext_validate_generic_ticker",
    "get_log_level",
    "recipe_active_cdx",
    "recipe_active_futures",
    "recipe_bqr",
    "recipe_cdx_ticker",
    "recipe_corporate_bonds",
    "recipe_currency_conversion",
    "recipe_dividend",
    "recipe_etf_holdings",
    "recipe_fut_ticker",
    "recipe_preferreds",
    "recipe_turnover",
    "recipe_yas",
    "sdk_version",
    "set_log_level",
    "version",
]

@typing.final
class PyEngine:
    r"""
    Python wrapper for the xbbg Engine.
    """
    def __new__(cls, host: builtins.str = 'localhost', port: builtins.int = 8194) -> PyEngine:
        r"""
        Create a new Engine with optional host/port configuration.
        
        This blocks while connecting to Bloomberg. GIL is released during connection.
        For more configuration options, use `Engine.with_config()`.
        """
    @staticmethod
    def with_config(config: PyEngineConfig) -> PyEngine:
        r"""
        Create a new Engine with full configuration.
        
        This blocks while connecting to Bloomberg. GIL is released during connection.
        
        Example:
        ```python
        config = EngineConfig(
            host="localhost",
            port=8194,
            request_pool_size=4,
            subscription_pool_size=8,
            overflow_policy="drop_newest",
        )
        engine = Engine.with_config(config)
        ```
        """
    def request(self, params: dict) -> typing.Any:
        r"""
        Generic async Bloomberg request.
        
        Accepts a dictionary of parameters and returns a PyArrow RecordBatch.
        
        Required keys:
        - service: Bloomberg service URI (e.g., "//blp/refdata")
        - operation: Request operation name (e.g., "ReferenceDataRequest")
          Use "" / Operation.RAW_REQUEST together with request_operation for raw mode.
        
        Optional keys:
        - extractor: Extractor type hint (e.g., "refdata", "histdata", "intraday_bar")
          If omitted, Rust resolves a default from `operation`.
        - request_operation: Actual Bloomberg operation name when operation=""
        
        Optional keys (depend on request type):
        - securities: List of security identifiers
        - security: Single security identifier
        - fields: List of field names
        - overrides: List of (name, value) tuples
        - start_date, end_date: For historical requests
        - start_datetime, end_datetime: For intraday requests
        - event_type: For intraday bars (TRADE, BID, ASK)
        - interval: Bar interval in minutes
        - options: Additional Bloomberg options
        """
    def resolve_exchange(self, ticker: builtins.str) -> typing.Any:
        r"""
        Resolve exchange metadata using override -> cache -> Bloomberg waterfall.
        """
    def fetch_market_info(self, ticker: builtins.str) -> typing.Any:
        r"""
        Fetch market-level metadata (exchange, timezone, futures cycle info).
        """
    def market_timing(self, ticker: builtins.str, date: builtins.str, timing: builtins.str = 'EOD', tz: typing.Optional[builtins.str] = None) -> typing.Any:
        r"""
        Resolve market timing (BOD/EOD/FINISHED) for a ticker/date.
        """
    def invalidate_exchange_cache(self, ticker: typing.Optional[builtins.str] = None) -> None:
        r"""
        Invalidate exchange cache (one ticker or all entries).
        """
    def save_exchange_cache(self) -> None:
        r"""
        Persist exchange cache to disk.
        """
    def resolve_field_types(self, fields: typing.Sequence[builtins.str], overrides: typing.Optional[typing.Mapping[builtins.str, builtins.str]] = None, default_type: builtins.str = 'string') -> typing.Any:
        r"""
        Resolve field types for a list of fields.
        """
    def get_field_info(self, field: builtins.str) -> typing.Optional[builtins.dict[builtins.str, builtins.str]]:
        r"""
        Get field info from cache.
        """
    def clear_field_cache(self) -> None:
        r"""
        Clear the field type cache.
        """
    def save_field_cache(self) -> None:
        r"""
        Save the field type cache to disk.
        """
    def field_cache_stats(self) -> typing.Any:
        r"""
        Get field cache statistics including the active cache path.
        """
    def validate_fields(self, fields: typing.Sequence[builtins.str]) -> typing.Any:
        r"""
        Validate Bloomberg field names.
        
        Queries Bloomberg's field info service to check if the given fields exist.
        Returns a list of invalid field names (fields that Bloomberg doesn't recognize).
        
        Example:
            invalid = await engine.validate_fields(["PX_LAST", "INVALID_FIELD"])
            # invalid = ["INVALID_FIELD"]
        """
    def get_schema(self, service: builtins.str) -> typing.Any:
        r"""
        Get service schema (from cache or introspect).
        
        Returns a dictionary with schema information including operations.
        First checks disk cache; if not cached, introspects the service.
        """
    def get_operation(self, service: builtins.str, operation: builtins.str) -> typing.Any:
        r"""
        Get a specific operation schema.
        
        Returns operation details including request/response element definitions.
        """
    def list_operations(self, service: builtins.str) -> typing.Any:
        r"""
        List all operations for a service.
        """
    def get_cached_schema(self, service: builtins.str) -> typing.Optional[builtins.str]:
        r"""
        Get cached schema without introspection.
        
        Returns None if the schema is not cached.
        """
    def invalidate_schema(self, service: builtins.str) -> None:
        r"""
        Invalidate a cached schema.
        """
    def clear_schema_cache(self) -> None:
        r"""
        Clear all cached schemas.
        """
    def list_cached_schemas(self) -> builtins.list[builtins.str]:
        r"""
        List all cached service URIs.
        """
    def get_enum_values(self, service: builtins.str, operation: builtins.str, element: builtins.str) -> typing.Any:
        r"""
        Get valid enum values for an element.
        
        Returns a list of valid enum values, or None if the element is not an enum.
        """
    def list_valid_elements(self, service: builtins.str, operation: builtins.str) -> typing.Any:
        r"""
        List all valid element names for an operation.
        """
    def subscribe(self, tickers: typing.Sequence[builtins.str], fields: typing.Sequence[builtins.str], flush_threshold: typing.Optional[builtins.int] = None, overflow_policy: typing.Optional[builtins.str] = None, stream_capacity: typing.Optional[builtins.int] = None, recovery_policy: typing.Optional[builtins.str] = None, all_fields: builtins.bool = False) -> typing.Any:
        r"""
        Subscribe to real-time market data.
        
        Returns a PySubscription that supports async iteration and dynamic add/remove.
        GIL is released during async operations; iteration and add/remove use separate
        locks to avoid contention.
        
        Example:
        ```python
        sub = await engine.subscribe(['AAPL US Equity'], ['LAST_PRICE', 'BID', 'ASK'])
        async for batch in sub:
            print(batch)
        await sub.unsubscribe()
        ```
        """
    def subscribe_with_options(self, service: builtins.str, tickers: typing.Sequence[builtins.str], fields: typing.Sequence[builtins.str], options: typing.Optional[typing.Sequence[builtins.str]] = None, flush_threshold: typing.Optional[builtins.int] = None, overflow_policy: typing.Optional[builtins.str] = None, stream_capacity: typing.Optional[builtins.int] = None, recovery_policy: typing.Optional[builtins.str] = None, all_fields: builtins.bool = False) -> typing.Any:
        r"""
        Subscribe to real-time data with custom service and options.
        
        This is the generic subscription method for services like //blp/mktvwap.
        
        Args:
            service: Bloomberg service URI (e.g., "//blp/mktvwap")
            tickers: List of securities to subscribe to
            fields: List of fields to subscribe to
            options: List of subscription options (e.g., ["VWAP_START_TIME=09:30"])
        
        Example:
        ```python
        sub = await engine.subscribe_with_options(
            '//blp/mktvwap',
            ['AAPL US Equity'],
            ['RT_PX_VWAP', 'RT_VWAP_VOLUME'],
            ['VWAP_START_TIME=09:30', 'VWAP_END_TIME=16:00']
        )
        async for batch in sub:
            print(batch)
        ```
        """
    def signal_shutdown(self) -> None:
        r"""
        Signal engine shutdown (non-blocking).
        
        Signals all worker threads to stop. They will terminate when they
        finish their current work or see the shutdown signal.
        
        This is called automatically during Python interpreter shutdown via atexit.
        You usually don't need to call this directly.
        """
    def worker_health(self) -> builtins.list[tuple[builtins.int, builtins.str]]: ...
    def is_connected(self) -> builtins.bool:
        r"""
        Check if the Bloomberg connection is healthy.
        
        Returns True if at least one worker has a live Bloomberg session.
        """

@typing.final
class PyEngineConfig:
    r"""
    Python configuration for the xbbg Engine.
    
    All settings have sensible defaults - you only need to specify what you want to change.
    
    The defaults are derived from `EngineConfig::default()` in xbbg-async, so they
    stay in sync automatically.
    """
    @property
    def host(self) -> builtins.str:
        r"""
        Bloomberg server host (default: "localhost")
        """
    @host.setter
    def host(self, value: builtins.str) -> None:
        r"""
        Bloomberg server host (default: "localhost")
        """
    @property
    def port(self) -> builtins.int:
        r"""
        Bloomberg server port (default: 8194)
        """
    @port.setter
    def port(self, value: builtins.int) -> None:
        r"""
        Bloomberg server port (default: 8194)
        """
    @property
    def servers(self) -> builtins.list[tuple[builtins.str, builtins.int]]:
        r"""
        Multiple servers for failover: list of (host, port) tuples. Overrides host/port when set.
        """
    @servers.setter
    def servers(self, value: builtins.list[tuple[builtins.str, builtins.int]]) -> None:
        r"""
        Multiple servers for failover: list of (host, port) tuples. Overrides host/port when set.
        """
    @property
    def zfp_remote(self) -> typing.Optional[builtins.str]: ...
    @zfp_remote.setter
    def zfp_remote(self, value: typing.Optional[builtins.str]) -> None: ...
    @property
    def request_pool_size(self) -> builtins.int:
        r"""
        Number of pre-warmed request workers (default: 2)
        """
    @request_pool_size.setter
    def request_pool_size(self, value: builtins.int) -> None:
        r"""
        Number of pre-warmed request workers (default: 2)
        """
    @property
    def subscription_pool_size(self) -> builtins.int:
        r"""
        Number of pre-warmed subscription sessions (default: 1)
        """
    @subscription_pool_size.setter
    def subscription_pool_size(self, value: builtins.int) -> None:
        r"""
        Number of pre-warmed subscription sessions (default: 1)
        """
    @property
    def validation_mode(self) -> builtins.str:
        r"""
        Validation mode: "disabled" (default), "strict", or "lenient"
        """
    @validation_mode.setter
    def validation_mode(self, value: builtins.str) -> None:
        r"""
        Validation mode: "disabled" (default), "strict", or "lenient"
        """
    @property
    def subscription_flush_threshold(self) -> builtins.int:
        r"""
        Number of ticks to buffer before flushing to Python (default: 1)
        """
    @subscription_flush_threshold.setter
    def subscription_flush_threshold(self, value: builtins.int) -> None:
        r"""
        Number of ticks to buffer before flushing to Python (default: 1)
        """
    @property
    def max_event_queue_size(self) -> builtins.int:
        r"""
        Bloomberg SDK event queue size (default: 10000)
        """
    @max_event_queue_size.setter
    def max_event_queue_size(self, value: builtins.int) -> None:
        r"""
        Bloomberg SDK event queue size (default: 10000)
        """
    @property
    def command_queue_size(self) -> builtins.int:
        r"""
        Internal command channel capacity (default: 256)
        """
    @command_queue_size.setter
    def command_queue_size(self, value: builtins.int) -> None:
        r"""
        Internal command channel capacity (default: 256)
        """
    @property
    def subscription_stream_capacity(self) -> builtins.int:
        r"""
        Subscription stream backpressure capacity (default: 256)
        """
    @subscription_stream_capacity.setter
    def subscription_stream_capacity(self, value: builtins.int) -> None:
        r"""
        Subscription stream backpressure capacity (default: 256)
        """
    @property
    def overflow_policy(self) -> builtins.str:
        r"""
        Overflow policy for slow consumers: "drop_newest" (default) or "block"
        """
    @overflow_policy.setter
    def overflow_policy(self, value: builtins.str) -> None:
        r"""
        Overflow policy for slow consumers: "drop_newest" (default) or "block"
        """
    @property
    def warmup_services(self) -> builtins.list[builtins.str]:
        r"""
        Services to pre-warm on startup (default: ["//blp/refdata", "//blp/apiflds"])
        """
    @warmup_services.setter
    def warmup_services(self, value: builtins.list[builtins.str]) -> None:
        r"""
        Services to pre-warm on startup (default: ["//blp/refdata", "//blp/apiflds"])
        """
    @property
    def field_cache_path(self) -> typing.Optional[builtins.str]:
        r"""
        Custom path for field cache JSON file (default: ~/.xbbg/field_cache.json)
        Set to None to use the default path.
        """
    @field_cache_path.setter
    def field_cache_path(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Custom path for field cache JSON file (default: ~/.xbbg/field_cache.json)
        Set to None to use the default path.
        """
    @property
    def auth_method(self) -> typing.Optional[builtins.str]:
        r"""
        Optional auth method: "user", "app", "userapp", "dir", "manual", or "token".
        """
    @auth_method.setter
    def auth_method(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Optional auth method: "user", "app", "userapp", "dir", "manual", or "token".
        """
    @property
    def app_name(self) -> typing.Optional[builtins.str]:
        r"""
        Bloomberg application name for app/userapp/manual auth.
        """
    @app_name.setter
    def app_name(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Bloomberg application name for app/userapp/manual auth.
        """
    @property
    def dir_property(self) -> typing.Optional[builtins.str]:
        r"""
        Active Directory property for dir auth.
        """
    @dir_property.setter
    def dir_property(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Active Directory property for dir auth.
        """
    @property
    def user_id(self) -> typing.Optional[builtins.str]:
        r"""
        Manual Bloomberg user id for manual auth.
        """
    @user_id.setter
    def user_id(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Manual Bloomberg user id for manual auth.
        """
    @property
    def ip_address(self) -> typing.Optional[builtins.str]:
        r"""
        Manual Bloomberg ip address for manual auth.
        """
    @ip_address.setter
    def ip_address(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        Manual Bloomberg ip address for manual auth.
        """
    @property
    def token(self) -> typing.Optional[builtins.str]: ...
    @token.setter
    def token(self, value: typing.Optional[builtins.str]) -> None: ...
    @property
    def tls_client_credentials(self) -> typing.Optional[builtins.str]: ...
    @tls_client_credentials.setter
    def tls_client_credentials(self, value: typing.Optional[builtins.str]) -> None: ...
    @property
    def tls_client_credentials_password(self) -> typing.Optional[builtins.str]: ...
    @tls_client_credentials_password.setter
    def tls_client_credentials_password(self, value: typing.Optional[builtins.str]) -> None: ...
    @property
    def tls_trust_material(self) -> typing.Optional[builtins.str]: ...
    @tls_trust_material.setter
    def tls_trust_material(self, value: typing.Optional[builtins.str]) -> None: ...
    @property
    def tls_handshake_timeout_ms(self) -> typing.Optional[builtins.int]: ...
    @tls_handshake_timeout_ms.setter
    def tls_handshake_timeout_ms(self, value: typing.Optional[builtins.int]) -> None: ...
    @property
    def tls_crl_fetch_timeout_ms(self) -> typing.Optional[builtins.int]: ...
    @tls_crl_fetch_timeout_ms.setter
    def tls_crl_fetch_timeout_ms(self, value: typing.Optional[builtins.int]) -> None: ...
    @property
    def num_start_attempts(self) -> builtins.int: ...
    @num_start_attempts.setter
    def num_start_attempts(self, value: builtins.int) -> None: ...
    @property
    def auto_restart_on_disconnection(self) -> builtins.bool:
        r"""
        Whether Bloomberg should auto-restart the session on disconnect (default: True).
        """
    @auto_restart_on_disconnection.setter
    def auto_restart_on_disconnection(self, value: builtins.bool) -> None:
        r"""
        Whether Bloomberg should auto-restart the session on disconnect (default: True).
        """
    @property
    def max_recovery_attempts(self) -> builtins.int: ...
    @max_recovery_attempts.setter
    def max_recovery_attempts(self, value: builtins.int) -> None: ...
    @property
    def recovery_timeout_ms(self) -> builtins.int: ...
    @recovery_timeout_ms.setter
    def recovery_timeout_ms(self, value: builtins.int) -> None: ...
    @property
    def retry_max_retries(self) -> builtins.int: ...
    @retry_max_retries.setter
    def retry_max_retries(self, value: builtins.int) -> None: ...
    @property
    def retry_initial_delay_ms(self) -> builtins.int: ...
    @retry_initial_delay_ms.setter
    def retry_initial_delay_ms(self, value: builtins.int) -> None: ...
    @property
    def retry_backoff_factor(self) -> builtins.float: ...
    @retry_backoff_factor.setter
    def retry_backoff_factor(self, value: builtins.float) -> None: ...
    @property
    def retry_max_delay_ms(self) -> builtins.int: ...
    @retry_max_delay_ms.setter
    def retry_max_delay_ms(self, value: builtins.int) -> None: ...
    @property
    def health_check_interval_ms(self) -> builtins.int: ...
    @health_check_interval_ms.setter
    def health_check_interval_ms(self, value: builtins.int) -> None: ...
    @property
    def sdk_log_level(self) -> builtins.str: ...
    @sdk_log_level.setter
    def sdk_log_level(self, value: builtins.str) -> None: ...
    @property
    def socks5_host(self) -> typing.Optional[builtins.str]:
        r"""
        SOCKS5 proxy hostname for Bloomberg connections.
        """
    @socks5_host.setter
    def socks5_host(self, value: typing.Optional[builtins.str]) -> None:
        r"""
        SOCKS5 proxy hostname for Bloomberg connections.
        """
    @property
    def socks5_port(self) -> typing.Optional[builtins.int]:
        r"""
        SOCKS5 proxy port (required when socks5_host is set).
        """
    @socks5_port.setter
    def socks5_port(self, value: typing.Optional[builtins.int]) -> None:
        r"""
        SOCKS5 proxy port (required when socks5_host is set).
        """
    def __new__(cls, **kwargs: typing.Any) -> PyEngineConfig:
        r"""
        Create a new configuration with defaults.
        
        All defaults are derived from the Rust EngineConfig to stay in sync.
        """
    def __repr__(self) -> builtins.str: ...

@typing.final
class PySubscription:
    r"""
    Python subscription handle for real-time market data.
    
    Supports:
    - Async iteration (`async for batch in sub`)
    - Dynamic add/remove of tickers
    - Explicit unsubscribe with optional drain
    - Context manager (`async with`)
    
    Data arrives as `Result<RecordBatch, BlpError>`:
    - `Ok(batch)` — yields a PyArrow RecordBatch
    - `Err(error)` — raises a Python exception (BlpRequestError, BlpInternalError, etc.)
    
    Design: Uses separate locks for rx (data receiving) vs stream (metadata snapshots),
    plus a dedicated operation lock to serialize add/remove/unsubscribe without holding
    the stream metadata lock across Bloomberg awaits.
    """
    @property
    def tickers(self) -> builtins.list[builtins.str]:
        r"""
        Get the currently subscribed tickers.
        """
    @property
    def fields(self) -> builtins.list[builtins.str]:
        r"""
        Get the subscribed fields.
        """
    @property
    def is_active(self) -> builtins.bool:
        r"""
        Check if the subscription is still active.
        """
    @property
    def all_failed(self) -> builtins.bool: ...
    @property
    def stats(self) -> typing.Any:
        r"""
        Get subscription metrics.
        
        Returns a dict with keys:
        - messages_received: int — total messages received from Bloomberg
        - dropped_batches: int — batches dropped due to overflow
        - batches_sent: int — batches successfully sent to Python
        - slow_consumer: bool — True if DATALOSS was received
        """
    @property
    def session_status(self) -> typing.Any: ...
    @property
    def admin_status(self) -> typing.Any: ...
    @property
    def service_status(self) -> builtins.list[tuple[builtins.str, builtins.bool, builtins.int]]: ...
    @property
    def topic_states(self) -> builtins.list[tuple[builtins.str, builtins.str, builtins.int]]: ...
    @property
    def events(self) -> builtins.list[tuple[builtins.int, builtins.str, builtins.str, builtins.str, typing.Optional[builtins.str], typing.Optional[builtins.str]]]: ...
    @property
    def failed_tickers(self) -> builtins.list[builtins.str]: ...
    @property
    def failures(self) -> builtins.list[tuple[builtins.str, builtins.str, builtins.str]]: ...
    def __aiter__(self) -> PySubscription:
        r"""
        Async iterator protocol.
        """
    def __anext__(self) -> typing.Any:
        r"""
        Get next batch of data.
        Only locks the rx, not the stream - so add/remove can run concurrently.
        
        Returns a PyArrow RecordBatch on success.
        Raises a Python exception (BlpRequestError, BlpInternalError, etc.) on error.
        Raises StopAsyncIteration when the subscription is closed.
        """
    def add(self, tickers: typing.Sequence[builtins.str]) -> typing.Any:
        r"""
        Add tickers to the subscription dynamically.
        Iteration can continue while Bloomberg work is in flight.
        """
    def remove(self, tickers: typing.Sequence[builtins.str]) -> typing.Any:
        r"""
        Remove tickers from the subscription dynamically.
        Iteration can continue while Bloomberg work is in flight.
        """
    def unsubscribe(self, drain: builtins.bool = False) -> typing.Any:
        r"""
        Unsubscribe and close the stream.
        
        If drain=True, returns remaining buffered batches before closing.
        """
    def __aenter__(self) -> PySubscription:
        r"""
        Context manager entry.
        """
    def __aexit__(self, _exc_type: typing.Optional[typing.Any] = None, _exc_val: typing.Optional[typing.Any] = None, _exc_tb: typing.Optional[typing.Any] = None) -> typing.Any:
        r"""
        Context manager exit - unsubscribes automatically.
        """
    def __repr__(self) -> builtins.str: ...

def enable_sdk_logging(level: builtins.str) -> None: ...

def ext_build_corporate_bonds_query(ticker: builtins.str, ccy: typing.Optional[builtins.str] = None, extra_fields: typing.Sequence[builtins.str] = [], active_only: builtins.bool = True) -> builtins.str:
    r"""
    Build a BQL query for corporate bonds.
    
    Args:
        ticker: Company ticker without suffix (e.g., "AAPL").
        ccy: Currency filter (None for all currencies).
        extra_fields: Additional fields beyond default (id).
        active_only: If true, only return active bonds.
    
    Returns: Complete BQL query string.
    """

def ext_build_earning_header_rename(header_row: typing.Sequence[tuple[builtins.str, builtins.str]], data_columns: typing.Sequence[builtins.str]) -> builtins.list[tuple[builtins.str, builtins.str]]:
    r"""
    Build column rename mapping from earnings header values.
    
    Args:
        header_row: List of (column_name, header_value) pairs from the header DataFrame.
        data_columns: Column names from the data DataFrame.
    
    Returns: List of (old_name, new_name) pairs for columns that need renaming.
    """

def ext_build_etf_holdings_query(etf_ticker: builtins.str, extra_fields: typing.Sequence[builtins.str] = []) -> builtins.str:
    r"""
    Build a BQL query for ETF holdings.
    
    Args:
        etf_ticker: ETF ticker (e.g., "SPY US Equity" or "SPY").
        extra_fields: Additional fields beyond defaults (id_isin, weights, id().position).
    
    Returns: Complete BQL query string.
    """

def ext_build_futures_ticker(prefix: builtins.str, month_code: builtins.str, year: builtins.str, asset: builtins.str) -> builtins.str:
    r"""
    Build a futures ticker from components.
    """

def ext_build_fx_pair(from_ccy: builtins.str, to_ccy: builtins.str) -> tuple[builtins.str, builtins.float, builtins.str, builtins.str]:
    r"""
    Build an FX pair ticker for currency conversion.
    
    Returns: (fx_pair, factor, from_ccy, to_ccy)
    """

def ext_build_preferreds_query(equity_ticker: builtins.str, extra_fields: typing.Sequence[builtins.str] = []) -> builtins.str:
    r"""
    Build a BQL query for preferred stocks.
    
    Args:
        equity_ticker: Company equity ticker (e.g., "BAC US Equity" or "BAC").
        extra_fields: Additional fields beyond defaults (id, name).
    
    Returns: Complete BQL query string.
    """

def ext_build_yas_overrides(settle_dt: typing.Optional[builtins.str] = None, yield_type: typing.Optional[builtins.int] = None, spread: typing.Optional[builtins.float] = None, yield_val: typing.Optional[builtins.float] = None, price: typing.Optional[builtins.float] = None, benchmark: typing.Optional[builtins.str] = None) -> builtins.list[tuple[builtins.str, builtins.str]]:
    r"""
    Build Bloomberg YAS override key-value pairs.
    
    Args:
        settle_dt: Settlement date string (optional).
        yield_type: Yield type flag value 1-9 (optional).
        spread: Spread value (optional).
        yield_val: Yield value (optional).
        price: Price value (optional).
        benchmark: Benchmark security (optional).
    
    Returns: List of (key, value) string pairs for Bloomberg overrides.
    """

def ext_calculate_level_percentages(values: typing.Sequence[typing.Optional[builtins.float]], levels: typing.Sequence[typing.Optional[builtins.int]]) -> builtins.list[typing.Optional[builtins.float]]:
    r"""
    Calculate level-based percentages for earnings data.
    
    Args:
        values: List of optional float values.
        levels: List of optional integer levels (1 = top level, 2 = sub-level).
    
    Returns: List of optional percentage values (0-100).
    """

def ext_cdx_gen_to_specific(gen_ticker: builtins.str, series: builtins.int) -> builtins.str:
    r"""
    Convert a generic CDX ticker to specific series.
    """

def ext_clear_exchange_override(ticker: typing.Optional[builtins.str] = None) -> None:
    r"""
    Clear one override (or all when ticker is None).
    """

def ext_contract_index(gen_ticker: builtins.str) -> builtins.int:
    r"""
    Get the contract index from a generic ticker (0-based).
    """

def ext_currencies_needing_conversion(currencies: typing.Sequence[builtins.str], target: builtins.str) -> builtins.list[builtins.str]:
    r"""
    Get currencies that need FX conversion.
    """

def ext_default_bqr_datetimes(start_datetime: typing.Optional[builtins.str] = None, end_datetime: typing.Optional[builtins.str] = None) -> tuple[builtins.str, builtins.str]:
    r"""
    Compute default datetime range for BQR (quote request) queries.
    
    Args:
        start_datetime: Start datetime string (optional, default: 1 hour before end).
        end_datetime: End datetime string (optional, default: now).
    
    Returns: Tuple of (start_datetime, end_datetime) as ISO-8601 datetime strings.
    """

def ext_default_turnover_dates(start_date: typing.Optional[builtins.str] = None, end_date: typing.Optional[builtins.str] = None) -> tuple[builtins.str, builtins.str]:
    r"""
    Compute default date range for turnover queries.
    
    Args:
        start_date: Start date string (optional, default: 30 days before end).
        end_date: End date string (optional, default: yesterday).
    
    Returns: Tuple of (start_date, end_date) as ISO-8601 date strings.
    """

def ext_derive_sessions(day_start: builtins.str, day_end: builtins.str, mic: typing.Optional[builtins.str], exch_code: typing.Optional[builtins.str]) -> builtins.dict[builtins.str, tuple[builtins.str, builtins.str]]:
    r"""
    Derive session windows from regular trading hours.
    
    Returns dict with keys: day, allday, pre, post, am, pm.
    Each value is a ``(start, end)`` tuple of ``"HH:MM"`` strings.
    Keys are omitted when the session does not apply.
    """

def ext_filter_candidates_by_cycle(candidates: typing.Sequence[tuple[builtins.str, builtins.int, builtins.int]], cycle: builtins.str) -> builtins.list[tuple[builtins.str, builtins.int, builtins.int]]:
    r"""
    Filter futures candidates by a cycle-months string from Bloomberg FUT_GEN_MONTH.
    
    Args:
        candidates: List of (ticker, year, month) tuples from ext_generate_futures_candidates.
        cycle: Month-code string from Bloomberg (e.g., "HMUZ").
    
    Returns: Filtered list preserving original order.
    """

def ext_filter_equity_tickers(tickers: typing.Sequence[builtins.str]) -> builtins.list[builtins.str]:
    r"""
    Filter to equity tickers only.
    """

def ext_filter_valid_contracts(contracts: typing.Sequence[tuple[builtins.str, builtins.str]], year: builtins.int, month: builtins.int, day: builtins.int) -> builtins.list[builtins.str]:
    r"""
    Filter and sort futures contracts by maturity date.
    
    Args:
        contracts: List of (ticker, maturity_date_str) pairs.
        year, month, day: Reference date components.
    
    Returns: List of ticker strings for contracts maturing after the reference date,
        sorted by maturity date ascending.
    """

def ext_fmt_date(year: builtins.int, month: builtins.int, day: builtins.int, fmt: typing.Optional[builtins.str] = None) -> builtins.str:
    r"""
    Format a date to string.
    """

def ext_generate_futures_candidates(gen_ticker: builtins.str, year: builtins.int, month: builtins.int, day: builtins.int, freq: builtins.str = 'M', count: builtins.int = 4) -> builtins.list[tuple[builtins.str, builtins.int, builtins.int]]:
    r"""
    Generate futures contract candidates.
    
    Returns list of (ticker, year, month) tuples.
    """

def ext_get_dvd_type(typ: builtins.str) -> typing.Optional[builtins.str]:
    r"""
    Get dividend type field name.
    """

def ext_get_dvd_types() -> dict:
    r"""
    Get all dividend type mappings.
    """

def ext_get_exchange_override(ticker: builtins.str) -> typing.Optional[typing.Any]:
    r"""
    Get runtime override for a ticker.
    """

def ext_get_futures_months() -> dict:
    r"""
    Get all futures month mappings.
    """

def ext_get_market_rule(mic: typing.Optional[builtins.str], exch_code: typing.Optional[builtins.str]) -> typing.Optional[typing.Any]:
    r"""
    Look up market rule by MIC code or Bloomberg exchange code.
    
    Returns dict with rule fields, or ``None`` if no rule matches.
    """

def ext_get_month_code(month: builtins.str) -> typing.Optional[builtins.str]:
    r"""
    Get futures month code for a month name.
    """

def ext_get_month_name(code: builtins.str) -> typing.Optional[builtins.str]:
    r"""
    Get month name for a futures month code.
    """

def ext_infer_timezone(country_iso: builtins.str) -> typing.Optional[builtins.str]:
    r"""
    Infer timezone from country ISO code.
    """

def ext_is_long_format(batch: typing.Any) -> builtins.bool:
    r"""
    Check if a RecordBatch is in long format (ticker, field, value).
    """

def ext_is_specific_contract(ticker: builtins.str) -> builtins.bool:
    r"""
    Check if a ticker is a specific contract (not generic).
    """

def ext_list_exchange_overrides() -> builtins.dict[builtins.str, typing.Any]:
    r"""
    List all runtime overrides.
    """

def ext_normalize_tickers(tickers: typing.Sequence[builtins.str]) -> builtins.list[builtins.str]:
    r"""
    Normalize tickers to a list.
    """

def ext_parse_cdx_ticker(ticker: builtins.str) -> tuple[builtins.str, builtins.str, builtins.str, builtins.str, builtins.bool, typing.Optional[builtins.int]]:
    r"""
    Parse a CDX ticker.
    
    Returns: (index, series, tenor, asset, is_generic, series_num)
    """

def ext_parse_date(date_str: builtins.str) -> tuple[builtins.int, builtins.int, builtins.int]:
    r"""
    Parse a date string into components (year, month, day).
    
    Supports: YYYY-MM-DD, YYYYMMDD, YYYY/MM/DD, DD-MM-YYYY, DD/MM/YYYY
    """

def ext_parse_ticker(ticker: builtins.str) -> tuple[builtins.str, builtins.int, builtins.str, typing.Optional[builtins.str]]:
    r"""
    Parse a Bloomberg ticker into components.
    
    Returns: (prefix, index, asset, exchange)
    """

def ext_pivot_to_wide(batch: typing.Any) -> typing.Any:
    r"""
    Pivot a PyArrow RecordBatch from long to wide format.
    
    Input: RecordBatch with columns (ticker, field, value)
    Output: RecordBatch with columns (ticker, field1, field2, ...)
    """

def ext_previous_cdx_series(ticker: builtins.str) -> typing.Optional[builtins.str]:
    r"""
    Get the previous series ticker for a CDX index.
    """

def ext_rename_dividend_columns(columns: typing.Sequence[builtins.str]) -> builtins.list[tuple[builtins.str, builtins.str]]:
    r"""
    Get dividend column rename mapping.
    """

def ext_rename_etf_columns(columns: typing.Sequence[builtins.str]) -> builtins.list[tuple[builtins.str, builtins.str]]:
    r"""
    Get ETF holdings column rename mapping.
    """

def ext_same_currency(ccy1: builtins.str, ccy2: builtins.str) -> builtins.bool:
    r"""
    Check if two currencies are effectively the same.
    """

def ext_session_times_to_utc(start_time: builtins.str, end_time: builtins.str, exchange_tz: builtins.str, date: builtins.str) -> tuple[builtins.str, builtins.str]:
    r"""
    Convert local exchange session times to UTC ISO timestamps.
    """

def ext_set_exchange_override(ticker: builtins.str, timezone: typing.Optional[builtins.str] = None, mic: typing.Optional[builtins.str] = None, exch_code: typing.Optional[builtins.str] = None, day: typing.Optional[tuple[builtins.str, builtins.str]] = None, allday: typing.Optional[tuple[builtins.str, builtins.str]] = None, pre: typing.Optional[tuple[builtins.str, builtins.str]] = None, post: typing.Optional[tuple[builtins.str, builtins.str]] = None, am: typing.Optional[tuple[builtins.str, builtins.str]] = None, pm: typing.Optional[tuple[builtins.str, builtins.str]] = None) -> None:
    r"""
    Set a runtime exchange override patch for a ticker.
    """

def ext_validate_generic_ticker(ticker: builtins.str) -> None:
    r"""
    Validate that a ticker is generic (not specific).
    """

def get_log_level() -> builtins.str:
    r"""
    Get the current Rust log level as a string.
    """

def recipe_active_cdx(engine: PyEngine, gen_ticker: builtins.str, dt: builtins.str, lookback_days: typing.Optional[builtins.int] = None) -> typing.Any:
    r"""
    Resolve the most active CDX series around a reference date.
    
    Args:
        engine: Bloomberg engine instance
        gen_ticker: Generic CDX ticker (e.g., "CDX IG CDSI GEN 5Y Corp")
        dt: Reference date (YYYYMMDD format)
        lookback_days: Lookback window for activity comparison (default: 10)
    """

def recipe_active_futures(engine: PyEngine, gen_ticker: builtins.str, dt: builtins.str, freq: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    Resolve the most active futures contract around a reference date.
    
    Args:
        engine: Bloomberg engine instance
        gen_ticker: Generic futures ticker (e.g., "ES1 Index")
        dt: Reference date (YYYYMMDD format)
        freq: Roll frequency ("M" monthly, "Q"/"QE" quarterly)
    """

def recipe_bqr(engine: PyEngine, ticker: builtins.str, start_datetime: builtins.str, end_datetime: builtins.str, event_types: typing.Optional[typing.Sequence[builtins.str]] = None, include_broker_codes: builtins.bool = True) -> typing.Any:
    r"""
    Bloomberg Quote Request - dealer quotes via IntradayTick.
    
    Args:
        engine: Bloomberg engine instance
        ticker: Security ticker (e.g., "US912810TM69 Govt")
        start_datetime: Start datetime (ISO format)
        end_datetime: End datetime (ISO format)
        event_types: Event types to retrieve (default: ["BID", "ASK"])
        include_broker_codes: Include broker/dealer codes (default: true)
    """

def recipe_cdx_ticker(engine: PyEngine, gen_ticker: builtins.str, dt: builtins.str) -> typing.Any:
    r"""
    Resolve a generic CDX ticker to the active specific series.
    
    Args:
        engine: Bloomberg engine instance
        gen_ticker: Generic CDX ticker (e.g., "CDX IG CDSI GEN 5Y Corp")
        dt: Reference date (YYYYMMDD format)
    """

def recipe_corporate_bonds(engine: PyEngine, ticker: builtins.str, ccy: typing.Optional[builtins.str] = None, fields: typing.Optional[typing.Sequence[builtins.str]] = None, active_only: builtins.bool = True) -> typing.Any:
    r"""
    Find corporate bonds for a company via BQL.
    
    Args:
        engine: Bloomberg engine instance
        ticker: Company ticker prefix (e.g., "AAPL")
        ccy: Currency filter (e.g., "USD"). None for all currencies.
        fields: Additional fields to retrieve (default: id)
        active_only: If true, only return active bonds (default: true)
    """

def recipe_currency_conversion(engine: PyEngine, ticker: builtins.str, target_ccy: builtins.str, start_date: builtins.str, end_date: builtins.str) -> typing.Any:
    r"""
    Fetch historical prices with currency conversion.
    
    Args:
        engine: Bloomberg engine instance
        ticker: Security ticker
        target_ccy: Target currency (e.g., "USD", "EUR")
        start_date: Start date (YYYYMMDD format)
        end_date: End date (YYYYMMDD format)
    """

def recipe_dividend(engine: PyEngine, tickers: typing.Sequence[builtins.str], start_date: builtins.str, end_date: builtins.str, dvd_type: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    Fetch dividend history for securities.
    
    Args:
        engine: Bloomberg engine instance
        tickers: Securities to query
        start_date: Start date (YYYYMMDD format)
        end_date: End date (YYYYMMDD format)
        dvd_type: Dividend type filter (e.g., "all", "regular")
    """

def recipe_etf_holdings(engine: PyEngine, etf_ticker: builtins.str, fields: typing.Optional[typing.Sequence[builtins.str]] = None) -> typing.Any:
    r"""
    Fetch ETF constituent holdings via BQL.
    
    Args:
        engine: Bloomberg engine instance
        etf_ticker: ETF ticker (e.g., "SPY US Equity")
        fields: Additional fields beyond defaults (id_isin, weights, id().position)
    """

def recipe_fut_ticker(engine: PyEngine, gen_ticker: builtins.str, dt: builtins.str, freq: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    Resolve a generic futures ticker to a specific contract ticker.
    
    Args:
        engine: Bloomberg engine instance
        gen_ticker: Generic futures ticker (e.g., "ES1 Index", "CL2 Comdty")
        dt: Reference date (YYYYMMDD format)
        freq: Roll frequency ("M" monthly, "Q"/"QE" quarterly)
    """

def recipe_preferreds(engine: PyEngine, ticker: builtins.str, fields: typing.Optional[typing.Sequence[builtins.str]] = None) -> typing.Any:
    r"""
    Find preferred stocks for a company via BQL.
    
    Args:
        engine: Bloomberg engine instance
        ticker: Company equity ticker (e.g., "BAC US Equity")
        fields: Additional fields to retrieve (default: id, name)
    """

def recipe_turnover(engine: PyEngine, tickers: typing.Sequence[builtins.str], start_date: builtins.str, end_date: builtins.str, ccy: typing.Optional[builtins.str] = None, factor: typing.Optional[builtins.float] = None) -> typing.Any:
    r"""
    Fetch trading volume and turnover for securities.
    
    Args:
        engine: Bloomberg engine instance
        tickers: Securities to query
        start_date: Start date (YYYYMMDD format)
        end_date: End date (YYYYMMDD format)
        ccy: Currency for conversion. None for local currency.
        factor: Division factor (e.g., 1_000_000.0 for millions)
    """

def recipe_yas(engine: PyEngine, tickers: typing.Sequence[builtins.str], fields: typing.Sequence[builtins.str], settle_dt: typing.Optional[builtins.str] = None, yield_type: typing.Optional[builtins.int] = None, spread: typing.Optional[builtins.float] = None, yield_val: typing.Optional[builtins.float] = None, price: typing.Optional[builtins.float] = None, benchmark: typing.Optional[builtins.str] = None) -> typing.Any:
    r"""
    YAS (Yield & Spread Analysis) recipe.
    
    Retrieves Bloomberg YAS data with optional yield type and pricing parameters.
    Returns a PyArrow RecordBatch.
    
    Args:
        engine: Bloomberg engine instance
        tickers: Securities to query
        fields: Fields to retrieve
        settle_dt: Settlement date (YYYYMMDD format)
        yield_type: Yield calculation type as integer (1=YTM, 2=YTC, ..., 9=YTAL)
        spread: Yield spread override
        yield_val: Yield value override
        price: Price override
        benchmark: Benchmark security for spread calculation
    """

def sdk_version() -> tuple[builtins.int, builtins.int, builtins.int, builtins.int]: ...

def set_log_level(level: builtins.str) -> None:
    r"""
    Set the Rust log level.
    
    Accepts: "trace", "debug", "info", "warn", "error".
    Default is "warn" (quiet for end users).
    
    This sets an atomic integer — no GIL is held on the logging hot path.
    For per-crate control, use the RUST_LOG environment variable instead.
    """

def version() -> builtins.str: ...

