Add docstrings for _threads (#127)

Author: Mandzhi

src/yandex_cloud_ml_sdk/_threads/domain.py

@@ -12,12 +12,17 @@
 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, UndefinedOr, 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 .thread import AsyncThread, Thread, ThreadTypeT
 
 
 class BaseThreads(BaseDomain, Generic[ThreadTypeT]):
+    """A class for managing threads. It is a part of Assistants API.
+
+    This class provides methods to create, retrieve, and list threads.
+    """
     _thread_impl: type[ThreadTypeT]
 
     async def _create(
@@ -30,6 +35,19 @@ async def _create(
         expiration_policy: UndefinedOr[ExpirationPolicyAlias] = UNDEFINED,
         timeout: float = 60,
     ) -> ThreadTypeT:
+        """Create a new thread.
+
+        This method creates a new thread with the specified parameters.
+
+        :param name: the name of the thread.
+        :param description: a description for the thread.
+        :param labels: a set of labels for the thread.
+        :param ttl_days: time-to-live in days for the thread.
+        :param expiration_policy: expiration policy for the file.
+            Assepts for passing ``static`` or ``since_last_active`` strings. Should be defined if ``ttl_days`` has been defined, otherwise both parameters should be undefined.
+        :param timeout: timeout for the service call 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")
 
@@ -59,6 +77,14 @@ async def _get(
         *,
         timeout: float = 60,
     ) -> ThreadTypeT:
+        """Retrieve a thread by its id.
+
+        This method fetches an already created thread using its unique identifier.
+
+        :param thread_id: the unique identifier of the thread to retrieve.
+        :param timeout: timeout for the service call in seconds.
+            Defaults to 60 seconds.
+        """
         # TODO: we need a global per-sdk cache on ids to rule out
         # possibility we have two Threads with same ids but different fields
         request = GetThreadRequest(thread_id=thread_id)
@@ -79,6 +105,15 @@ async def _list(
         page_size: UndefinedOr[int] = UNDEFINED,
         timeout: float = 60
     ) -> AsyncIterator[ThreadTypeT]:
+        """List threads in the specified folder.
+
+        This method retrieves a list of threads. It continues
+        to fetch threads until there are no more available.
+
+        :param page_size: the maximum number of threads to return per page.
+        :param timeout: timeout for the service call in seconds.
+            Defaults to 60 seconds.
+        """
         page_token_ = ''
         page_size_ = get_defined_value(page_size, 0)
 
@@ -104,10 +139,11 @@ async def _list(
 
                 page_token_ = response.next_page_token
 
-
+@doc_from(BaseThreads)
 class AsyncThreads(BaseThreads[AsyncThread]):
     _thread_impl = AsyncThread
 
+    @doc_from(BaseThreads._create)
     async def create(
         self,
         *,
@@ -127,6 +163,7 @@ async def create(
             timeout=timeout,
         )
 
+    @doc_from(BaseThreads._get)
     async def get(
         self,
         thread_id: str,
@@ -138,6 +175,7 @@ async def get(
             timeout=timeout,
         )
 
+    @doc_from(BaseThreads._list)
     async def list(
         self,
         *,
@@ -150,14 +188,15 @@ async def list(
         ):
             yield thread
 
-
+@doc_from(BaseThreads)
 class Threads(BaseThreads[Thread]):
     _thread_impl = Thread
 
     __get = run_sync(BaseThreads._get)
     __create = run_sync(BaseThreads._create)
     __list = run_sync_generator(BaseThreads._list)
 
+    @doc_from(BaseThreads._create)
     def create(
         self,
         *,
@@ -177,6 +216,7 @@ def create(
             timeout=timeout,
         )
 
+    @doc_from(BaseThreads._get)
     def get(
         self,
         thread_id: str,
@@ -188,6 +228,7 @@ def get(
             timeout=timeout,
         )
 
+    @doc_from(BaseThreads._list)
     def list(
         self,
         *,

src/yandex_cloud_ml_sdk/_threads/thread.py

@@ -17,11 +17,16 @@
 from yandex_cloud_ml_sdk._types.message import MessageType
 from yandex_cloud_ml_sdk._types.misc import UNDEFINED, UndefinedOr, get_defined_value
 from yandex_cloud_ml_sdk._types.resource import ExpirableResource, safe_on_delete
+from yandex_cloud_ml_sdk._utils.doc import doc_from
 from yandex_cloud_ml_sdk._utils.sync import run_sync, run_sync_generator
 
 
 @dataclasses.dataclass(frozen=True)
 class BaseThread(ExpirableResource):
+    """A class for a thread resource.
+
+    It provides methods for working with messages that the thread contains (e.g. updating, deleting, writing to, and reading from).
+    """
     @safe_on_delete
     async def _update(
         self,
@@ -33,6 +38,17 @@ async def _update(
         expiration_policy: UndefinedOr[ExpirationPolicyAlias] = UNDEFINED,
         timeout: float = 60,
     ) -> Self:
+        """Update the thread's properties, including the name, the description, labels,
+        ttl days, and the expiration policy of the thread.
+
+        :param name: the new name of the thread.
+        :param description: the new description for the thread.
+        :param labels: a set of new labels for the thread.
+        :param ttl_days: the updated time-to-live in days for the thread.
+        :param expiration_policy: an updated expiration policy for the file.
+        :param timeout: timeout for the operation in seconds.
+            Defaults to 60 seconds.
+        """
         # pylint: disable=too-many-locals
         name_ = get_defined_value(name, '')
         description_ = get_defined_value(description, '')
@@ -78,6 +94,14 @@ async def _delete(
         *,
         timeout: float = 60,
     ) -> None:
+        """Delete the thread.
+
+        This method deletes the thread and marks it as deleted.
+        Raises an exception if the deletion fails.
+
+        :param timeout: timeout for the operation.
+            Defaults to 60 seconds.
+        """
         request = DeleteThreadRequest(thread_id=self.id)
 
         async with self._client.get_service_stub(ThreadServiceStub, timeout=timeout) as stub:
@@ -97,6 +121,16 @@ async def _write(
         labels: UndefinedOr[dict[str, str]] = UNDEFINED,
         timeout: float = 60,
     ) -> Message:
+        """Write a message to the thread.
+
+        This method allows sending a message to the thread with optional labels.
+
+        :param message: the message to be sent to the thread. Could be a string, a dictionary, or a result object.
+            Read more about other possible message types in the `documentation <https://yandex.cloud/docs/foundation-models/sdk/#usage>`_.
+        :param labels: optional labels for the message.
+        :param timeout: timeout for the operation.
+            Defaults to 60 seconds.
+        """
         # pylint: disable-next=protected-access
         return await self._sdk._messages._create(
             thread_id=self.id,
@@ -110,6 +144,13 @@ async def _read(
         *,
         timeout: float = 60,
     ) -> AsyncIterator[Message]:
+        """Read messages from the thread.
+
+        This method allows iterating over messages in the thread.
+
+        :param timeout: timeout for the operation.
+            Defaults to 60 seconds.
+        """
         # NB: in other methods it is solved via @safe decorator, but it is doesn't work
         # with iterators, so, temporary here will be small copypaste
         # Also I'm not sure enough if we need to put whole thread reading under a lock
@@ -125,17 +166,26 @@ async def _read(
 
 @dataclasses.dataclass(frozen=True)
 class RichThread(BaseThread):
+    #: the name of the thread
     name: str | None
+    #: the description of the thread
     description: str | None
+    #: the identifier of the user who created the thread
     created_by: str
+    #: the timestamp when the thread was created
     created_at: datetime
+    #: the identifier of the user who last updated the thread
     updated_by: str
+    #: the timestamp when the thread was last updated
     updated_at: datetime
+    #: the timestamp when the thread will expire
     expires_at: datetime
+    #: additional labels associated with the thread
     labels: dict[str, str] | None
 
-
 class AsyncThread(RichThread):
+
+    @doc_from(BaseThread._update)
     async def update(
         self,
         *,
@@ -155,13 +205,15 @@ async def update(
             timeout=timeout,
         )
 
+    @doc_from(BaseThread._delete)
     async def delete(
         self,
         *,
         timeout: float = 60,
     ) -> None:
         await self._delete(timeout=timeout)
 
+    @doc_from(BaseThread._write)
     async def write(
         self,
         message: MessageType,
@@ -175,6 +227,7 @@ async def write(
             timeout=timeout
         )
 
+    @doc_from(BaseThread._read)
     async def read(
         self,
         *,
@@ -183,15 +236,16 @@ async def read(
         async for message in self._read(timeout=timeout):
             yield message
 
+    #: alias for the read method
     __aiter__ = read
 
-
 class Thread(RichThread):
     __update = run_sync(RichThread._update)
     __delete = run_sync(RichThread._delete)
     __write = run_sync(RichThread._write)
     __read = run_sync_generator(RichThread._read)
 
+    @doc_from(BaseThread._update)
     def update(
         self,
         *,
@@ -211,13 +265,15 @@ def update(
             timeout=timeout,
         )
 
+    @doc_from(BaseThread._delete)
     def delete(
         self,
         *,
         timeout: float = 60,
     ) -> None:
         self.__delete(timeout=timeout)
 
+    @doc_from(BaseThread._write)
     def write(
         self,
         message: MessageType,
@@ -231,6 +287,7 @@ def write(
             timeout=timeout
         )
 
+    @doc_from(BaseThread._read)
     def read(
         self,
         *,