Metadata-Version: 2.4
Name: ningfastforge
Version: 0.1.4
Summary: A modern FastAPI project scaffolding CLI tool
Author-email: ning <ln729500172@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ning3739/forge
Project-URL: Documentation, https://github.com/ning3739/forge#readme
Project-URL: Repository, https://github.com/ning3739/forge
Project-URL: Issues, https://github.com/ning3739/forge/issues
Keywords: fastapi,cli,scaffolding,generator,template
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.21.0
Requires-Dist: rich>=14.0.0
Requires-Dist: questionary>=1.10.0
Requires-Dist: packaging>=21.0
Dynamic: license-file

<div align="center">
  <img src="assets/logo.png" alt="Forge Logo" width="480"/>
</div>

<br/>

<div align="center">

[![PyPI version](https://badge.fury.io/py/ningfastforge.svg)](https://badge.fury.io/py/ningfastforge)
[![Python Versions](https://img.shields.io/pypi/pyversions/ningfastforge.svg)](https://pypi.org/project/ningfastforge/)
[![Downloads](https://static.pepy.tech/badge/ningfastforge)](https://pepy.tech/project/ningfastforge)
[![Downloads per month](https://static.pepy.tech/badge/ningfastforge/month)](https://pepy.tech/project/ningfastforge)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

---

Forge is a powerful command-line tool that helps you quickly bootstrap production-ready FastAPI projects with best practices, intelligent defaults, and a beautiful interactive interface.

## ✨ Features

- 🎨 **Beautiful Interactive UI** - Stunning terminal interface with gradient colors and smooth animations
- 🚀 **Smart Presets** - Carefully curated presets for testing, dev tools, deployment, and monitoring
- 🔐 **Authentication Ready** - Built-in support for JWT authentication (Basic & Complete)
- 🗄️ **Database Flexibility** - Support for PostgreSQL and MySQL with SQLModel/SQLAlchemy
- 📦 **Modular Architecture** - Choose only the features you need
- 🧪 **Testing Built-in** - Pre-configured pytest with async support and coverage
- 🐳 **Docker Ready** - Production-ready Docker and Docker Compose configurations
- 🔍 **Type Safe** - Full type hints throughout generated code
- ⚡ **Async First** - Optimized for FastAPI's async capabilities

## 📋 Requirements

- Python 3.9+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

## 🚀 Quick Start

### Installation

#### From PyPI (Recommended)

```bash
pip install ningfastforge
```

#### Upgrade to Latest Version

If you already have Forge installed, upgrade to the latest version:

```bash
pip install --upgrade ningfastforge
```

> 💡 **Tip**: Always use the latest version to get new features, bug fixes, and security updates!

#### From Source

```bash
# Clone the repository
git clone https://github.com/ning3739/forge.git
cd forge

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .
```

### Verify Installation

Check that Forge is installed correctly and see the current version:

```bash
forge --version
```

### Create Your First Project

```bash
# Interactive mode (recommended)
forge init

# Or specify project name
forge init my-awesome-api

# Non-interactive mode with defaults
forge init my-api --no-interactive
```

### Run Your Project

```bash
cd my-awesome-api
uv sync
uv run uvicorn app.main:app --reload
# Visit:
http://127.0.0.1:8000/docs # docs
http://127.0.0.1:8000/redoc #redoc
```

## 🏗️ Architecture

Forge follows a **"Configuration-First"** design principle with a **dynamic generator system**:

1. **Init Command** collects user preferences interactively
2. **Configuration File** (`.forge/config.json`) is saved first
3. **Dynamic Generator System** automatically discovers and executes generators based on configuration

### Dynamic Generator System

Forge uses a decorator-based system for automatic generator discovery and management:

```python
@Generator(
    category="model",
    priority=40,
    requires=["DatabaseConnectionGenerator"],
    enabled_when=lambda c: c.has_auth()
)
class UserModelGenerator:
    def generate(self):
        # Generate user model code
```

**Benefits:**
- ✅ Automatic generator discovery - no manual registration needed
- ✅ Dependency resolution - generators execute in correct order
- ✅ Conditional execution - only enabled generators run
- ✅ Easy extensibility - add new generators by creating files

This separation ensures:

- ✅ Configuration persistence and traceability
- ✅ Clear separation of concerns
- ✅ Easy project regeneration and updates
- ✅ Configuration sharing and templates
- ✅ Modular and maintainable codebase

## 🎯 Configuration Options

### Database Options

- **PostgreSQL** (Recommended) - Robust, feature-rich, excellent for production
- **MySQL** - Popular, widely supported relational database

### ORM Support

- **SQLModel** (Recommended) - Modern, type-safe ORM built on SQLAlchemy and Pydantic
- **SQLAlchemy** - Mature and powerful ORM with extensive features

### Authentication & Security

#### Authentication Options

- **Complete JWT Auth** (Recommended) - Full-featured authentication system
  - Login & Register
  - Email Verification
  - Password Reset (Forgot Password)
  - Email Service (SMTP)
  - Refresh Token
- **Basic JWT Auth** - Simple authentication
  - Login & Register only
  - Optional Refresh Token

#### Security Features

- CORS (Configurable)
- Rate Limiting (Built-in decorator - auto-included)
- Input Validation (Pydantic - auto-included)
- Password Hashing (bcrypt - auto-included with auth)
- SQL Injection Protection (ORM - auto-included)
- XSS Protection (FastAPI - auto-included)

### Core Features

All projects include:

- **Logging** - Structured logging (automatically included)
- **API Documentation** - Swagger UI and ReDoc (automatically included)
- **Health Check** - Basic health check endpoint (automatically included)
- **Rate Limiting** - Decorator-based rate limiting for API protection (automatically included)

### Development Tools

- **Standard** (Recommended) - Black (formatter) + Ruff (linter)
- **None** - Skip dev tools

### Testing Setup

When you enable testing, Forge generates:

- **pytest** - Testing framework with async support
- **httpx** - HTTP client for testing
- **pytest-cov** - Code coverage
- **pytest-asyncio** - Async test support

**Generated Test Files:**

- `tests/conftest.py` - Pytest configuration with database fixtures
- `tests/test_main.py` - Tests for main API endpoints (health check, docs)
- `tests/api/test_auth.py` - Authentication endpoint tests
- `tests/api/test_users.py` - User endpoint tests

**Running Tests:**

```bash
# Run all tests
pytest

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

# Run specific test file
pytest tests/test_main.py

# Run with verbose output
pytest -v
```

### Deployment

- **Docker** - Dockerfile and docker-compose.yml
- Includes database service configuration
- Production-ready setup

## 📁 Generated Project Structure

```
my-awesome-api/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI application entry point
│   ├── core/
│   │   ├── config/          # Configuration management
│   │   │   ├── base.py      # Base configuration
│   │   │   ├── settings.py  # Settings aggregator
│   │   │   └── modules/     # Config modules (app, database, jwt, cors, email, logger)
│   │   ├── database/        # Database connection
│   │   │   ├── connection.py
│   │   │   ├── dependencies.py
│   │   │   └── postgresql.py / mysql.py
│   │   ├── deps.py          # Global dependencies
│   │   ├── logger.py        # Logging configuration
│   │   └── security.py      # Security utilities (password hashing, JWT)
│   ├── decorators/          # Custom decorators
│   │   └── rate_limit.py    # Rate limiting decorator
│   ├── models/              # Database models
│   │   ├── user.py
│   │   └── token.py         # (if refresh token enabled)
│   ├── schemas/             # Pydantic schemas
│   │   ├── user.py
│   │   └── token.py
│   ├── crud/                # CRUD operations
│   │   ├── user.py
│   │   └── token.py         # (if refresh token enabled)
│   ├── services/            # Business logic
│   │   └── auth.py
│   ├── routers/             # API routes
│   │   └── v1/              # API version 1
│   │       ├── __init__.py  # Router aggregator
│   │       ├── auth.py
│   │       └── users.py
│   └── utils/               # Utility functions
│       └── email.py         # (if complete auth enabled)
├── tests/                   # Test files (if enabled)
│   ├── conftest.py          # Pytest configuration and fixtures
│   ├── test_main.py         # Main API endpoint tests
│   ├── api/
│   │   ├── test_auth.py     # Authentication tests
│   │   └── test_users.py    # User endpoint tests
│   └── unit/                # Unit tests directory
├── alembic/                 # Database migrations (if enabled)
│   ├── versions/            # Migration versions
│   ├── env.py               # Alembic environment
│   ├── script.py.mako       # Migration template
│   └── README.md
├── static/                  # Static files
│   └── email_template/      # Email templates (if complete auth)
│       ├── base.html
│       ├── verification.html
│       ├── password_reset.html
│       └── welcome.html
├── secret/                  # Environment files
│   ├── .env.example         # Environment variables template
│   ├── .env.development     # Development environment
│   └── .env.production      # Production environment
├── docker-compose.yml       # Docker Compose configuration (if enabled)
├── Dockerfile               # Docker configuration (if enabled)
├── .dockerignore            # Docker ignore file (if enabled)
├── .gitignore               # Git ignore file
├── pyproject.toml           # Project dependencies
├── uv.lock                  # UV lock file
└── README.md                # Project documentation
```

## 🎨 Smart Features

### Intelligent Defaults

- **Database**: PostgreSQL with SQLModel
- **Migration**: Alembic enabled
- **Authentication**: Complete JWT Auth with Refresh Token
- **Security**: CORS enabled
- **Dev Tools**: Black + Ruff
- **Testing**: pytest with coverage
- **Deployment**: Docker + Docker Compose

### Technology Recommendations

- **PostgreSQL** for database (production-ready, feature-rich)
- **SQLModel** for ORM (modern, type-safe, FastAPI-friendly)
- **JWT** for authentication (stateless, scalable, API-friendly)
- **Alembic** for migrations (industry standard)

## 🛠️ Commands

### `forge init`

Initialize a new FastAPI project with interactive prompts.

```bash
# Interactive mode
forge init

# Specify project name
forge init my-project

# Non-interactive mode (uses defaults)
forge init my-project --no-interactive
```

### `forge --version`

Show the current version of Forge.

```bash
forge --version
# or
forge -v
```

## 🎯 Best Practices

### For API Projects

```
✅ PostgreSQL + SQLModel
✅ Complete JWT Auth
✅ CORS enabled
✅ Black + Ruff
✅ pytest with coverage
✅ Docker deployment
```

### For Simple Projects

```
✅ PostgreSQL + SQLModel
✅ Basic JWT Auth (or no auth)
✅ CORS enabled
✅ Docker deployment
```

## 📂 Project Structure

```
Forge/
├── commands/              # CLI command modules
│   ├── __init__.py       # Command exports
│   └── init.py           # Project initialization command
├── core/                 # Core business logic
│   ├── decorators/       # Decorator system
│   │   └── generator.py  # @Generator decorator and registry
│   ├── config_reader.py  # Configuration file reader
│   ├── project_generator.py  # Project generator
│   ├── generators/       # Code generators
│   │   ├── structure.py  # Project structure generator
│   │   ├── orchestrator.py  # Dynamic generator coordinator
│   │   ├── configs/      # Config file generators
│   │   ├── deployment/   # Deployment config generators
│   │   └── templates/    # Application code generators
│   └── utils/            # Utility functions
├── ui/                   # User interface components
│   ├── colors.py         # Color management system
│   ├── components.py     # UI components
│   └── logo.py           # Logo rendering
├── main.py               # CLI entry point
├── pyproject.toml        # Project configuration
└── README.md             # This file
```

### Key Components

- **`@Generator` Decorator** - Automatic generator registration system
- **`orchestrator.py`** - Discovers and executes generators in correct order
- **40+ Generators** - Each responsible for specific files/features
- **Configuration-First** - All decisions driven by `.forge/config.json`

## 🤝 Contributing

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

### Development Setup

```bash
# Clone the repository
git clone https://github.com/ning3739/forge.git
cd forge

# Install dependencies
uv sync

# Test build
./scripts/test_build.sh
```

## Publishing

### Automated Release Process

The project uses automated publishing via GitHub Actions:

1. **Update version** in `pyproject.toml`
2. **Update** `CHANGELOG.md` with changes
3. **Commit and push**:
   ```bash
   git add pyproject.toml CHANGELOG.md
   git commit -m "Bump version to 0.1.1"
   git push
   ```
4. **Create and push tag**:
   ```bash
   git tag v0.1.1
   git push origin v0.1.1
   ```
5. **Automatic process**:
   - ✅ CI tests run on all Python versions
   - ✅ Package is built and validated
   - ✅ Published to PyPI automatically
   - ✅ GitHub Release is created

See [PUBLISHING.md](PUBLISHING.md) for detailed instructions.

## 📝 License

[MIT License](LICENSE)

## 🎉 Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.

## 🙏 Acknowledgments

Built with:

- [FastAPI](https://fastapi.tiangolo.com/) - Modern, fast web framework
- [Typer](https://typer.tiangolo.com/) - CLI framework
- [Rich](https://rich.readthedocs.io/) - Beautiful terminal output
- [Questionary](https://questionary.readthedocs.io/) - Interactive prompts

## 📧 Support

For issues, questions, or suggestions, please open an issue on GitHub.

---

Made with ❤️ for the FastAPI community
