Skip to content

README.md

Latest commit

 

History

History
95 lines (62 loc) · 4.83 KB

README.md

File metadata and controls

95 lines (62 loc) · 4.83 KB
Raw

Aloha

License GitHub Workflow Status PyPI version PyPI Downloads Code Activity Recent Code Update

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! GitHub Starts

  • To understand the package, read the 📚docs or Ask DeepWiki

  • To contribute or talk to a human: Open an Issue on GitHub Join the Discord Chat Join the Gitter Chat

🚀 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: