Aloha: Python Utilities and Microservice Boilerplate
Aloha is an open-source Python utility library and microservice project template. It helps Python teams build containerized services with HOCON configuration, structured and multi-process-safe logging, database integrations, encryption utilities, and pytest testing helpers.
Use the installable aloha package to add common service-building utilities to an existing Python project, or use this repository as a FastAPI/Uvicorn-oriented microservice boilerplate with Docker-based development and deployment examples.
- Documentation: English · 中文
- PyPI: aloha
- Issues and feature requests: GitHub Issues
Why Aloha?
- One library for common service foundations: configuration, logging, database access, encryption, HTTP service helpers, and tests live in the
alohapackage. - Configuration that fits deployments: load modular HOCON files and apply environment-specific settings through
PROFILE_ENV,FILES_CONFIG, and environment substitutions. - Logs built for services: write plain or JSON logs to console and daily rotating files, with a multi-process-safe file handler.
- Database integrations: use SQLAlchemy-backed operators and helpers for PostgreSQL, MySQL, SQLite, DuckDB, MongoDB, Redis, Elasticsearch, Oracle, and Kafka.
- A practical microservice starting point: the repository includes FastAPI/Uvicorn service examples, Dockerfiles, Docker Compose development setup, and pytest examples.
- Optional binary builds: compile Python modules to native extensions with the
aloha compilecommand and Cython.
Install
The base package supports Python 3.10 and later:
python -m pip install aloha
Install optional dependency groups for the capabilities you need:
python -m pip install "aloha[service]" # FastAPI and Uvicorn helpers
python -m pip install "aloha[db]" # Database integrations
python -m pip install "aloha[all]" # All optional integrations and tools
Quick Start
Check the installed library version:
from aloha import __version__
print(__version__)
Use the shared application logger after configuring the service's HOCON settings:
from aloha.logger import LOG
LOG.info("Service is ready")
The global logger reads deploy.log_level, deploy.log_format_file, and deploy.log_format_stream from the loaded configuration. File logs default to JSON; console logs default to plain text. See the logging guide for formats, fields, timestamps, and configuration details.
What Is Included?
| Module | What it helps with |
|---|---|
aloha.config |
Load HOCON settings, profiles, and environment-based configuration. |
aloha.logger |
Configure global and named loggers, JSON/plain output, and daily rotating logs. |
aloha.db |
Connect to supported SQL and service databases with reusable operators and password-vault integration. |
aloha.encrypt |
Use AES, RSA, JWT, hashing, and password-vault helpers. |
aloha.service |
Build FastAPI/Uvicorn services and reusable HTTP API handlers. |
aloha.testing |
Test utilities for unit tests and service API tests. |
aloha compile |
Build selected Python modules as native extensions using Cython. |
Explore the API documentation or the detailed Aloha Python Skill guide.
Use This Repository as a Service Template
The repository includes a runnable application example under src/, modular configuration under src/resource/config/, and Docker-based development helpers.
Start the development container from the repository root:
./tool/cicd/run-dev.sh up
./tool/cicd/run-dev.sh enter
Inside the container, run the example service and tests:
cd /workspace/src
python3 main.py app_common.main
pytest ./
To build a production Docker image from the repository root:
source tool/tool.sh
build_image app_common latest src/app-demo.Dockerfile
See the development and scaffolding guide for container lifecycle, configuration, ports, and production builds.
Repository Layout
pkg/— source code and packaging metadata for the installablealohalibrary.src/— example application, HOCON configuration, and tests.tool/— Docker, Compose, and development lifecycle scripts.doc/— user documentation, API references, and contributor skills.notebook/— notebooks for interactive examples and experiments.
Contributing
Before changing code, review the repository contributor guidelines for coding, configuration, logging, and testing standards. See the Aloha Python Skill for package development and the Aloha CI/CD & Scaffolding Skill for local development and builds.
Contributions, bug reports, and feature requests are welcome via GitHub Issues.
Release files for aloha 2026.928.112
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| aloha-2026.928.112.tar.gz | 56.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| aloha-2026.928.112-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 139.6 kB
Release files / aloha-2026.928.112.tar.gz
| Download URL | aloha-2026.928.112.tar.gz |
|---|---|
| Size | 56.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
67f85b31e9deba3be9216de5cbb21d78146c03d02b7dd7c05c8b3e24bb6e0416
|
|
BLAKE2b-256 checksum How to use checksums |
04d5199de43cf45fb4e92cf6868ca1326694d7f76e3f08be17689b66b59ade00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / aloha-2026.928.112-py3-none-any.whl
| Download URL | aloha-2026.928.112-py3-none-any.whl |
|---|---|
| Size | 83.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
20ffe3b40ab9fe11baa408cab6bc987187563b15a826978202e3d3954e3dd7d6
|
|
BLAKE2b-256 checksum How to use checksums |
6ff6689ff7a57c874f169864aef926cdeb241f1eb5a1b7d48f1e0bf1c6217853
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
