Add docstrings for _files/domain.py (#98)

Author: Mandzhi

src/yandex_cloud_ml_sdk/_files/domain.py

@@ -12,12 +12,18 @@
 from yandex_cloud_ml_sdk._types.domain import BaseDomain
 from yandex_cloud_ml_sdk._types.expiration import ExpirationConfig, ExpirationPolicyAlias
 from yandex_cloud_ml_sdk._types.misc import UNDEFINED, PathLike, UndefinedOr, coerce_path, get_defined_value, is_defined
+from yandex_cloud_ml_sdk._utils.doc import doc_from
 from yandex_cloud_ml_sdk._utils.sync import run_sync, run_sync_generator
 
 from .file import AsyncFile, File, FileTypeT
 
 
 class BaseFiles(BaseDomain, Generic[FileTypeT]):
+    """Files domain, which contains API for working with files.
+
+    Files is a part of :ref:`Assistants API`, which is the only place you could use it.
+    Provides upload, get and list methods that allow you to work with remote file objects you created earlier.
+    """
     _file_impl: type[FileTypeT]
 
     async def _upload_bytes(
@@ -32,6 +38,20 @@ async def _upload_bytes(
         expiration_policy: UndefinedOr[ExpirationPolicyAlias] = UNDEFINED,
         timeout: float = 60,
     ) -> FileTypeT:
+        """Uploads a byte array as a file.
+
+        :param data: The byte data to upload.
+        :param name: The name of the file on the server.
+        :param description: A description of the file.
+        :param mime_type: The MIME type of the file.
+            By default (i.e. when UNDEFINED) the server will try to auto-detect mime-type and you could override this file.
+        :param labels: Labels associated with the file.
+        :param ttl_days: Time-to-live in days for the file.
+        :param expiration_policy: Expiration policy for the file.
+            Assepts for passing :ref:`static` or :ref:`since_last_active` strings. Should be defined if :ref:`ttl_days` has been defined, otherwise both parameters should be undefined.
+        :param timeout: Timeout for the operation in seconds.
+            Defaults to 60 seconds.
+        """
         if is_defined(ttl_days) != is_defined(expiration_policy):
             raise ValueError("ttl_days and expiration policy must be both defined either undefined")
 
@@ -69,6 +89,20 @@ async def _upload(
         expiration_policy: UndefinedOr[ExpirationPolicyAlias] = UNDEFINED,
         timeout: float = 60,
     ) -> FileTypeT:
+        """Uploads a file from a specified path.
+
+        :param path: The path of the file to upload.
+        :param name: The name of the file on the server.
+        :param description: A description of the file.
+        :param mime_type: The MIME type of the file.
+            By default (i.e. when UNDEFINED) the server will try to auto-detect mime-type and you could override this file.
+        :param labels: Labels associated with the file.
+        :param ttl_days: Time-to-live in days for the file.
+        :param expiration_policy: Expiration policy for the file.
+            Assepts for passing :ref:`static` or :ref:`since_last_active` strings.
+        :param timeout: Timeout for the operation in seconds.
+            Defaults to 60.
+        """
         path = coerce_path(path)
         return await self._upload_bytes(
             data=path.read_bytes(),
@@ -87,6 +121,12 @@ async def _get(
         *,
         timeout: float = 60,
     ) -> FileTypeT:
+        """Retrieves a file by its ID.
+
+        :param file_id: The unique identifier of the file to retrieve.
+        :param timeout: Timeout for the operation in seconds.
+            Defaults to 60.
+        """
         # TODO: we need a global per-sdk cache on file_ids to rule out
         # possibility we have two Files with same ids but different fields
         request = GetFileRequest(file_id=file_id)
@@ -107,6 +147,12 @@ async def _list(
         page_size: UndefinedOr[int] = UNDEFINED,
         timeout: float = 60
     ) -> AsyncIterator[FileTypeT]:
+        """Lists Files in the SDK folder.
+
+        :param page_size: The maximum number of files to return per page.
+        :param timeout: Timeout for the operation in seconds.
+            Defaults to 60.
+        """
         page_token_ = ''
         page_size_ = get_defined_value(page_size, 0)
 
@@ -132,10 +178,11 @@ async def _list(
 
                 page_token_ = response.next_page_token
 
-
+@doc_from(BaseFiles)
 class AsyncFiles(BaseFiles[AsyncFile]):
     _file_impl = AsyncFile
 
+    @doc_from(BaseFiles._upload_bytes)
     async def upload_bytes(
         self,
         data: bytes,
@@ -159,6 +206,7 @@ async def upload_bytes(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._upload)
     async def upload(
         self,
         path: PathLike,
@@ -182,6 +230,7 @@ async def upload(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._get)
     async def get(
         self,
         file_id: str,
@@ -193,6 +242,7 @@ async def get(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._list)
     async def list(
         self,
         *,
@@ -205,7 +255,7 @@ async def list(
         ):
             yield file
 
-
+@doc_from(BaseFiles)
 class Files(BaseFiles[File]):
     _file_impl = File
 
@@ -214,6 +264,7 @@ class Files(BaseFiles[File]):
     __get = run_sync(BaseFiles._get)
     __list = run_sync_generator(BaseFiles._list)
 
+    @doc_from(BaseFiles._upload_bytes)
     def upload_bytes(
         self,
         data: bytes,
@@ -237,6 +288,7 @@ def upload_bytes(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._upload)
     def upload(
         self,
         path: PathLike,
@@ -260,6 +312,7 @@ def upload(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._get)
     def get(
         self,
         file_id: str,
@@ -271,6 +324,7 @@ def get(
             timeout=timeout
         )
 
+    @doc_from(BaseFiles._list)
     def list(
         self,
         *,