Metadata-Version: 2.4
Name: api-template-py
Version: 0.1.0
Summary: A CLI tool to scaffold Python API projects following Clean Architecture principles with FastAPI
Author-email: Your Name <your.email@example.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/api-template-py
Project-URL: Documentation, https://github.com/yourusername/api-template-py#readme
Project-URL: Repository, https://github.com/yourusername/api-template-py
Project-URL: Bug Tracker, https://github.com/yourusername/api-template-py/issues
Keywords: fastapi,clean-architecture,api,template,cli,scaffold
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# API Template PY

[![PyPI version](https://badge.fury.io/py/api-template-py.svg)](https://badge.fury.io/py/api-template-py)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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:

```bash
pip install api-template-py
```

Or install from source:

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

## Quick Start

### Create a New Project (Interactive)

```bash
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)

```bash
api-template create my-api-project \
  --author "John Doe" \
  --email "john@example.com" \
  --python-version 3.10
```

### Run Your New Project

```bash
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

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

### 2. Repository Pattern

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

### 3. Service Layer Pattern

```python
# 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

```python
# 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:

```bash
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:**

```bash
# 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 "jane@example.com" \
  --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](https://fastapi.tiangolo.com/)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)
- [Repository Pattern](https://martinfowler.com/eaaCatalog/repository.html)
- [Dependency Injection](https://fastapi.tiangolo.com/tutorial/dependencies/)

## 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](LICENSE) file for details.

## Author

**API Template PY Contributors**

## Acknowledgments

- Inspired by Clean Architecture principles by Robert C. Martin
- Built with [FastAPI](https://fastapi.tiangolo.com/)
- CLI powered by [Click](https://click.palletsprojects.com/) and [Rich](https://rich.readthedocs.io/)

## 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!**

