sotkalib 0.0.2__tar.gz → 0.0.3__tar.gz

{sotkalib-0.0.2 → sotkalib-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sotkalib
-Version: 0.0.2
+Version: 0.0.3
 Summary: 
 Author: alexey
 Author-email: alexey <me@pyrorhythm.dev>
@@ -8,6 +8,7 @@ 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-Dist: redis>=7.1.0
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 

{sotkalib-0.0.2 → sotkalib-0.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sotkalib"
-version = "0.0.2"
+version = "0.0.3"
 description = ""
 authors = [
     { email = "me@pyrorhythm.dev", name = "alexey" }
@@ -12,6 +12,7 @@ dependencies = [
     "dotenv>=0.9.9",
     "loguru>=0.7.3",
     "pydantic>=2.12.5",
+    "redis>=7.1.0",
 ]
 
 
@@ -36,7 +37,9 @@ dev = [
     "mypy>=1.19.0",
     "pyrefly>=0.45.2",
     "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
     "ruff>=0.14.9",
+    "testcontainers>=4.14.1",
 ]
 
 [tool.ruff]
@@ -47,6 +50,7 @@ src = ["src"]
 [tool.ruff.format]
 docstring-code-format = true
 line-ending = "lf"
+indent-style = "tab"
 
 [tool.ruff.lint]
 # Allow autofix for all enabled rules (when `--fix`) is provided.

sotkalib-0.0.3/src/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)
+
+		self.__log = get_logger("utilities.appsettings") if logger is None else logger
+		self.__deferred = []
+		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)
+		}
+
+		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))
+			self.__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:
+			if 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
+
+			raise TypeError(f"unknown type for a factory: {type(settings_field.factory)}")
+
+		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-0.0.3/src/sotkalib/enum/__init__.py

@@ -0,0 +1,3 @@
+from .mixins import UppercaseStrEnumMixin, ValidatorStrEnumMixin
+
+__all__ = ["ValidatorStrEnumMixin", "UppercaseStrEnumMixin"]

sotkalib-0.0.3/src/sotkalib/enum/mixins.py

@@ -0,0 +1,59 @@
+from collections.abc import Sequence
+from enum import Enum
+from typing import Any, Literal, Self, overload
+
+
+class UppercaseStrEnumMixin(str, Enum):
+    @staticmethod
+    def _generate_next_value_(name: str, start: int, count: int, last_values: Sequence) -> str:  # noqa
+        return name.upper()
+
+
+class ValidatorStrEnumMixin(str, Enum):
+    @classmethod
+    def _normalize_value(cls, val: Any) -> str:
+        if isinstance(val, (str, bytes, bytearray)):
+            return val.decode("utf-8") if isinstance(val, (bytes, bytearray)) else val
+        raise TypeError("value must be str-like")
+
+    @overload
+    @classmethod
+    def validate(cls, *, val: Any, req: Literal[False] = False) -> Self | None: ...
+
+    @overload
+    @classmethod
+    def validate(cls, *, val: Any, req: Literal[True]) -> Self: ...
+
+    @classmethod
+    def validate(cls, *, val: Any, req: bool = False) -> Self | None:
+        if val is None:
+            if req:
+                raise ValueError("value is None and req=True")
+            return None
+        normalized = cls._normalize_value(val)
+        try:
+            return cls(normalized)
+        except ValueError as e:
+            raise TypeError(f"{normalized=} not valid: {e}") from e
+
+    @overload
+    @classmethod
+    def get(cls, val: Any, default: Literal[None] = None) -> Self | None: ...
+
+    @overload
+    @classmethod
+    def get(cls, val: Any, default: Self) -> Self: ...
+
+    @classmethod
+    def get(cls, val: Any, default: Self | None = None) -> Self | None:
+        try:
+            return cls.validate(val=val, req=False) or default
+        except (ValueError, TypeError):
+            return default
+
+    def in_(self, *enum_values: Self) -> bool:
+        return self in enum_values
+
+    @classmethod
+    def values(cls) -> Sequence[Self]:
+        return list(cls)

sotkalib-0.0.3/src/sotkalib/exceptions/api/exc.py

