Merge branch 'master' into refactor_proto_result

Author: vhaldemar

CONTRIBUTING.md

@@ -0,0 +1,85 @@
+# Tests
+
+## Run all the tests
+```bash
+tox
+```
+
+## Run specific python version
+
+```bash
+tox -e python3.12-extra-deps
+```
+
+## Filtering tests further
+
+```bash
+tox -e ... -- path/to/test/file.py -k <substring_of_test_name>
+```
+
+or to speedup the process, look into `tox.ini` and run commands without tox environment:
+
+```bash
+pip install -r test_requirements.txt -r test_requirements_extra.txt
+
+# to run one and only one test
+pytest path/to/test/file.py -k <substring_of_test_name>
+
+# to run only flakes
+pytest --flakes src/ examples/
+```
+
+Bash above is just examples how to run some of the commands without tox, there many more possibilities.
+
+## Test cassetes
+
+In some tests we are using [pytest-recording](https://github.com/kiwicom/pytest-recording) library to record
+http requests to a local test cassetes to not to use network in future runs and to increase determinacy
+of test runs (with the assupmtion that backend will not break contract and will not make any breaking changes).
+
+But pytest-recording supports only http/https cassetes so we have something like this for grpc requests
+[written by us](src/yandex_cloud_ml_sdk/_testing/interceptor.py).
+
+It is not so convenient to use and have it's problems, but basically to use it you need to:
+
+1) Place `@pytest.mark.allow_grpc` to the test.
+
+2) Edit `tests/conftest.py:fixture_folder_id` (TODO: make it using env vars by default)
+
+3) Export any auth into environment like `export YC_API_KEY="..."` or any other auth method
+
+4) Run your new test for the first time `pytest path/to/test/file.py -k <test_name> --generate-grpc` which will create
+  a new cassete file
+
+5) In case of the test failed or if you want to regenerate cassete -- `pytest <...> --regenerate-grpc` will help
+
+6) When you will thinkn that cassete is okay, run pytest without any `--...-grpc` flags
+
+7) Do not forget to commit new cassete file.
+
+
+# Pre-commit hooks
+
+We are using https://pre-commit.com/ to improve our PR review experience.
+
+It is generally a good idea to setup pre-commit locally, otherwise some robot will come to your PR and
+will either make commit with fixes (and you will need to pull it or overwrite with a force push),
+either it will break the tests with the things it can't fix.
+
+
+# Documentation
+
+On PR we are running `sphinx-build -W` which are failing in case of any warnings such as
+unresolved references or wrong rst syntaxt in docstrings.
+
+To install sphinx and other required for work with documentation, run
+`pip isntall -r docs/requirements.txt -e .` in the repo root.
+
+To run sphinx locally to check if there are any errors or warnings,
+run `sphinx-build docs docs/_build -E -W` in the repo root.
+It will generate html in the `docs/_build` folder which you could check out in case
+you want to be sure how is your doc will looks like.
+
+Also you could install `sphinx-autobuild` and run `sphinx-autobuild docs docs/_build --watch src`
+to run a webserver (it will be available at http://localhost:8000 by-default) and automatically
+rebuild a doc when you save a file.

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,17 @@
 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[ProtoThread]):
+    """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 +39,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 +95,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 +122,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 +145,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 +167,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 +206,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 +228,7 @@ async def write(
             timeout=timeout
         )
 
+    @doc_from(BaseThread._read)
     async def read(
         self,
         *,
@@ -183,15 +237,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 +266,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 +288,7 @@ def write(
             timeout=timeout
         )
 
+    @doc_from(BaseThread._read)
     def read(
         self,
         *,

test_requirements_extra.txt

@@ -0,0 +1,2 @@
+langchain-core>=0.3; python_version >= '3.9'
+numpy