snowflake-snowpark-python 1.53.0__tar.gz → 1.53.1__tar.gz

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Release History
 
+## 1.53.1 (2026-07-14)
+
+No user-facing changes in this release.
+
 ## 1.53.0 (2026-07-09)
 
 ### Snowpark Python API Updates

{snowflake_snowpark_python-1.53.0/src/snowflake_snowpark_python.egg-info → snowflake_snowpark_python-1.53.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-snowpark-python
-Version: 1.53.0
+Version: 1.53.1
 Summary: Snowflake Snowpark for Python
 Home-page: https://www.snowflake.com/
 Author: Snowflake, Inc

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/_internal/utils.py

@@ -2009,6 +2009,23 @@ def remove_comments(sql_query: str, uuids: List[str]) -> str:
     )
 
 
+def _validate_iceberg_named_version_ref(
+    value: Optional[str], param_name: str
+) -> Optional[str]:
+    """Validate a non-empty Iceberg tag/branch/version-ref name."""
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(
+            f"'{param_name}' must be a string Iceberg name, "
+            f"got {type(value).__name__}."
+        )
+    stripped = value.strip()
+    if not stripped:
+        raise ValueError(f"'{param_name}' must be a non-empty Iceberg name.")
+    return stripped
+
+
 class TimeTravelConfig(NamedTuple):
     """Configuration for time travel operations."""
 
@@ -2020,6 +2037,8 @@ class TimeTravelConfig(NamedTuple):
     stream: Optional[str] = None
     version: Optional[int] = None
     version_tag: Optional[str] = None
+    version_ref: Optional[str] = None
+    branch: Optional[str] = None
 
     @staticmethod
     def validate_and_normalize_params(
@@ -2031,6 +2050,8 @@ class TimeTravelConfig(NamedTuple):
         stream: Optional[str] = None,
         version: Optional[int] = None,
         version_tag: Optional[str] = None,
+        version_ref: Optional[str] = None,
+        branch: Optional[str] = None,
     ) -> Optional["TimeTravelConfig"]:
         """
         Validates and normalizes time travel parameters.
@@ -2052,9 +2073,31 @@ class TimeTravelConfig(NamedTuple):
         Raises:
             ValueError: If parameters are invalid.
         """
+        version_tag = _validate_iceberg_named_version_ref(version_tag, "version_tag")
+        version_ref = _validate_iceberg_named_version_ref(version_ref, "version_ref")
+        branch = _validate_iceberg_named_version_ref(branch, "branch")
+
+        named_ref_count = sum(
+            arg is not None for arg in (version_tag, version_ref, branch)
+        )
+        if named_ref_count > 1:
+            raise ValueError(
+                "Exactly one of 'version_tag', 'version_ref', or 'branch' may be "
+                "provided for Iceberg named-ref time travel."
+            )
+
         time_travel_arg_count = sum(
             arg is not None
-            for arg in (statement, offset, timestamp, stream, version, version_tag)
+            for arg in (
+                statement,
+                offset,
+                timestamp,
+                stream,
+                version,
+                version_tag,
+                version_ref,
+                branch,
+            )
         )
 
         # Validate mode
@@ -2089,32 +2132,25 @@ class TimeTravelConfig(NamedTuple):
                 f"'version' must be an int Iceberg snapshot id, got {type(version).__name__}."
             )
 
-        # version_tag (Iceberg tag name, mapped to Snowflake's
-        # ``AT(VERSION_TAG => '<name>')`` grammar) only works with 'at' mode —
-        # Iceberg tag reads are positional (bound to a specific snapshot),
-        # not range-of-time, so ``BEFORE`` has no meaning.
-        if version_tag is not None and time_travel_mode.lower() != "at":
-            raise ValueError(
-                "Iceberg version_tag time travel can only be used with "
-                "time_travel_mode='at', not 'before'."
-            )
-
-        # Validate version_tag type — Iceberg tag names are strings. Empty
-        # strings are invalid.
-        if version_tag is not None:
-            if not isinstance(version_tag, str):
+        # Named Iceberg refs (tag / branch / version_ref) map to Snowflake's
+        # ``AT(VERSION_REF => '<name>')`` grammar and only work with 'at' mode.
+        for param_name, param_value in (
+            ("version_tag", version_tag),
+            ("version_ref", version_ref),
+            ("branch", branch),
+        ):
+            if param_value is not None and time_travel_mode.lower() != "at":
                 raise ValueError(
-                    f"'version_tag' must be a string Iceberg tag name, "
-                    f"got {type(version_tag).__name__}."
+                    f"Iceberg {param_name} time travel can only be used with "
+                    "time_travel_mode='at', not 'before'."
                 )
