Alpha

Alpha is a foundational Python library providing standard building blocks for Python applications that use APIs, authentication and/or database interactions.

Badges

PyPI version PyPI Downloads Build Status Supported Python versions Coverage Status uv mypy Pytest PEP8 Ruff Documentation Status MIT License Sponsor

TL;DR

Alpha provides a comprehensive set of tools for building Python applications that interact with APIs and databases, including API code generation, authentication and authorization, database access layers, error handling, logging, and more. It is designed to be the first dependency you add to your project, providing a solid foundation for your application's architecture.

Status

Development status

Keep in mind that the library is still in development. We are working towards a stable 1.0 release, but in the meantime, you can already use the library in your projects and provide feedback on the features and functionality. The library can be used for productive applications, but be aware that there may be breaking changes in the future as we continue to develop and improve the library. We recommend keeping an eye on the changelog and documentation for updates and changes. To prevent failures in production, we recommend locking the library version in your dependency manager.

Core features

  • API code generation — OpenAPI code generation via CLI, Flask integration, request/response utilities
  • Authentication & Authorization — OIDC/KeyCloak, LDAP/Active Directory, JWT and password-based authentication
  • Database access layer — SQLAlchemy abstraction with Repository and Unit of Work patterns
  • REST API access layer — REST API repository implementations for external API interactions
  • Model support — Domain models with audit trail, attrs, Pydantic, dataclasses and OpenAPI model support
  • Error handling — Custom exceptions, error handlers and standardized error responses
  • Logging — Structured logging with context support, log enrichment and integration with logging frameworks
  • JSON Serialization — JSONEncoder for complex types: numpy, pandas, datetime, UUID, Enums and dataclasses

Installation

Install the core library:

pip install alpha-python

Install with optional extras:

# Flask APIs with PostgreSQL
pip install alpha-python[flask,postgresql]

# CLI for OpenAPI code generation (development dependency)
pip install alpha-python[api-generator]

See Installation for all available extras and package manager examples (Poetry, uv).

Quick example

from alpha import SqlAlchemyDatabase, SqlAlchemyUnitOfWork, SqlAlchemyRepository

# Configure database
db = SqlAlchemyDatabase("postgresql+psycopg2://user:pass@localhost/mydb")

# Use the Unit of Work pattern
with SqlAlchemyUnitOfWork(db) as uow:
    user = uow.users.get_by_id(1)

Learn more

  • Installation

    All available extras and installation options for pip, Poetry and uv.

    Installation

  • Quickstart

    A complete end-to-end example to get up and running quickly.

    Quickstart

  • Concepts

    Architecture overview and explanation of the underlying patterns.

    Concepts

  • Guides

    Step-by-step guides for common tasks and use cases.

    Guides

  • API Reference

    Full API documentation, auto-generated from the source code.

    API Reference

Support

If Alpha saves you time in production, consider supporting development by buying me a coffee! Your support helps me to continue improving the library and adding new features. Thank you!

Future Development Directions

Additional Template Set For FastAPI

Planned direction: add an extra template set so alpha api gen can generate FastAPI-based code in addition to the current Flask-oriented templates.

Suggested implementation outline:

  • add template directory support for a FastAPI generator target
  • expose this target via --generator-name (for example python-fastapi)
  • document behavioral differences between Flask and FastAPI output
  • provide migration notes for teams switching generator targets

Asynchronous API Code Generation

Planned direction: add support for generating asynchronous API code, potentially via FastAPI templates.

Asynchronous Database Support

Planned direction: add support for asynchronous database interactions, potentially via SQLAlchemy 2.0's async features.