prozes 1.1.1

Professional Python project generator - CLI tool for scaffolding production-ready applications

Prozes

Professional Python Project Generator

A powerful CLI tool for scaffolding production-ready Python applications. Stop wasting time on boilerplate. Start building features from day one.

Installation • Quick Start • Documentation • Examples • Contributing

---

Overview

Prozes is a command-line project generator that creates production-ready Python applications with enterprise-grade architectures. Whether you're building a web application, REST API, CLI tool, or following Clean Architecture principles, Prozes provides the scaffolding you need to start coding immediately.

Type: CLI Tool / Project Generator (not a framework or library) Usage: Run prozes commands to generate project structures - no imports needed

Why Prozes?

• Battle-Tested Architectures: MVC, REST API, CLI, and Clean Architecture patterns
• Framework Agnostic: Works with Flask, FastAPI, and more
• Production-Ready: Includes logging, environment variables, real tests, and CI/CD
• Zero Configuration: Sensible defaults that work out of the box
• Best Practices Included: Testing setup, linting, Git integration, and virtual environments
• Bilingual Support: Full internationalization (English and Portuguese)
• Beautiful CLI: Rich terminal output with progress indicators and helpful messages

---

Table of Contents

• Installation
• Quick Start
• Key Features
• Architecture Types
• Authentication
• Usage
• Examples
• Configuration
• Development
• Roadmap
• Contributing
• License

---

Installation

Via pip (Recommended)

pip install prozes

From Source

git clone https://github.com/jaopdc11/prozes.git
cd prozes
pip install -e .

Verify Installation

prozes --version  # Should show 1.0.0
prozes --help

---

Quick Start

Get up and running in 30 seconds:

# Create a FastAPI REST API with JWT authentication
prozes api my_api --type fastapi --auth jwt --venv --git --install-deps

cd my_api
cp .env.example .env  # Configure your JWT_SECRET_KEY
source venv/bin/activate  # or venv\Scripts\activate on Windows
uvicorn main:app --reload

That's it! Your API is running at http://localhost:8000 with:

• ✅ Auto-generated docs at /docs
• ✅ JWT authentication ready
• ✅ User registration and login endpoints
• ✅ Protected routes

Other Quick Examples

# MVC web application with Flask and Session auth
prozes mvc blog --type web-flask --auth session --venv --git

# API with Basic authentication
prozes api internal --type fastapi --auth basic --venv --git

# Clean Architecture with OAuth2
prozes clean backend --type fastapi --auth oauth2 --venv --git

---

Key Features

🏗️ Multiple Architectures MVC (Model-View-Controller) REST API CLI Applications Clean Architecture ⚡ Framework Support Flask FastAPI Click (for CLI) 🔧 Development Tools Automatic virtual environment creation Git initialization Dependency installation Testing scaffolding 🔐 Authentication JWT (Token-based) Session (Cookie-based) Basic (HTTP Basic Auth) OAuth2 (Third-party)

🌍 Internationalization English (default) Portuguese (pt) Easily extensible 📦 Production Ready Environment variables (.env.example) Logging configuration Real test cases (not placeholders) Separate dev dependencies CI/CD with GitHub Actions Configuration management 🎨 Developer Experience Beautiful CLI with Rich library Progress indicators Colored output Verbose mode for debugging

---

Architecture Types

🌐 MVC (Model-View-Controller)

Perfect for web applications with server-side rendering.

prozes mvc my_webapp --type web-flask --venv --git

Includes:

• Separate concerns: Models, Views, Controllers
• Template engine setup
• Static files organization
• Configuration management

Use cases: Traditional web apps, admin panels, dashboards

---

🔌 REST API

Lean and focused API without frontend bloat.

prozes api my_api --type fastapi --venv --git

Includes:

• RESTful route structure
• Data models and schemas
• Request/response handling
• Auto-generated API documentation (FastAPI)

Use cases: Backend services, mobile app APIs, microservices

---

💻 CLI Application

Command-line tools using Click framework.

prozes cli my_tool --venv --git

Includes:

• Command structure
• Argument parsing
• Configuration handling
• Distribution setup (setup.py)

Use cases: DevOps tools, automation scripts, data processing

---

🏛️ Clean Architecture

Enterprise-grade architecture with clear separation of concerns.

prozes clean my_project --type fastapi --venv --git

Includes:

• Entities (Domain layer)
• Use Cases (Business logic)
• Adapters (Interfaces)
• Frameworks (External dependencies)

Use cases: Large applications, microservices, long-term projects

---

Usage

Command Syntax

prozes <architecture> <project_name> [options]

Common Options

All commands support these options:

Option	Description	Default
--venv	Create virtual environment	false
--git	Initialize Git repository	false
--python-version	Python version for venv	System default
--install-deps	Install dependencies	false
--auth	Authentication type (none, jwt, session, basic, oauth2)	none
-v, --verbose	Verbose output	false
-L, --lang	Language (en, pt, es, it, fr)	Config or en

Architecture-Specific Options

MVC & API Commands

-t, --type   Framework type (web-flask, web-fastapi, flask, fastapi)

Configuration Command

