weblite-framework 0.1.0__tar.gz

weblite_framework-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.3
+Name: weblite_framework
+Version: 0.1.0
+Summary: 
+Author: Чернов Михаил
+Author-email: mihail.tchernov@yandex.ru
+Requires-Python: ==3.12.6
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: aioboto3 (==15.1.0)
+Requires-Dist: pydantic-settings (==2.10.1)
+Requires-Dist: pydantic[email] (==2.11.7)
+Requires-Dist: sqlalchemy[asyncio] (==2.0.36)
+Description-Content-Type: text/markdown
+
+# Weblite Framework
+
+Базовый фреймворк для веб-приложений.
+
+## Установка
+
+```bash
+pip install weblite-framework
+```
+
+## BaseRepositoryClass - Базовый класс для репозиториев
+
+`BaseRepositoryClass` предоставляет базовую функциональность для работы с базой данных через SQLAlchemy. Этот класс реализует паттерн Repository и обеспечивает типизированную работу с ORM моделями и DTO объектами.
+
+### Основные возможности
+
+- **Типизированная работа** с Generic типами `BaseRepositoryClass[DTO, SQLModel]`
+- **Абстрактные методы** для маппинга между моделями и DTO
+- **Управление транзакциями** с гибкими настройками
+- **Базовые операции** CRUD для работы с БД
+
+### Использование
+
+```python
+from typing import TypeVar
+from weblite_framework.repository.base import BaseRepositoryClass
+from weblite_framework.database.models import BaseModel
+
+# Определяем типы
+class UserDTO:
+    def __init__(self, id_: int, name: str):
+        self.id_ = id_
+        self.name = name
+
+class UserModel(BaseModel):
+    id_: int
+    name: str
+
+# Создаем репозиторий
+class UserRepository(BaseRepositoryClass[UserDTO, UserModel]):
+    def _model_to_dto(self, model: UserModel) -> UserDTO:
+        return UserDTO(id_=model.id_, name=model.name)
+    
+    def _dto_to_model(self, dto: UserDTO) -> UserModel:
+        model = UserModel()
+        model.id_ = dto.id_
+        model.name = dto.name
+        return model
+
+# Использование
+async def create_user(session: AsyncSession):
+    repo = UserRepository(session=session)
+    
+    # Создание записи
+    user_model = UserModel()
+    user_model.name = "John"
+    created_user = await repo._add_record(model=user_model)
+    
+    # Обновление записи
+    existing_user = UserModel()
+    existing_user.id_ = 1
+    existing_user.name = "Old Name"
+    
+    new_data = UserModel()
+    new_data.name = "New Name"
+    
+    updated_user = await repo._update(
+        existing_model=existing_user, 
+        new_data=new_data
+    )
+    
+    # Выполнение запросов
+    from sqlalchemy import select
+    query = select(UserModel).where(UserModel.id_ == 1)
+    result = await repo.execute(statement=query, is_use_active_transaction=False)
+    
+    # Коммит изменений
+    await repo.commit()
+```
+
+### Основные методы
+
+#### `_add_record(model: SQLModel) -> SQLModel`
+Создает новую запись в базе данных и возвращает модель с присвоенным идентификатором.
+
+#### `_update(existing_model: SQLModel, new_data: SQLModel, ignore_fields: list[str] | None = None) -> SQLModel`
+Обновляет существующую запись в базе данных. Поле `_sa_instance_state` всегда игнорируется.
+
+#### `execute(statement: Executable, is_use_active_transaction: bool = True) -> Result[Any]`
+Выполняет SQL запрос с возможностью управления транзакциями:
+- `is_use_active_transaction=True` - использует активную транзакцию
+- `is_use_active_transaction=False` - создает новую транзакцию
+
+#### `commit() -> None`
+Выполняет коммит текущей транзакции.
+
+#### `flush() -> None`
+Сбрасывает изменения в базу данных без коммита.
+
+#### `refresh(instance: SQLModel) -> None`
+Обновляет состояние модели из базы данных.
+
+### Абстрактные методы
+
+#### `_model_to_dto(model: SQLModel) -> DTO`
+Преобразует ORM модель в DTO объект. Должен быть реализован в дочернем классе.
+
+#### `_dto_to_model(dto: DTO) -> SQLModel`
+Преобразует DTO объект в ORM модель. Должен быть реализован в дочернем классе.
+
+### Пример выполнения кастомных запросов
+
+```python
+from sqlalchemy import text
+
+# Выполнение raw SQL
+query = text("SELECT * FROM users WHERE age > :min_age")
+result = await repo.execute(
+    statement=query, 
+    is_use_active_transaction=False
+)
+
+# Выполнение в рамках активной транзакции
+async with session.begin():
+    await repo._add_record(model=user_model)
+    await repo.execute(statement=query, is_use_active_transaction=True)
+    # Все операции выполняются в одной транзакции
+```
+
+### Примечания
+
+- Все методы работают асинхронно
+- Класс использует SQLAlchemy 2.0+ синтаксис
+- Поддерживает типизацию через Generic типы
+- Следует паттерну Repository для разделения логики доступа к данным
+
+### Обработка ошибок и Rollback
+
+Все транзакционные методы автоматически выполняют rollback при возникновении исключений:
+
+```python
+# При ошибке в любом методе автоматически выполняется rollback
+try:
+    await repo._add_record(model=user_model)
+    await repo.commit()
+except Exception as e:
+    # Транзакция уже откачена автоматически
+    print(f"Ошибка: {e}")
+```
+
+**Методы с автоматическим rollback:**
+- `_add_record()` - при ошибке создания записи
+- `_update()` - при ошибке обновления записи  
+- `commit()` - при ошибке коммита
+- `execute()` - при ошибке выполнения запроса
+- `refresh()` - при ошибке обновления модели
+- `flush()` - при ошибке сброса изменений
+

