From 41b879584a6768e567ae87efff47e6453535279b Mon Sep 17 00:00:00 2001
From: teplyakov <teolyakov@perx.ru>
Date: Wed, 2 Apr 2025 12:47:06 +0300
Subject: [PATCH 1/3] feat: AUTO-4049 Add docstrings

---
 perxis/provider.py | 615 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 604 insertions(+), 11 deletions(-)

diff --git a/perxis/provider.py b/perxis/provider.py
index f1afca9..91f0b18 100644
--- a/perxis/provider.py
+++ b/perxis/provider.py
@@ -1,3 +1,16 @@
+"""
+Модуль для работы с данными и файлами в системе Perxis.
+
+Этот модуль предоставляет классы для взаимодействия с API Perxis.
+
+- `PerxisFilesWrapper` низкоуровневый сервис для работы с файлами в Perxis.
+- `PerxisReferencesWrapper` низкоуровневый сервис для работы со ссылками в Perxis.
+- `PerxisItemsWrapper` низкоуровневый сервис для работы с элементами в Perxis.
+- `PerxisDataProvider` сервис, предоставляющий методы для работы с элементами и
+                       ссылками в конкретном окружении Perxis.
+- `PerxisFileProvider` сервис, предоставляющий методы для загрузки файлов.
+"""
+
 from google.protobuf.struct_pb2 import Struct
 from google.protobuf.empty_pb2 import Empty
 from perxis.common import common_pb2
@@ -10,18 +23,50 @@ from perxis.files import files_pb2, files_pb2_grpc
 
 
 DEFAULT_PAGE_SIZE: int = 100
+"""Размер страницы по умолчанию для постраничного получения записей.
+
+Эта переменная определяет количество записей, которое будет возвращаться за один запрос при постраничном
+поиске данных в системе. Значение по умолчанию равно `100`.
+"""
+
 DEFAULT_PART_SIZE: int = 1024 * 5
+"""Размер части файла по умолчанию для загрузки.
+
+Эта переменная определяет размер каждой части файла, который будет загружаться в системе. Значение
+по умолчанию равно 5 килобайт (5120 байт).
+"""
 
 
 class PerxisFilesWrapper:
+    """Сервис для работы с файлами в Perxis.
+
+    Этот класс используется для загрузки файлов в систему Perxis через gRPC.
+
+    Attributes:
+        __stub (files_pb2_grpc.FilesStub): `FilesStub` объект.
+    """
+
     __stub: files_pb2_grpc.FilesStub
 
     def __init__(self, stub: files_pb2_grpc.FilesStub) -> None:
+        """Инициализирует сервис для работы с файлами.
+
+        Arguments:
+            stub (files_pb2_grpc.FilesStub): `FilesStub` объект.
+        """
         self.__stub = stub
 
     async def start_upload(
         self, file_name: str, file_size: int
     ) -> files_pb2.StartUploadResponse:
