Aloha

aloha-python is a modern project template (boilerplate) and a versatile utility library (aloha package) designed to build robust, containerized microservices in Python.

---

Please generously STAR★ our project or donate to us!

• To understand the package, read the 📚docs or

• To contribute or talk to a human:

---

🚀 Key Features

• Configuration Management (aloha.config): Lazy-loaded settings (SETTINGS) using HOCON (Human-Optimized Config Object Notation), supporting environment profile overrides (ENV_PROFILE / FILES_CONFIG) and environment variable injection.
• Concurrent-Safe Logging (aloha.logger): Multi-process safe daily rotating log file handler, console output, and automatic log paths configuration.
• Database Operators (aloha.db): Pre-built SQLAlchemy-backed connections for PostgreSQL, MySQL, SQLite, DuckDB, MongoDB, Redis, Elasticsearch, and Kafka, with password resolution via a secure PasswordVault wrapper.
• Encryption & Utilities (aloha.encrypt): Fast helpers for AES (ECB/CBC) encryption, RSA asymmetric key-pair generation/signatures, JWT encoding/decoding, and Base62 hashing.
• Testing Harness (aloha.testing): Extended UnitTestCase and integration ServiceTestCase structures for testing HTTP endpoints.
• Binary Code Protection (aloha compile): Utility compiler using Cython to package python source files (.py) into platform-native compiled dynamic libraries (.so/.pyd), protecting intellectual property.

---

📁 Repository Layout

• src/: Application-specific codebase, configuration files (src/resource/config/), and unit/integration tests (src/tests/).
• pkg/: The core aloha utility library source code.
• tool/: Local CI/CD files and setup helpers (e.g. docker-compose configurations, lifecycle scripts).
• doc/: Documentation files and AI Agent Skills.
• notebook/: Jupyter notebooks for interactive analysis.

---

🛠️ Local Development Quick Start

Local development is fully containerized using Docker & Docker Compose to maintain environment consistency.

1. Launch Dev Container

Run the lifecycle helper script:

# Check port availability and spin up the development container
./tool/cicd/run-dev.sh up

# Open an interactive terminal inside the container
./tool/cicd/run-dev.sh enter

Note: Development ports (PORT_APP and PORT_WEB) are dynamically computed based on your User ID (UID) to avoid conflicts on shared servers.

2. Run Tests

Inside the running container terminal:

# Execute pytest suite
pytest src/

# Run tests with code coverage report
pytest --cov=src src/

3. Production Packaging

To build a production-ready Docker image with optional binary compilation enabled:

source tool/tool.sh
build_image app_common latest src/app-demo.Dockerfile

---

✍️ Coding Guidelines

When developing in this project, variables should place their type or primary characteristics/role prefix first:

• Correct: name_service, port_service, svc_ingress, cfg_postgres.
• Incorrect: service_name, service_port, ingress_service, postgres_config.

For details on local setups, CI/CD specifications, and sub-module APIs, inspect our agent instruction files:

• Aloha Python Skills Guide
• Aloha CI/CD & Scaffolding Guide