weblite_framework-0.1.0/README.md

@@ -0,0 +1,157 @@
+# Weblite Framework
+
+Базовый фреймворк для веб-приложений.
+
+## Установка
+
+```bash
+pip install weblite-framework
+```
+
+## BaseRepositoryClass - Базовый класс для репозиториев
+
+`BaseRepositoryClass` предоставляет базовую функциональность для работы с базой данных через SQLAlchemy. Этот класс реализует паттерн Repository и обеспечивает типизированную работу с ORM моделями и DTO объектами.
+
+### Основные возможности
+
+- **Типизированная работа** с Generic типами `BaseRepositoryClass[DTO, SQLModel]`
+- **Абстрактные методы** для маппинга между моделями и DTO
+- **Управление транзакциями** с гибкими настройками
+- **Базовые операции** CRUD для работы с БД
+
+### Использование
+
+```python
+from typing import TypeVar
+from weblite_framework.repository.base import BaseRepositoryClass
+from weblite_framework.database.models import BaseModel
+
+# Определяем типы
+class UserDTO:
+    def __init__(self, id_: int, name: str):
+        self.id_ = id_
+        self.name = name
+
+class UserModel(BaseModel):
+    id_: int
+    name: str
+
+# Создаем репозиторий
+class UserRepository(BaseRepositoryClass[UserDTO, UserModel]):
+    def _model_to_dto(self, model: UserModel) -> UserDTO:
+        return UserDTO(id_=model.id_, name=model.name)
+    
+    def _dto_to_model(self, dto: UserDTO) -> UserModel:
+        model = UserModel()
+        model.id_ = dto.id_
+        model.name = dto.name
+        return model
+
+# Использование
+async def create_user(session: AsyncSession):
+    repo = UserRepository(session=session)
+    
+    # Создание записи
+    user_model = UserModel()
+    user_model.name = "John"
+    created_user = await repo._add_record(model=user_model)
+    
+    # Обновление записи
+    existing_user = UserModel()
+    existing_user.id_ = 1
+    existing_user.name = "Old Name"
+    
+    new_data = UserModel()
+    new_data.name = "New Name"
+    
+    updated_user = await repo._update(
+        existing_model=existing_user, 
+        new_data=new_data
+    )
+    
+    # Выполнение запросов
+    from sqlalchemy import select
+    query = select(UserModel).where(UserModel.id_ == 1)
+    result = await repo.execute(statement=query, is_use_active_transaction=False)
+    
+    # Коммит изменений
+    await repo.commit()
+```
+
+### Основные методы
+
+#### `_add_record(model: SQLModel) -> SQLModel`
+Создает новую запись в базе данных и возвращает модель с присвоенным идентификатором.
+
+#### `_update(existing_model: SQLModel, new_data: SQLModel, ignore_fields: list[str] | None = None) -> SQLModel`
+Обновляет существующую запись в базе данных. Поле `_sa_instance_state` всегда игнорируется.
+
+#### `execute(statement: Executable, is_use_active_transaction: bool = True) -> Result[Any]`
+Выполняет SQL запрос с возможностью управления транзакциями:
+- `is_use_active_transaction=True` - использует активную транзакцию
+- `is_use_active_transaction=False` - создает новую транзакцию
+
+#### `commit() -> None`
+Выполняет коммит текущей транзакции.
+
+#### `flush() -> None`
+Сбрасывает изменения в базу данных без коммита.
+
+#### `refresh(instance: SQLModel) -> None`
+Обновляет состояние модели из базы данных.
+
+### Абстрактные методы
+
+#### `_model_to_dto(model: SQLModel) -> DTO`
+Преобразует ORM модель в DTO объект. Должен быть реализован в дочернем классе.
+
+#### `_dto_to_model(dto: DTO) -> SQLModel`
+Преобразует DTO объект в ORM модель. Должен быть реализован в дочернем классе.
+
+### Пример выполнения кастомных запросов
+
+```python
+from sqlalchemy import text
+
+# Выполнение raw SQL
+query = text("SELECT * FROM users WHERE age > :min_age")
+result = await repo.execute(
+    statement=query, 
+    is_use_active_transaction=False
+)
+
+# Выполнение в рамках активной транзакции
+async with session.begin():
+    await repo._add_record(model=user_model)
+    await repo.execute(statement=query, is_use_active_transaction=True)
+    # Все операции выполняются в одной транзакции
+```
+
+### Примечания
+
+- Все методы работают асинхронно
+- Класс использует SQLAlchemy 2.0+ синтаксис
+- Поддерживает типизацию через Generic типы
+- Следует паттерну Repository для разделения логики доступа к данным
+
+### Обработка ошибок и Rollback
+
+Все транзакционные методы автоматически выполняют rollback при возникновении исключений:
+
+```python
+# При ошибке в любом методе автоматически выполняется rollback
+try:
+    await repo._add_record(model=user_model)
+    await repo.commit()
+except Exception as e:
+    # Транзакция уже откачена автоматически
+    print(f"Ошибка: {e}")
+```
+
+**Методы с автоматическим rollback:**
+- `_add_record()` - при ошибке создания записи
+- `_update()` - при ошибке обновления записи  
+- `commit()` - при ошибке коммита
+- `execute()` - при ошибке выполнения запроса
+- `refresh()` - при ошибке обновления модели
+- `flush()` - при ошибке сброса изменений

