api-template-py 0.1.0

A CLI tool to scaffold Python API projects following Clean Architecture principles with FastAPI

API Template PY

A powerful CLI tool to scaffold Python API projects following Clean Architecture principles with FastAPI.

Features

• Clean Architecture: Clear separation of concerns with layered architecture
• FastAPI: Modern, fast, and production-ready web framework
• Complete Project Structure: Pre-configured with all necessary layers
• Interactive CLI: Beautiful terminal UI with prompts and colors
• Dependency Injection: Built-in DI pattern for loose coupling
• Type Hints: Full type safety throughout the codebase
• Testing Ready: Pre-configured pytest setup with examples
• Production Ready: CORS, logging, and error handling configured
• Well Documented: Comprehensive docstrings and README

Architecture

Projects generated with api-template-py follow Clean Architecture:

┌────────────────────────────────────────────┐
│         API Layer (FastAPI)                │  ← Presentation Layer
│         api/v1/ - REST endpoints           │
└──────────────────┬─────────────────────────┘
                   ↓
┌────────────────────────────────────────────┐
│      Service Layer (Business Logic)        │  ← Business Layer
│      services/ - Domain logic              │
└──────────────────┬─────────────────────────┘
                   ↓
┌────────────────────────────────────────────┐
│    Repository Layer (Data Access)          │  ← Data Layer
│    repositories/ - Data persistence        │
└────────────────────────────────────────────┘

Installation

Install from PyPI:

pip install api-template-py

Or install from source:

git clone https://github.com/yourusername/api-template-py.git
cd api-template-py
pip install -e .

Quick Start

Create a New Project (Interactive)

api-template create

The CLI will prompt you for:

• Project name
• Description
• Author name and email
• Python version
• Git initialization

Create a New Project (Non-Interactive)

api-template create my-api-project \
  --author "John Doe" \
  --email "[e-mail]" \
  --python-version 3.10

Run Your New Project

cd my-api-project
python -m venv .venv
source .venv/bin/activate 
pip install -e .
uvicorn src.main:app --reload

Your API will be available at:

• API: http://localhost:8000
• Interactive Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Generated Project Structure

my-api-project/
├── src/                        # Source code
│   ├── api/                    # API Layer
│   │   ├── dependencies.py     # Dependency injection
│   │   └── v1/                 # API version 1
│   │       ├── health.py       # Health checks
│   │       └── items.py        # Example CRUD
│   ├── services/               # Service Layer
│   │   ├── base_service.py
│   │   └── item_service.py
│   ├── repositories/           # Repository Layer
│   │   ├── interfaces.py
│   │   ├── base_repository.py
│   │   └── item_repository.py
│   ├── models/                 # Domain Models
│   │   ├── domain.py
│   │   └── schemas.py
│   ├── core/                   # Core Infrastructure
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   └── middleware.py
│   └── main.py                 # Entry point
├── tests/
│   └── test_items.py
├── pyproject.toml
├── README.md
├── .env.example
└── .gitignore

Key Design Patterns

1. Dependency Injection

# api/dependencies.py
@lru_cache
def get_item_service(
    repository: Annotated[ItemRepository, Depends(get_item_repository)]
) -> ItemService:
    return ItemService(repository=repository)

2. Repository Pattern

# repositories/interfaces.py
class IRepository(ABC, Generic[T]):
    @abstractmethod
    async def create(self, entity: T) -> T:
        pass

3. Service Layer Pattern

# services/item_service.py
class ItemService(BaseService[Item]):
    async def create_item(self, item_data: ItemCreate) -> ItemResponse:
        # Business logic here
        item = Item(**item_data.dict())
        return await self.repository.create(item)

4. DTO Pattern

# models/schemas.py
class ItemCreate(BaseModel):
    name: str
    price: float

class ItemResponse(BaseModel):
    id: int
    name: str
    price: float

Testing

Generated projects include test examples:

pytest
pytest --cov=src --cov-report=html

CLI Commands

api-template create

Create a new API project.

Options:

• PROJECT_NAME - Project name (optional, will prompt if not provided)
• --description, -d - Project description
• --author, -a - Author name
• --email, -e - Author email
• --python-version, -p - Python version (3.10, 3.11, 3.12)
• --no-git - Skip git initialization
• --non-interactive - Non-interactive mode

Examples:

# Interactive mode
api-template create

# With project name
api-template create my-api

# Full non-interactive
api-template create my-api \
  --description "My API" \
  --author "Jane Doe" \
  --email "[e-mail]" \
  --python-version 3.11 \
  --non-interactive

What You Get

Pre-configured FastAPI Application

• CORS middleware
• Logging middleware
• Custom exception handling
• Lifespan events
• OpenAPI documentation

Complete CRUD Example

• Item model with validation
• Service layer with business logic
• Repository with in-memory storage
• Full CRUD endpoints
• Request/response schemas

Health Check Endpoints

• /api/v1/health - Basic health check
• /api/v1/health/ready - Readiness probe
• /api/v1/health/live - Liveness probe

Development Tools

• Type hints throughout
• Comprehensive docstrings
• pytest configuration
• Environment variables support
• Code formatting setup (Black, Ruff)

Documentation

For Generated Projects

Each generated project includes:

• Comprehensive README with architecture explanation
• Inline code documentation
• Example implementations
• Setup instructions
• Development guidelines

Learn More

• FastAPI Documentation
• Clean Architecture
• Repository Pattern
• Dependency Injection

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

API Template PY Contributors

Acknowledgments

• Inspired by Clean Architecture principles by Robert C. Martin
• Built with FastAPI
• CLI powered by Click and Rich

Support

If you have any questions or need help, please:

• Open an issue on GitHub
• Check existing issues for solutions
• Read the generated project's README

---

Happy coding!