first commit 🚀

Author: luchog01

.env.example

@@ -0,0 +1,9 @@
+# Application Settings
+PROJECT_NAME=Hero API
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/heroes
+DEBUG=true
+
+# JWT Settings
+JWT_SECRET=your-secret-key-change-in-production
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION=30

.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "0.5.8"
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "pyproject.toml"
+        
+    - name: Install the project
+      run: uv sync --all-extras
+
+    - name: Check imports with isort
+      run: uv run isort --check-only --diff .
+
+    - name: Check code formatting with black
+      run: uv run black --check .
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        version: "0.5.8"
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: "pyproject.toml"
+        
+    - name: Install the project
+      run: uv sync --all-extras
+        
+    - name: Run tests
+      run: uv run pytest tests
+      env:
+        DATABASE_URL: "postgresql+asyncpg://postgres:postgres@localhost:5432/test_db"
+        SECRET_KEY: "test_secret_key"
+        ALGORITHM: "HS256"
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test_db
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5

.python-version

@@ -0,0 +1 @@
+3.12

.vscode/launch.json

@@ -0,0 +1,59 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "FastAPI: Debug",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "api.main:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000",
+                "--reload"
+            ],
+            "jinja": true,
+            "justMyCode": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        },
+        {
+            "name": "FastAPI: Run with Reload",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "api.main:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000",
+                "--reload"
+            ],
+            "jinja": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        },
+        {
+            "name": "FastAPI: Run without Reload",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "api.main:app",
+                "--host",
+                "0.0.0.0",
+                "--port",
+                "8000"
+            ],
+            "jinja": true,
+            "env": {
+                "PYTHONPATH": "${workspaceFolder}"
+            }
+        }
+    ]
+}

README.md

@@ -0,0 +1,100 @@
+# Hero API
+
+A FastAPI-based CRUD application for managing heroes, following best practices and modern Python async patterns.
+
+## Features
+
+- Full CRUD operations for heroes
+- Async SQLAlchemy with PostgreSQL
+- Alembic migrations
+- Clean architecture with repository pattern
+- Custom exception handling
+- Type hints and documentation
+
+## Project Structure
+
+```
+app/
+├── core/
+│   ├── config.py      # Application configuration
+│   └── database.py    # Database setup and session management
+├── heroes/
+│   ├── exceptions.py  # Custom exceptions
+│   ├── models.py      # SQLAlchemy models
+│   ├── repository.py  # Database operations
+│   ├── routes.py      # API endpoints
+│   ├── schemas.py     # Pydantic models
+│   └── service.py     # Business logic
+└── main.py           # FastAPI application setup
+```
+
+## Requirements
+
+- Python 3.8+
+- PostgreSQL
+- Dependencies listed in requirements.txt
+
+## Setup
+
+1. Create a virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+venv\Scripts\activate     # Windows
+```
+
+2. Install dependencies:
+```bash
+pip install -r requirements.txt
+```
+
+3. Create PostgreSQL database:
+```sql
+CREATE DATABASE hero_db;
+```
+
+4. Set up environment variables (or create .env file):
+```
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/hero_db
+```
+
+5. Run database migrations:
+```bash
+alembic upgrade head
+```
+
+6. Start the application:
+```bash
+uvicorn app.main:app --reload
+```
+
+## API Endpoints
+
+- `GET /heroes` - List all heroes
+- `GET /heroes/{id}` - Get a specific hero
+- `POST /heroes` - Create a new hero
+- `PATCH /heroes/{id}` - Update a hero
+- `DELETE /heroes/{id}` - Delete a hero
+
+## Example Usage
+
+Create a new hero:
+```bash
+curl -X POST "http://localhost:8000/heroes/" -H "Content-Type: application/json" -d '{
+    "name": "Peter Parker",
+    "alias": "Spider-Man",
+    "powers": "Wall-crawling, super strength, spider-sense"
+}'
+```
+
+## Development
+
+To create a new database migration:
+```bash
+alembic revision --autogenerate -m "description"
+```
+
+To apply migrations:
+```bash
+alembic upgrade head
+```

alembic.ini

@@ -0,0 +1,37 @@
+[alembic]
+script_location = alembic
+sqlalchemy.url = postgresql+asyncpg://postgres:postgres@localhost:5432/hero_db
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = INFO
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = ERROR
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = ERROR
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

alembic/env.py

@@ -0,0 +1,79 @@
+import asyncio
+import os
+import sys
+from logging.config import fileConfig
+
+# Add the project root directory to the Python path
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from sqlalchemy import pool
+from sqlalchemy.engine import Connection
+from sqlalchemy.ext.asyncio import async_engine_from_config
+
+from alembic import context
+from api.core.config import settings
+
+# Import your models here
+from api.core.database import Base
+
+# this is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set sqlalchemy.url
+config.set_main_option("sqlalchemy.url", settings.DATABASE_URL)
+
+# Add your model's MetaData object here for 'autogenerate' support
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def do_run_migrations(connection: Connection) -> None:
+    context.configure(connection=connection, target_metadata=target_metadata)
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+async def run_async_migrations() -> None:
+    """In this scenario we need to create an Engine
+    and associate a connection with the context."""
+
+    connectable = async_engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    async with connectable.connect() as connection:
+        await connection.run_sync(do_run_migrations)
+
+    await connectable.dispose()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+
+    asyncio.run(run_async_migrations())
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}