# python-abacus-models

**SQLAlchemy Models for Abacus**

This repository contains all shared database models used across Abacus services, providing a single source of truth for data structures and relationships.

## Features

- **SQLAlchemy 2.0**: Modern, performant ORM with full type safety
- **Relationship Integrity**: All cross-model relationships defined in one place
- **Auto-generated**: Models generated from database schema with automatic relationship detection
- **Extensible**: Add custom methods and business logic through extension classes
- **Easy to Use**: Simple imports, consistent patterns

## Installation

```bash
# Using uv (recommended)
uv add abacus-models

# Using pip
pip install -i https://pypi.theorchard.io/pypi/ abacus-models
```

## Auto-generating Models

Models are automatically generated from the database schema using SQLAlchemy's reflection capabilities.

### Configuration

Create a `.env` file in the project root with your database connection details:

```bash
# Copy the template file
cp .env.shadow .env

# Then edit .env with your database credentials
```

Example `.env` configuration:

```bash
# Database connection
DB_VENDOR=mysql
DB_HOST=127.0.0.1
DB_USER=royalties
DB_PASS=1234
DB_NAME=royalty_accounting
DB_PORT=6057
```

### Generate Models

```bash
# Generate all models from the database
make generate
```

This will:
- Connect to the database using credentials from `.env`
- Reflect the database schema
- Auto-generate SQLAlchemy model classes
- Detect and configure relationships between models
- Output models to `abacus_models/<DB_VENDOR>/<DB_NAME>/generated.py`

### Notes

- Always review generated models before committing
- Models should be regenerated when the database schema changes
- Custom business logic should be added through model extensions, not in the generated files

## Local Development

If you're making changes to the library and want to test locally before publishing:

### Prerequisites

Install [uv](https://docs.astral.sh/uv/) (modern Python package manager):
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv
```

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/theorchard/python-abacus-models.git
cd python-abacus-models

# Install all dependencies and create virtual environment
uv sync

# This automatically:
# - Creates .venv/ directory
# - Installs the package in editable mode
# - Installs all dependencies from pyproject.toml
# - Configures private PyPI registry (pypi.theorchard.io)
```

### Testing

```bash
# Run linter
make lint

# Fix linting issues automatically
make lint_fix

# Check code formatting
make format

# Fix formatting issues automatically
make format_fix

# Run tests
make test

# Run integration tests
make test_integration
```

#### Testing with Docker

You can run the tests inside Docker using the commands that are used in the pipeline.

You'll first need to login to Docker with the shared AWS account:

```bash

# Login to Docker
awsume <shared_profile>
make docker_login

# Run unit and functional tests
make ci_unit_lint

# Run integration tests
make ci_test_integration
```

### Watch mode / Editable mode

To test your local changes in a downstream service:

```bash
# In the downstream project
pip install -e /path/to/python-abacus-models

# Or with uv
uv add --editable /path/to/python-abacus-models
```

## Migrating to SQLAlchemy 2.0

- **[SQLAlchemy 2.0 Migration Guide](https://docs.sqlalchemy.org/en/20/changelog/migration_20.html)**: Official SQLAlchemy migration docs

### Migration Checklist

Currently used by:

1. [ ] [ows-abacus-event](https://github.com/theorchard/ows-abacus-event)
1. [ ] [ows-abacus-schedule](https://github.com/theorchard/ows-abacus-schedule)
1. [ ] [ows-abacus-state](https://github.com/theorchard/ows-abacus-state)
1. [ ] [ows-abacus-worksheet](https://github.com/theorchard/ows-abacus-worksheet)
1. [ ] [ows-abacus-account](https://github.com/theorchard/ows-abacus-account)
1. [ ] [ows-royalties](https://github.com/theorchard/ows-royalties)
1. [ ] [ows-ledger](https://github.com/theorchard/ows-ledger)
1. etc.