Metadata-Version: 2.4
Name: stacking-pr
Version: 0.1.0
Summary: A FastAPI application for task management with database integration
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: alembic==1.14.1
Requires-Dist: fastapi==0.115.12
Requires-Dist: psycopg2-binary==2.9.10
Requires-Dist: pydantic==2.10.6
Requires-Dist: SQLAlchemy==2.0.40
Requires-Dist: uvicorn==0.34.2
Provides-Extra: dev
Requires-Dist: black==25.1.0; extra == "dev"
Requires-Dist: flake8==7.2.0; extra == "dev"
Requires-Dist: isort==6.0.1; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest==8.3.4; extra == "test"
Requires-Dist: pytest-cov==6.0.0; extra == "test"
Requires-Dist: httpx==0.28.1; extra == "test"

<!--
SPDX-FileCopyrightText: 2024 Hitesh Arora
SPDX-FileContributor: Hitesh Arora

SPDX-License-Identifier: MIT
-->

<div align="center" markdown="1">
  <br />
  <h1>Stacked PR FastAPI Task Tracker</h1>
  <p>
    A clean, professional-grade backend project built with FastAPI, Docker, PostgreSQL, and SQLAlchemy.
  </p>
  <p>
    Built in a stacked PR workflow, step-by-step, from in-memory to production-ready DB logic.
  </p>

  <!-- Badges -->
  <p>
    <img src="https://github.com/yourname/stacking_pr/workflows/CI%2FCD%20Pipeline/badge.svg" alt="CI/CD Status" />
    <img src="https://img.shields.io/badge/python-3.8%2B-blue" alt="Python 3.8+" />
    <img src="https://img.shields.io/badge/fastapi-0.115.12-009688" alt="FastAPI" />
    <img src="https://img.shields.io/badge/coverage-%3E80%25-brightgreen" alt="Coverage >80%" />
    <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black" />
  </p>

  <a href="#stacked-prs">Stacked PR Structure</a> •
  <a href="#tech-stack">Tech Stack</a> •
  <a href="#testing">Testing</a> •
  <a href="#usage">Usage</a> •
  <a href="#api">API</a> •
  <a href="#ci-cd-pipeline">CI/CD</a>

  <br />
  <br />

</div>

---

## 🌟 Stacked PRs

This repo is structured into clearly defined Pull Requests:

1. **`feat: add Task schema and in-memory task endpoints`**
2. **`feat: integrate PostgreSQL with SQLAlchemy and Alembic`**
3. **`feat: replace in-memory task store with PostgreSQL CRUD`**

Each PR builds cleanly on top of the previous, keeping history modular and understandable.

---

## 🚀 Tech Stack

- **FastAPI**: Web framework
- **SQLAlchemy**: ORM for PostgreSQL
- **Alembic**: Schema migrations
- **Docker + Compose**: Containerized dev environment
- **PostgreSQL**: Relational database
- **Pytest**: Testing framework with coverage
- **GitHub Actions**: CI/CD pipeline
- **Black/isort/flake8**: Code formatting and linting

---

## 📃 Project Structure

```bash
stacking_pr/
├── app/                   # Main application package
│   ├── __init__.py       
│   ├── main.py           # FastAPI app and entrypoint
│   ├── db.py             # Database engine/session
│   ├── dependencies.py   # FastAPI dependencies
│   ├── api/              # API routers
│   │   └── task_router.py
│   ├── models/           # SQLAlchemy models
│   │   └── task.py
│   └── schemas/          # Pydantic schemas
│       └── task.py
├── tests/                # Test suite
│   ├── __init__.py
│   ├── conftest.py       # Shared test fixtures
│   ├── test_main.py      # Main app tests
│   ├── api/              # API endpoint tests
│   ├── models/           # Model tests
│   ├── schemas/          # Schema validation tests
│   └── integration/      # Integration tests
├── alembic/              # Database migrations
├── .github/
│   └── workflows/        # CI/CD pipelines
├── alembic.ini           # Alembic configuration
├── docker-compose.yml    # Docker services
├── Dockerfile            # App containerization
├── pyproject.toml        # Project metadata & config
├── requirements.txt      # Python dependencies
├── Makefile              # Development commands
└── README.md             # Project documentation
```

---

## 🚧 Usage

### ⚡ Run Locally

