Metadata-Version: 2.4
Name: fastapi-template-cli
Version: 1.2.8
Summary: A powerful CLI tool for generating production-ready FastAPI applications with SQLAlchemy and MongoDB support
Author-email: FastAPI Template CLI <sohailahmad34280@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Sohail342/fastapi-template
Project-URL: Documentation, https://github.com/Sohail342/fastapi-template#readme
Project-URL: Repository, https://github.com/Sohail342/fastapi-template
Project-URL: Issues, https://github.com/Sohail342/fastapi-template/issues
Keywords: fastapi,cli,scaffold,template,python,sqlalchemy,mongodb,beanie,async
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: jinja2>=3.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.5; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/fastapi-template-logo.svg" alt="FastAPI Template Logo" width="400">
</p>

<h1 align="center">FastAPI Template</h1>

<p align="center">
  <strong>A powerful CLI tool for generating production-ready FastAPI projects with best practices, integrated authentication, and flexible ORM options.</strong>
</p>

## Features

- 🚀 **Production Ready**: Pre-configured with security, logging, and deployment best practices
- 🔐 **Integrated Authentication**: FastAPI-Users integration with JWT authentication
- 🗄️ **Flexible ORM**: Choose between SQLAlchemy (PostgreSQL) or Beanie (MongoDB)
- 🐳 **Docker Support**: Complete Docker setup with docker-compose
- 📦 **Celery Integration**: Background task processing (fullstack projects)
- 🧪 **Testing Ready**: Pre-configured testing setup
- 📊 **API Documentation**: Auto-generated OpenAPI/Swagger documentation
- 🎯 **CLI Driven**: Simple command-line interface for project generation

## Quick Start

### Installation

```bash
pip install fastapi-template-cli
```

### Create a New Project

```bash
# Create an API-only project with SQLAlchemy
fastapi-template new my-api --orm sqlalchemy --type api

# Create a fullstack project with MongoDB
fastapi-template new my-app --orm beanie --type fullstack

# Create with project description
fastapi-template new my-project --orm sqlalchemy --type fullstack \
  --description "My awesome FastAPI project" --author "Your Name"
```

## Project Types

### API-Only Projects
- Lightweight FastAPI backend
- Database integration (SQLAlchemy or Beanie)
- FastAPI-Users authentication
- No frontend or background tasks

### Fullstack Projects
- Complete backend with FastAPI
- Database integration
- FastAPI-Users authentication
- Celery for background tasks
- Redis for caching and task queue
- Docker setup with docker-compose

## ORM Options

### SQLAlchemy (PostgreSQL)
- **Database**: PostgreSQL
- **ORM**: SQLAlchemy 2.0 with async support
- **Migrations**: Alembic
- **Connection**: asyncpg driver

### Beanie (MongoDB)
- **Database**: MongoDB
- **ODM**: Beanie (async MongoDB ODM)
- **Driver**: Motor
- **Schema**: Pydantic-based documents

## Usage

### Basic Commands

```bash
# List available templates
fastapi-template list-templates

# Create a new project
fastapi-template new myproject

# Show version
fastapi-template version
```

### Project Structure

Generated projects follow a clean architecture:

```
myproject/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── api.py
│   │       └── endpoints/
│   │           └── users.py
│   ├── core/
│   │   ├── config.py
│   │   └── security.py
│   ├── db/
│   │   ├── session.py (SQLAlchemy) or mongo.py (Beanie)
│   │   └── base_class.py (SQLAlchemy)
│   ├── models/
│   │   └── user.py
│   ├── schemas/
│   │   └── user.py
│   ├── users.py (FastAPI-Users config)
│   └── main.py
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml (fullstack only)
├── alembic/ (SQLAlchemy only)
├── workers/ (fullstack only)
├── pyproject.toml
├── .env
└── .gitignore
```

## Template Comparison

### Fullstack Template
- **Includes Redis** as Celery broker and result backend
- **Separate Celery worker** for long-running tasks
- **Celery Beat** for scheduled tasks
- **Complete frontend integration**
- **Production-ready Docker setup**

### API Template
- **Lightweight FastAPI core**
- **Database-only backend**
- **Minimal dependencies**
- **Optimized for microservices**
- **Simplified Docker setup**

## Project Structure Details

### API Template (`/d:/Projects dir/cli-tool/e-commerce/`)
```
e-commerce/
├── app/
│   ├── api/v1/
│   │   ├── api.py              # Main API router
│   │   └── endpoints/
│   │       └── users.py        # User endpoints
│   ├── core/
│   │   ├── config.py           # Application configuration
│   │   ├── security.py         # Security utilities
│   │   └── users.py           # User management
│   ├── database/
│   │   ├── base.py            # Database base setup
│   │   ├── base_class.py      # Base model class
│   │   └── session.py         # Database session
│   ├── models/
│   │   └── users.py           # User models
│   ├── schemas/
│   │   └── user.py            # Pydantic schemas
│   ├── users/
│   │   ├── dependencies.py    # User dependencies
│   │   └── manager.py         # User manager
│   └── main.py                # FastAPI application
├── alembic/                   # Database migrations
├── docker/                    # Docker configuration
├── tests/                     # Test files
├── .env.dev                   # Development environment
├── .env.prod                  # Production environment
└── pyproject.toml            # Project dependencies
```

