sotkalib 0.0.2__py3-none-any.whl

sotkalib/__init__.py

@@ -0,0 +1,5 @@
+"""
+
+Library with utils, made for s0tka.ru
+
+"""

sotkalib/config/__init__.py

@@ -0,0 +1,6 @@
+from .struct import AppSettings, SettingsField
+
+__all__ = [
+    "AppSettings",
+    "SettingsField",
+]

sotkalib/config/field.py

@@ -0,0 +1,27 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+
+type AllowedTypes = int | float | complex | str | bool | None
+
+
+@dataclass(init=True, slots=True, frozen=True)
+class SettingsField[T: AllowedTypes]:
+    """
+
+    Typed field declaration for AppSettings.
+
+    **Parameters:**
+
+    - `T`: Python type of the value (see AllowedTypes).
+
+    **Attributes:**
+
+    - `default`: Optional fallback value when the variable is missing.
+    - `factory`: A callable returning a value, or a name of a @property on the class that will be evaluated after initialization.
+    - `nullable`: Whether None is allowed when no value is provided and no default/factory is set.
+
+    """
+
+    default: T | None = None
+    factory: Callable[[], T] | str | None = None
+    nullable: bool = False

sotkalib/config/struct.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from os import PathLike, getenv
+from types import NoneType, UnionType
+from typing import TYPE_CHECKING, Any, get_args
+from warnings import warn
+
+from dotenv import load_dotenv
+
+from sotkalib.log import get_logger
+
+from .field import AllowedTypes, SettingsField
+
+if TYPE_CHECKING:
+    from logging import (
+        Logger as StdLogger,
+    )
+
+    from loguru import Logger as LoguruLogger
+
+    type _loggers = StdLogger | LoguruLogger
+
+
+@dataclass
+class AppSettings:
+    """
+
+    Base class for reading typed settings from environment variables.
+
+        Declare attributes with type annotations and assign SettingsField(...) to each.
+        On initialization, values are resolved from the environment (loading .env if provided),
+        then from default/factory, or set to None if nullable.
+
+        **Notes:**
+
+        Only immutable primitive types are allowed: int, float, complex, str, bool, None.
+
+        If explicit_format is True, attribute names must be UPPER_SNAKE_CASE.
+
+        **Example:**
+
+        >>> import secrets
+        >>> class MySettings(AppSettings):
+        ...     BOT_TOKEN: str = SettingsField(nullable=False)
+        ...     POSTGRES_USER: str = SettingsField(default="pg_user")
+        ...     POSTGRES_PASSWORD: str = SettingsField(nullable=False, factory=lambda: secrets.token_urlsafe(8))
+        ...     SECRET_ALIAS: str = SettingsField(factory="secret")
+        ...
+        ...     @property
+        ...     def secret(self) -> str:
+        ...         return "computed"
+
+
+        >>> settings = MySettings()
+
+    """
+
+    def __init__(
+        self,
+        dotenv_path: str | PathLike[str] | None = None,
+        logger: _loggers | None = None,
+        explicit_format: bool = True,
+        strict: bool = False,
+    ) -> None:
+        """
+
+        Initialize AppSettings and resolve annotated fields.
+
+        **Parameters:**
+
+        - `dotenv_path`: Optional path to a .env file. If None, python-dotenv searches recursively.
+        - `logger`: Optional log or loguru logger.
+        - `explicit_format`: If True, attribute names must be uppercase with underscores.
+        - `strict`: If True, any mutable types will raise an exception rather than being set to
+        None.
+
+        **Raises:**
+
+        - `AttributeError`: If an attribute name violates explicit_format constraint or a declared property is missing.
+        - `TypeError`: If an annotation uses a disallowed (mutable) type or a factory reference is not a property.
+        - `ValueError`: If a required field (nullable=False, no default/factory) is missing in the environment.
+
+        """
+
+        def _unwrap_type(tp: type) -> type:
+            if isinstance(tp, UnionType):
+                args = [a for a in get_args(tp) if a is not NoneType]
+                return args[0] if args else NoneType
+            return tp
+
+        def evaluate_var(_type: type, _var: str) -> Any:
+            _type = _unwrap_type(_type)
+            if _type is NoneType:
+                return None
+            if _type is bool:
+                return _var.lower() in ("yes", "true", "1", "y")
+            return _type(_var)
+
+        load_dotenv(dotenv_path=dotenv_path)
+
+        _log = get_logger("utilities.appsettings") if logger is None else logger
+        self.__log = _log
+
+        self.__strict = strict
+
+        cls_annotations = self.__class__.__annotations__
+        cls_dict = self.__class__.__dict__
+
+        settings_fields: dict[str, SettingsField] = {
+            attr: val for attr, val in cls_dict.items() if isinstance(val, SettingsField)
+        }
+
+        self.__deferred = []
+
+        for attr, settings_field in settings_fields.items():
+            if explicit_format and not re.fullmatch(r"[A-Z][A-Z0-9_]*", attr):
+                raise AttributeError("AppSettings attributes should contain only capital letters and underscores")
+
+            annotated = cls_annotations.get(attr, NoneType)
+            string_value = getenv(attr, None)
+
+            if string_value is None:
+                self.__validate_empty_string_value(attr, settings_field)
+                continue
+
+            typed_value = evaluate_var(annotated, string_value)
+
+            setattr(self, attr, self.__validate(typed_value, strict=self.__strict))
+            _log.debug(f"evaluated {attr} from environment")
+
+        self.__post_init__()
+
+    def __validate_empty_string_value(self, attr: str, settings_field: SettingsField) -> None:
+        if settings_field.default is not None:
+            setattr(self, attr, self.__validate(settings_field.default, strict=self.__strict))
+            self.__log.debug(f"evaluated {attr} from default")
+            return
+
+        if settings_field.factory is not None and isinstance(settings_field.factory, str):
+            self.__deferred.append((attr, settings_field.factory))
+            self.__log.debug(f"defer {attr} init as factory is a str; => property")
+            return
+
+        if callable(settings_field.factory):
+            setattr(self, attr, self.__validate(settings_field.factory(), strict=self.__strict))
+            self.__log.debug(f"evaluated {attr} from factory")
+            return
+
+        if settings_field.nullable:
+            setattr(self, attr, None)
+            self.__log.debug(f"evaluated {attr} as None (nullable)")
+            return
+
+        raise ValueError(f"reqd field {attr} was not found in .env")
+
+    def __post_init__(self) -> None:
+        for attr, factory in self.__deferred:
+            if factory not in self.__class__.__dict__:
+                raise AttributeError(f"property {factory} was not found in {self.__class__.__name__}")
+            if not isinstance(getattr(self.__class__, factory), property):
+                raise TypeError(f"method {factory} is not a property")
+            self.__log.debug(f"evaluated {attr} from property {factory}")
+            setattr(self, attr, self.__validate(getattr(self, factory), strict=self.__strict))
+
+    @staticmethod
+    def __validate[T: Any](val: T, strict: bool) -> T | None:
+        typeval = type(val)
+        allowed = get_args(AllowedTypes.__value__)
+
+        if typeval not in allowed:
+            if strict:
+                raise TypeError(f"{typeval} is not an allowed immutable type")
+            else:
+                warn(f"{typeval} is mutable, setting value to None", stacklevel=2)
+                return None
+
+        return val