```bash
git clone https://github.com/yourname/stacking_pr.git
cd stacking_pr

# Build and run containers
make docker

# Run alembic migrations
make migrate

# Follow logs
make logs
```

Open browser:
```
http://localhost:8000/docs
```

To stop:
```bash
make docker-down
```

---

## 📊 API

### Create a Task
```http
POST /tasks
Content-Type: application/json

{
  "id": 1,
  "title": "Stacked PRs FTW!",
  "is_completed": false
}
```

### Get All Tasks
```http
GET /tasks
```

---

## 🧪 Testing

### Running Tests

```bash
# Install test dependencies
pip install -e ".[test,dev]"

# Run all tests
make test

# Run tests with coverage report
make test-cov

# Run specific test file
make test-file

# Run tests matching a pattern
make test-pattern
```

### Test Structure

- **Unit Tests**: Individual component testing
- **API Tests**: FastAPI endpoint testing with TestClient
- **Model Tests**: SQLAlchemy model validation
- **Schema Tests**: Pydantic schema validation
- **Integration Tests**: End-to-end workflow testing

### Coverage

Tests maintain **80% minimum coverage** with HTML reports generated in `htmlcov/`.

---

## 📄 Makefile Commands

```bash
make setup         # Create virtual environment and install dependencies
make install       # Install requirements into venv
make run          # Run FastAPI locally (development)
make test         # Run pytest test suite
make test-cov     # Run tests with coverage report
make test-file    # Run specific test file
make test-pattern # Run tests matching a pattern
make docker       # Start Docker containers
make docker-down  # Stop and remove containers
make migrate      # Run alembic migrations
make logs         # Follow Docker logs
make clean        # Delete venv + __pycache__
make help         # Show all available commands
```

---

## 🚀 CI/CD Pipeline

### GitHub Actions Workflow

The project includes a comprehensive CI/CD pipeline that runs on:
- **Push** to `main` or `develop` branches
- **Pull Requests** to `main` or `develop`
- **Manual dispatch**

#### Pipeline Stages:

1. **Testing Matrix**:
   - Python versions: 3.8, 3.9, 3.10, 3.11
   - PostgreSQL integration testing
   - Code quality checks (Black, isort, flake8)
   - Test coverage reporting

2. **Security Scanning**:
   - Bandit security linting
   - Safety vulnerability checking
   - Security report artifacts

3. **Build & Package**:
   - Python package building
   - Package validation with twine
   - Build artifact uploads

4. **Docker**:
   - Multi-stage Docker builds
   - Container health testing
   - Image validation

### Code Quality Standards

- **Code Formatting**: Black (88 char line length)
- **Import Sorting**: isort (Black compatible)
- **Linting**: flake8 with complexity checks
- **Test Coverage**: Minimum 80% required

---

## ✅ License

This project is licensed under the MIT License.

---

## 💻 Development Workflow

### Getting Started

1. **Clone and Setup**:
   ```bash
   git clone https://github.com/yourname/stacking_pr.git
   cd stacking_pr
   make setup
   ```

2. **Install Dependencies**:
   ```bash
   # Production dependencies
   pip install -e .
   
   # Development dependencies
   pip install -e ".[dev]"
   
   # Test dependencies  
   pip install -e ".[test]"
   
   # All dependencies
   pip install -e ".[dev,test]"
   ```

3. **Run Tests**:
   ```bash
   make test-cov
   ```

4. **Start Development Server**:
   ```bash
   # Local development
   make run
   
   # Docker development
   make docker
   make migrate
   ```

### Development Best Practices

- **Code Formatting**: Run `black app tests` before committing
- **Import Sorting**: Run `isort app tests` before committing  
- **Linting**: Run `flake8 app` to check code quality
- **Testing**: Maintain 80%+ test coverage
- **Commits**: Use conventional commit messages

### Pre-commit Checklist

```bash
black app tests          # Format code
isort app tests          # Sort imports
flake8 app              # Lint code
make test-cov           # Run tests with coverage
```

---

## 🚀 Coming Soon

- 🌐 Deployment configurations (Render/Railway/Docker)
- 📊 Advanced monitoring and logging
- 🔐 Authentication and authorization
- 👁️ Optional frontend in React or HTML
- 📈 Performance optimization guides

---

Made with ❤️ by Hitesh Arora.