### Fullstack Template (`/d:/Projects dir/cli-tool/full-erp/`)
```
full-erp/
├── app/
│   ├── core/
│   │   ├── config.py           # Application configuration
│   │   ├── security.py         # Security utilities
│   │   └── users.py           # User management
│   ├── database/
│   │   ├── base.py            # Database base setup
│   │   ├── base_class.py      # Base model class
│   │   └── session.py         # Database session
│   ├── models/
│   │   └── users.py           # User models
│   ├── routers/
│   │   └── test.py            # Test endpoints
│   ├── schemas/
│   │   └── user.py            # Pydantic schemas
│   ├── services/              # Business logic services
│   ├── users/
│   │   ├── dependencies.py    # User dependencies
│   │   └── manager.py         # User manager
│   ├── utils/                 # Utility functions
│   ├── workers/
│   │   ├── celery_app.py      # Celery configuration
│   │   └── tasks.py           # Background tasks
│   └── main.py                # FastAPI application
├── alembic/                   # Database migrations
├── docker/                    # Docker configuration
├── tests/                     # Test files
├── .env.dev                   # Development environment
├── .env.prod                  # Production environment
├── docker-compose.dev.yml     # Development Docker setup
├── docker-compose.prod.yml    # Production Docker setup
└── pyproject.toml            # Project dependencies
```

## Development

### SQLAlchemy Projects

1. **Setup Database**
   ```bash
   cd myproject
   pip install -e .
   alembic upgrade head
   ```

2. **Run Development Server**
   ```bash
   uvicorn app.main:app --reload
   ```

3. **Create Database Migration**
   ```bash
   alembic revision --autogenerate -m "Add new table"
   ```

### Beanie Projects

1. **Setup MongoDB**
   ```bash
   cd myproject
   pip install -e .
   # MongoDB will auto-initialize on first connection
   ```

2. **Run Development Server**
   ```bash
   uvicorn app.main:app --reload
   ```

### Fullstack Projects (Docker)

1. **Start All Services**
   ```bash
   cd myproject
   docker-compose up -d
   ```

2. **Access Services**
   - API: http://localhost:8000
   - API Docs: http://localhost:8000/docs
   - MongoDB: localhost:27017 (Beanie)
   - PostgreSQL: localhost:5432 (SQLAlchemy)
   - Redis: localhost:6379

## Configuration

### Environment Variables

Create a `.env` file in your project root:

```bash
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/dbname  # SQLAlchemy
MONGODB_URL=mongodb://localhost:27017/myproject  # Beanie

# Security
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Redis (fullstack)
REDIS_URL=redis://localhost:6379/0

# Email (optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-password
```

### Database Configuration

#### SQLAlchemy (PostgreSQL)
```bash
# Install PostgreSQL
# Create database
createdb myproject

# Set DATABASE_URL
export DATABASE_URL=postgresql+asyncpg://user:password@localhost/myproject
```

#### Beanie (MongoDB)
```bash
# Install MongoDB
# MongoDB will create database on first connection
export MONGODB_URL=mongodb://localhost:27017/myproject
```

## API Endpoints

Generated projects include these endpoints:

### Authentication
- `POST /auth/jwt/login` - User login
- `POST /auth/jwt/logout` - User logout
- `POST /auth/register` - User registration
- `POST /auth/forgot-password` - Request password reset
- `POST /auth/reset-password` - Reset password

### Users
- `GET /users/me` - Get current user
- `PATCH /users/me` - Update current user
- `GET /users/{id}` - Get user by ID
- `GET /users` - List users (admin only)

### Health Check
- `GET /health` - API health status
- `GET /` - Welcome message

## Testing

Generated projects include testing setup:

```bash
# Run tests
pytest

# Run with coverage
pytest --cov=app tests/

# Run specific test file
pytest tests/test_users.py
```

## Deployment

### Docker Deployment

For fullstack projects:

```bash
# Build and run
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down
```

### Production Deployment

1. **Environment Variables**
   ```bash
   export SECRET_KEY=your-production-secret
   export DATABASE_URL=your-production-db-url
   ```

2. **Gunicorn/Uvicorn**
   ```bash
   gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
   ```

3. **Traefik Reverse Proxy**
   Both templates includes Traefik configuration in `docker-compose.prod.yml`:
   ```yaml
   services:
     traefik:
       image: traefik:v3.0
       command:
         - --api.dashboard=true
         - --providers.docker=true
         - --entrypoints.web.address=:80
         - --entrypoints.websecure.address=:443
         - --certificatesresolvers.letsencrypt.acme.tlschallenge=true
         - --certificatesresolvers.letsencrypt.acme.email=your-email@domain.com
         - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
   ```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Add tests for new functionality
5. Run tests: `pytest`
6. Commit your changes: `git commit -am 'Add feature'`
7. Push to the branch: `git push origin feature-name`
8. Submit a pull request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📖 [Documentation](https://github.com/your-org/fastapi-template/wiki)
- 🐛 [Issue Tracker](https://github.com/your-org/fastapi-template/issues)
- 💬 [Discussions](https://github.com/your-org/fastapi-template/discussions)

## Changelog

### v1.0.0
- Initial release
- SQLAlchemy and Beanie support
- API-only and fullstack project types
- FastAPI-Users integration
- Docker support
- CLI tool
