From dc6f35482f739256cc76a8d35bdd4ff663903fb7 Mon Sep 17 00:00:00 2001
From: teplyakov <teolyakov@perx.ru>
Date: Wed, 2 Apr 2025 13:04:39 +0300
Subject: [PATCH] feat: AUTO-4048 Add docstrings

---
 perxis/channel.py | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/perxis/channel.py b/perxis/channel.py
index 329b78a..3a7a144 100644
--- a/perxis/channel.py
+++ b/perxis/channel.py
@@ -1,9 +1,26 @@
+"""
+Этот модуль предоставляет класс для создания защищенного gRPC-соединения.
+
+### Основные компоненты:
+- [`GrpcChannel`](#GrpcChannel) — создание и управление защищенным gRPC-соединением.
+- [`get_grpc_channel`](#get_grpc_channel) — фабричная функция для создания экземпляра [`GrpcChannel`](#GrpcChannel).
+"""
+
 import grpc
 
 from perxis.auth import APIKeyPlugin
 
 
 class GrpcChannel:
+    """Класс для создания защищенного gRPC-соединения.
+
+    Attributes:
+        call_credentials (grpc.CallCredentials): gRPC-учетные данные для вызова.
+        channel_credentials (grpc.ChannelCredentials): gRPC-учетные данные канала.
+        composite_credentials (grpc.ChannelCredentials): Комбинированные учетные данные.
+        channel (grpc.Channel | None): Активный gRPC-канал или None, если соединение не установлено.
+    """
+
     call_credentials: grpc.CallCredentials
     channel_credentials: grpc.ChannelCredentials
     composite_credentials: grpc.ChannelCredentials
@@ -17,6 +34,15 @@ class GrpcChannel:
         project_version: str,
         call_credentials_name: str = "api-key",
     ) -> None:
+        """Создает новый экземпляр и устанавливает соединение.
+
+        Arguments:
+            target (str): Адрес gRPC-сервера.
+            metadata_plugin (grpc.AuthMetadataPlugin): Плагин аутентификации.
+            project_name (str): Название проекта.
+            project_version (str): Версия проекта.
+            call_credentials_name (str): Название плагина (по умолчанию "api-key").
+        """
         self.target = target
         self.metadata_plugin = metadata_plugin
         self.call_credentials_name = call_credentials_name
@@ -24,6 +50,7 @@ class GrpcChannel:
         self.connect(project_name, project_version)
 
     def _init_credentials(self) -> None:
+        """Инициализирует учетные данные для gRPC-соединения."""
         self.call_credentials = grpc.metadata_call_credentials(
             self.metadata_plugin, name=self.call_credentials_name
         )
@@ -33,6 +60,12 @@ class GrpcChannel:
         )
 
     def connect(self, project_name: str, project_version: str) -> None:
+        """Устанавливает защищенное соединение с gRPC-сервером.
+
+        Arguments:
+            project_name (str): Название проекта.
+            project_version (str): Версия проекта.
+        """
         if not self.channel:
             self.channel = grpc.aio.secure_channel(
                 self.target,
@@ -43,12 +76,23 @@ class GrpcChannel:
             )
 
     async def close(self) -> None:
+        """Закрывает активное gRPC-соединение."""
         await self.channel.close()
 
 
 def get_grpc_channel(
     target: str, api_key: str, project_name: str, project_version: str
 ) -> GrpcChannel:
+    """Создает и возвращает новый экземпляр [`GrpcChannel`](#GrpcChannel).
+
+    Arguments:
+        target (str): Адрес gRPC-сервера.
+        api_key (str): API-ключ для аутентификации.
+        project_name (str): Название проекта.
+        project_version (str): Версия проекта.
+    Returns:
+        GrpcChannel: Новый экземпляр [`GrpcChannel`](#GrpcChannel).
+    """
     return GrpcChannel(
         target=target,
         metadata_plugin=APIKeyPlugin(token=api_key),
-- 
GitLab