@@ -0,0 +1,56 @@
+import http
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ErrorSchema(BaseModel):
+	code: str | None = None
+	phrase: str | None = None
+	desc: str | None = None
+	ctx: Mapping[str, Any] | str | list[Any] | None = None
+
+
+class BaseHTTPError(Exception):
+	def __init__(self, status_code: int, detail: str | None = None, headers: Mapping[str, str] | None = None) -> None:
+		if detail is None:
+			detail = http.HTTPStatus(status_code).phrase
+		self.status_code = status_code
+		self.detail = detail
+		self.headers = headers
+
+	def __str__(self) -> str:
+		return f"{self.status_code}: {self.detail}"
+
+	def __repr__(self) -> str:
+		class_name = self.__class__.__name__
+		return f"{class_name}(status_code={self.status_code!r}, detail={self.detail!r})"
+
+
+class APIError(BaseHTTPError):
+	def __init__(
+		self,
+		*,
+		status: http.HTTPStatus | int = http.HTTPStatus.BAD_REQUEST,
+		code: str | None = None,
+		desc: str | None = None,
+		ctx: Mapping[str, Any] | list[Any] | str | None = None,
+	):
+		if isinstance(status, int):
+			status = http.HTTPStatus(status)
+
+		self.status = status
+		self.phrase = status.phrase
+		self.code = code
+		self.desc = desc
+		self.ctx = ctx
+
+		self.schema = ErrorSchema(
+			code=self.code,
+			phrase=self.phrase,
+			desc=self.desc,
+			ctx=self.ctx,
+		)
+
+		super().__init__(status_code=self.status.value, detail=self.schema.model_dump_json())

sotkalib-0.0.3/src/sotkalib/exceptions/handlers/args_incl_error.py

@@ -0,0 +1,21 @@
+import inspect
+
+
+class ArgsIncludedError(Exception):
+	def __init__(self, *args, stack_depth: int = 2):
+		_args = args
+		stack_args_to_exc = []
+		frames = inspect.stack()[1:-1][::-1][:stack_depth]
+		for frame_info in frames:
+			frame = frame_info.frame
+			args, _, _, values = inspect.getargvalues(frame)
+			f_locals = frame.f_locals
+			args_with_values = {arg: values[arg] for arg in args}
+			stack_args_to_exc.append(
+				args_with_values
+				| {
+					"frame_name": frame.f_code.co_name,
+				}
+				| f_locals
+			)
+		super().__init__(*_args, *stack_args_to_exc)

sotkalib-0.0.3/src/sotkalib/exceptions/handlers/core.py

@@ -0,0 +1,33 @@
+from collections.abc import Callable, Coroutine
+from functools import wraps
+from typing import Any
+
+from .args_incl_error import ArgsIncludedError
+
+
+def exception_handler[**P, R](
+	func: Callable[P, R],
+	stack_depth: int = 3,
+) -> Callable[P, R]:
+	@wraps(func)
+	def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+		try:
+			return func(*args, **kwargs)
+		except Exception as e:
+			raise ArgsIncludedError(*e.args, stack_depth=stack_depth) from e
+
+	return wrapper
+
+
+def aexception_handler[**P, R](
+	func: Callable[P, Coroutine[Any, Any, R]],
+	stack_depth: int = 7,
+) -> Callable[P, Coroutine[Any, Any, R]]:
+	@wraps(func)
+	async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+		try:
+			return await func(*args, **kwargs)
+		except Exception as e:
+			raise ArgsIncludedError(*e.args, stack_depth=stack_depth) from e
+
+	return wrapper

sotkalib-0.0.3/src/sotkalib/http/__init__.py

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

