soap-client 0.1.0__tar.gz

soap_client-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: soap-client
+Version: 0.1.0
+Summary: SOAP client for working with services using SOAP and WSDL.
+Author: Freontt
+Author-email: Freontt <freontt.public@gmail.com>
+License-Expression: MIT
+Requires-Dist: aiolimiter>=1.3.0
+Requires-Dist: lxml>=6.1.3
+Requires-Dist: pydantic>=2.14.2
+Requires-Dist: pydantic-settings>=2.16.2
+Requires-Dist: zeep[async]>=4.3.3
+Requires-Python: >=3.11
+Project-URL: Homepage, https://freontt.github.io/soap-client/
+Project-URL: Repository, https://github.com/Freontt/soap-client
+Project-URL: Issues, https://github.com/Freontt/soap-client/issues
+Description-Content-Type: text/markdown
+
+# SOAP-клиент для общения с сервисами по WSDL контракту
+
+Данная библиотека предоставляет удобную обёртку для использования SOAP-клиента из библиотеки zeep. Оболочка предназначена в первую очередь для асинхронных приложений.
+
+Библиотека состоит из следующих компонентов:
+- [exceptions.py](src/soap_client/exceptions.py): Исключения библиотеки.
+- [manager.py](src/soap_client/manager.py): Manager для управления клиентом.
+- [registry.py](src/soap_client/registry.py): Класс-реестр всех SOAP-клиентов.
+- [settings.py](src/soap_client/settings.py): Настройки для управления клиентом.
+

soap_client-0.1.0/README.md

@@ -0,0 +1,10 @@
+# SOAP-клиент для общения с сервисами по WSDL контракту
+
+Данная библиотека предоставляет удобную обёртку для использования SOAP-клиента из библиотеки zeep. Оболочка предназначена в первую очередь для асинхронных приложений.
+
+Библиотека состоит из следующих компонентов:
+- [exceptions.py](src/soap_client/exceptions.py): Исключения библиотеки.
+- [manager.py](src/soap_client/manager.py): Manager для управления клиентом.
+- [registry.py](src/soap_client/registry.py): Класс-реестр всех SOAP-клиентов.
+- [settings.py](src/soap_client/settings.py): Настройки для управления клиентом.
+