weblite_framework-0.1.0/pyproject.toml

@@ -0,0 +1,78 @@
+[tool.poetry]
+name = "weblite_framework"
+version = "0.1.0"
+description = ""
+authors = ["Чернов Михаил <mihail.tchernov@yandex.ru>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "3.12.6"
+pydantic = { version = "2.11.7", extras = ["email"] }
+pydantic-settings = "2.10.1"
+aioboto3 = "15.1.0"
+sqlalchemy = {extras = ["asyncio"], version = "2.0.36"}
+
+[tool.poetry.group.test.dependencies]
+pytest = "8.4.1"
+pytest-asyncio = "1.1.0"
+pyhamcrest = "2.1.0"
+
+[tool.poetry.group.lint.dependencies]
+isort = "6.0.1"
+flake8 = "7.3.0"
+flake8-quotes = "3.4.0"
+flake8-annotations = "3.1.1"
+flake8-docstrings = "1.7.0"
+flake8-dunder-all = "0.5.0"
+flake8-pyproject = "1.2.3"
+black = "25.1.0"
+mypy = "1.17.1"
+
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "4.3.0"
+twine = "6.1.0"
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+pythonpath = "."
+testpaths = "tests"
+asyncio_mode = "auto"
+
+[tool.flake8]
+exclude = ["__pycache__"]
+max-line-length = 79
+max-doc-length = 79
+docstring-convention = "google"
+require-annotations = 1
+ignore = ["ANN002", "ANN003","ANN101", "ANN102"]
+per-file-ignores = [
+    "__init__.py:D104",
+    "tests/*:DALL000,D104,D100,FKA100"
+]
+max-complexity = 5
+
+[tool.black]
+line-length = 79
+skip-string-normalization = true
+
+[tool.isort]
+include_trailing_comma = true
+multi_line_output = 3
+line_length = 79
+
+[tool.mypy]
+strict = true
+plugins = "pydantic.mypy"
+ignore_missing_imports = true
+namespace_packages = true
+explicit_package_bases = true
+
+disable_error_code = [
+    "import-untyped",
+    "no-untyped-call"
+]
+
+[build-system]
+requires = ["poetry-core==2.0.1"]
+build-backend = "poetry.core.masonry.api"

weblite_framework-0.1.0/weblite_framework/database/models.py

@@ -0,0 +1,12 @@
+"""Модуль моделей SQLAlchemy."""
+
+from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlalchemy.orm import DeclarativeBase
+
+__all__ = ['BaseModel']
+
+
+class BaseModel(AsyncAttrs, DeclarativeBase):
+    """Базовый класс для всех моделей SQLAlchemy."""
+
+    pass

weblite_framework-0.1.0/weblite_framework/logging/logger.py

@@ -0,0 +1,96 @@
+"""Модуль логирования для weblite-framework."""
+
+import json
+import logging
+import sys
+from datetime import datetime
+from logging.handlers import QueueHandler, QueueListener
+from queue import Queue
+
+__all__ = [
+    'JsonFormatter',
+    'get_logger',
+]
+
+
+class JsonFormatter(logging.Formatter):
+    """Класс для преобразования записей логов в JSON-строки с полями."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Форматирует запись лога в JSON строку.
+
+        Поля:
+        timestamp: Временная метка
+        level: Уровень логирования
+        source: Источник сообщения (модуль)
+        message: Текст сообщения
+
+        Args:
+            record: Запись лога для форматирования
+
+        Returns:
+              JSON-строка с отформатированным логом
+        """
+        log_record = {
+            'timestamp': datetime.fromtimestamp(record.created)
+            .astimezone()
+            .isoformat(),
+            'level': record.levelname,
+            'source': record.module,
+            'message': record.getMessage(),
+        }
+        return json.dumps(log_record, ensure_ascii=False)
+
+
+_loggers: dict[str, logging.Logger] = {}
+_handler: logging.Handler | None = None
+
+
+def get_handler() -> logging.Handler:
+    """Создает и возвращает обработчик логов.
+
+    Обработчик использует очередь и listener для асинхронного логирования
+    во всех логгерах.
+
+    Returns:
+        logging.Handler: Настроенный обработчик логов
+    """
+    global _handler
+
+    if _handler is not None:
+        return _handler
+
+    log_queue: Queue[logging.LogRecord] = Queue()
+
+    stream_handler = logging.StreamHandler(stream=sys.stdout)
+    stream_handler.setFormatter(fmt=JsonFormatter())
+
+    listener = QueueListener(log_queue, stream_handler)
+    listener.start()
+
+    _handler = QueueHandler(queue=log_queue)
+
+    return _handler
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Создает и возвращает логгер.
+
+    Логирование происходит в отдельном потоке через QueueHandler.
+
+    Args:
+        name: str
+
+    Returns:
+        logging.Logger: Настроенный логгер
+    """
+    if name in _loggers:
+        return _loggers[name]
+
+    logger: logging.Logger = logging.getLogger(name=name)
+    logger.setLevel(level=logging.INFO)
+    logger.addHandler(hdlr=get_handler())
+
+    _loggers[name] = logger
+
+    return logger

weblite_framework-0.1.0/weblite_framework/provider/s3.py

@@ -0,0 +1,211 @@
+# TODO:
+# В ручках FastAPI перехватывать ошибки валидации из провайдера
+# и возвращать корректные HTTP-коды.
+
+"""S3-провайдер на aioboto3: upload/get/delete/list."""
+
+from typing import Any
+
+import aioboto3
+from botocore.config import Config
+
+from weblite_framework.settings.s3 import S3Settings
+
+__all__ = ['S3Provider']
+
+
+class S3Provider:
+    """Класс для работы с S3 через aioboto3.
+
+    Note:
+        Используйте провайдер только внутри блока ``async with``.
+
+    Examples:
+        async with S3Provider(settings) as s3p:
+            await s3p.upload_file(filename="a.txt", data=b"...")
+            data: bytes = await s3p.get_file(filename="a.txt")
+    """
+
+    def __init__(self, settings: S3Settings) -> None:
+        """Создаёт провайдер с заданными настройками.
+
+        Args:
+            settings : S3Settings
+        """
+        self.settings = settings
+        self._session = aioboto3.Session()
+
+        self._config = Config(
+            region_name=settings.region,
+            signature_version=settings.signature_version,
+            s3={
+                'addressing_style': (
+                    'path' if settings.path_style else 'virtual'
+                ),
+            },
+            retries={
+                'max_attempts': settings.max_attempts,
+                'mode': 'standard',
+            },
+            connect_timeout=settings.connect_timeout,
+            read_timeout=settings.read_timeout,
+        )
+
+        self._client_kwargs = {
+            'endpoint_url': settings.endpoint_url,
+            'aws_access_key_id': settings.access_key,
+            'aws_secret_access_key': settings.secret_key,
+            'config': self._config,
+        }
+
+        self._client_cm: Any = None
+        self._client: Any = None
+
+    async def __aenter__(self) -> 'S3Provider':
+        """Открывает S3-клиент и возвращает провайдер.
+
+        Returns:
+            S3Provider: Экземпляр провайдера с открытым S3-клиентом.
+        """
+        self._client_cm = self._session.client(
+            service_name='s3',
+            **self._client_kwargs,
+        )
+        self._client = await self._client_cm.__aenter__()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object | None,
+    ) -> None:
+        """Закрывает соединение с S3.
+
+        Args:
+            exc_type: Тип исключения, если оно возникло.
+            exc: Экземпляр исключения, если он был.
+            tb: Трейсбек исключения.
+
+        Returns:
+            None: Исключения не подавляются.
+        """
+        try:
+            if self._client_cm is not None:
+                await self._client_cm.__aexit__(
+                    exc_type=exc_type,
+                    exc_value=exc,
+                    traceback=tb,
+                )
+        finally:
+            self._client = None
+            self._client_cm = None
+
+    @classmethod
+    def __validate_filename(cls, filename: str) -> None:  # noqa: ANN102
+        """Проверяет, что имя файла непустое.
+
+        Args:
+            filename: Имя файла.
+
+        Raises:
+            ValueError: Если имя файла пустое.
+        """
+        if not filename:
+            raise ValueError('filename is required')
+
+    def _ensure_client(self) -> Any:  # noqa: ANN401
+        """Возвращает активный S3-клиент или бросает исключение.
+
+        Raises:
+            RuntimeError: Если провайдер используется вне `async with`.
+        """
+        if self._client is None:
+            raise RuntimeError(
+                'S3Provider нужно использовать внутри'
+                ' "async with S3Provider(...)"',
+            )
+        return self._client
+
+    async def upload_file(self, filename: str, data: bytes) -> None:
+        """Загружает байты в S3 под именем `filename`.
+
+        Args:
+            filename (str): Имя файла для сохранения в S3.
+            data: Данные для загрузки.
+
+        Raises:
+            ValueError: Если имя файла или данные не указаны.
+        """
+        self.__validate_filename(filename=filename)
+        if data is None:
+            raise ValueError('data is required')
+
+        s3 = self._ensure_client()
+        await s3.put_object(
+            Bucket=self.settings.bucket,
+            Key=filename,
+            Body=data,
+        )
+
+    async def get_file(self, filename: str) -> bytes:
+        """Читает содержимое объекта и возвращает его как bytes.
+
+        Args:
+            filename: Имя файла в S3.
+
+        Returns:
+            bytes: Содержимое файла.
+
+        Raises:
+            ValueError: Если имя файла пустое.
+        """
+        self.__validate_filename(filename=filename)
+
+        s3 = self._ensure_client()
+        resp = await s3.get_object(
+            Bucket=self.settings.bucket,
+            Key=filename,
+        )
+        async with resp['Body'] as stream:
+            content: bytes = await stream.read()
+        return content
+
+    async def delete_file(self, filename: str) -> None:
+        """Удаляет объект из S3 (идемпотентно).
+
+        Args:
+            filename: Имя файла для удаления.
+
+        Raises:
+            ValueError: Если имя файла пустое.
+        """
+        self.__validate_filename(filename=filename)
+
+        s3 = self._ensure_client()
+        await s3.delete_object(
+            Bucket=self.settings.bucket,
+            Key=filename,
+        )
+
+    async def get_files_list(self, prefix: str = '') -> list[str]:
+        """Возвращает список ключей, начинающихся с указанного префикса.
+
+        Args:
+            prefix: Префикс ключей. По умолчанию пустая строка.
+
+        Returns:
+            list: Список имён файлов (ключей).
+        """
+        keys: list[str] = []
+
+        s3 = self._ensure_client()
+        paginator = s3.get_paginator(operation_name='list_objects_v2')
+        async for page in paginator.paginate(
+            Bucket=self.settings.bucket,
+            Prefix=prefix,
+        ):
+            for obj in page.get('Contents') or []:
+                keys.append(obj['Key'])
+
+        return keys

weblite_framework-0.1.0/weblite_framework/repository/__init__.py

@@ -0,0 +1,5 @@
+"""Модуль репозиториев."""
+
+from .base import BaseRepositoryClass
+
+__all__ = ['BaseRepositoryClass']

weblite_framework-0.1.0/weblite_framework/repository/base.py

@@ -0,0 +1,225 @@
+"""Модуль базового репозитория для работы с БД."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy import Executable, Result
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from weblite_framework.database.models import BaseModel
+
+__all__ = [
+    'BaseRepositoryClass',
+]
+
+DTO = TypeVar('DTO')
+SQLModel = TypeVar('SQLModel', bound=BaseModel)
+
+
+class BaseRepositoryClass(Generic[DTO, SQLModel], ABC):
+    """Базовый репозиторий с общим контролем выполняемых транзакций."""
+
+    def __init__(self, session: AsyncSession) -> None:
+        """Инициализирует экземпляр репозитория.
+
+        Args:
+            session: AsyncSession
+        """
+        self.__session = session
+
+    def _get_session_for_testing(self) -> AsyncSession:
+        """Возвращает сессию для тестирования.
+
+        Returns:
+            AsyncSession: Сессия для тестирования
+        """
+        return self.__session
+
+    @abstractmethod
+    def _model_to_dto(self, model: SQLModel) -> DTO:
+        """Производит маппинг данных из ORM модели в класс DTO.
+
+        Args:
+            model: ORM модель
+
+        Returns:
+            DTO: объект dataclass
+        """
+        pass
+
+    @abstractmethod
+    def _dto_to_model(self, dto: DTO) -> SQLModel:
+        """Производит маппинг данных из DTO класса в ORM модель.
+
+        Args:
+            dto: объект dataclass
+
+        Returns:
+            SQLModel: ORM модель
+        """
+        pass
+
+    async def _add_record(
+        self,
+        model: SQLModel,
+    ) -> SQLModel:
+        """Создает запись в БД.
+
+        Данный метод создает запись в БД
+        и обновляет поля модели без коммита.
+
+        Args:
+            model: ORM модель
+
+        Returns:
+            SQLModel: ORM модель с присвоенным идентификатором
+        """
+        try:
+            self.add(model)
+            await self.flush()
+            return model
+        except Exception as e:
+            await self.__session.rollback()
+            raise e
+
+    def _prepare_ignore_fields(
+        self,
+        ignore_fields: list[str] | None = None,
+    ) -> list[str]:
+        """Подготавливает список игнорируемых полей.
+
+        Args:
+            ignore_fields: Список игнорируемых полей
+
+        Returns:
+            list[str]: Подготовленный список игнорируемых полей
+        """
+        if ignore_fields is None:
+            ignore_fields = []
+        ignore_fields.append('_sa_instance_state')
+        return ignore_fields
+
+    def _update_model_fields(
+        self,
+        existing_model: SQLModel,
+        new_data: SQLModel,
+        ignore_fields: list[str],
+    ) -> None:
+        """Обновляет поля модели.
+
+        Args:
+            existing_model: Существующая модель
+            new_data: Новые данные
+            ignore_fields: Список игнорируемых полей
+        """
+        for key, value in new_data.__dict__.items():
+            if key not in ignore_fields:
+                setattr(existing_model, key, value)
+
+    async def _update(
+        self,
+        existing_model: SQLModel,
+        new_data: SQLModel,
+        ignore_fields: list[str] | None = None,
+    ) -> SQLModel:
+        """Обновляет существующую запись в БД.
+
+        Данный метод обновляет данные в существующей записи в БД,
+        при этом коммит не производится.
+
+        Args:
+            existing_model: ORM модель с информацией, связанная с записью в БД
+            new_data: ORM модель с данными для обновления
+            ignore_fields: Список игнорируемых полей
+
+        Returns:
+            SQLModel: ORM модель, связанная с БД с обновленными полями
+        """
+        try:
+            prepared_ignore_fields = self._prepare_ignore_fields(ignore_fields)
+            self._update_model_fields(
+                existing_model=existing_model,
+                new_data=new_data,
+                ignore_fields=prepared_ignore_fields,
+            )
+            await self.flush()
+            return existing_model
+        except Exception as e:
+            await self.__session.rollback()
+            raise e
+
+    def add(self, instance: SQLModel) -> None:
+        """Выполняет добавление в сессию переданного instance.
+
+        Args:
+            instance: ORM модель
+        """
+        self.__session.add(instance)
+
+    async def commit(self) -> None:
+        """Выполняет коммит в текущей сессии."""
+        try:
+            await self.__session.commit()
+        except Exception as e:
+            await self.__session.rollback()
+            raise e
+
+    async def execute(
+        self,
+        statement: Executable,
+        is_use_active_transaction: bool = True,
+    ) -> Result[Any]:
+        """Выполняет переданный SQL-запрос с учетом активной транзакции.
+
+        Данный метод выполняет переданный запрос, при этом:
+            Если передать is_use_active_transaction=True,
+                новая транзакция создана не будет.
+                Используется для связки методов,
+                которые должны выполняться атомарно.
+                Такие методы в дочерних классах должны
+                быть объявлены как _protected.
+            Если передать is_use_active_transaction=False,
+                будет создана новая временная транзакция.
+                Используется для отдельно взятых запросов,
+                не связанных между собой. Такие методы в
+                дочерних классах должны быть объявлены как public.
+
+        Args:
+            statement: SQL-запрос
+            is_use_active_transaction: Флаг на использование
+                активной транзакции
+
+        Returns:
+            Result: Результат выполнения запроса в БД
+        """
+        try:
+            if is_use_active_transaction:
+                return await self.__session.execute(statement)
+            else:
+                async with self.__session.begin():
+                    result = await self.__session.execute(statement)
+                    await self.__session.commit()
+                    return result
+        except Exception as e:
+            await self.__session.rollback()
+            raise e
+
+    async def refresh(self, instance: SQLModel) -> None:
+        """Выполняет обновление модели, обращаясь к БД.
+
+        Args:
+            instance: ORM модель, состояние которой обновляется из БД
+        """
+        try:
+            await self.__session.refresh(instance)
+        except Exception as e:
+            await self.__session.rollback()
+            raise e
+
+    async def flush(self) -> None:
+        """Сбрасывает изменения в базу данных без коммита."""
+        try:
+            await self.__session.flush()
+        except Exception as e:
+            await self.__session.rollback()
+            raise e

weblite_framework-0.1.0/weblite_framework/schemas/base.py

@@ -0,0 +1,103 @@
+"""Модуль с родительской Pydantic схемой."""
+
+from typing import Any, Final, Type, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+
+T = TypeVar('T', bound='CustomBaseModel')
+
+__all__ = ['CustomBaseModel']
+
+REQUIRED_FIELD_ATTRIBUTES: Final[tuple[str, ...]] = (
+    'alias',
+    'description',
+    'examples',
+)
+
+
+class CustomBaseModel(BaseModel):
+    """Родительская кастомная Pydantic BaseModel схема.
+
+    Данная схема имеет встроенные проверки и расширенную функциональность.
+    """
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        arbitrary_types_allowed=True,
+    )
+
+    @classmethod
+    def __check_required_fields(cls) -> list[str]:
+        """Проверяет обязательные поля для заполнения.
+
+        Данные метод проверяет поля, обязательные для заполнения
+        в Pydantic схеме и возвращает список ошибок.
+        Если ошибки не найдены, будет возвращен пустой список.
+
+        Args:
+            cls
+
+        Returns:
+            errors: Список возникших ошибок
+        """
+        errors = []
+        for field_name, field_info in cls.model_fields.items():
+            for attr_name in REQUIRED_FIELD_ATTRIBUTES:
+                attr_value = getattr(field_info, attr_name, None)
+                if attr_value is None:
+                    errors.append(f'{field_name}: отсутствует {attr_name}')
+                elif attr_name == 'examples' and len(attr_value) != 1:
+                    errors.append(
+                        f'{field_name}: '
+                        f'{attr_name} должен содержать ровно одно значение',
+                    )
+        return errors
+
+    @classmethod
+    def __pydantic_init_subclass__(
+        cls,
+        **kwargs: Any,  # noqa: ANN401
+    ) -> None:
+        """Инициализация схемы после загрузки данных из атрибутов класса.
+
+        Данный метод проверяет все поля схемы Pydantic на
+        наличие alias, description и example.
+
+        Args:
+            cls
+            kwargs: Дополнительные передаваемые именованные аргументы
+
+        Raises:
+            TypeError: Ошибка при валидации полей схемы
+        """
+        super().__pydantic_init_subclass__(**kwargs)
+
+        errors = cls.__check_required_fields()
+        if errors:
+            fields_str = '\n'.join(errors)
+            raise TypeError(
+                f'Модель {cls.__name__} не прошла проверку документации: '
+                f'\n{fields_str}',
+            )
+
+    @classmethod
+    def generate_example(cls: Type[T]) -> T:
+        """Автоматическая генерация примера на основе alias и example.
+
+        Args:
+            cls
+
+        Returns:
+            CustomBaseModel
+        """
+        example = {}
+
+        for field_name, field_info in cls.model_fields.items():
+            if field_info.examples is not None:
+                key = field_info.alias or field_name
+                example[key] = field_info.examples[0]
+
+        return cls.model_validate(
+            obj=example,
+            from_attributes=False,
+        )

