Merge branch 'feature/AUTO-4047' into 'master'

feat: AUTO-4047 Add docstrings

See merge request !93

README.md

@@ -62,8 +62,8 @@ def metadata_call_credentials(metadata_plugin, name=None):
 
 Объект CallCredentials можно передать непосредственно в RPC, например:
 ```python
-call_credentials = grpc.metadata_call_credentials(my_foo_plugin)
-stub.FooRpc(request, credentials=call_credentials)
+>>> call_credentials = grpc.metadata_call_credentials(my_foo_plugin)
+>>> stub.FooRpc(request, credentials=call_credentials)
 ```
 
 ### Пример авторизации и аутентификации OAuth2
@@ -89,11 +89,22 @@ class ExtendedClient(Client):
     def prepare_request_body(self, body='', scope=None, include_client_id=False, **kwargs):
         kwargs['client_id'] = self.client_id
         kwargs['include_client_id'] = include_client_id
-        return prepare_token_request(self.grant_type, body=body, username=self.username,
-                                     password=self.password, scope=scope, **kwargs)
+        return prepare_token_request(
+            self.grant_type, 
+            body=body, 
+            username=self.username,              
+            password=self.password, 
+            scope=scope, 
+            **kwargs
+        )
 
 oauth2_plugin = OAuth2Plugin(
-    client=ExtendedClient(client_id='client_id', grant_type='password', username='user', password='pass'), 
+    client=ExtendedClient(
+        client_id='client_id', 
+        grant_type='password', 
+        username='user', 
+        password='pass'
+    ), 
     client_secret='client_secret', 
     token_url='https://example.com/oauth/token', 
     audience='audience'

perxis/auth.py

-import time
+"""
+Модуль для аутентификации в gRPC с использованием OAuth2 и API-ключей.
 
-import grpc
+Этот модуль предоставляет два класса для аутентификации:
+
+- [`OAuth2Plugin`](#OAuth2Plugin): Аутентификация с помощью OAuth2.
+- [`APIKeyPlugin`](#APIKeyPlugin): Аутентификация с использованием API-ключа.
+
+Данный код можно использовать для настройки gRPC-клиента с нужным типом аутентификации.
 
+## Пример использования:
+.. include:: ../README.md
+   :start-line: 22
+   :end-line: 108
+---
+"""
+
+import time
+import grpc
 from oauthlib.oauth2 import Client, OAuth2Token
 from requests_oauthlib import OAuth2Session
 
 
 class OAuth2Plugin(grpc.AuthMetadataPlugin):
+    """Спецификация аутентификации для gRPC с использованием OAuth2.
+
+    Этот класс управляет получением и обновлением токена OAuth2 для аутентификации
+    gRPC-запросов.
+
+    Attributes:
+        _token (str | None): Токен. По умолчанию None.
+        oauth2 (OAuth2Session): Сессия OAuth2 для управления токенами.
+    Args:
+        client (Client): OAuth2 клиент.
+        client_secret (str): Секрет клиента.
+        token_url (str): URL для получения токена.
+        audience (str): Получатель (аудитория) токена, указывающая, для какого
+                        сервиса он предназначен.
+        signature_header_key (str, optional): Заголовок для подписи запроса.
+                                              По умолчанию "authorization".
+        token_type (str, optional): Тип токена. По умолчанию "Bearer".
+    """
+
     _token = None
 
     def __init__(
@@ -18,12 +52,25 @@ class OAuth2Plugin(grpc.AuthMetadataPlugin):
         signature_header_key: str = "authorization",
         token_type: str = "Bearer",
     ) -> None:
+        """Инициализирует объект аутентификации OAuth2 для gRPC.
+
+        Этот метод устанавливает основные параметры OAuth2-клиента, необходимые
+        для получения и обновления токена.
+
+        Args:
+            client (Client): OAuth2 клиент для аутентификации.
+            client_secret (str): Секретный ключ клиента.
+            token_url (str): URL-адрес сервера авторизации для получения токена.
+            audience (str): Аудитория токена, указывающая целевой сервис.
+            signature_header_key (str, optional): Заголовок, в который будет добавляться токен.
+                                                  По умолчанию "authorization".
+            token_type (str, optional): Тип токена. По умолчанию "Bearer".
+        """
         self._client_secret = client_secret
         self._token_url = token_url
         self._audience = audience
         self._signature_header_key = signature_header_key
         self._token_type = token_type
-
         self.oauth2 = OAuth2Session(client=client)
 
     def __call__(
@@ -31,6 +78,12 @@ class OAuth2Plugin(grpc.AuthMetadataPlugin):
         context: grpc.AuthMetadataContext,
         callback: grpc.AuthMetadataPluginCallback,
     ) -> None:
+        """Добавляет токен в метаданные gRPC-запроса.
+
+        Args:
+            context (grpc.AuthMetadataContext): Контекст аутентификации gRPC.
+            callback (grpc.AuthMetadataPluginCallback): Callback для передачи метаданных.
+        """
         callback(
             metadata=(
                 (
@@ -43,6 +96,12 @@ class OAuth2Plugin(grpc.AuthMetadataPlugin):
 
     @property
     def token(self) -> OAuth2Token:
+        """Получает текущий OAuth2-токен, обновляя его при необходимости.
+
+        Returns:
+            OAuth2Token: Актуальный токен.
+        """
+
         def fetch_token() -> OAuth2Token:
             return self.oauth2.fetch_token(
                 token_url=self._token_url,
@@ -65,11 +124,26 @@ class OAuth2Plugin(grpc.AuthMetadataPlugin):
                 self._token = refresh_token()
             else:
                 self._token = fetch_token()
-
         return self._token
 
 
 class APIKeyPlugin(grpc.AuthMetadataPlugin):
+    """Спецификация аутентификации для gRPC с использованием API-ключа.
+
+    Этот класс добавляет API-ключ в заголовок запроса для аутентификации
+    gRPC-запросов.
+
+    Attributes:
+        _token (str): API-ключ.
+        _signature_header_key (str): Заголовок, в который вставляется ключ.
+        _token_type (str): Тип токена (например, "API-Key").
+    Args:
+        token (str): API-ключ.
+        signature_header_key (str, optional): Заголовок для подписи запроса.
+                                              По умолчанию "authorization".
+        token_type (str, optional): Тип токена. По умолчанию "API-Key".
+    """
+
     _token = None
 
     def __init__(
@@ -78,6 +152,14 @@ class APIKeyPlugin(grpc.AuthMetadataPlugin):
         signature_header_key: str = "authorization",
         token_type: str = "API-Key",
     ) -> None:
+        """Инициализирует объект аутентификации API-ключа для gRPC.
+
+        Args:
+            token (str): API-ключ, используемый для аутентификации.
+            signature_header_key (str, optional): Заголовок, в который будет добавляться API-ключ.
+                                                  По умолчанию "authorization".
+            token_type (str, optional): Тип токена. По умолчанию "API-Key".
+        """
         self._token = token
         self._signature_header_key = signature_header_key
         self._token_type = token_type
@@ -87,6 +169,12 @@ class APIKeyPlugin(grpc.AuthMetadataPlugin):
         context: grpc.AuthMetadataContext,
         callback: grpc.AuthMetadataPluginCallback,
     ) -> None:
+        """Добавляет API-ключ в метаданные gRPC-запроса.
+
+        Args:
+            context (grpc.AuthMetadataContext): Контекст аутентификации gRPC.
+            callback (grpc.AuthMetadataPluginCallback): Callback для передачи метаданных.
+        """
         callback(
             metadata=(
                 (self._signature_header_key, f"{self._token_type} {self._token}"),