snowflake-connector-python 5.2.0__cp315-cp315-win_amd64.whl

snowflake/connector/connection_config.py

@@ -0,0 +1,517 @@
+"""Auto-generated from PARAM_DEFS in sf_params_spec. DO NOT EDIT.
+
+Regenerated by the generate-connection-config pre-commit hook whenever the
+sf_params_spec registry or the generator changes.  Any manual changes will be
+silently overwritten.
+
+This file intentionally contains only information derivable from
+``PARAM_DEFS``: the dataclass fields and the ``_ALIAS_MAP`` /
+``_PYTHON_TO_RUST_NAME`` / ``_SENSITIVE_PARAMS`` lookup tables.  Behavioural
+helpers (``from_kwargs``, ``to_options``, ``to_proto_options``, legacy
+rewrites, application validation, Python-only fields) live in
+:mod:`snowflake.connector._internal.connection_config_mixin` and are inherited
+via :class:`ConnectionConfigMixin`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, ClassVar
+
+from snowflake.connector._internal.connection_config_mixin import (
+    ConnectionConfigMixin,
+    OptionsModifier,
+)
+
+
+__all__ = ["ConnectionConfig", "OptionsModifier"]
+
+
+@dataclass
+class ConnectionConfig(ConnectionConfigMixin):
+    """Typed connection configuration derived from sf_params_spec PARAM_DEFS.
+
+    Fields use defaults from the Rust core where defined, ``None`` otherwise.
+    Behavioural helpers (``from_kwargs``, ``to_options``, etc.) are inherited
+    from :class:`ConnectionConfigMixin`.
+    """
+
+    # -- Connection parameters --------------------------------------------------
+    account: str | None = None
+    """Snowflake account identifier. Required"""
+
+    allow_empty_proxy: bool | None = True
+    """Empty PROXY value explicitly disables proxy (overrides env). Default: True"""
+
+    application: str | None = None
+    """User-facing application name sent as CLIENT_ENVIRONMENT.APPLICATION (falls back to client_app_id)"""
+
+    authentication_timeout: int | None = 120
+    """Timeout in seconds for native Okta SSO authentication. Default: 120"""
+
+    authenticator: str | None = None
+    """Authenticator type for the connection"""
+
+    client_app_id: str | None = None
+    """Driver identity sent as CLIENT_APP_ID in the login request (e.g. PythonConnector, SnowSQL)"""
+
+    client_app_version: str | None = None
+    """Driver version sent as CLIENT_APP_VERSION in the login request"""
+
+    client_store_temporary_credential: bool | None = True
+    """When true, persist ID, OAuth, and MFA tokens in the OS credential store. Defaults to true. An explicit value
+    always wins.
+
+    Default: True
+    """
+
+    connect_timeout: int | None = None
+    """HTTP connect timeout in seconds for name lookup, TCP, and TLS (0 = no timeout, absent = 60)"""
+
+    connection_diag_allowlist_path: str | None = None
+    """Path to a pre-fetched allowlist.json; if absent the driver fetches it via system$allowlist()"""
+
+    connection_diag_log_path: str | None = None
+    """Directory where the diagnostic report file is written (defaults to system tmpdir)"""
+
+    connection_name: str | None = None
+    """Named connection to load from TOML configuration files"""
+
+    crl_allow_certificates_without_crl_url: bool | None = False
+    """Allow certificates that do not include a CRL distribution URL. Default: False"""
+
+    crl_cache_cleanup_interval: int | None = 3600
+    """Interval in seconds between background CRL cache cleanup passes. Default: 3600"""
+
+    crl_cache_dir: str | None = None
+    """Directory for CRL cache files"""
+
+    crl_cache_start_cleanup: bool | None = False
+    """Run the background CRL cache cleanup task. Default: False"""
+
+    crl_check_mode: str | None = "DISABLED"
+    """Certificate revocation check mode (DISABLED, ENABLED, ADVISORY). Default: 'DISABLED'"""
+
+    crl_connection_timeout: int | None = 10
+    """Connection timeout in seconds for CRL endpoints. Default: 10"""
+
+    crl_enable_disk_caching: bool | None = True
+    """Enable disk caching for CRL responses. Default: True"""
+
+    crl_enable_memory_caching: bool | None = True
+    """Enable in-memory caching for CRL responses. Default: True"""
+
+    crl_http_timeout: int | None = 10
+    """HTTP timeout in seconds for CRL endpoint requests. Default: 10"""
+
+    crl_max_download_size: int | None = 20971520
+    """Maximum CRL download size in bytes before the download is aborted. Default: 20971520"""
+
+    crl_on_disk_cache_removal_delay: int | None = 604800
+    """Delay in seconds after a CRL's nextUpdate before it is purged from the on-disk cache. Default: 604800"""
+
+    crl_unsafe_skip_file_permissions_check: bool | None = False
+    """Skip verification that on-disk CRL cache files and directory are owner-only (0600/0700). Default: False"""
+
+    crl_validity_time: int | None = 86400
+    """Maximum age in seconds of a cached CRL before it is re-fetched. Default: 86400"""
+
+    custom_root_store_path: str | None = None
+    """Path to custom root certificate store"""
+
+    disable_parallel_user_prompt: bool | None = True
+    """When true (default), enables process-global serialization of interactive auth prompts (external browser, MFA,
+    OAuth) so that only one prompt is shown per <user, host> when clientStoreTemporaryCredential is enabled. Set to
+    false to allow each concurrent connection to show its own prompt..
+
+    Default: True
+    """
+
+    disable_query_context_cache: bool | None = False
+    """When true, disables the client-side query context cache. No context is sent in requests and server-returned
+    context is ignored..
+
+    Default: False
+    """
+
+    disable_saml_url_check: bool | None = False
+    """Skip the Okta SAML URL host-match safety check. Default: False"""
+
+    enable_connection_diag: bool | None = None
+    """Run connectivity diagnostics during connect and write a report"""
+
+    enable_server_session_keep_alive_auto_detection: bool | None = None
+    """Enable auto-detection of async queries before logout (SNOW-2314152)"""
+
+    external_session_id: str | None = None
+    """External session identifier used with authenticator=PAT_WITH_EXTERNAL_SESSION. Sent as
+    X-Snowflake-External-Session-ID on every request; the server keys the session by (PAT, external_session_id).
+
+    Required when authenticator=PAT_WITH_EXTERNAL_SESSION
+    """
+
+    host: str | None = None
+    """Snowflake server hostname"""
+
+    include_retry_reason: bool | None = True
+    """When true, appends retryReason (the HTTP status code that triggered the retry, or 0 for transport errors with no
+    HTTP response) alongside retryCount on retried query requests..
+
+    Default: True
+    """
+
+    jwt_timeout: int | None = 120
+    """Lifetime in seconds for each key-pair authentication JWT (0 uses the default; must not be negative).
+
+    Default: 120
+    """
+
+    log_max_query_length: int | None = 80
+    """Maximum number of characters of a query string to include in log messages. Default: 80"""
+
+    log_query_parameters: bool | str | None = False
+    """Include the (truncated) JSON bindings in INFO query logs (requires log_query_text). Default: False"""
+
+    log_query_text: bool | str | None = False
+    """Include the (truncated) SQL text in INFO query logs. Default: False"""
+
+    login_timeout: int | None = 120
+    """Wall-clock timeout in seconds for the entire login operation including retries (0 = no timeout). Default: 120"""
+
+    logout_error_strategy: str | None = None
+    """Error handling strategy for logout: 'best_effort' or 'strict'"""
+
+    logout_max_attempts: int | None = None
+    """Maximum total attempts for logout (1 = no retry, 3 = 2 retries)"""
+
+    logout_request_timeout_seconds: int | None = None
+    """Per-request socket timeout for individual logout attempts"""
+
+    logout_total_timeout_seconds: int | None = None
+    """Total timeout budget for logout operation including retries"""
+
+    master_token: str | None = None
+    """Pre-acquired master token for session token authentication"""
+
+    master_validity_in_seconds: int | None = None
+    """Remaining validity in seconds for the master token (session token auth)"""
+
+    max_tls_version: str | None = "tls13"
+    """Maximum TLS protocol version to negotiate (tls12 or tls13). Default: 'tls13'"""
+
+    min_tls_version: str | None = "tls12"
+    """Minimum TLS protocol version to negotiate (tls12 or tls13). Default: 'tls12'"""
+
+    no_proxy: str | None = None
+    """Comma-separated list of hosts to bypass the proxy for"""
+
+    oauth_authorization_url: str | None = None
+    """IdP authorization endpoint (defaults to https://{host}/oauth/authorize)"""
+
+    oauth_client_id: str | None = None
+    """OAuth client identifier (LOCAL_APPLICATION when Snowflake is the IdP)"""
+
+    oauth_client_secret: str | None = None
+    """OAuth client secret (redacted from logs)"""
+
+    oauth_credentials_in_body: bool | None = False
+    """Send client_id/client_secret in the OAUTH_CLIENT_CREDENTIALS token request body (client_secret_post) instead of
+    the HTTP Basic header.
+
+    Default: False
+    """
+
+    oauth_disable_pkce: bool | None = False
+    """Disable PKCE S256 challenge for OAUTH_AUTHORIZATION_CODE (Python-compatible escape hatch). Default: False"""
+
+    oauth_enable_dpop: bool | None = False
+    """Enable RFC 9449 DPoP proof-of-possession (JDBC-compatible). Default: False"""
+
+    oauth_enable_single_use_refresh_tokens: bool | None = False
+    """Request single-use refresh-token rotation (Snowflake-IdP only). Default: False"""
+
+    oauth_redirect_uri: str | None = None
+    """Loopback redirect URI advertised to the IdP (defaults to http://127.0.0.1:<random>)"""
+
+    oauth_scope: str | None = None
+    """OAuth scope (space-separated; defaults to session:role:<role>)"""
+
+    oauth_token_request_url: str | None = None
+    """IdP token endpoint (CC only; defaults to https://{host}/oauth/token-request for AC).
+
+    Required when authenticator=OAUTH_CLIENT_CREDENTIALS
+    """
+
+    okta_username: str | None = None
+    """Okta username (defaults to the Snowflake user if omitted)"""
+
+    passcode: str | None = None
+    """MFA passcode for USERNAME_PASSWORD_MFA authentication"""
+
+    passcode_in_password: bool | None = False
+    """Whether the MFA passcode is appended to the password. Default: False"""
+
+    password: str | None = None
+    """Login password. Required when authenticator=SNOWFLAKE_PASSWORD"""
+
+    platform_detection_timeout_seconds: float | None = None
+    """Python-only. Accepted for compatibility and ignored; each cloud-metadata platform check is limited to 2 seconds.
+    """
+
+    port: int | None = None
+    """Server port number"""
+
+    preserve_underscores_in_hostname: bool | None = False
+    """Preserve underscores in the hostname derived from the account name. Default: False"""
+
+    private_key: Any | None = None
+    """Private key for key-pair authentication (PEM or base64 text, DER bytes, or an RSAPrivateKey or
+    EllipticCurvePrivateKey).
+
+    Required when authenticator=SNOWFLAKE_JWT
+    """
+
+    private_key_file: str | None = None
+    """Path to private key file for key-pair authentication"""
+
+    private_key_password: str | None = None
+    """Passphrase for encrypted private key"""
+
+    protocol: str | None = None
+    """Connection protocol (http or https)"""
+
+    proxy: str | None = None
+    """Proxy URL ([scheme://][user:pass@]host[:port]); legacy ODBC `PROXY` form"""
+
+    proxy_host: str | None = None
+    """Proxy server hostname"""
+
+    proxy_password: str | None = None
+    """Proxy server password for Basic auth"""
+
+    proxy_port: int | None = None
+    """Proxy server port"""
+
+    proxy_scheme: str | None = None
+    """Scheme for the hop to the proxy: http (default) or https"""
+
+    proxy_user: str | None = None
+    """Proxy server username for Basic auth"""
+
+    put_get_max_attempts: int | None = 6
+    """Maximum total attempts for a single PUT/GET file transfer (1 = no retry). Default: 6"""
+
+    query_timeout: int | None = 0
+    """Wall-clock timeout in seconds for query execution including retries (0 = no timeout). Default: 0"""
+
+    request_timeout: int | None = 120
+    """Wall-clock timeout in seconds for all other operations (close session, heartbeat, etc.) including retries (0 = no
+    timeout).
+
+    Default: 120
+    """
+
+    retry_backoff_base_ms: int | None = 250
+    """Initial exponential-backoff delay in milliseconds between retry attempts. Default: 250"""
+
+    retry_backoff_cap_ms: int | None = 16000
+    """Maximum exponential-backoff delay in milliseconds between retry attempts. Default: 16000"""
+
+    retry_backoff_factor: float | None = 2
+    """Multiplier applied to the backoff delay after each retry attempt. Default: 2"""
+
+    retry_backoff_jitter: str | None = "decorrelated"
+    """Backoff jitter strategy: 'none', 'full', or 'decorrelated'. Default: 'decorrelated'"""
+
+    retry_extra_status_codes: str | None = None
+    """Additional HTTP status codes (comma-separated) to retry on general HTTP and PUT/GET calls, beyond the built-in
+    408/429/307/308/5xx set
+    """
+
+    retry_max_attempts: int | None = 6
+    """Maximum total attempts for general HTTP calls (login, query, logout). 1 = no retry. Default: 6"""
+
+    retry_timeout: int | None = None
+    """Per-request timeout in seconds for a single HTTP attempt within a retry loop (0 = no timeout, absent = 300)"""
+
+    secondary_roles: str | None = None
+    """Secondary-roles activation mode sent at login (e.g. ALL or NONE)"""
+
+    serialize_session_operations: bool | None = None
+    """When true, core holds a per-connection gate across every backend session operation so only one is in flight at a
+    time. When unset, defaults to the wrapper's preset, client-only. Set at connect, cannot be changed after.
+    """
+
+    server_session_keep_alive: bool | None = None
+    """Control server session lifecycle: true=keep alive, false=always logout, null=auto-detect"""
+
+    server_url: str | None = None
+    """Full server URL (alternative to host/port/protocol)"""
+
+    session_token: str | None = None
+    """Pre-acquired session token for session token authentication"""
+
+    ssl: bool | None = None
+    """Enable or disable SSL/TLS (sets protocol to https or http). Deprecated: use protocol instead"""
+
+    tls_skip_verify: bool | None = False
+    """Skip all TLS verification with a single switch: disables both certificate and hostname checks (and, since
+    certificate verification is off, CRL revocation checks are bypassed too). Insecure; intended for testing only.
+
+    Default: False
+    """
+
+    token: str | None = None
+    """Pre-acquired bearer token (PAT, legacy OAUTH, or OIDC WIF). Alternative to token_file_path.
+
+    Required when authenticator=PROGRAMMATIC_ACCESS_TOKEN
+    """
+
+    token_file_path: str | None = None
+    """Path to a file containing a pre-acquired bearer token (PAT, legacy OAUTH, or OIDC WIF). If both token and
+    token_file_path are set, the file contents are used
+    """
+
+    unsafe_file_write: bool | None = False
+    """When true, GET downloads use the process umask permissions instead of owner-only (0600). Unix-only; ignored on
+    Windows.
+
+    Default: False
+    """
+
+    unsafe_skip_config_file_permissions_check: bool | None = False
+    """When true, skip file permission checks on config.toml and connections.toml during connection setup. Use in
+    environments where permissions cannot be controlled (CI runners, containers). Unix-only; ignored on Windows.
+
+    Default: False
+    """
+
+    use_current_catalog: bool | None = False
+    """When true, a NULL CatalogName on catalog functions is the current database. When false (default), the catalog is
+    unconstrained unless CLIENT_METADATA_REQUEST_USE_CONNECTION_CTX fills it.
+
+    Default: False
+    """
+
+    use_proxy_env: bool | None = None
+    """Honour HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars when no explicit proxy is set. Unset uses the wrapper preset
+    (true for Python and Node.js, false otherwise)
+    """
+
+    user: str | None = None
+    """Login username. Required"""
+
+    validate_default_parameters: bool | None = None
+    """Validate that the default database, schema, and warehouse exist on the server at connect time"""
+
+    verify_certificates: bool | None = True
+    """Whether to verify TLS certificates. Default: True"""
+
+    verify_hostname: bool | None = True
+    """Whether to verify the server hostname in TLS. Default: True"""
+
+    wif_host: str | None = None
+    """AWS STS hostname for Workload Identity Federation. Unset keeps the regional default"""
+
+    workload_identity_aws_use_outbound_token: bool | None = False
+    """Use outbound STS GetWebIdentityToken for AWS WIF (default: pre-signed GetCallerIdentity). Default: False"""
+
+    workload_identity_entra_resource: str | None = None
+    """Azure Entra resource URI for managed-identity token (Azure only; defaults to
+    api://fd3f753b-eed3-462c-b6a7-a4b5bb650aad)
+    """
+
+    workload_identity_impersonation_path: str | None = None
+    """Comma-separated impersonation chain for WIF (AWS role ARNs or GCP service account emails)"""
+
+    workload_identity_provider: str | None = None
+    """Cloud provider for WIF attestation (AWS, AZURE, GCP, OIDC). Required when authenticator=WORKLOAD_IDENTITY"""
+
+    # -- Session parameters --------------------------------------------------
+    client_memory_limit: int | None = 1536
+    """Memory budget in MB for chunk prefetch buffer (0 = unlimited). Default: 1536"""
+
+    client_prefetch_threads: int | None = None
+    """Number of concurrent chunk prefetch threads for result set downloading"""
+
+    client_session_keep_alive: bool | None = None
+    """Keep the session alive with periodic heartbeat requests"""
+
+    client_session_keep_alive_heartbeat_frequency: int | None = None
+    """Heartbeat frequency in seconds (clamped to interval master_token_validity/16..master_token_validity/4)"""
+
+    autocommit: bool | None = None
+    """Session autocommit mode"""
+
+    client_metadata_request_use_connection_ctx: bool | None = None
+    """Use the connection context for metadata requests"""
+
+    client_out_of_band_telemetry_enabled: bool | None = None
+    """Enable out-of-band client telemetry"""
+
+    client_timestamp_type_mapping: str | None = None
+    """Timestamp type used for generic timestamp values"""
+
+    database: str | None = None
+    """Default database to use"""
+
+    gcs_use_downscoped_credential: bool | None = None
+    """Use downscoped credentials for GCS"""
+
+    query_tag: str | None = None
+    """String label attached to queries and surfaced in QUERY_HISTORY. Settable at the session level (connection option
+    or session override, forwarded as a login session parameter) and overridable per-statement.
+    """
+
+    role: str | None = None
+    """Default role to use"""
+
+    schema: str | None = None
+    """Default schema to use"""
+
+    service_name: str | None = None
+    """Snowflake service name"""
+
+    timezone: str | None = None
+    """Session timezone, overridable per statement"""
+
+    use_s3_regional_url: bool | None = False
+    """Force the S3 regional endpoint for PUT/GET (PrivateLink-to-S3). Default: False"""
+
+    warehouse: str | None = None
+    """Default warehouse to use"""
+
+    _ALIAS_MAP: ClassVar[dict[str, str]] = {
+        "enable_retry_reason_in_query_response": "include_retry_reason",
+        "enable_stage_s3_privatelink_for_us_east_1": "use_s3_regional_url",
+        "passcodeinpassword": "passcode_in_password",
+        "private_key_file_pwd": "private_key_password",
+        "workload_identity_host": "wif_host",
+    }
+    """Lowercased alias -> Python field name."""
+
+    _PYTHON_TO_RUST_NAME: ClassVar[dict[str, str]] = {
+        "client_memory_limit": "CLIENT_MEMORY_LIMIT",
+        "client_prefetch_threads": "CLIENT_PREFETCH_THREADS",
+        "client_session_keep_alive": "CLIENT_SESSION_KEEP_ALIVE",
+        "client_session_keep_alive_heartbeat_frequency": "CLIENT_SESSION_KEEP_ALIVE_HEARTBEAT_FREQUENCY",
+        "passcode_in_password": "passcodeInPassword",
+    }
+    """Python field name -> Rust canonical name (only for names that differ)."""
+
+    _SENSITIVE_PARAMS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "external_session_id",
+            "master_token",
+            "oauth_client_secret",
+            "passcode",
+            "password",
+            "private_key",
+            "private_key_password",
+            "proxy",
+            "proxy_password",
+            "session_token",
+            "token",
+        }
+    )
+    """Fields that contain secrets (for log redaction)."""

