yclibs 0.2.0

Shared Python utilities and helpers for database and date operations.

YCLibs

Shared Python utilities for database and date operations.

---

A production-ready Python library for database operations (SQLAlchemy 2.0+, sync/async) and date utilities. Built for FastAPI projects and modern Python 3.13+.

Features

• Database — SQLAlchemy 2.0+ with PostgreSQL (psycopg3, asyncpg)
  • Sync and async managers with type-safe CRUD
  • Connection pooling, DatabaseConfig for flexible setup
  • Declarative models with Mapped / mapped_column
• Date — DateHelper for common date operations
  • Relative dates (yesterday, last week, last month)
  • Ranges (week, month, quarter, year)
  • Business day calculations
  • Date comparisons and formatting
• Typed — Full PEP 484 type hints
• Tested — pytest, optional dev tooling (ruff)

Installation

# Using uv (recommended)
uv add yclibs

# Or pip
pip install yclibs

Requirements: Python 3.13+

Quick Start

Database

from yclibs.database.database import (
    Base,
    DatabaseConfig,
    DatabaseManager,
    get_db_session,
)
from yclibs.database.models import MyModel

# Custom config (optional)
config = DatabaseConfig(
    host="localhost",
    database="mydb",
    username="user",
    password="secret",
)
db = DatabaseManager(config)

# Or use defaults
with db.session() as session:
    result = db.get_all(MyModel, limit=10)

# Context manager
with get_db_session() as session:
    item = session.get(MyModel, 1)

Async

from yclibs.database.database import AsyncDatabaseManager

async with AsyncDatabaseManager() as db:
    items = await db.get_all(MyModel, limit=10)

DateHelper

from yclibs.date.date_helper import DateHelper, Weekday
from datetime import date

dh = DateHelper()

# Relative dates
yesterday = dh.yesterday()
last_week = dh.same_day_last_week()

# Ranges
start, end = dh.current_month_range()
quarter_start, quarter_end = dh.current_quarter_range()

# Business days
next_business = dh.next_business_day()

# Reference date
dh = DateHelper(date(2025, 1, 15))
week_start = dh.start_of_week(Weekday.MONDAY)

Project Structure

yclibs/
├── database/           # SQLAlchemy 2.0 layer
│   ├── database.py     # DatabaseManager, AsyncDatabaseManager, Base, DatabaseConfig
│   └── models.py       # Base model definitions
├── date/               # Date utilities
│   └── date_helper.py  # DateHelper
└── configs/            # Default settings

Configuration

DatabaseConfig supports:

• Individual params: host, port, database, username, password
• Full URL: url="postgresql+psycopg://user:pass@host:5432/db"
• Pool options: pool_size, max_overflow, pool_pre_ping, echo, etc.

Development

# Clone and install with dev deps
git clone https://github.com/Shiftryon/YCLibs.git
cd YCLibs
uv sync

# Run tests
uv run pytest

# Lint / format
uv run ruff check . && uv run ruff format .

License

MIT © Shiftryon