-            if not version_tag:
-                raise ValueError("'version_tag' must be a non-empty Iceberg tag name.")
 
         # Validate exactly one parameter is provided
         if time_travel_arg_count != 1:
             raise ValueError(
                 "Exactly one of 'statement', 'offset', 'timestamp', 'stream', "
-                "'version', or 'version_tag' must be provided."
+                "'version', 'version_tag', 'version_ref', or 'branch' must be "
+                "provided."
             )
 
         # Normalize timestamp
@@ -2150,6 +2186,8 @@ class TimeTravelConfig(NamedTuple):
             stream=stream,
             version=version,
             version_tag=version_tag,
+            version_ref=version_ref,
+            branch=branch,
         )
 
     def generate_sql_clause(self) -> str:
@@ -2160,11 +2198,12 @@ class TimeTravelConfig(NamedTuple):
         Returns:
             SQL clause like " AT (TIMESTAMP => TO_TIMESTAMP_NTZ('...'))",
             " AT (VERSION => 1234567890)" for Iceberg snapshot id time travel,
-            or " AT (VERSION_TAG => 'release_v1')" for Iceberg tag time
-            travel.
+            or " AT (VERSION_REF => 'audit-branch')" for Iceberg tag/branch
+            time travel.
 
         Note on escaping: string-valued parameters (``statement``,
-        ``stream``, ``version_tag``, ``timestamp``) are embedded inside
+        ``stream``, ``version_tag``, ``version_ref``, ``branch``,
+        ``timestamp``) are embedded inside
         single-quoted SQL literals via the existing ``str_to_sql``
         helper in ``analyzer.datatype_mapper`` so embedded ``'``, ``\\``
         and newline characters are properly escaped. This keeps the
@@ -2191,8 +2230,12 @@ class TimeTravelConfig(NamedTuple):
             clause += f"(STREAM => {str_to_sql(self.stream)})"
         elif self.version is not None:
             clause += f"(VERSION => {self.version})"
+        elif self.version_ref is not None:
+            clause += f"(VERSION_REF => {str_to_sql(self.version_ref)})"
+        elif self.branch is not None:
+            clause += f"(VERSION_REF => {str_to_sql(self.branch)})"
         elif self.version_tag is not None:
-            clause += f"(VERSION_TAG => {str_to_sql(self.version_tag)})"
+            clause += f"(VERSION_REF => {str_to_sql(self.version_tag)})"
         elif self.timestamp is not None:
             if self.timestamp_type is not None:
                 timestamp_type = self.timestamp_type.upper()

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/dataframe_reader.py

@@ -165,12 +165,17 @@ def _extract_time_travel_from_options(options: dict) -> dict:
 
     Special handling for 'VERSION_TAG' / 'VERSION-TAG' (Iceberg tag name) —
     both aliases map to the internal ``version_tag`` time travel parameter