soap_client-0.1.0/pyproject.toml

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "soap-client"
+version = "0.1.0"
+description = "SOAP client for working with services using SOAP and WSDL."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "aiolimiter>=1.3.0",
+    "lxml>=6.1.3",
+    "pydantic>=2.14.2",
+    "pydantic-settings>=2.16.2",
+    "zeep[async]>=4.3.3",
+]
+
+[[project.authors]]
+name = "Freontt"
+email = "freontt.public@gmail.com"
+
+[project.urls]
+Homepage = "https://freontt.github.io/soap-client/"
+Repository = "https://github.com/Freontt/soap-client"
+Issues = "https://github.com/Freontt/soap-client/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "pytest-cov>=7.1.0",
+    "pytest-httpserver>=1.2.0",
+    "pytest-mock>=3.17.0",
+]
+docs = [
+    "mike>=2.2.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.8.0",
+    "mkdocstrings[python]>=1.0.8",
+]
+lint = [
+    "lxml-stubs>=0.5.1",
+    "mypy>=2.4.1",
+    "ruff>=0.17.3",
+]
+
+[[dependency-groups.dev]]
+include-group = "test"
+
+[[dependency-groups.dev]]
+include-group = "docs"
+
+[[dependency-groups.dev]]
+include-group = "lint"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+exclude = ["tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "W",
+    "F",
+    "I",
+    "B",
+    "S",
+    "PERF",
+    "RUF",
+    "UP",
+    "D",
+    "ANN",
+    "ASYNC",
+    "T20",
+    "PTH",
+    "RET",
+    "SIM",
+    "ARG",
+    "LOG",
+    "G",
+    "TC",
+    "N",
+    "C4",
+    "RSE",
+    "ISC",
+    "ICN",
+    "TRY",
+    "FURB",
+    "PL",
+    "PT",
+    "A",
+]
+ignore = [
+    "RUF002",
+    "RUF003",
+    "D105",
+    "TRY003",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src"]
+strict = true
+show_error_codes = true
+pretty = true
+exclude = [
+    "build/",
+    "dist/",
+]
+disable_error_code = ["no-untyped-call"]
+enable_error_code = [
+    "redundant-expr",
+    "truthy-bool",
+    "truthy-iterable",
+    "ignore-without-code",
+    "possibly-undefined",
+    "unused-awaitable",
+    "redundant-self",
+    "explicit-override",
+    "mutable-override",
+]
+
+[tool.pytest]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+markers = ["performance: speed metering"]

soap_client-0.1.0/pyproject.toml.orig

@@ -0,0 +1,132 @@
+[build-system]
+requires = ["uv_build>=0.13.6,<0.14.0"]
+build-backend = "uv_build"
+
+
+[project]
+name = "soap-client"
+version = "0.1.0"
+description = "SOAP client for working with services using SOAP and WSDL."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Freontt", email = "freontt.public@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "aiolimiter>=1.3.0",
+    "lxml>=6.1.3",
+    "pydantic>=2.14.2",
+    "pydantic-settings>=2.16.2",
+    "zeep[async]>=4.3.3",
+]
+
+
+[project.urls]
+Homepage = "https://freontt.github.io/soap-client/"
+Repository = "https://github.com/Freontt/soap-client"
+Issues = "https://github.com/Freontt/soap-client/issues"
+
+
+[dependency-groups]
+test = [
+    "pytest>=9.2.0",
+    "pytest-asyncio>=1.4.1.post1",
+    "pytest-cov>=7.1.0",
+    "pytest-httpserver>=1.2.0",
+    "pytest-mock>=3.17.0",
+]
+
+docs = [
+    "mike>=2.2.0",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.8.0",
+    "mkdocstrings[python]>=1.0.8",
+]
+
+lint = [
+    "lxml-stubs>=0.5.1",
+    "mypy>=2.4.1",
+    "ruff>=0.17.3",
+]
+
+dev = [
+    { include-group = "test" },
+    { include-group = "docs" },
+    { include-group = "lint" },
+]
+
+
+[tool.ruff]
+# Set the maximum line length to 100.
+target-version = "py313"
+line-length = 100
+exclude = ["tests"]
+
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "B",     # flake8-bugbear
+    "S",     # flake8-bandit
+    "PERF",  # perflint
+    "RUF",   # ruff-specific
+    "UP",    # pyupgrade
+    "D",     # pydocstyle
+    "ANN",   # flake8-annotations
+    "ASYNC", # flake8-async
+    "T20",   # flake8-print
+    "PTH",   # flake8-use-pathlib
+    "RET",   # flake8-return
+    "SIM",   # flake8-simplify
+    "ARG",   # flake8-unused-arguments
+    "LOG",   # flake8-logging
+    "G",     # flake8-logging-format
+    "TC",    # flake8-type-checking
+    "N",     # Naming
+    "C4",    # flake8-comprehensions
+    "RSE",   # flake8-raise
+    "ISC",   # flake8-implicit-str-concat
+    "ICN",   # flake8-import-conventions
+    "TRY",   # Correct exception's handling
+    "FURB",  # Idioms
+    "PL",
+    "PT",
+    "A",
+]
+ignore = ["RUF002", "RUF003", "D105", "TRY003"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+
+[tool.mypy]
+python_version = "3.13"
+files = ["src"]
+strict = true
+show_error_codes = true
+pretty = true
+exclude = ["build/", "dist/"]
+disable_error_code = ["no-untyped-call"]
+enable_error_code = [
+    "redundant-expr",       # meaningless expressions (x or x)
+    "truthy-bool",          # objects with __bool__ always True
+    "truthy-iterable",      # literals, always truthy
+    "ignore-without-code",  # # type: ignore without the code
+    "possibly-undefined",   # the variable may not be defined
+    "unused-awaitable",     # forgotten await
+    "redundant-self",       # superfluous Self in arguments
+    "explicit-override",    # require @override
+    "mutable-override",     # redefinition with mutable type
+]
+
+
+[tool.pytest]
+asyncio_default_fixture_loop_scope = "function"
+asyncio_default_test_loop_scope = "function"
+markers = [
+    "performance: speed metering",
+]

soap_client-0.1.0/src/soap_client/__init__.py

@@ -0,0 +1,14 @@
+"""SOAP client library."""
+
+import logging
+
+from soap_client.exceptions import SoapError
+from soap_client.manager import SoapClientManager
+from soap_client.registry import SoapRegistry
+from soap_client.settings import BaseSoapClientSettings
+
+__all__ = ["BaseSoapClientSettings", "SoapClientManager", "SoapError", "SoapRegistry"]
+__version__ = "0.1.0"
+
+
+logging.getLogger("soap_client").addHandler(logging.NullHandler())

soap_client-0.1.0/src/soap_client/exceptions.py

@@ -0,0 +1,24 @@
+"""Файл хранит классы-исключения."""
+
+from typing import Any
+
+
+class SoapError(ConnectionError):
+    """Ошибка при обращении к SOAP-методу.
+
+    Используется в исключениях связанных с ``SoapClientManager``.
+    """
+
+    def __init__(self, action: str, detail: str, params: dict[Any, Any] | None = None) -> None:
+        """Инициализатор класса ``SoapError``.
+
+        Args:
+            action (``str``): Действие, которое было вызвано клиентом.
+            detail (``str``): Дополнительные подробности об операции.
+            params (``dict | None``, ``optional``): Дополнительные параметры,
+                указанные для action. Defaults to None.
+        """
+        super().__init__(f"SOAP-метод {action!r} завершился ошибкой: {detail}")
+        self.action = action
+        self.detail = detail
+        self.params = params

soap_client-0.1.0/src/soap_client/manager.py

@@ -0,0 +1,127 @@
+"""File contains implementation of the SoapClientManager."""
+
+import logging
+from asyncio import Semaphore
+from typing import Any, cast
+
+from aiolimiter import AsyncLimiter
+from zeep import AsyncClient
+from zeep.exceptions import Error
+from zeep.transports import AsyncTransport
+
+from soap_client.exceptions import SoapError
+from soap_client.settings import BaseSoapClientSettings
+
+logger = logging.getLogger(__name__)
+
+
+class SoapClientManager:
+    """Класс-обёртка над клиентом zeep для работы с 1с.
+
+    Attributes:
+        config (``SoapClientConfig``): Конфигурация SOAP-клиента.
+        timeout (``int``): Максимальное время ожидания ответа.
+        client (``zeep.AsyncClient | None``): SOAP-клиент.
+    """
+
+    def __init__(self, settings: BaseSoapClientSettings, *, timeout: int = 120) -> None:
+        """Инициализатор класса ``SoapClientManager``.
+
+        Args:
+            settings (``SoapClientConfig``): Конфигурация SOAP-клиента.
+            timeout (``int``, ``optional``): Максимальное время ожидания. Defaults to 120.
+        """
+        self.settings = settings
+        self.timeout = timeout
+        self.client: AsyncClient | None = None
+        self.__semaphore = Semaphore(settings.max_concurrent)
+        self.__limiter = AsyncLimiter(settings.rate_limit, 1)
+        logger.debug("Manager created for wsdl=%r", settings.wsdl)
+
+    def init(self) -> None:
+        """Создаёт zeep-клиент и настраивает подключение.
+
+        Note:
+            Необходимо единоразово вызвать (к примеру: в ``lifespan`` FastAPI).
+        """
+        logger.debug("Initializing client for wsdl=%r", self.settings.wsdl)
+        if self.is_initialized:
+            logger.warning("Trying to init client when that inited already.")
+            return
+        try:
+            transport = AsyncTransport(
+                timeout=self.timeout,
+                operation_timeout=self.timeout,
+            )
+            if self.settings.login and self.settings.password:
+                transport.wsdl_client.auth = (self.settings.login, self.settings.password)
+                transport.client.auth = (self.settings.login, self.settings.password)
+            else:
+                logger.debug("No auth credentials provided; skipping Basic auth")
+            logger.debug("zeep AsyncTransport created")
+
+            wsdl = self.settings.wsdl
+            self.client = AsyncClient(wsdl=wsdl, transport=transport)
+            logger.info("zeep client created for wsdl=%r", self.settings.wsdl)
+        except Exception as e:
+            logger.debug("Incorrect init data", exc_info=True)
+            raise SoapError(action="<init>", detail=str(e)) from e
+
+    @property
+    def is_initialized(self) -> bool:
+        """Свойство - инициализирован ли SOAP-клиент из zeep.
+
+        Returns:
+            ``bool``: Если инициализирован - ``true``, иначе ``false``.
+        """
+        return self.client is not None
+
+    async def load(self, action: str, params: dict[str, Any] | None = None) -> object:
+        """Вызывает SOAP-метод по имени.
+
+        Args:
+            action (``str``): Имя метода, как объявлено в WSDL.
+            params (``dict[str, Any] | None``): Параметры, которые
+                необходимо отправить вместе с действием.
+
+        Returns:
+            ``object``: Результат, который вернул ``zeep`` клиент.
+
+        Raises:
+            ``RuntimeError``: Если клиент не инициализирован.
+            ``AttributeError``: Если требуемого динамического атрибута нет.
+            ``SoapError``: Если произошла ошибка при работе zeep клиента.
+
+        See Also:
+            - :class:`SoapError`: Класс ошибок SOAP-подключений.
+            - :class:`BaseSoapClientSettings`: Базовый класс настроек.
+        """
+        if self.client is None:
+            logger.error("Trying to load without inited client.")
+            raise RuntimeError("Client didn't init.")
+        logger.debug("load(%r) params=%r", action, params)
+        try:
+            method = getattr(self.client.service, action)
+        except AttributeError:
+            logger.exception("Unknown action %r", action)
+            raise
+        async with self.__limiter, self.__semaphore:
+            try:
+                result = await method(**(params or {}))
+            except Error as e:
+                logger.debug("load(%r) failed params=%r.", action, params, exc_info=True)
+                raise SoapError(action=action, detail=str(e)) from e
+            else:
+                logger.debug("load(%r) ok.", action)
+                return result
+
+    async def aclose(self) -> None:
+        """Функция для закрытия клиента."""
+        logger.debug("Closing client for wsdl=%r.", self.settings.wsdl)
+        if self.client is not None:
+            transport = cast("AsyncTransport", self.client.transport)
+            await transport.aclose()
+            self.client = None
+            logger.info("Client closed for wsdl=%r.", self.settings.wsdl)
+        else:
+            logger.warning("Trying to close client when that didn't init.")

soap_client-0.1.0/src/soap_client/registry.py

@@ -0,0 +1,84 @@
+"""File contains implementation of the SoapRegistry."""
+
+import logging
+from collections.abc import Mapping
+
+from soap_client.manager import SoapClientManager
+from soap_client.settings import BaseSoapClientSettings
+
+logger = logging.getLogger(__name__)
+
+
+class SoapRegistry:
+    """Класс для запуска, настройки, проверки и закрытия SOAP-клиентов.
+
+    See Also:
+    - :class:`SoapClientManager`: Менеджер SOAP-клиента.
+    - :class:`BaseSoapClientSettings`: Базовый класс настроек.
+    """
+
+    def __init__(self, settings: Mapping[str, BaseSoapClientSettings]) -> None:
+        """Инициализатор класса ``SoapRegistry``.
+
+        Args:
+            settings (``SoapClientSettings``): Настройки для клиентов.
+        """
+        self._settings = dict(settings)
+        self._clients: dict[str, SoapClientManager] = {}
+        logger.debug("Registry created for %d clients: %r", len(settings), list(settings))
+
+    def init_all(self) -> None:
+        """Инициализация всех клиентов.
+
+        Note:
+            Блокирует event loop на время загрузки WSDL. Вызывайте из lifespan.
+        """
+        logger.debug("Initializing all clients")
+        for name in self._settings:
+            self.get(name)
+        logger.info("All clients initialized")
+
+    def get(self, soap_client_name: str) -> SoapClientManager:
+        """Получить или создать SOAP-клиента.
+
+        Args:
+            soap_client_name (``str``): Имя SOAP-клиента.
+
+        Returns:
+            ``SoapClientManager``: Запрашиваемый менеджер SOAP-клиента.
+
+        Raises:
+            ``KeyError``: Возникает если передан незаданный тип клиента.
+            ``SoapError``: Если не удалось инициализировать клиента.
+
+        Note:
+            При создании выполняет синхронную загрузку WSDL и блокирует
+            event loop. Вызывайте из lifespan FastAPI или похожего по роли контекста.
+        """
+        if soap_client_name not in self._settings:
+            logger.error(
+                "Unknown client %r; available: %r",
+                soap_client_name,
+                list(self._settings),
+            )
+            raise KeyError(
+                f"Unknown soap client: {soap_client_name!r}. Available: {list(self._settings)!r}"
+            )
+        if soap_client_name not in self._clients:
+            logger.debug("Creating client %r", soap_client_name)
+            config = self._settings[soap_client_name]
+            client = SoapClientManager(config)
+            client.init()
+            self._clients[soap_client_name] = client
+        return self._clients[soap_client_name]
+
+    async def aclose_all(self) -> None:
+        """Закрыть все соединения."""
+        logger.debug("Closing %d clients", len(self._clients))
+        for name, client in self._clients.items():
+            try:
+                await client.aclose()
+            except Exception:
+                logger.exception("Failed to close client %r", name)
+        self._clients.clear()
+        logger.info("All clients closed")

soap_client-0.1.0/src/soap_client/settings.py

@@ -0,0 +1,57 @@
+"""File contains implementation of the BaseSoapClientSettings and helpful function."""
+
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseSoapClientSettings(BaseSettings):
+    """Базовые настройки SOAP-клиента для взаимодействия с 1с.
+
+    Attributes:
+        wsdl (``str``): WSDL - контракт интерфейса по взаимодействию с 1С.
+        login (``str``): Логин, по которому происходит вход.
+        password (``str``): Пароль, по которому происходит вход.
+        max_concurrent (``int``): Максимально число одновременных вызовов.
+        rate_limit (``int``): Максимальное число запросов в секунду.
+
+    Note:
+        - Используется для создания пользовательских типов конфигураций.
+        - Вызовите ``get_model_config`` для создания Pydantic настроек.
+        Без этого подкласс унаследует дефолтный конфиг Pydantic, и настройки
+        не будут читаться из ``.env``.
+    """
+
+    # Main settings of connection by wsdl
+    wsdl: str = Field(min_length=1)
+    login: str
+    password: str
+    # Settings of the connection load
+    max_concurrent: int = Field(gt=0)
+    rate_limit: int = Field(gt=0)
+
+
+def get_model_config(
+    env_prefix: str, env_file: str | Path = ".env", env_file_encoding: str = "UTF-8"
+) -> SettingsConfigDict:
+    """Вспомогательная функция для генерации model_config.
+
+    Args:
+        env_prefix (``str``): Префикс в ``.env`` файле,
+            который будет использован для настроек.
+        env_file (``str | Path``, ``optional``): Путь до ``.env`` файла. Defaults to ".env".
+        env_file_encoding (``str``, ``optional``):
+            Кодировка ``.env`` файла. Defaults to "UTF-8".
+
+    Returns:
+        SettingsConfigDict: model_config для настроек.
+    """
+    return SettingsConfigDict(
+        env_file=env_file,
+        env_file_encoding=env_file_encoding,
+        env_prefix=env_prefix,
+        extra="ignore",
+        frozen=True,
+        case_sensitive=False,
+    )