sotkalib 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

sotkalib/__init__.py

@@ -1,5 +1,3 @@
-"""
+from . import config, enum, exceptions, http, log, redis, sqla
 
-Library with utils, made for s0tka.ru
-
-"""
+__all__ = ["config", "enum", "exceptions", "http", "log", "redis", "sqla"]

sotkalib/config/field.py

@@ -6,22 +6,6 @@ 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

@@ -14,166 +14,166 @@ from sotkalib.log import get_logger
 from .field import AllowedTypes, SettingsField
 
 if TYPE_CHECKING:
-    from logging import (
-        Logger as StdLogger,
-    )
+	from logging import (
+		Logger as StdLogger,
+	)
 
-    from loguru import Logger as LoguruLogger
+	from loguru import Logger as LoguruLogger
 
-    type _loggers = StdLogger | LoguruLogger
+	type _loggers = StdLogger | LoguruLogger
 
 
 @dataclass
 class AppSettings:
-    """
+	"""
 
-    Base class for reading typed settings from environment variables.
+		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.
+		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:**
+	**Notes:**
 
-        Only immutable primitive types are allowed: int, float, complex, str, bool, None.
+		Only immutable primitive types are allowed: int, float, complex, str, bool, None.
 
-        If explicit_format is True, attribute names must be UPPER_SNAKE_CASE.
+		If explicit_format is True, attribute names must be UPPER_SNAKE_CASE.
 
-        **Example:**
+	**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"
+		>>> 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()
+	>>> settings = MySettings()
 
-    """
+	"""
 
-    def __init__(
-        self,
-        dotenv_path: str | PathLike[str] | None = None,
-        logger: _loggers | None = None,
-        explicit_format: bool = True,
-        strict: bool = False,
-    ) -> None:
-        """
+	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.
+		Initialize AppSettings and resolve annotated fields.
 
-        **Parameters:**
+		**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.
+		- `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:**
+		**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.
+		- `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 _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)
+		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)
+		load_dotenv(dotenv_path=dotenv_path)
 
-        _log = get_logger("utilities.appsettings") if logger is None else logger
-        self.__log = _log
+		self.__log = get_logger("utilities.appsettings") if logger is None else logger
+		self.__deferred = []
+		self.__strict = strict
 
-        self.__strict = strict
+		cls_annotations = self.__class__.__annotations__
+		cls_dict = self.__class__.__dict__
 
-        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)
+		}
 
-        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")
 
-        self.__deferred = []
+			annotated = cls_annotations.get(attr, NoneType)
+			string_value = getenv(attr, None)
 
-        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")
+			if string_value is None:
+				self.__validate_empty_string_value(attr, settings_field)
+				continue
 
-            annotated = cls_annotations.get(attr, NoneType)
-            string_value = getenv(attr, None)
+			typed_value = evaluate_var(annotated, string_value)
 
-            if string_value is None:
-                self.__validate_empty_string_value(attr, settings_field)
-                continue
+			setattr(self, attr, self.__validate(typed_value, strict=self.__strict))
+			self.__log.debug(f"evaluated {attr} from environment")
 
-            typed_value = evaluate_var(annotated, string_value)
+		self.__post_init__()
 
-            setattr(self, attr, self.__validate(typed_value, strict=self.__strict))
-            _log.debug(f"evaluated {attr} from environment")
+	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
 
-        self.__post_init__()
+		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)}")
 
-    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.nullable:
+			setattr(self, attr, None)
+			self.__log.debug(f"evaluated {attr} as None (nullable)")
+			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
+		raise ValueError(f"reqd field {attr} was not found in .env")
 
-        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
+	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))
 
-        if settings_field.nullable:
-            setattr(self, attr, None)
-            self.__log.debug(f"evaluated {attr} as None (nullable)")
-            return
+	@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
 
-        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
+		return val

sotkalib/enum/__init__.py

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

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/exceptions/__init__.py

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

sotkalib/exceptions/api/__init__.py

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

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/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/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/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/http/__init__.py

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