prozes config --lang pt           # Set default language
prozes config --show              # Show current configuration

Generated Project Structure

MVC Project

my_webapp/
├── .github/
│   └── workflows/       # CI/CD pipelines
├── app/
│   ├── controllers/     # Request handlers
│   ├── models/          # Data models
│   ├── views/           # View logic
│   ├── templates/       # HTML templates
│   └── static/          # CSS, JS, images
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/               # Test suite with real tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
├── .env.example         # Environment variables template
└── .gitignore          # Git ignore rules

API Project

my_api/
├── .github/workflows/   # CI/CD pipelines
├── app/
│   ├── auth/            # Authentication (if --auth specified)
│   │   ├── models.py    # User model
│   │   ├── routes.py    # Auth endpoints
│   │   ├── utils.py     # Password hashing, tokens
│   │   ├── storage.py   # User storage
│   │   └── config.py    # Auth configuration
│   ├── models/          # Data models
│   └── routes/          # API endpoints
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/
│   ├── auth/            # Auth tests (if --auth specified)
│   └── test_api.py      # API tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies (with auth deps)
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
└── .env.example         # Environment variables (with auth vars)

CLI Project

my_tool/
├── .github/workflows/   # CI/CD pipelines
├── my_tool/
│   ├── commands/        # CLI commands
│   └── main.py          # Entry point
├── tests/               # Test suite with Click runner tests
├── setup.py             # Distribution setup
├── pyproject.toml       # Project metadata + pytest config
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
└── .env.example         # Environment variables template

Clean Architecture Project

my_project/
├── .github/workflows/   # CI/CD pipelines
├── src/
│   ├── entities/        # Domain entities
│   ├── use_cases/       # Business logic
│   ├── adapters/        # Interfaces & repositories
│   └── frameworks/      # External dependencies
├── config/
│   ├── __init__.py      # Configuration
│   └── logging.py       # Logging setup
├── tests/
│   ├── unit/            # Unit tests for use cases
│   └── integration/     # Integration tests
├── main.py              # Entry point
├── requirements.txt     # Production dependencies
├── requirements-dev.txt # Development dependencies
├── pyproject.toml       # Pytest configuration
└── .env.example         # Environment variables template

---

🔐 Authentication

Prozes includes production-ready authentication support for all project types. Choose from 4 authentication strategies:

JWT (JSON Web Tokens)

Token-based authentication with access and refresh tokens.

prozes api my_api --type fastapi --auth jwt --venv --install-deps

Features:

• Access tokens (30min expiration)
• Refresh tokens (7 days expiration)
• Stateless authentication
• Ideal for APIs and SPAs

Endpoints:

• POST /auth/register - Register new user
• POST /auth/login - Login and get tokens
• POST /auth/refresh - Refresh access token
• GET /auth/me - Get current user (protected)
• POST /auth/logout - Logout

Session Authentication

Cookie-based authentication with server-side sessions.

prozes mvc my_app --type web-flask --auth session --venv

Features:

• HTTPOnly cookies
• Server-side session storage
• 7 days expiration
• Ideal for traditional web apps

Endpoints:

• POST /auth/register - Register and create session
• POST /auth/login - Login and create session
• GET /auth/me - Get current user (protected)
• POST /auth/logout - Logout and destroy session

Basic Authentication

Simple HTTP Basic Auth with username and password.

prozes api internal_api --type fastapi --auth basic --venv

Features:

• Username/password authentication
• WWW-Authenticate headers
• Simple and lightweight
• Ideal for internal APIs

Endpoints:

• POST /auth/register - Register new user
• GET /auth/me - Get current user (requires Basic Auth)

OAuth2

Third-party authentication (Google, GitHub, etc).

prozes api oauth_app --type fastapi --auth oauth2 --venv

Features:

• OAuth2 flow integration
• Automatic user creation
• Support for multiple providers
• Ideal for social login

Endpoints:

• GET /auth/login - Redirect to OAuth provider
• GET /auth/callback - OAuth callback handler
• GET /auth/me - Get current user (protected)
• POST /auth/logout - Logout

What You Get

All authentication types include:

✅ User Model - Ready-to-use User dataclass ✅ Password Hashing - Bcrypt with automatic salting ✅ Storage - In-memory storage (replace with DB for production) ✅ Protected Routes - Middleware/dependencies ready ✅ Tests - Comprehensive test suite ✅ Environment Variables - Pre-configured in .env.example ✅ Auto Dependencies - All packages auto-added to requirements.txt

Quick Example

# 1. Create API with JWT auth
prozes api secure_api --type fastapi --auth jwt --venv --install-deps

# 2. Configure
cd secure_api
cp .env.example .env
# Edit .env and set JWT_SECRET_KEY

# 3. Run
uvicorn main:app --reload

# 4. Test
curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","email":"[e-mail]","password":"secret123"}'

# 5. Access protected route
curl http://localhost:8000/auth/me \
  -H "Authorization: Bearer <your-token>"

Security Features

• ✅ Bcrypt password hashing
• ✅ Automatic salt generation
• ✅ Token expiration (JWT)
• ✅ Session expiration
• ✅ HTTPOnly cookies (Session)
• ✅ User active status check
• ✅ Duplicate prevention