+        """Начинает процесс загрузки файла.
+
+        Arguments:
+            file_name (str): Имя файла для загрузки.
+            file_size (int): Размер файла в байтах.
+        Returns:
+            files_pb2.StartUploadResponse: Ответ с информацией о начале загрузки.
+        """
         message = await self.__stub.StartUpload(
             files_pb2.StartUploadRequest(
                 upload=files_pb2.MultipartUpload(
@@ -38,6 +83,17 @@ class PerxisFilesWrapper:
         parts: list[str],
         part_size: int = DEFAULT_PART_SIZE,
     ) -> files_pb2.CompleteUploadResponse:
+        """Завершает процесс загрузки файла.
+
+        Arguments:
+            file_id (str): Идентификатор загружаемого файла.
+            upload_id (str): Идентификатор процесса загрузки.
+            parts (list[str]): Список идентификаторов частей файла.
+            part_size (int, optional): Размер части файла.
+                                       По умолчанию используется `DEFAULT_PART_SIZE`.
+        Returns:
+            files_pb2.CompleteUploadResponse: Ответ с информацией о завершении загрузки.
+        """
         message = await self.__stub.CompleteUpload(
             files_pb2.CompleteUploadRequest(
                 upload=files_pb2.MultipartUpload(
@@ -55,6 +111,14 @@ class PerxisFilesWrapper:
 
 
 class PerxisReferencesWrapper:
+    """Сервис для работы со ссылками на записи в Perxis.
+
+    Этот класс используется для получения связей (ссылок) на записи в системе Perxis через gRPC.
+
+    Attributes:
+        __references (references_pb2_grpc.ReferencesStub): `ReferencesStub` объект.
+    """
+
     __references: references_pb2_grpc.ReferencesStub
 
     def __init__(self, references: references_pb2_grpc.ReferencesStub):
@@ -63,7 +127,16 @@ class PerxisReferencesWrapper:
     async def get_references(
         self, references: list[Reference], space_id: str, env_id: str
     ) -> items_pb2.GetResponse:
-        """Метод получения связей."""
+        """Получает связи (ссылки) на записи.
+
+        Arguments:
+            references (list[Reference]): Список объектов Reference.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+
+        Returns:
+            items_pb2.GetResponse: Ответ с данными.
+        """
         message = await self.__references.Get(
             references_pb2.GetRequest(
                 space_id=space_id,
@@ -78,15 +151,38 @@ class PerxisReferencesWrapper:
 
 
 class PerxisItemsWrapper:
+    """Сервис для работы с элементами в системе Perxis.
+
+    Этот класс предоставляет методы для выполнения различных операций с элементами,
+    таких как получение, создание, обновление, поиск, публикация и удаление элементов.
+
+    Attributes:
+        __items (items_pb2_grpc.ItemsStub): `ItemsStub` объект.
+    """
+
     __items: items_pb2_grpc.ItemsStub
 
-    def __init__(self, items: items_pb2_grpc.ItemsStub):
+    def __init__(self, items: items_pb2_grpc.ItemsStub) -> None:
+        """Инициализирует сервис для работы с элементами.
+
+        Arguments:
+            items (items_pb2_grpc.ItemsStub): `ItemsStub` объект.
+        """
         self.__items = items
 
     async def get(
         self, item_id: str, collection_id: str, space_id: str, env_id: str
     ) -> items_pb2.GetResponse:
-        """Получение записи по идентификатору."""
+        """Получает элемент по его идентификатору.
+
+        Arguments:
+            item_id (str): Идентификатор элемента для получения.
+            collection_id (str): Идентификатор коллекции, к которой принадлежит элемент.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            items_pb2.GetResponse: Ответ с данными элемента.
+        """
         message = await self.__items.Get(
             items_pb2.GetRequest(
                 item_id=item_id,
@@ -100,6 +196,16 @@ class PerxisItemsWrapper:
     async def create(
         self, data: Struct, collection_id: str, space_id: str, env_id: str
     ) -> items_pb2.CreateResponse:
+        """Создает новый элемент в указанной коллекции.
+
+        Arguments:
+            data (Struct): Данные элемента для создания.
+            collection_id (str): Идентификатор коллекции для создания элемента.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            items_pb2.CreateResponse: Ответ с данными созданного элемента.
+        """
         message = await self.__items.Create(
             items_pb2.CreateRequest(
                 item=items_pb2.Item(
@@ -115,6 +221,17 @@ class PerxisItemsWrapper:
     async def update(
         self, item_id: str, data: Struct, collection_id: str, space_id: str, env_id: str
     ) -> Empty:
+        """Обновляет существующий элемент.
+
+        Arguments:
+            item_id (str): Идентификатор элемента для обновления.
+            data (Struct): Новые данные для элемента.
+            collection_id (str): Идентификатор коллекции, к которой принадлежит элемент.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешном обновлении.
+        """
         message = await self.__items.Update(
             items_pb2.UpdateRequest(
                 item=items_pb2.Item(
@@ -146,7 +263,27 @@ class PerxisItemsWrapper:
         hidden: bool = False,
         templates: bool = False,
     ) -> items_pb2.FindResponse:
-        """Метод поиска записей в коллекции."""
+        """Ищет записи в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Фильтры для поиска.
+            sort_by (list[str] | None): Поля для сортировки.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Максимальное количество возвращаемых записей.
+            offset (int | None): Смещение для пагинации.
+            page_num (int | None): Номер страницы для пагинации.
+            page_size (int | None): Размер страницы для пагинации.
+            deleted (bool): Учитывать ли удаленные записи.
+            regular (bool): Учитывать ли обычные записи.
+            hidden (bool): Учитывать ли скрытые записи.
+            templates (bool): Учитывать ли шаблоны.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными записями.
+        """
         message = await self.__items.Find(
             items_pb2.FindRequest(
                 space_id=space_id,
@@ -186,7 +323,23 @@ class PerxisItemsWrapper:
         page_num: int | None = None,
         page_size: int | None = DEFAULT_PAGE_SIZE,
     ) -> items_pb2.FindResponse:
-        """Метод поиска опубликованных записей в коллекции."""
+        """Ищет опубликованные записи в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Фильтры для поиска.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            sort_by (list[str] | None): Поля для сортировки.
+            limit (int | None): Максимальное количество возвращаемых записей.
+            offset (int | None): Смещение для пагинации.
+            page_num (int | None): Номер страницы для пагинации.
+            page_size (int | None): Размер страницы для пагинации.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными опубликованными записями.
+        """
         message = await self.__items.FindPublished(
             items_pb2.FindPublishedRequest(
                 space_id=space_id,
@@ -219,7 +372,20 @@ class PerxisItemsWrapper:
         sort_by: list[str] | None = None,
         page_size: int | None = DEFAULT_PAGE_SIZE,
     ) -> items_pb2.FindResponse:
-        """Метод поиска всех опубликованных записей в коллекции."""
+        """Ищет все опубликованные записи в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Фильтры для поиска.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            sort_by (list[str] | None): Поля для сортировки.
+            page_size (int | None): Размер страницы для пагинации.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными опубликованными записями.
+        """
         kwargs = {
             "collection_id": collection_id,
             "filters": filters,
@@ -248,7 +414,16 @@ class PerxisItemsWrapper:
     async def unpublish(
         self, item_id: str, collection_id: str, space_id: str, env_id: str
     ) -> Empty:
-        """Метод снятия с публикации записи в коллекции."""
+        """Снимает с публикации запись в коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для снятия с публикации.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешном снятии с публикации.
+        """
         message = await self.__items.Unpublish(
             items_pb2.UnpublishRequest(
                 item=items_pb2.Item(
@@ -264,7 +439,16 @@ class PerxisItemsWrapper:
     async def publish(
         self, item_id: str, collection_id: str, space_id: str, env_id: str
     ) -> Empty:
-        """Метод публикации записи в коллекции."""
+        """Публикует запись в коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для публикации.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешной публикации.
+        """
         message = await self.__items.Publish(
             items_pb2.PublishRequest(
                 item=items_pb2.Item(
@@ -292,7 +476,24 @@ class PerxisItemsWrapper:
         hidden: bool = False,
         templates: bool = False,
     ) -> items_pb2.FindResponse:
-        """Метод получения всех записей коллекции."""
+        """Получает все записи из указанной коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для получения записей.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Необязательные фильтры для получения записей.
+            fields (list[str] | None): Необязательные поля для включения в ответ.
+            exclude_fields (bool): Указывать, нужно ли исключать указанные поля из ответа.
+            sort_by (list[str] | None): Необязательные поля для сортировки результатов.
+            page_size (int | None): Размер страницы для пагинации.
+            deleted (bool): Учитывать ли удаленные записи.
+            regular (bool): Учитывать ли обычные записи.
+            hidden (bool): Учитывать ли скрытые записи.
+            templates (bool): Учитывать ли шаблоны.
+        Returns:
+            items_pb2.FindResponse: Ответ, содержащий полученные записи.
+        """
         items = []
         storage_data = await self.find(
             collection_id=collection_id,
@@ -347,6 +548,20 @@ class PerxisItemsWrapper:
         erase: bool = True,
         **kwargs,
     ) -> Empty:
+        """Удаляет запись из указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для удаления.
+            collection_id (str): Идентификатор коллекции, из которой нужно удалить запись.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            update_attrs (bool): Обновить системные поля `created_by`, `created_at`,
+                                        `created_rev_at`, `updated_by`, `updated_at`.
+            erase (bool): Полное удаление без сохранения удаленной версии объекта.
+            **kwargs: Дополнительные параметры.
+        Returns:
+            Empty: Пустой ответ при успешном удалении.
+        """
         message = await self.__items.Delete(
             items_pb2.DeleteRequest(
                 item=items_pb2.Item(
@@ -370,6 +585,19 @@ class PerxisItemsWrapper:
         update_attrs: bool = False,
         **kwargs,
     ) -> Empty:
+        """Восстанавливает запись из состояния удаления в указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для восстановления.
+            collection_id (str): Идентификатор коллекции, из которой нужно восстановить запись.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            update_attrs (bool): Обновить системные поля `created_by`, `created_at`,
+                                        `created_rev_at`, `updated_by`, `updated_at`.
+            **kwargs: Дополнительные параметры.
+        Returns:
+            Empty: Пустой ответ при успешном восстановлении.
+        """
         message = await self.__items.Undelete(
             items_pb2.UndeleteRequest(
                 item=items_pb2.Item(
@@ -392,6 +620,18 @@ class PerxisItemsWrapper:
         env_id: str,
         locale_id: str | None = None,
     ) -> items_pb2.GetPublishedResponse:
+        """Получает опубликованную запись из указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для получения.
+            collection_id (str): Идентификатор коллекции, из которой нужно получить запись.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            locale_id (str | None): Идентификатор языка перевода который будет использоваться.
+                                Если не указан, то возвращаются данные для языка по умолчанию.
+        Returns:
+            items_pb2.GetPublishedResponse: Ответ с данными опубликованной записи.
+        """
         message = await self.__items.GetPublished(
             items_pb2.GetPublishedRequest(
                 item_id=item_id,
@@ -411,6 +651,17 @@ class PerxisItemsWrapper:
         aggregate_options: dict[str, str] | None = None,
         filters: list[str] | None = None,
     ) -> items_pb2.AggregateResponse:
+        """Выполняет агрегирование данных в указанной коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для агрегирования данных.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            aggregate_options (dict[str, str] | None): Необязательные параметры агрегирования.
+            filters (list[str] | None): Необязательные фильтры для агрегирования.
+        Returns:
+            items_pb2.AggregateResponse: Ответ с результатами агрегирования.
+        """
         message = await self.__items.Aggregate(
             items_pb2.AggregateRequest(
                 space_id=space_id,
@@ -430,6 +681,17 @@ class PerxisItemsWrapper:
         aggregate_options: dict[str, str] | None = None,
         filters: list[str] | None = None,
     ) -> items_pb2.AggregatePublishedResponse:
+        """Выполняет агрегирование опубликованных данных в указанной коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для агрегирования данных.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            aggregate_options (dict[str, str] | None): Необязательные параметры агрегирования.
+            filters (list[str] | None): Необязательные фильтры для агрегирования.
+        Returns:
+            items_pb2.AggregatePublishedResponse: Ответ с результатами агрегирования опубликованных данных.
+        """
         message = await self.__items.AggregatePublished(
             items_pb2.AggregatePublishedRequest(
                 space_id=space_id,
@@ -449,6 +711,17 @@ class PerxisItemsWrapper:
         space_id: str,
         env_id: str,
     ) -> items_pb2.GetRevisionResponse:
+        """Получает информацию о ревизии записи из указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для получения ревизии.
+            revision_id (str): Идентификатор ревизии для получения.
+            collection_id (str): Идентификатор коллекции, из которой нужно получить ревизию.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            items_pb2.GetRevisionResponse: Ответ с данными о ревизии.
+        """
         message = await self.__items.GetRevision(
             items_pb2.GetRevisionRequest(
                 item_id=item_id,
@@ -472,6 +745,21 @@ class PerxisItemsWrapper:
         limit: int | None = None,
         offset: int | None = None,
     ) -> items_pb2.ListRevisionsResponse:
+        """Получает список всех ревизий записи из указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для получения списка ревизий.
+            collection_id (str): Идентификатор коллекции, из которой нужно получить ревизии.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            sort_by (list[str] | None): Необязательные параметры для сортировки.
+            fields (list[str] | None): Необязательные поля для включения в ответ.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Ограничение на количество возвращаемых ревизий.
+            offset (int | None): Смещение для пагинации.
+        Returns:
+            items_pb2.ListRevisionsResponse: Ответ с данными о ревизиях.
+        """
         message = await self.__items.ListRevisions(
             items_pb2.ListRevisionsRequest(
                 item_id=item_id,
@@ -498,6 +786,16 @@ class PerxisItemsWrapper:
         space_id: str,
         env_id: str,
     ) -> Empty:
+        """Архивирует запись в указанной коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для архивирования.
+            collection_id (str): Идентификатор коллекции, содержащей запись.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешной архивации.
+        """
         message = await self.__items.Archive(
             items_pb2.ArchiveRequest(
                 item=items_pb2.Item(
@@ -517,6 +815,16 @@ class PerxisItemsWrapper:
         space_id: str,
         env_id: str,
     ) -> Empty:
+        """Разархивирует ранее архивированную запись.
+
+        Arguments:
+            item_id (str): Идентификатор записи для разархивирования.
+            collection_id (str): Идентификатор коллекции, содержащей запись.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешном разархивации.
+        """
         message = await self.__items.Unarchive(
             items_pb2.UnarchiveRequest(
                 item=items_pb2.Item(
@@ -541,6 +849,21 @@ class PerxisItemsWrapper:
         limit: int | None = None,
         offset: int | None = None,
     ) -> items_pb2.FindArchivedResponse:
+        """Находит все архивированные записи в указанной коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Фильтры для поиска архивированных записей.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Максимальное количество возвращаемых архивированных записей.
+            offset (int | None): Смещение для пагинации.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными архивированными записями.
+        """
         message = await self.__items.FindArchived(
             items_pb2.FindArchivedRequest(
                 space_id=space_id,
@@ -562,12 +885,32 @@ class PerxisItemsWrapper:
 
 
 class PerxisDataProvider:
+    """Провайдер данных для работы с Perxis API.
+
+    Позволяет выполнять операции с данными, такие как получение, создание, обновление,
+    поиск и удаление записей в коллекциях.
+
+    Attributes:
+        channel (GrpcChannel): gRPC-канал для связи с сервером.
+        space_id (str): Идентификатор пространства.
+        env_id (str): Идентификатор окружения.
+        references_wrapper (PerxisReferencesWrapper): Обертка для работы со ссылками на записи в Perxis.
+        items_wrapper (PerxisItemsWrapper): Обертка для работы с элементами (записями) в Perxis.
+    """
+
     def __init__(
         self,
         channel: GrpcChannel,
         space_id: str,
         env_id: str,
     ) -> None:
+        """Инициализация провайдера данных.
+
+        Arguments:
+            channel (GrpcChannel): gRPC-канал для взаимодействия с API.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        """
         self.channel = channel
         self.space_id = space_id
         self.env_id = env_id
@@ -579,7 +922,14 @@ class PerxisDataProvider:
         )
 
     async def get(self, item_id: str, collection_id: str) -> items_pb2.GetResponse:
-        """Получение записи по идентификатору."""
+        """Получение записи по идентификатору.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+        Returns:
+            items_pb2.GetResponse: Ответ с данными записи.
+        """
         message = await self.items_wrapper.get(
             item_id=item_id,
             collection_id=collection_id,
@@ -591,6 +941,14 @@ class PerxisDataProvider:
     async def create(
         self, data: Struct, collection_id: str
     ) -> items_pb2.CreateResponse:
+        """Создание новой записи в коллекции.
+
+        Arguments:
+            data (Struct): Данные для создания записи.
+            collection_id (str): Идентификатор коллекции.
+        Returns:
+            items_pb2.CreateResponse: Ответ с данными созданной записи.
+        """
         message = await self.items_wrapper.create(
             data=data,
             collection_id=collection_id,
@@ -600,6 +958,15 @@ class PerxisDataProvider:
         return message
 
     async def update(self, item_id: str, data: Struct, collection_id: str) -> Empty:
+        """Обновляет существующую запись в коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи, которую нужно обновить.
+            data (Struct): Обновленные данные для записи.
+            collection_id (str): Идентификатор коллекции, в которой находится запись.
+        Returns:
+            Empty: Пустой ответ при успешном удалении.
+        """
         message = await self.items_wrapper.update(
             item_id=item_id,
             data=data,
@@ -625,6 +992,25 @@ class PerxisDataProvider:
         hidden: bool = False,
         templates: bool = False,
     ) -> items_pb2.FindResponse:
+        """Ищет записи в коллекции с возможностью фильтрации и сортировки.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для поиска.
+            filters (list[str] | None): Фильтры для поиска записей.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Максимальное количество возвращаемых записей.
+            offset (int | None): Смещение для пагинации.
+            page_num (int | None): Номер страницы для пагинации.
+            page_size (int | None): Размер страницы.
+            deleted (bool): Включить удаленные записи в результат.
+            regular (bool): Включить регулярные записи в результат.
+            hidden (bool): Включить скрытые записи в результат.
+            templates (bool): Включить шаблоны в результат.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными записями.
+        """
         message = await self.items_wrapper.find(
             collection_id=collection_id,
             space_id=self.space_id,
@@ -656,6 +1042,21 @@ class PerxisDataProvider:
         page_num: int | None = None,
         page_size: int | None = DEFAULT_PAGE_SIZE,
     ) -> items_pb2.FindResponse:
+        """Ищет опубликованные записи в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для поиска.
+            filters (list[str] | None): Фильтры для поиска опубликованных записей.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            limit (int | None): Максимальное количество возвращаемых записей.
+            offset (int | None): Смещение для пагинации.
+            page_num (int | None): Номер страницы для пагинации.
+            page_size (int | None): Размер страницы.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными опубликованными записями.
+        """
         message = await self.items_wrapper.find_published(
             collection_id=collection_id,
             space_id=self.space_id,
@@ -679,7 +1080,17 @@ class PerxisDataProvider:
         sort_by: list[str] | None = None,
         page_size: int | None = DEFAULT_PAGE_SIZE,
     ) -> items_pb2.FindResponse:
-        """Метод поиска всех опубликованных записей в коллекции."""
+        """Получает все опубликованные записи в коллекции постранично.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для поиска.
+            filters (list[str] | None): Фильтры для поиска записей.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            page_size (int | None): Размер страницы.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными опубликованными записями.
+        """
         kwargs = {
             "collection_id": collection_id,
             "filters": filters,
@@ -703,6 +1114,14 @@ class PerxisDataProvider:
             yield await self.find_published(**kwargs)
 
     async def unpublish(self, item_id: str, collection_id: str) -> Empty:
+        """Снимает запись с публикации.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+        Returns:
+            Empty: Пустой ответ при успешном удалении.
+        """
         message = await self.items_wrapper.unpublish(
             item_id=item_id,
             collection_id=collection_id,
@@ -712,6 +1131,14 @@ class PerxisDataProvider:
         return message
 
     async def publish(self, item_id: str, collection_id: str) -> Empty:
+        """Публикует запись в коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+        Returns:
+            Empty: Пустой ответ при успешном удалении.
+        """
         message = await self.items_wrapper.publish(
             item_id=item_id,
             collection_id=collection_id,
@@ -727,6 +1154,16 @@ class PerxisDataProvider:
         sort_by: list[str] | str = None,
         page_size: int | None = DEFAULT_PAGE_SIZE,
     ) -> items_pb2.FindResponse:
+        """Получает все записи из коллекции постранично.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции для поиска.
+            filters (list[str] | None): Фильтры для поиска записей.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            page_size (int | None): Размер страницы.
+        Returns:
+            items_pb2.FindResponse: Ответ с найденными записями.
+        """
         message = await self.items_wrapper.fetch_all(
             collection_id=collection_id,
             space_id=self.space_id,
@@ -740,6 +1177,13 @@ class PerxisDataProvider:
     async def get_references(
         self, references: list[Reference]
     ) -> items_pb2.GetResponse:
+        """Получает данные по ссылкам.
+
+        Arguments:
+            references (list[Reference]): Список объектов Reference для получения данных.
+        Returns:
+            items_pb2.GetResponse: Ответ с данными о записях.
+        """
         message = await self.references_wrapper.get_references(
             references=references, space_id=self.space_id, env_id=self.env_id
         )
@@ -755,6 +1199,19 @@ class PerxisDataProvider:
         erase: bool = True,
         **kwargs,
     ) -> Empty:
+        """Удаляет запись из коллекции.
+
+        Arguments:
+            item_id (str): Идентификатор записи для удаления.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            update_attrs (bool): Обновить системные поля `created_by`, `created_at`,
+                                        `created_rev_at`, `updated_by`, `updated_at`.
+            erase (bool): Полностью удалить запись.
+        Returns:
+            Empty: Пустой ответ при успешном удалении.
+        """
         message = await self.items_wrapper.delete(
             item_id=item_id,
             collection_id=collection_id,
@@ -775,6 +1232,18 @@ class PerxisDataProvider:
         update_attrs: bool = False,
         **kwargs,
     ) -> Empty:
+        """Восстанавливает ранее удаленную запись.
+
+        Arguments:
+            item_id (str): Идентификатор записи для восстановления.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            update_attrs (bool): Обновить системные поля `created_by`, `created_at`,
+                                        `created_rev_at`, `updated_by`, `updated_at`.
+        Returns:
+            Empty: Пустой ответ при успешном восстановлении.
+        """
         message = await self.items_wrapper.undelete(
             item_id=item_id,
             collection_id=collection_id,
@@ -793,6 +1262,18 @@ class PerxisDataProvider:
         env_id: str,
         locale_id: str | None = None,
     ) -> items_pb2.GetPublishedResponse:
+        """Получает опубликованные записи.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            locale_id (str | None): Идентификатор языка перевода который будет использоваться.
+                                Если не указан, то возвращаются данные для языка по умолчанию.
+        Returns:
+            items_pb2.GetPublishedResponse: Ответ с опубликованными данными.
+        """
         message = await self.items_wrapper.get_published(
             item_id=item_id,
             collection_id=collection_id,
@@ -810,6 +1291,17 @@ class PerxisDataProvider:
         aggregate_options: dict[str, str] | None = None,
         filters: list[str] | None = None,
     ) -> items_pb2.AggregateResponse:
+        """Выполняет агрегацию данных в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            aggregate_options (dict[str, str] | None): Опции агрегации.
+            filters (list[str] | None): Фильтры для агрегации.
+        Returns:
+            items_pb2.AggregateResponse: Ответ с результатами агрегации.
+        """
         message = await self.items_wrapper.aggregate(
             collection_id=collection_id,
             space_id=space_id,
@@ -827,6 +1319,17 @@ class PerxisDataProvider:
         aggregate_options: dict[str, str] | None = None,
         filters: list[str] | None = None,
     ) -> items_pb2.AggregatePublishedResponse:
+        """Выполняет агрегацию опубликованных данных в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            aggregate_options (dict[str, str] | None): Опции агрегации.
+            filters (list[str] | None): Фильтры для агрегации.
+        Returns:
+            items_pb2.AggregatePublishedResponse: Ответ с результатами агрегации опубликованных данных.
+        """
         message = await self.items_wrapper.aggregate_published(
             collection_id=collection_id,
             space_id=space_id,
@@ -844,6 +1347,17 @@ class PerxisDataProvider:
         space_id: str,
         env_id: str,
     ) -> items_pb2.GetRevisionResponse:
+        """Получает ревизию записи.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            revision_id (str): Идентификатор ревизии.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            items_pb2.GetRevisionResponse: Ответ с данными ревизии.
+        """
         message = await self.items_wrapper.get_revision(
             item_id=item_id,
             revision_id=revision_id,
@@ -865,6 +1379,21 @@ class PerxisDataProvider:
         limit: int | None = None,
         offset: int | None = None,
     ) -> items_pb2.ListRevisionsResponse:
+        """Получает список ревизий записи.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            sort_by (list[str] | None): Поля для сортировки.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Максимальное количество возвращаемых ревизий.
+            offset (int | None): Смещение для пагинации.
+        Returns:
+            items_pb2.ListRevisionsResponse: Ответ с данными ревизий.
+        """
         message = await self.items_wrapper.list_revisions(
             item_id=item_id,
             collection_id=collection_id,
@@ -885,6 +1414,16 @@ class PerxisDataProvider:
         space_id: str,
         env_id: str,
     ) -> Empty:
+        """Архивирует запись.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешной архивации.
+        """
         message = await self.items_wrapper.archive(
             item_id=item_id,
             collection_id=collection_id,
@@ -900,6 +1439,16 @@ class PerxisDataProvider:
         space_id: str,
         env_id: str,
     ) -> Empty:
+        """Восстанавливает запись из архива.
+
+        Arguments:
+            item_id (str): Идентификатор записи.
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+        Returns:
+            Empty: Пустой ответ при успешном восстановлении.
+        """
         message = await self.items_wrapper.archive(
             item_id=item_id,
             collection_id=collection_id,
@@ -920,6 +1469,22 @@ class PerxisDataProvider:
         limit: int | None = None,
         offset: int | None = None,
     ) -> items_pb2.FindArchivedResponse:
+        """Ищет архивированные записи в коллекции.
+
+        Arguments:
+            collection_id (str): Идентификатор коллекции.
+            space_id (str): Идентификатор пространства.
+            env_id (str): Идентификатор окружения.
+            filters (list[str] | None): Фильтры для поиска архивированных записей.
+            sort_by (list[str] | None): Поля для сортировки результатов.
+            fields (list[str] | None): Поля, которые необходимо вернуть.
+            exclude_fields (bool): Исключить указанные поля из результата.
+            limit (int | None): Максимальное количество возвращаемых архивированных записей.
+            offset (int | None): Смещение для пагинации.
+
+        Returns:
+            items_pb2.FindArchivedResponse: Ответ с найденными архивированными записями.
+        """
         message = await self.items_wrapper.find_archived(
             collection_id=collection_id,
             space_id=space_id,
@@ -935,9 +1500,19 @@ class PerxisDataProvider:
 
 
 class PerxisFileProvider:
+    """Провайдер файлов для работы с Perxis API.
+
+    Позволяет загружать файлы и управлять ими.
+    """
+
     __files_wrapper: PerxisFilesWrapper
 
     def __init__(self, channel: GrpcChannel) -> None:
+        """Инициализация провайдера файлов.
+
+        Arguments:
+            channel (GrpcChannel): gRPC-канал для взаимодействия с API.
+        """
         self.__files_wrapper = PerxisFilesWrapper(
             stub=files_pb2_grpc.FilesStub(channel.channel)
         )
@@ -945,6 +1520,14 @@ class PerxisFileProvider:
     async def start_upload(
         self, file_name: str, file_size: int
     ) -> files_pb2.StartUploadResponse:
+        """Инициализация загрузки файла.
+
+        Arguments:
+            file_name (str): Имя загружаемого файла.
+            file_size (int): Размер файла в байтах.
+        Returns:
+            files_pb2.StartUploadResponse: Ответ с параметрами загрузки.
+        """
         message = await self.__files_wrapper.start_upload(
             file_name=file_name, file_size=file_size
         )
@@ -957,6 +1540,16 @@ class PerxisFileProvider:
         parts: list[str],
         part_size: int = DEFAULT_PART_SIZE,
     ) -> files_pb2.CompleteUploadResponse:
+        """Завершение загрузки файла.
+
+        Arguments:
+            file_id (str): Идентификатор файла.
+            upload_id (str): Идентификатор загрузки.
+            parts (list[str]): Список частей загруженного файла.
+            part_size (int, optional): Размер одной части. По умолчанию `DEFAULT_PART_SIZE`.
+        Returns:
+            files_pb2.CompleteUploadResponse: Ответ с информацией о завершённой загрузке.
+        """
         message = await self.__files_wrapper.complete_upload(
             file_id=file_id, upload_id=upload_id, parts=parts, part_size=part_size
         )
-- 
GitLab


From e89f286334cb91ea27c21f66f63e8910548edd7e Mon Sep 17 00:00:00 2001
From: teplyakov <teolyakov@perx.ru>
Date: Tue, 15 Apr 2025 13:00:51 +0300
Subject: [PATCH 2/3] feat: AUTO-4047 Update description

---
 perxis/provider.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/perxis/provider.py b/perxis/provider.py
index 91f0b18..4114557 100644
--- a/perxis/provider.py
+++ b/perxis/provider.py
@@ -9,6 +9,10 @@
 - `PerxisDataProvider` сервис, предоставляющий методы для работы с элементами и
                        ссылками в конкретном окружении Perxis.
 - `PerxisFileProvider` сервис, предоставляющий методы для загрузки файлов.
+
+Принципиальная разница:
+- `Wrapper` может работать с любым пространством.
+- `Provider` работает только с конкретным.
 """
 
 from google.protobuf.struct_pb2 import Struct
-- 
GitLab


From 046fa649c6e6f5ede268f3221992eacf3ad74fc3 Mon Sep 17 00:00:00 2001
From: Eterevskiy Georgiy <eterevskiy@perx.ru>
Date: Tue, 15 Apr 2025 15:35:38 +0000
Subject: [PATCH 3/3] Apply 1 suggestion(s) to 1 file(s)

---
 perxis/provider.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/perxis/provider.py b/perxis/provider.py
index 4114557..89ef792 100644
--- a/perxis/provider.py
+++ b/perxis/provider.py
@@ -6,7 +6,7 @@
 - `PerxisFilesWrapper` низкоуровневый сервис для работы с файлами в Perxis.
 - `PerxisReferencesWrapper` низкоуровневый сервис для работы со ссылками в Perxis.
 - `PerxisItemsWrapper` низкоуровневый сервис для работы с элементами в Perxis.
-- `PerxisDataProvider` сервис, предоставляющий методы для работы с элементами и
+- `PerxisDataProvider` сервис, предоставляющий методы для работы и с элементами, и
                        ссылками в конкретном окружении Perxis.
 - `PerxisFileProvider` сервис, предоставляющий методы для загрузки файлов.
 
-- 
GitLab