BasicRepositoryMixin

Repository pattern mixins for SQLAlchemy models with automatic type conversion, pagination, and advanced querying capabilities (no third-party time dependency).

Features

• Rich query helpers for common database operations
• Automatic type conversion for primary keys
• Built-in pagination with total count
• Optional logging helpers
• Composite key support

Installation

Makefile (Linux/macOS) vs Windows

• Makefile targets Linux/macOS.
• On Windows, use Makefile.windows:

  make -f Makefile.windows install-dev
  make -f Makefile.windows test
  make -f Makefile.windows check
  

Core Install

uv add BasicRepositoryMixin

For Development

uv sync --extra dev

Quick Start

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import declarative_base

from basic_repository_mixin import BasicRepositoryMixin, AuditMixin

Base = declarative_base()

class User(Base, BasicRepositoryMixin, AuditMixin):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True)
    email = Column(String, unique=True)
    username = Column(String)

user = User.get_by_id(1, session=session)

Available Methods

BasicRepositoryMixin

• get_by_id()
• get_by_composed_id()
• count_all()
• is_empty()
• get_top_n()
• get_all()
• get_all_by()
• get_first_or_none_by()
• get_page()

AuditMixin

Adds UTC audit columns with Python defaults and database server defaults.

• created_at: default=_utc_now, server_default=func.now()
• updated_at: default=_utc_now, server_default=func.now(), onupdate=_utc_now, server_onupdate=func.now()

Advanced Usage

Composite Primary Keys

class UserRole(Base, BasicRepositoryMixin):
    __tablename__ = "user_roles"

    user_id = Column(Integer, primary_key=True)
    role_id = Column(Integer, primary_key=True)

user_role = UserRole.get_by_composed_id(
    {"user_id": 1, "role_id": 2},
    session=session,
)

Custom Logger

import logging
from basic_repository_mixin import configure_default_logger

logger = logging.getLogger("my_app")
configure_default_logger(logger)

Session Configuration

from basic_repository_mixin import configure_default_session

configure_default_session(my_session)

Requirements

• Python >= 3.11
• SQLAlchemy >= 2.0.0

Contributing

Contributions are welcome. See CONTRIBUTING.md and INSTALLATION_GUIDE.md for local setup and checks.

License

This project is licensed under the MIT License. See LICENSE.

Author

Daniel Correa Lobato

• Website: sites.lobato.org
• Email: daniel@lobato.org