Production Notes

⚠️ Important: Generated projects use in-memory storage for quick development. For production:

1. Replace app/auth/storage.py with database implementation
2. Use PostgreSQL, MongoDB, or your preferred database
3. Set strong secrets in .env (32+ characters)
4. Enable HTTPS
5. Consider rate limiting for auth endpoints

📚 Documentation:

• Quick Start Guide
• Testing Guide
• Implementation Details

---

Examples

1. Blog Application (MVC + Flask)

Build a full-featured blog with Flask:

# Generate the project
prozes mvc blog --type web-flask --venv --git --install-deps -v

# Start development
cd blog
source venv/bin/activate  # Windows: venv\Scripts\activate
python main.py

# Visit http://localhost:5000

What you get:

• MVC structure with controllers, models, and views
• Template system ready
• Static files organized
• Development server configured
• Real tests for routes and application
• Logging configured
• CI/CD pipeline ready

---

2. User Management API with Authentication (FastAPI)

Create a modern API with auth and auto-generated documentation:

# Generate the project with JWT authentication
prozes api user_service --type fastapi --auth jwt --venv --git --install-deps

# Configure
cd user_service
cp .env.example .env
# Edit .env and set JWT_SECRET_KEY

# Start the server
source venv/bin/activate
uvicorn main:app --reload

# Interactive docs at http://localhost:8000/docs

What you get:

• RESTful endpoints structure
• Complete JWT authentication system
• User registration and login
• Protected routes with token validation
• Pydantic models for validation
• Automatic OpenAPI documentation (FastAPI)
• Real API tests with test client (including auth tests)
• Health check endpoint
• Logging configured
• CI/CD pipeline ready

---

3. DevOps CLI Tool

Build a distributable command-line tool:

# Generate the project
prozes cli devops-tools --venv --git --install-deps

# Install in development mode
cd devops-tools
pip install -e .

# Use your CLI
devops-tools --help
devops-tools deploy --env production

What you get:

• Click framework integrated
• Command structure ready
• Configuration management
• Package ready for PyPI
• Tests with Click runner
• CI/CD pipeline ready

---

4. Microservice (Clean Architecture + FastAPI)

Enterprise-grade microservice with Clean Architecture:

# Generate the project
prozes clean payment-service --type fastapi --venv --git --install-deps

# Run tests
cd payment-service
pytest tests/ -v

# Start the service
uvicorn main:app --reload

What you get:

• Separated layers (entities, use cases, adapters, frameworks)
• Dependency injection examples
• Testability built-in (unit + integration tests)
• Dependency inversion principle applied
• Repository pattern implemented
• Ready for complex business logic

---

Configuration

Global Configuration

Set your preferences globally:

# Set default language to Portuguese
prozes config --lang pt

# View current configuration
prozes config --show

Per-Project Configuration

Each generated project includes:

• config/ directory for environment-specific settings
• .env.example for environment variables (where applicable)
• requirements.txt with pinned dependencies

---

Documentation

• PyPI Package: pypi.org/project/prozes
• GitHub Repository: github.com/jaopdc11/prozes
• Issue Tracker: GitHub Issues
• Changelog: CHANGELOG.md

For detailed command information:

prozes --help
prozes mvc --help    # Help for specific commands
prozes api --help
prozes cli --help
prozes clean --help

---

Roadmap

We have ambitious plans for Prozes. Check out our ROADMAP.md to see what's coming:

• ✅ Authentication scaffolding DONE (JWT, Session, Basic, OAuth2)
• 🔌 Plugin system for custom templates
• 🐳 Docker integration
• 🗄️ Database templates (PostgreSQL, MongoDB, etc.)
• 🌐 More frameworks (Django, Tornado, Sanic)
• 🏗️ More architectures (Hexagonal, CQRS, Event-Driven)

View Full Roadmap →

---

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/jaopdc11/prozes.git
cd prozes

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=prozes --cov-report=html

# Run specific test file
pytest tests/test_core.py -v

Code Quality

# Format code
black prozes tests

# Lint code
ruff check prozes tests

# Type checking
mypy prozes

# Run all checks (what CI runs)
pre-commit run --all-files

See CONTRIBUTING.md for detailed guidelines.

---

Contributing

We welcome contributions! Here's how you can help:

• 🐛 Report bugs via GitHub Issues
• 💡 Suggest features through GitHub Discussions
• 📝 Improve documentation
• 🔧 Submit pull requests

Please read our Contributing Guide before submitting PRs.

Contributors

Thanks to all our contributors!

---

Community

• GitHub Discussions: Ask questions and share ideas
• Issues: Report bugs
• Discord: [Coming Soon]
• Twitter: [Coming Soon]

---

License

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

---

Acknowledgments

Built with:

• Click - Command line interface
• Rich - Beautiful terminal output
• Flask & FastAPI - Web frameworks

Inspired by:

• Cookiecutter
• Vue CLI
• Create React App

---

⬆ Back to Top

Made with ❤️ by jaopdc11 & mednick-sys

If you find this project useful, please consider giving it a ⭐️