snowflake/connector/constants.py

@@ -0,0 +1,52 @@
+"""Constants module for snowflake-connector-python."""
+
+from enum import Enum, unique
+
+from ._internal.authenticator_type import AuthenticatorType  # noqa: F401 - backward compatibility re-exports
+from ._internal.type_codes import FIELD_ID_TO_NAME  # noqa: F401 - backward compatibility re-exports
+from .config_manager import CONFIG_FILE, CONNECTIONS_FILE  # noqa: F401 - backward compatibility re-exports
+
+
+@unique
+class QueryStatus(Enum):
+    RUNNING = 0
+    ABORTING = 1
+    SUCCESS = 2
+    FAILED_WITH_ERROR = 3
+    ABORTED = 4
+    QUEUED = 5
+    FAILED_WITH_INCIDENT = 6
+    DISCONNECTED = 7
+    RESUMING_WAREHOUSE = 8
+    QUEUED_REPARING_WAREHOUSE = 9  # intentional typo, matches server-side QueryDTO.java
+    RESTARTED = 10
+    BLOCKED = 11
+    NO_DATA = 12
+
+
+# backward compatibility constant
+UTF8 = "utf-8"
+
+# Partner programs set this so CLIENT_ENVIRONMENT.APPLICATION is populated
+# without passing ``application=`` to connect(). Mirrors snowflake-connector-python.
+ENV_VAR_PARTNER = "SF_PARTNER"
+
+
+class StatementParameterName:
+    """Known statement-level parameter names.
+
+    These correspond to the statement-scoped entries in sf_core's
+    ``param_registry``.  Pass them via the ``parameters`` dict when
+    executing a statement.
+    """
+
+    MULTI_STATEMENT_COUNT = "MULTI_STATEMENT_COUNT"
+    ASYNC_EXECUTION = "ASYNC_EXECUTION"
+    SKIP_UPLOAD_ON_CONTENT_MATCH = "skip_upload_on_content_match"
+
+
+class SessionParameterName:
+    """Known Snowflake session parameter names referenced by the connector."""
+
+    CLIENT_STAGE_ARRAY_BINDING_THRESHOLD = "CLIENT_STAGE_ARRAY_BINDING_THRESHOLD"
+    CLIENT_TELEMETRY_ENABLED = "CLIENT_TELEMETRY_ENABLED"

