sotkalib 0.0.2__tar.gz → 0.0.4__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sotkalib"
-version = "0.0.2"
+version = "0.0.4"
 description = ""
 authors = [
     { email = "me@pyrorhythm.dev", name = "alexey" }
@@ -12,6 +12,8 @@ dependencies = [
     "dotenv>=0.9.9",
     "loguru>=0.7.3",
     "pydantic>=2.12.5",
+    "redis>=7.1.0",
+    "sqlalchemy[asyncio]>=2.0.46",
 ]
 
 
@@ -36,7 +38,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 +51,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.4/src/sotkalib/__init__.py

@@ -0,0 +1,3 @@
+from . import config, enum, exceptions, http, log, redis, sqla
+
+__all__ = ["config", "enum", "exceptions", "http", "log", "redis", "sqla"]

sotkalib-0.0.4/src/sotkalib/config/field.py

@@ -0,0 +1,11 @@
+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]:
+    default: T | None = None
+    factory: Callable[[], T] | str | None = None
+    nullable: bool = False

sotkalib-0.0.4/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.4/src/sotkalib/enum/__init__.py

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

sotkalib-0.0.4/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.4/src/sotkalib/exceptions/__init__.py

@@ -0,0 +1,3 @@
+from . import api, handlers
+
+__all__ = ["api", "handlers"]

sotkalib-0.0.4/src/sotkalib/exceptions/api/__init__.py

@@ -0,0 +1 @@
+from .exc import APIError, ErrorSchema

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

@@ -0,0 +1,53 @@
+import http
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class ErrorSchema(BaseModel):
+	code: 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.code = code
+		self.desc = desc
+		self.ctx = ctx
+
+		self.schema = ErrorSchema(
+			code=self.code,
+			desc=self.desc,
+			ctx=self.ctx,
+		)
+
+		super().__init__(status_code=self.status.value, detail=self.schema.model_dump_json())

sotkalib-0.0.4/src/sotkalib/exceptions/handlers/__init__.py

@@ -0,0 +1,4 @@
+from .args_incl_error import ArgsIncludedError
+from .core import aexception_handler, exception_handler
+
+__all__ = ["aexception_handler", "exception_handler", "ArgsIncludedError"]

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

@@ -0,0 +1,15 @@
+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 | f_locals | { "frame_name": frame.f_code.co_name })
+		super().__init__(*_args, *stack_args_to_exc)

sotkalib-0.0.4/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.4/src/sotkalib/http/__init__.py

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