sotkalib-0.0.3/src/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 ClientSettings(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 ClientSession[R = aiohttp.ClientResponse | None]:
+	config: ClientSettings
+	_session: aiohttp.ClientSession
+	_middlewares: list[Callable[[Handler[Any]], Handler[Any]]]
+
+	def __init__(
+		self,
+		config: ClientSettings | None = None,
+		_middlewares: list[Callable[[Handler[Any]], Handler[Any]]] | None = None,
+	) -> None:
+		self.config = config if config is not None else ClientSettings()
+		self._session = None
+		self._middlewares = _middlewares or []
+
+	def use[NewR](self, mw: Middleware[R, NewR]) -> ClientSession[NewR]:
+		new_session: ClientSession[NewR] = ClientSession(
+			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-0.0.3/src/sotkalib/redis/client.py

@@ -0,0 +1,38 @@
+import asyncio
+from contextlib import AbstractAsyncContextManager
+
+from pydantic import BaseModel, Field
+from redis.asyncio import ConnectionPool, Redis
+
+
+class RedisPoolSettings(BaseModel):
+	uri: str = Field(default="redis://localhost:6379")
+	db_num: int = Field(default=4)
+	max_connections: int = Field(default=50)
+	socket_timeout: float = Field(default=5)
+	socket_connect_timeout: float = Field(default=5)
+	retry_on_timeout: bool = Field(default=True)
+	health_check_interval: float = Field(default=30)
+	decode_responses: bool = Field(default=True)
+
+
+class RedisPool(AbstractAsyncContextManager):
+	def __init__(self, settings: RedisPoolSettings | None = None):
+		if not settings:
+			settings = RedisPoolSettings()
+
+		self._pool = ConnectionPool.from_url(
+			settings.uri + "/" + str(settings.db_num),
+			**settings.model_dump(exclude={"uri", "db_num"}),
+		)
+
+		self._usage_counter = 0
+		self._usage_lock = asyncio.Lock()
+
+	async def __aenter__(self: RedisPool) -> Redis:
+		try:
+			return Redis(connection_pool=self._pool)
+		except Exception:
+			raise
+
+	async def __aexit__(self, exc_type, exc_value, traceback): ...

sotkalib-0.0.3/src/sotkalib/redis/lock.py

@@ -0,0 +1,89 @@
+import asyncio
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from time import time
+from typing import Any
+
+from redis.asyncio import Redis
+
+from sotkalib.redis.client import RedisPool
+
+
+class ContextLockError(Exception):
+	def __init__(self, *args, can_retry: bool = True):
+		super().__init__(*args)
+		self.can_retry = can_retry
+
+
+async def _try_acquire(rc: Redis, key_to_lock: str, acquire_timeout: int) -> bool:
+	"""Atomically acquire a lock using SET NX (set-if-not-exists)."""
+	return bool(await rc.set(key_to_lock, "acquired", nx=True, ex=acquire_timeout))
+
+
+async def wait_till_lock_free(
+	client: Redis,
+	key_to_lock: str,
+	lock_timeout: float = 10.0,
+	base_delay: float = 0.1,
+	max_delay: float = 5.0,
+) -> None:
+	"""
+	Wait until lock is free with exponential backoff.
+
+	:param key_to_lock: Redis key for the lock
+	:param lock_timeout: Maximum time to wait in seconds
+	:param base_delay: Initial delay between checks in seconds
+	:param max_delay: Maximum delay between checks in seconds
+	:raises ContextLockError: If timeout is reached
+	"""
+	start = time()
+	attempt = 0
+	while await client.get(key_to_lock) is not None:
+		if (time() - start) > lock_timeout:
+			raise ContextLockError(
+				f"{key_to_lock} lock already acquired, timeout after {lock_timeout}s",
+				can_retry=False,
+			)
+		delay = min(base_delay * (2**attempt), max_delay)
+		await asyncio.sleep(delay)
+		attempt += 1
+
+
+@asynccontextmanager
+async def redis_context_lock(
+	client: Redis | RedisPool,
+	key_to_lock: str,
+	can_retry_if_lock_catched: bool = True,
+	wait_for_lock: bool = False,
+	wait_timeout: float = 60.0,
+	acquire_timeout: int = 5,
+	args_to_lock_exception: list[Any] | None = None,
+) -> AsyncGenerator[None]:
+	"""
+	Acquire a Redis lock atomically using SET NX.
+
+	:param key_to_lock: Redis key for the lock
+	:param can_retry_if_lock_catched: Whether task should retry if lock is taken (only used if wait_for_lock=False)
+	:param wait_for_lock: If True, wait for lock to be free instead of immediately failing
+	:param wait_timeout: Maximum time to wait for lock in seconds (only used if wait_for_lock=True)
+	"""
+	if args_to_lock_exception is None:
+		args_to_lock_exception = []
+
+	if wait_for_lock:
+		async with client as rc:
+			await wait_till_lock_free(key_to_lock=key_to_lock, client=rc, lock_timeout=wait_timeout)
+
+	try:
+		async with client as rc:
+			acquired = await _try_acquire(rc, key_to_lock, acquire_timeout)
+			if not acquired:
+				raise ContextLockError(
+					f"{key_to_lock} lock already acquired",
+					*args_to_lock_exception,
+					can_retry=can_retry_if_lock_catched,
+				)
+		yield
+	finally:
+		async with client as rc:
+			await rc.delete(key_to_lock)

sotkalib-0.0.2/src/sotkalib/config/struct.py

@@ -1,179 +0,0 @@
-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-0.0.2/src/sotkalib/http/__init__.py

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

sotkalib-0.0.2/src/sotkalib/http/client_session.py

@@ -1,247 +0,0 @@
-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)