weblite_framework-0.1.0/weblite_framework/settings/s3.py

@@ -0,0 +1,42 @@
+"""Настройки для подключения к S3."""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ['S3Settings']
+
+
+class S3Settings(BaseSettings):
+    """Конфигурация подключения к S3.
+
+    Args:
+        bucket: Имя S3-бакета.
+        access_key: Ключ доступа AWS/S3.
+        secret_key: Секретный ключ AWS/S3.
+        region: Регион S3.
+        endpoint_url: URL эндпоинта S3 (например, для MinIO).
+        path_style: Включает использование path-style addressing.
+            Если True, запросы будут формироваться в виде
+            ``https://endpoint/bucket/key`` (необходимо для MinIO и
+            совместимых сервисов). Если False — используется
+            virtual-hosted style ``https://bucket.endpoint/key`` (дефолт AWS).
+        signature_version: Версия алгоритма подписи запросов к S3.
+        max_attempts: Максимальное число повторных попыток.
+        connect_timeout: Таймаут подключения в секундах.
+        read_timeout: Таймаут чтения в секундах.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix='S3_',
+        extra='ignore',
+    )
+
+    bucket: str
+    access_key: str
+    secret_key: str
+    region: str
+    endpoint_url: str
+    path_style: bool = True
+    signature_version: str = 's3v4'
+    max_attempts: int = 3
+    connect_timeout: int = 5
+    read_timeout: int = 30