SNOW-1998295: Update docs for SnowflakeFile writes general availability (#3182)

Author: sfc-gh-aissa

CHANGELOG.md

@@ -12,6 +12,11 @@
   - Removed the need to `cache_result` in the internal implementation of the input dataframe resulting in a pure lazy dataframe operation.
   - The `seed` argument now behaves as expected with repeatable results across multiple calls and sessions.
 - `DataFrame.fillna` and `DataFrame.replace` now both support fitting `int` and `float` into `Decimal` columns if `include_decimal` is set to True.
+- Added documentation for the following UDF and stored procedure functions in `files.py` as a result of their General Availability.
+  - `SnowflakeFile.write`
+  - `SnowflakeFile.writelines`
+  - `SnowflakeFile.writeable`
+- Minor documentation changes for `SnowflakeFile` and `SnowflakeFile.open()`
 
 #### Bug Fixes
 

docs/source/snowpark/files.rst

@@ -27,17 +27,23 @@ Files
 
     ~SnowflakeFile.close
     ~SnowflakeFile.fileno
+    ~SnowflakeFile.isatty
     ~SnowflakeFile.open
+    ~SnowflakeFile.open_new_result
     ~SnowflakeFile.read
     ~SnowflakeFile.read1
-    ~SnowflakeFile.readline
     ~SnowflakeFile.readable
     ~SnowflakeFile.readall
     ~SnowflakeFile.readinto
     ~SnowflakeFile.readinto1
+    ~SnowflakeFile.readline
+    ~SnowflakeFile.readlines
     ~SnowflakeFile.seek
     ~SnowflakeFile.seekable
     ~SnowflakeFile.tell
+    ~SnowflakeFile.write
+    ~SnowflakeFile.writable
+    ~SnowflakeFile.writelines
 
 
 .. rubric:: Attributes

src/snowflake/snowpark/files.py

@@ -15,8 +15,6 @@
 import sys
 from io import RawIOBase
 
-from snowflake.snowpark._internal.utils import private_preview
-
 # Python 3.8 needs to use typing.Iterable because collections.abc.Iterable is not subscriptable
 # Python 3.9 can use both
 # Python 3.10 needs to use collections.abc.Iterable because typing.Iterable is removed
@@ -34,7 +32,7 @@ class SnowflakeFile(RawIOBase):
     SnowflakeFile supports most operations supported by Python IOBase objects.
     A SnowflakeFile object can be used as a Python IOBase object.
 
-    The constructor of this class is not supposed to be called directly. Call :meth:`~snowflake.snowpark.file.SnowflakeFile.open` to create a SnowflakeFile object.
+    The constructor of this class is not supposed to be called directly. Call :meth:`~snowflake.snowpark.file.SnowflakeFile.open` to create a read-only SnowflakeFile object, and call :meth:`~snowflake.snowpark.file.SnowflakeFile.open_new_result` to create a write-only SnowflakeFile object.
 
     This class is intended for usage within UDFs and stored procedures and many methods do not work locally.
     """
@@ -73,26 +71,39 @@ def open(
         require_scoped_url: bool = True,
     ) -> SnowflakeFile:
         """
-        Returns a :class:`~snowflake.snowpark.file.SnowflakeFile`.
-        In UDF and Stored Procedures, the object works like a Python IOBase object and as a wrapper for an IO stream of remote files. The IO Stream is to support the file operations defined in this class.
+        Used to create a :class:`~snowflake.snowpark.file.SnowflakeFile` which can only be used for read-based IO operations on the file.
+
+        In UDFs and Stored Procedures, the object works like a read-only Python IOBase object and as a wrapper for an IO stream of remote files.
 
         All files are accessed in the context of the UDF owner (with the exception of caller's rights stored procedures which use the caller's context).
         UDF callers should use scoped URLs to allow the UDF to access their files. By accepting only scoped URLs the UDF owner can ensure
-        the UDF caller had access to the provided file. Removing the requirement that the URL is a scoped URL (require_scoped_url=false) allows the caller
+        the UDF caller had access to the provided file. Removing the requirement that the URL is a scoped URL (require_scoped_url=False) allows the caller
         to provide URLs that may be only accessible by the UDF owner.
 
         is_owner_file is marked for deprecation. For Snowflake release 7.8 and onwards please use require_scoped_url instead.
 
         Args:
             file_location: scoped URL, file URL, or string path for files located in a stage
-            mode: A string used to mark the type of an IO stream.
+            mode: A string used to mark the type of an IO stream. Supported modes are "r" for text read and "rb" for binary read.
             is_owner_file: (Deprecated) A boolean value, if True, the API is intended to access owner's files and all URI/URL are allowed. If False, the API is intended to access files passed into the function by the caller and only scoped URL is allowed.
             require_scoped_url: A boolean value, if True, file_location must be a scoped URL. A scoped URL ensures that the caller cannot access the UDF owners files that the caller does not have access to.
         """
         return cls(
             file_location, mode, is_owner_file, require_scoped_url=require_scoped_url
         )
 
+    @classmethod
+    def open_new_result(cls, mode: str = "w") -> SnowflakeFile:
+        """
+        Used to create a :class:`~snowflake.snowpark.file.SnowflakeFile` which can only be used for write-based IO operations. UDFs/Stored Procedures should return the file to materialize it, and it is then made accessible via a scoped URL returned in the query results.
+
+        In UDFs and Stored Procedures, the object works like a write-only Python IOBase object and as a wrapper for an IO stream of remote files.
+
+        Args:
+            mode: A string used to mark the type of an IO stream. Supported modes are "w" for text write and "wb" for binary write.
+        """
+        return cls("new results file", mode, require_scoped_url=0, from_result_api=True)
+
     def close(self) -> None:
         """
         In UDF and Stored Procedures, the close func closes the IO Stream included in the SnowflakeFile.
@@ -121,24 +132,10 @@ def flush(self) -> None:
 
     def isatty(self) -> None:
         """
-        Returns false, file streams in stored procedures and UDFs are never interactive in Snowflake.
+        Returns False, file streams in stored procedures and UDFs are never interactive in Snowflake.
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
 
-    @classmethod
-    @private_preview(version="1.22.1")
-    def open_new_result(cls, mode: str = "w") -> SnowflakeFile:
-        """
-        Returns a :class:`~snowflake.snowpark.file.SnowflakeFile`.
-        In UDF and Stored Procedures, the object works like a Python IOBase object and as a wrapper for an IO stream of remote files. The IO Stream is to support the file operations defined in this class.
-
-        This stream will open a writable result file that will be materialized when it's returned by a UDF or Stored Procedure. When the file is materialized then file_uri will be set to a scoped URL that temporarily references this file.
-
-        Args:
-            mode: A string used to mark the type of an IO stream.
-        """
-        return cls("new results file", mode, require_scoped_url=0, from_result_api=True)
-
     def read(self, size: int = -1) -> None:
         """
         See https://docs.python.org/3/library/io.html#io.RawIOBase.read
@@ -151,12 +148,6 @@ def read1(self, size: int = -1) -> None:
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
 
-    def readline(self, size: int = -1) -> None:
-        """
-        See https://docs.python.org/3/library/io.html#io.IOBase.readline
-        """
-        raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
-
     def readable(self) -> None:
         """
         See https://docs.python.org/3/library/io.html#io.IOBase.readable
@@ -181,6 +172,12 @@ def readinto1(self, b: bytes | bytearray | array.array) -> None:
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
 
+    def readline(self, size: int = -1) -> None:
+        """
+        See https://docs.python.org/3/library/io.html#io.IOBase.readline
+        """
+        raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
+
     def readlines(self, hint: int = -1) -> None:
         """
         See https://docs.python.org/3/library/io.html#io.IOBase.readlines
@@ -213,18 +210,18 @@ def truncate(self, size: int | None = None) -> None:
 
     def write(self, b: bytes | bytearray | array.array) -> None:
         """
-        Not yet supported in UDF and Stored Procedures.
+        See https://docs.python.org/3/library/io.html#io.RawIOBase.write
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
 
     def writable(self) -> None:
         """
-        Not yet supported in UDF and Stored Procedures.
+        See https://docs.python.org/3/library/io.html#io.IOBase.writable
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)
 
     def writelines(self, lines: Iterable[str] | list[str]) -> None:
         """
-        Not yet supported in UDF and Stored Procedures.
+        See https://docs.python.org/3/library/io.html#io.IOBase.writelines
         """
         raise NotImplementedError(_DEFER_IMPLEMENTATION_ERR_MSG)

tests/unit/test_files.py

@@ -6,7 +6,6 @@
 
 import pytest
 
-from snowflake.snowpark._internal.utils import private_preview
 from snowflake.snowpark.files import _DEFER_IMPLEMENTATION_ERR_MSG, SnowflakeFile
 
 
@@ -16,7 +15,6 @@ def test_create_snowflakefile():
         assert snowflake_file._mode == "r"
 
 
-@private_preview(version="1.22.1")
 def test_write_snowflakefile():
     with SnowflakeFile.open_new_result("w") as snowflake_file:
         assert snowflake_file._file_location == "new results file"