-    and emit ``AT(VERSION_TAG => '<name>')`` on the Snowflake side (see
-    Spark Iceberg's ``VERSION AS OF '<tag_name>'`` reader path):
-    - Automatically set time_travel_mode to 'at'
-      (tag reads are positional — bound to a specific snapshot — not
-      range-of-time)
-    - Cannot be used with time_travel_mode='before' (raises error)
+    and emit ``AT(VERSION_REF => '<name>')`` on the Snowflake side.
+
+    Special handling for 'VERSION_REF' / 'VERSION-REF' (Iceberg tag or
+    branch name) — maps to the internal ``version_ref`` parameter.
+
+    Special handling for 'BRANCH' (Spark Iceberg WAP branch read) — maps
+    to the internal ``branch`` parameter and emits
+    ``AT(VERSION_REF => '<name>')``.
+
+    Special handling for 'TAG' (Spark Iceberg ``SparkReadOptions.TAG``) —
+    maps to the internal ``version_tag`` parameter.
     """
     result = {}
     excluded_keys = set()
@@ -221,27 +226,64 @@ def _extract_time_travel_from_options(options: dict) -> dict:
             )
         result["time_travel_mode"] = "at"
 
-    # Handle Iceberg tag (``version_tag`` / ``version-tag``). Both aliases
-    # route to the internal ``version_tag`` parameter and emit
-    # ``AT(VERSION_TAG => '<name>')`` server-side. Auto-sets mode='at'.
-    version_tag_value = options.get("VERSION_TAG")
-    version_tag_source = "version_tag"
-    if version_tag_value is None:
-        version_tag_value = options.get("VERSION-TAG")
-        version_tag_source = "version-tag"
-    if version_tag_value is not None:
+    def _set_named_ref_option(
+        result: dict,
+        *,
+        param_name: str,
+        option_source: str,
+        raw_value: Any,
+    ) -> None:
         if (
             "TIME_TRAVEL_MODE" in options
             and options["TIME_TRAVEL_MODE"].lower() == "before"
         ):
             raise ValueError(
-                f"Cannot use '{version_tag_source}' option with "
-                "time_travel_mode='before'. Iceberg tag time travel only "
-                "supports time_travel_mode='at'."
+                f"Cannot use '{option_source}' option with "
+                "time_travel_mode='before'. Iceberg named-ref time travel "
+                "only supports time_travel_mode='at'."
             )
-        result["version_tag"] = str(version_tag_value)
+        result[param_name] = str(raw_value)
         result["time_travel_mode"] = "at"
 
+    # Handle Iceberg tag (``version_tag`` / ``version-tag`` / Spark ``tag``).
+    version_tag_value = options.get("VERSION_TAG")
+    version_tag_source = "version_tag"
+    if version_tag_value is None:
+        version_tag_value = options.get("VERSION-TAG")
+        version_tag_source = "version-tag"
+    if version_tag_value is None:
+        version_tag_value = options.get("TAG")
+        version_tag_source = "tag"
+    if version_tag_value is not None:
+        _set_named_ref_option(
+            result,
+            param_name="version_tag",
+            option_source=version_tag_source,
+            raw_value=version_tag_value,
+        )
+
+    version_ref_value = options.get("VERSION_REF")
+    version_ref_source = "version_ref"
+    if version_ref_value is None:
+        version_ref_value = options.get("VERSION-REF")
+        version_ref_source = "version-ref"
+    if version_ref_value is not None:
+        _set_named_ref_option(
+            result,
+            param_name="version_ref",
+            option_source=version_ref_source,
+            raw_value=version_ref_value,
+        )
+
+    branch_value = options.get("BRANCH")
+    if branch_value is not None:
+        _set_named_ref_option(
+            result,
+            param_name="branch",
+            option_source="branch",
+            raw_value=branch_value,
+        )
+
     for option_key, param_name in _TIME_TRAVEL_OPTIONS_PARAMS_MAP.items():
         if option_key in options and option_key not in excluded_keys:
             result[param_name] = options[option_key]
@@ -737,6 +779,8 @@ class DataFrameReader:
         version_tag = kwargs.pop("version_tag", None)
         start_snapshot_id = kwargs.pop("start_snapshot_id", None)
         end_snapshot_id = kwargs.pop("end_snapshot_id", None)
+        version_ref = kwargs.pop("version_ref", None)
+        branch = kwargs.pop("branch", None)
         if kwargs:
             raise TypeError(
                 f"table() got unexpected keyword arguments: {sorted(kwargs)}"
@@ -793,15 +837,23 @@ class DataFrameReader:
             time_travel_mode is not None
             or version is not None
             or version_tag is not None
+            or version_ref is not None
+            or branch is not None
         ):
-            # If version / version_tag is provided without mode, default to
-            # 'at' — snapshot ids and tag reads only make sense with AT
-            # (symmetric with the as-of-timestamp option handling).
+            # If version / named-ref params are provided without mode,
+            # default to 'at'.
             effective_mode = (
                 time_travel_mode
                 if time_travel_mode
                 else (
-                    "at" if (version is not None or version_tag is not None) else None
+                    "at"
+                    if (
+                        version is not None
+                        or version_tag is not None
+                        or version_ref is not None
+                        or branch is not None
+                    )
+                    else None
                 )
             )
             time_travel_params = {
@@ -813,6 +865,8 @@ class DataFrameReader:
                 "stream": stream,
                 "version": version,
                 "version_tag": version_tag,
+                "version_ref": version_ref,
+                "branch": branch,
             }
             table = self._session.table(name, _emit_ast=False, **time_travel_params)
         else:

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/functions.py

@@ -13821,7 +13821,7 @@ def ai_complete(
         >>> # With detailed output
         >>> df = session.range(1).select(
         ...     ai_complete(
-        ...         model='mistral-large',
+        ...         model='mistral-large2',
         ...         prompt='Explain AI in one sentence.',
         ...         show_details=True
         ...     ).alias("detailed_response")

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/query_history.py

@@ -1,11 +1,15 @@
 #
 # Copyright (c) 2012-2025 Snowflake Computing Inc. All rights reserved.
 #
+import os
 from abc import abstractmethod
+from logging import getLogger
 from typing import Dict, List, NamedTuple, Tuple
 
 import snowflake.snowpark
 
+_logger = getLogger(__name__)
+
 
 class QueryRecord(NamedTuple):
     """Contains the query information returned from the Snowflake database after the query is run."""
@@ -141,3 +145,94 @@ class AstListener(QueryListener):
     @property
     def base64_batches(self) -> List[str]:
         return self._ast_batches
+
+
+class _VscHistoryExporter(QueryListener):
+    """Exports executed query IDs to a directory watched by the Snowflake VS Code extension.
+
+    For each query, an empty file named after the query ID is created in the
+    target directory.
+
+    Note that this exporter is active only when the
+    ``SNOWFLAKE_SNOWPARK_VSC_QUERY_HISTORY_DIR`` environment variable is set.
+
+    The exported files are meant to be consumed by the Snowflake VS Code
+    extension, which is responsible for cleaning up the directory; the exporter
+    never removes files on its own. As a safeguard against an unbounded
+    directory, the constructor counts the files already present and disables the
+    exporter (making it a no-op) if that count is at or above a threshold. The
+    threshold defaults to :attr:`DEFAULT_FILE_COUNT_LIMIT_AT_INIT` and can be
+    overridden via the ``SNOWFLAKE_SNOWPARK_VSC_QUERY_HISTORY_DIR_MAX_FILES``
+    environment variable.
+    """
+
+    DEFAULT_FILE_COUNT_LIMIT_AT_INIT = 1000
+
+    def __init__(self, query_history_dir: str) -> None:
+        """
+        Initializes the _VscHistoryExporter.
+
+        Args:
+            query_history_dir: Directory into which an empty file named after each
+                executed query ID is written. Created if it does not already exist.
+        """
+        self._query_history_dir = query_history_dir
+        # When _disabled is True, _notify becomes a pure no-op. Default to
+        # disabled, and only enable below if the target directory is ready
+        # (created or already present) and confirmed below the file-count
+        # limit; any failure leaves it disabled.
+        self._disabled = True
+        try:
+            os.makedirs(query_history_dir, exist_ok=True)
+        except OSError:
+            # Exporting query history is a best-effort feature for the VS Code
+            # extension; a failure here must not break the user's session.
+            _logger.debug(
+                "Failed to create query history directory %s",
+                query_history_dir,
+                exc_info=True,
+            )
+            return
+
+        # Resolve the file-count limit, falling back to the default when the env
+        # var is unset or not a valid integer.
+        try:
+            limit = int(
+                os.environ.get(
+                    "SNOWFLAKE_SNOWPARK_VSC_QUERY_HISTORY_DIR_MAX_FILES",
+                    self.DEFAULT_FILE_COUNT_LIMIT_AT_INIT,
+                )
+            )
+        except ValueError:
+            limit = self.DEFAULT_FILE_COUNT_LIMIT_AT_INIT
+        try:
+            # Enable exporting only if the directory is below the limit; if it is
+            # already saturated we stay disabled so we do not keep growing it.
+            self._disabled = len(os.listdir(self._query_history_dir)) >= limit
+        except OSError:
+            # If we cannot inspect the directory, err on the side of caution
+            # by keeping the exporter disabled.
+            _logger.debug(
+                "Failed to count files in query history directory %s",
+                self._query_history_dir,
+                exc_info=True,
+            )
+
+    def _notify(self, query_record: QueryRecord, **kwargs) -> None:
+        if self._disabled:
+            return
+        if query_record.is_describe or not query_record.query_id:
+            return
+        try:
+            open(
+                os.path.join(self._query_history_dir, query_record.query_id), "w"
+            ).close()
+        except OSError:
+            # Exporting query history is a best-effort feature for the VS Code
+            # extension; a failure here must not break the user's session.
+            _logger.debug(
+                "Failed to write query history file for query id %s in %s",
+                query_record.query_id,
+                self._query_history_dir,
+                exc_info=True,
+            )

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/session.py

@@ -856,6 +856,20 @@ class Session:
 
         _logger.info("Snowpark Session information: %s", self._session_info)
 
+        self._vsc_history_exporter = None
+        self._vsc_history_dir = os.environ.get(
+            "SNOWFLAKE_SNOWPARK_VSC_QUERY_HISTORY_DIR"
+        )
+        if self._vsc_history_dir:
+            from snowflake.snowpark.query_history import _VscHistoryExporter
+
+            _logger.debug(
+                "Setting up VS Code query history exporter with directory %s",
+                self._vsc_history_dir,
+            )
+            self._vsc_history_exporter = _VscHistoryExporter(self._vsc_history_dir)
+            self._conn.add_query_listener(self._vsc_history_exporter)
+
         # Register self._close_at_exit so it will be called at interpreter shutdown
         atexit.register(self._close_at_exit)
 
@@ -2782,6 +2796,8 @@ class Session:
         version_tag = kwargs.pop("version_tag", None)
         start_snapshot_id = kwargs.pop("start_snapshot_id", None)
         end_snapshot_id = kwargs.pop("end_snapshot_id", None)
+        version_ref = kwargs.pop("version_ref", None)
+        branch = kwargs.pop("branch", None)
         if kwargs:
             raise TypeError(
                 f"table() got unexpected keyword arguments: {sorted(kwargs)}"
@@ -2827,6 +2843,8 @@ class Session:
             version_tag=version_tag,
             start_snapshot_id=start_snapshot_id,
             end_snapshot_id=end_snapshot_id,
+            version_ref=version_ref,
+            branch=branch,
         )
         # Replace API call origin for table
         set_api_call_source(t, "Session.table")

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/table.py

@@ -306,6 +306,8 @@ class Table(DataFrame):
         version_tag = kwargs.pop("version_tag", None)
         start_snapshot_id = kwargs.pop("start_snapshot_id", None)
         end_snapshot_id = kwargs.pop("end_snapshot_id", None)
+        version_ref = kwargs.pop("version_ref", None)
+        branch = kwargs.pop("branch", None)
         if kwargs:
             raise TypeError(
                 f"Table() got unexpected keyword arguments: {sorted(kwargs)}"
@@ -344,6 +346,8 @@ class Table(DataFrame):
             stream=stream,
             version=version,
             version_tag=version_tag,
+            version_ref=version_ref,
+            branch=branch,
         )
         if iceberg_changes_config is not None and time_travel_config is not None:
             raise ValueError(

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1}/src/snowflake/snowpark/version.py

@@ -2,4 +2,4 @@
 
 
 # Update this for the versions
-VERSION = (1, 53, 0)
+VERSION = (1, 53, 1)

{snowflake_snowpark_python-1.53.0 → snowflake_snowpark_python-1.53.1/src/snowflake_snowpark_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-snowpark-python
-Version: 1.53.0
+Version: 1.53.1
 Summary: Snowflake Snowpark for Python
 Home-page: https://www.snowflake.com/
 Author: Snowflake, Inc