Python Archist

Archist is a lightweight bash utility designed to scaffold Clean Architecture directory structures for Python projects in seconds. It organizes your code into layers, making it decoupled, testable, and easy to maintain.

Directory Tree

The project is organized into layers following the Archist philosophy:

src/
├── Application/        # Application services and use cases
│   ├── DTO/           # Data Transfer Objects
│   ├── Service/       # Domain-independent services
│   └── UseCase/       # Orchestration of domain logic
├── Domain/            # Enterprise/Business logic (Pure Python)
│   ├── Entity/        # Domain models
│   ├── Exception/     # Domain-specific errors
│   ├── Repository/    # Port definitions (Interfaces)
│   └── ValueObject/   # Immutable data structures
├── Infrastructure/     # External tools and technical details
│   ├── Delivery/      # Entry points (Http/FastAPI, Console)
│   ├── ExternalApi/   # Third-party integrations
│   └── Persistence/   # Database implementations (Adapters)
└── Shared/            # Logic shared across all layers

Key Features

• Framework Agnostic: The core logic does not depend on external frameworks.
• Dependency Inversion: High-level modules (Domain) do not depend on low-level modules (Infrastructure).
• Environment Configuration: Ready for .env management using python-dotenv.
• Modern Python Tooling: Uses pyproject.toml for dependency management and pytest for testing.
• Type Hinting: Encourages the use of Python type hints for better IDE support and error catching.

Usage

Prerequisites

• Python 3.8 or higher.
• Pip (Python package installer).

Installation

1. Download the script

You can download the initialization script directly from the repository using curl:

Using curl:

curl -O https://raw.githubusercontent.com/AFelipeTrujillo/py-archist/refs/heads/master/py_archist.sh

2. Set Execution Permissions

Before running the script, you must grant it execution permissions:

chmod +x py_archist.sh

3. Run the Scaffolding Tool

Execute the script in the directory where you want to start your new project:

./py_archist.sh

4. Install dependencies:

pip install .

Development

Running the Application

The entry point of the application is main.py:

python main.py

Running Tests

The project is configured to work with pytest:

pytest

Layers Philosophy

Domain

The "heart" of the software. It contains the business rules. It should have no dependencies on any external library or framework.

Application

Orchestrates the flow of data to and from the domain entities. It contains the Use Cases of the system.

Infrastructure

This layer contains the implementation of the ports defined in the Domain. It is where the database code, API clients, and the web framework (like FastAPI or Flask) live.

---

Inspired by the php-archist project.