yclibs 0.2.1
Shared Python utilities and helpers for database and date operations.
Requires Python: >=3.13
Keywords: asyncio, database, date, fastapi, python, sqlalchemy, utilities, uvicorn, yclibs

# YCLibs

<p align="center">
  <strong>Shared Python utilities for database and date operations.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/yclibs/"><img src="https://img.shields.io/pypi/v/yclibs?style=flat-square" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.13+-blue?style=flat-square" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License"></a>
</p>

---

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

```bash
# Using uv (recommended)
uv add yclibs

# Or pip
pip install yclibs
```

**Requirements:** Python 3.13+

## Quick Start

### Database

```python
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

```python
from yclibs.database.database import AsyncDatabaseManager

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

### DateHelper

```python
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

```bash
# 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](https://github.com/Shiftryon)