snowflake/connector/cursor/__init__.py

@@ -0,0 +1,37 @@
+"""
+PEP 249 Database API 2.0 Cursor Objects
+
+This package defines the cursor classes as specified in PEP 249.
+
+Hierarchy:
+    SnowflakeCursorBase
+    ├── SnowflakeCursor  — returns tuple rows
+    └── DictCursor       — returns dict rows
+"""
+
+from __future__ import annotations
+
+from .._internal.cursor import DictRow, QueryResultStats, ResultMetadata, ResultMetadataV2, Row
+from .._internal.cursor.query_result_waiter import _RETRY_PATTERN as ASYNC_RETRY_PATTERN
+from ._base import SnowflakeCursorBase
+from ._dict_cursor import DictCursor
+from ._snowflake_cursor import SnowflakeCursor
+
+
+CursorType = type[SnowflakeCursor] | type[DictCursor]
+CursorInstance = SnowflakeCursor | DictCursor
+
+
+__all__ = [
+    "ASYNC_RETRY_PATTERN",  # snowpark_compat
+    "CursorInstance",
+    "CursorType",
+    "DictCursor",
+    "DictRow",
+    "QueryResultStats",
+    "ResultMetadata",
+    "ResultMetadataV2",
+    "Row",
+    "SnowflakeCursor",
+    "SnowflakeCursorBase",
+]