sotkalib/http/__init__.py

@@ -0,0 +1,17 @@
+from .client_session import (
+    ExceptionSettings,
+    Handler,
+    Middleware,
+    RetryableClientSession,
+    RetryableClientSettings,
+    StatusSettings,
+)
+
+__all__ = (
+    "RetryableClientSession",
+    "ExceptionSettings",
+    "StatusSettings",
+    "RetryableClientSettings",
+    "Handler",
+    "Middleware",
+)

sotkalib/http/client_session.py

@@ -0,0 +1,247 @@
+import asyncio
+import importlib
+import ssl
+from collections.abc import Callable
+from http import HTTPStatus
+from typing import Any, Literal, Protocol, Self
+
+import aiohttp
+from aiohttp import client_exceptions
+from pydantic import BaseModel, ConfigDict, Field
+
+from sotkalib.log import get_logger
+
+try:
+    certifi = importlib.import_module("certifi")
+except ImportError:
+    certifi = None
+
+
+MAXIMUM_BACKOFF: float = 120
+
+
+class RunOutOfAttemptsError(Exception):
+    pass
+
+
+class StatusRetryError(Exception):
+    status: int
+    context: str
+
+    def __init__(self, status: int, context: str) -> None:
+        super().__init__(f"{status}: {context}")
+        self.status = status
+        self.context = context
+
+
+class CriticalStatusError(Exception):
+    pass
+
+
+class StatusSettings(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    to_raise: set[HTTPStatus] = Field(default={HTTPStatus.FORBIDDEN})
+    to_retry: set[HTTPStatus] = Field(default={HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.FORBIDDEN})
+    exc_to_raise: type[Exception] = Field(default=CriticalStatusError)
+    not_found_as_none: bool = Field(default=True)
+    unspecified: Literal["retry", "raise"] = Field(default="retry")
+
+
+class ExceptionSettings(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    to_raise: tuple[type[Exception]] = Field(
+        default=(
+            client_exceptions.ConnectionTimeoutError,
+            client_exceptions.ClientProxyConnectionError,
+            client_exceptions.ContentTypeError,
+        ),
+    )
+
+    to_retry: tuple[type[Exception]] = Field(
+        default=(
+            TimeoutError,
+            client_exceptions.ServerDisconnectedError,
+            client_exceptions.ClientConnectionResetError,
+            client_exceptions.ClientOSError,
+            client_exceptions.ClientHttpProxyError,
+        ),
+    )
+
+    exc_to_raise: type[Exception] | None = Field(default=None)
+
+    unspecified: Literal["retry", "raise"] = Field(default="retry")
+
+
+class RetryableClientSettings(BaseModel):
+    timeout: float = Field(default=5.0, gt=0)
+    base: float = Field(default=1.0, gt=0)
+    backoff: float = Field(default=2.0, gt=0)
+    maximum_retries: int = Field(default=3, ge=1)
+
+    useragent_factory: Callable[[], str] | None = Field(default=None)
+
+    status_settings: StatusSettings = Field(default_factory=StatusSettings)
+    exception_settings: ExceptionSettings = Field(default_factory=ExceptionSettings)
+
+    session_kwargs: dict[str, Any] = Field(default_factory=dict)
+    use_cookies_from_response: bool = Field(default=False)
+
+
+class Handler[T](Protocol):
+    async def __call__(self, *args: Any, **kwargs: Any) -> T: ...
+
+
+type Middleware[T, R] = Callable[[Handler[T]], Handler[R]]
+
+
+def _make_ssl_context(disable_tls13: bool = False) -> ssl.SSLContext:
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.load_default_certs()
+
+    if certifi:
+        ctx.load_verify_locations(certifi.where())
+
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.maximum_version = ssl.TLSVersion.TLSv1_2 if disable_tls13 else ssl.TLSVersion.TLSv1_3
+
+    ctx.set_ciphers(
+        "TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256:"
+        "TLS_CHACHA20_POLY1305_SHA256:"
+        "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:"
+        "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256"
+    )
+
+    ctx.check_hostname = True
+    ctx.verify_mode = ssl.CERT_REQUIRED
+
+    return ctx
+
+
+class RetryableClientSession[R = aiohttp.ClientResponse | None]:
+    config: RetryableClientSettings
+    _session: aiohttp.ClientSession
+    _middlewares: list[Callable[[Handler[Any]], Handler[Any]]]
+
+    def __init__(
+        self,
+        config: RetryableClientSettings | None = None,
+        _middlewares: list[Callable[[Handler[Any]], Handler[Any]]] | None = None,
+    ) -> None:
+        self.config = config if config is not None else RetryableClientSettings()
+        self._session = None
+        self._middlewares = _middlewares or []
+
+    def use[NewR](self, mw: Middleware[R, NewR]) -> RetryableClientSession[NewR]:
+        new_session: RetryableClientSession[NewR] = RetryableClientSession(
+            config=self.config,
+            _middlewares=[*self._middlewares, mw],
+        )
+        return new_session
+
+    async def __aenter__(self) -> Self:
+        ctx = _make_ssl_context(disable_tls13=False)
+
+        if self.config.session_kwargs.get("connector") is None:
+            self.config.session_kwargs["connector"] = aiohttp.TCPConnector(ssl=ctx)
+        if self.config.session_kwargs.get("trust_env") is None:
+            self.config.session_kwargs["trust_env"] = False
+
+        self._session = aiohttp.ClientSession(
+            timeout=aiohttp.ClientTimeout(total=self.config.timeout),
+            **self.config.session_kwargs,
+        )
+
+        get_logger("http.client_session").debug(
+            f"RetryableClientSession initialized with timeout: {self.config.timeout}"
+        )
+
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._session:
+            await self._session.close()
+
+    async def _handle_statuses(self, response: aiohttp.ClientResponse) -> aiohttp.ClientResponse | None:
+        sc = response.status
+        if self.config.use_cookies_from_response:
+            self._session.cookie_jar.update_cookies(response.cookies)
+        if sc in self.config.status_settings.to_retry:
+            raise StatusRetryError(status=sc, context=(await response.text()))
+        elif sc in self.config.status_settings.to_raise:
+            raise self.config.status_settings.exc_to_raise(f"status code: {sc} | {await response.text()}")
+        elif self.config.status_settings.not_found_as_none and sc == HTTPStatus.NOT_FOUND:
+            return None
+
+        return response
+
+    def _get_make_request_func(self) -> Handler[R]:
+        async def _make_request(*args: Any, **kwargs: Any) -> aiohttp.ClientResponse | None:
+            return await self._handle_statuses(await self._session.request(*args, **kwargs))
+
+        handler: Handler[Any] = _make_request
+        for mw in reversed(self._middlewares):
+            handler = mw(handler)
+
+        return handler
+
+    async def _handle_request(
+        self,
+        method: str,
+        url: str,
+        make_request_func: Handler[R],
+        **kw,
+    ) -> R:
+        kw_for_request = kw.copy()
+        if self.config.useragent_factory is not None:
+            user_agent_header = {"User-Agent": self.config.useragent_factory()}
+            kw_for_request["headers"] = kw_for_request.get("headers", {}) | user_agent_header
+        return await make_request_func(method, url, **kw_for_request)
+
+    async def _handle_retry(self, attempt: int, e: Exception, _: str, __: str, **___) -> None:
+        if attempt == self.config.maximum_retries:
+            raise RunOutOfAttemptsError(f"failed after {self.config.maximum_retries} retries: {type(e)} {e}") from e
+
+        await asyncio.sleep(self.config.base * min(MAXIMUM_BACKOFF, self.config.backoff**attempt))
+
+    async def _handle_to_raise(self, e: Exception, url: str, method: str, **kw) -> None:
+        if self.config.exception_settings.exc_to_raise is None:
+            raise e
+
+        raise self.config.exception_settings.exc_to_raise(f"EXC: {type(e)} {e}; {url} {method} {kw}") from e
+
+    async def _handle_exception(self, e: Exception, url: str, method: str, attempt: int, **kw) -> None:
+        if self.config.exception_settings.unspecified == "raise":
+            raise e
+
+        await self._handle_retry(attempt, e, url, method, **kw)
+
+    async def _request_with_retry(self, method: str, url: str, **kw) -> R:
+        _make_request = self._get_make_request_func()
+        for attempt in range(self.config.maximum_retries + 1):
+            try:
+                return await self._handle_request(method, url, _make_request, **kw)
+            except self.config.exception_settings.to_retry + (StatusRetryError,) as e:
+                await self._handle_retry(attempt, e, url, method, **kw)
+            except self.config.exception_settings.to_raise as e:
+                await self._handle_to_raise(e, url, method, **kw)
+            except Exception as e:
+                await self._handle_exception(e, url, method, attempt, **kw)
+
+        return await _make_request()
+
+    async def get(self, url: str, **kwargs: Any) -> R:
+        return await self._request_with_retry("GET", url, **kwargs)
+
+    async def post(self, url: str, **kwargs: Any) -> R:
+        return await self._request_with_retry("POST", url, **kwargs)
+
+    async def put(self, url: str, **kwargs: Any) -> R:
+        return await self._request_with_retry("PUT", url, **kwargs)
+
+    async def delete(self, url: str, **kwargs: Any) -> R:
+        return await self._request_with_retry("DELETE", url, **kwargs)
+
+    async def patch(self, url: str, **kwargs: Any) -> R:
+        return await self._request_with_retry("PATCH", url, **kwargs)

sotkalib/log/__init__.py

@@ -0,0 +1,3 @@
+from .factory import get_logger
+
+__all__ = ["get_logger"]

sotkalib/log/factory.py

@@ -0,0 +1,29 @@
+from functools import lru_cache
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from loguru import Logger
+
+
+@lru_cache
+def get_logger(logger_name: str | None = None) -> Logger:
+    """
+
+    Return a cached loguru Logger optionally bound with a humanized name.
+
+    If a name is provided, the returned logger is bound with extra["logger_name"]
+    in a " src -> sub -> leaf " format so it can be referenced in loguru sinks.
+
+    **Parameters:**
+
+    - `logger_name`: Dotted logger name (e.g., "src.database.service"). If None, return the global logger.
+
+    **Returns:**
+
+    A cached loguru Logger with the extra context bound when name is provided.
+
+    """
+
+    return logger if logger_name is None else logger.bind(logger_name=f" {logger_name.replace('.', ' -> ')} ")

sotkalib-0.0.2.dist-info/METADATA

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: sotkalib
+Version: 0.0.2
+Summary: 
+Author: alexey
+Author-email: alexey <me@pyrorhythm.dev>
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.12.5
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# ...

sotkalib-0.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+sotkalib/__init__.py,sha256=ebrSgK8GtSh2aZNdP3vKA6A4b1iHLFNWzpgznyOOn8Q,48
+sotkalib/config/__init__.py,sha256=CSjn02NCnBPO14QOg4OzKI-lTxyKoBxQ4ODsiWamlIM,102
+sotkalib/config/field.py,sha256=UaIiZBa4TUOB-akEqIvFJKxj2QjjsTaAjL2r163N-V4,790
+sotkalib/config/struct.py,sha256=kUabPNOv9uA8d0SzBOfr-w08YOYKy-D8LN0sof_ZQ5Q,6453
+sotkalib/http/__init__.py,sha256=gkuf1ZM7qXRmnm-yDUMmxxbCuu7bLek_PL3UmMQBtlM,317
+sotkalib/http/client_session.py,sha256=9AyOLFQFXf_lkirJcfp0NBIzx5owdRtDJZM-PEcCKtI,8952
+sotkalib/log/__init__.py,sha256=xrBx--c8QU5xkb3_n61LuqF8ySUaxlQkHCxHyH_D8aE,58
+sotkalib/log/factory.py,sha256=N8SZNvCdBLmsM0ES38x2BxZbJD1GgdMHtJ8h8lZjv7A,806
+sotkalib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sotkalib-0.0.2.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+sotkalib-0.0.2.dist-info/METADATA,sha256=TOF1FK1cVfMXt1kXc4gVjFsFsGj8hi5uMdQkude7sMQ,309
+sotkalib-0.0.2.dist-info/RECORD,,

sotkalib-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any