fastapi-auth-starter 0.1.3__py3-none-any.whl

fastapi_auth_starter/__init__.py

@@ -0,0 +1,7 @@
+"""
+FastAPI Auth Starter Package
+A reusable FastAPI starter template with authentication
+"""
+
+__version__ = "0.1.3"
+

fastapi_auth_starter/cli.py

@@ -0,0 +1,326 @@
+"""
+CLI tool for scaffolding new FastAPI projects from this starter template
+Reference: https://docs.python.org/3/library/argparse.html
+"""
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+
+def get_template_files() -> list[Path]:
+    """
+    Get list of template files to copy when scaffolding a new project.
+    
+    Returns paths relative to the package root that should be included.
+    """
+    # Files and directories to include in the template
+    # These are relative to the project root
+    # Note: fastapi_auth_starter/ is excluded - it's only for the package itself
+    template_files = [
+        "app",
+        "alembic",
+        "alembic.ini",
+        "pyproject.toml",
+        "README.md",
+        "runtime.txt",
+        "vercel.json",
+        ".gitignore",  # Include .gitignore if it exists
+    ]
+    
+    # Convert to Path objects
+    return [Path(f) for f in template_files]
+
+
+def copy_template_files(source_dir: Path, dest_dir: Path, project_name: str) -> None:
+    """
+    Copy template files from source to destination, customizing as needed.
+    
+    Args:
+        source_dir: Source directory containing template files
+        dest_dir: Destination directory for new project
+        project_name: Name of the new project (for customization)
+    """
+    template_files = get_template_files()
+    
+    # Create destination directory
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    
+    # Copy each file/directory
+    for item in template_files:
+        source_path = source_dir / item
+        dest_path = dest_dir / item
+        
+        if not source_path.exists():
+            # Skip silently for optional files like .gitignore
+            if item != ".gitignore":
+                print(f"Warning: Template file {item} not found, skipping...")
+            continue
+        
+        # Explicitly exclude the package directory
+        if item == "fastapi_auth_starter":
+            continue
+        
+        if source_path.is_dir():
+            # Copy directory recursively, excluding __pycache__ and .pyc files
+            shutil.copytree(
+                source_path, 
+                dest_path, 
+                dirs_exist_ok=True,
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.pyo")
+            )
+        else:
+            # Copy file
+            shutil.copy2(source_path, dest_path)
+    
+    # Create a clean pyproject.toml for standalone application
+    pyproject_path = dest_dir / "pyproject.toml"
+    if pyproject_path.exists():
+        # Read original to extract dependencies
+        original_content = pyproject_path.read_text()
+        
+        # Extract dependencies from original
+        import re
+        deps_match = re.search(r'dependencies = \[(.*?)\]', original_content, re.DOTALL)
+        dev_deps_match = re.search(r'\[project\.optional-dependencies\]\s+dev = \[(.*?)\]', original_content, re.DOTALL)
+        
+        dependencies = deps_match.group(1).strip() if deps_match else ""
+        dev_dependencies = dev_deps_match.group(1).strip() if dev_deps_match else ""
+        
+        # Sanitize project name
+        sanitized_name = project_name.lower().replace(" ", "_").replace("-", "_")
+        
+        # Create clean pyproject.toml for standalone application
+        clean_content = f"""[project]
+name = "{sanitized_name}"
+version = "0.1.0"
+description = "FastAPI application"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+{dependencies}
+]
+
+# Development dependencies
+[project.optional-dependencies]
+dev = [
+{dev_dependencies}
+]
+"""
+        pyproject_path.write_text(clean_content)
+    
+    print(f"✓ Created new FastAPI project: {dest_dir}")
+
+
+def find_package_root() -> Path:
+    """
+    Find the root directory containing template files.
+    
+    When installed as a package, template files are in the package's shared-data.
+    In development mode, they're in the project root.
+    """
+    try:
+        # First, try development mode (current file's parent's parent)
+        package_file = Path(__file__).resolve()
+        dev_root = package_file.parent.parent
+        
+        # Check if we're in development mode
+        if (dev_root / "app").exists() and (dev_root / "alembic").exists():
+            return dev_root
+        
+        # Debug: Print where we're looking
+        print(f"Debug: Package file location: {package_file}", file=sys.stderr)
+        print(f"Debug: Package directory: {package_file.parent}", file=sys.stderr)
+        print(f"Debug: Package parent (site-packages): {package_file.parent.parent}", file=sys.stderr)
+        
+        # If installed as a package, template files are in shared-data
+        # Hatchling places shared-data files in the package's installation directory
+        # We need to find where the package is installed and look for shared-data
+        try:
+            import site
+            import sysconfig
+            
+            # Get all possible site-packages locations
+            site_dirs = site.getsitepackages()
+            if hasattr(site, 'getsitepackages'):
+                # Also check user site-packages
+                try:
+                    user_site = site.getusersitepackages()
+                    if user_site:
+                        site_dirs.append(user_site)
+                except AttributeError:
+                    pass
+            
+            # Also check where this package is actually installed
+            # The package is at fastapi_auth_starter/__init__.py, so parent is fastapi_auth_starter/
+            package_location = Path(__file__).parent
+            package_parent = package_location.parent  # This is site-packages or similar
+            
+            print(f"Debug: Checking package_parent: {package_parent}", file=sys.stderr)
+            print(f"Debug: app exists? {(package_parent / 'app').exists()}", file=sys.stderr)
+            print(f"Debug: alembic exists? {(package_parent / 'alembic').exists()}", file=sys.stderr)
+            
+            # List what's actually in site-packages for debugging
+            if package_parent.exists():
+                print(f"Debug: Contents of {package_parent}:", file=sys.stderr)
+                try:
+                    for item in sorted(package_parent.iterdir())[:30]:  # First 30 items
+                        item_type = "DIR" if item.is_dir() else "FILE"
+                        print(f"Debug:   {item_type}: {item.name}", file=sys.stderr)
+                        # If we find app or alembic, note it
+                        if item.name in ["app", "alembic"]:
+                            print(f"Debug:   *** FOUND {item.name} at {item} ***", file=sys.stderr)
+                except Exception as e:
+                    print(f"Debug: Error listing directory: {e}", file=sys.stderr)
+            
+            # Try to find app/alembic by searching recursively (limited depth)
+            if package_parent.exists():
+                print(f"Debug: Searching for app/ and alembic/ directories...", file=sys.stderr)
+                for item in package_parent.iterdir():
+                    if item.is_dir() and item.name in ["app", "alembic"]:
+                        # Found one, check if the other exists nearby
+                        other_name = "alembic" if item.name == "app" else "app"
+                        other_path = item.parent / other_name
+                        if other_path.exists():
+                            print(f"Debug: *** FOUND BOTH at {item.parent} ***", file=sys.stderr)
+                            return item.parent
+            
+            # Hatchling shared-data places files at the site-packages level
+            # So if package is at site-packages/fastapi_auth_starter/
+            # Shared data is at site-packages/app/, site-packages/alembic/, etc.
+            if package_parent.exists():
+                # Check if shared-data is at the site-packages level
+                if (package_parent / "app").exists() and (package_parent / "alembic").exists():
+                    print(f"Debug: Found template files at site-packages level: {package_parent}", file=sys.stderr)
+                    return package_parent
+                
+                # Also check parent of site-packages (unlikely but possible)
+                if package_parent.parent.exists():
+                    if (package_parent.parent / "app").exists() and (package_parent.parent / "alembic").exists():
+                        print(f"Debug: Found template files at parent level: {package_parent.parent}", file=sys.stderr)
+                        return package_parent.parent
+            
+            # Check standard site-packages locations
+            for site_dir in site_dirs:
+                site_path = Path(site_dir)
+                
+                # Check if shared-data is in site-packages root
+                if (site_path / "app").exists() and (site_path / "alembic").exists():
+                    return site_path
+                
+                # Check in package directory
+                package_dir = site_path / "fastapi_auth_starter"
+                if package_dir.exists():
+                    # Check parent (shared-data might be at site-packages level)
+                    if (site_path / "app").exists():
+                        return site_path
+                    # Or in package directory itself
+                    if (package_dir / "app").exists():
+                        return package_dir
+                    
+                    # Check parent of package (hatchling shared-data location)
+                    package_parent = package_dir.parent
+                    if (package_parent / "app").exists():
+                        return package_parent
+                        
+        except Exception as e:
+            # Log error but continue to fallback
+            print(f"Warning: Error checking site-packages: {e}", file=sys.stderr)
+        
+        # Fallback: use development root
+        # This handles editable installs and other scenarios
+        return dev_root
+        
+    except Exception as e:
+        print(f"Error finding package root: {e}", file=sys.stderr)
+        # Final fallback: use current file's parent's parent
+        return Path(__file__).resolve().parent.parent
+
+
+def init_project(project_name: str, target_dir: Path | None = None) -> None:
+    """
+    Initialize a new FastAPI project from this starter template.
+    
+    Args:
+        project_name: Name of the new project
+        target_dir: Target directory (defaults to current directory/project_name)
+    """
+    if target_dir is None:
+        target_dir = Path.cwd() / project_name
+    
+    # Check if target directory already exists
+    if target_dir.exists():
+        print(f"Error: Directory {target_dir} already exists!")
+        sys.exit(1)
+    
+    # Find the template source directory
+    source_dir = find_package_root()
+    
+    if not source_dir.exists():
+        print(f"Error: Could not find template source directory!")
+        sys.exit(1)
+    
+    print(f"Creating new FastAPI project '{project_name}' from template...")
+    print(f"Source: {source_dir}")
+    print(f"Destination: {target_dir}")
+    
+    # Debug: Verify source directory has required files
+    if not (source_dir / "app").exists():
+        print(f"Warning: 'app' directory not found at {source_dir / 'app'}", file=sys.stderr)
+    if not (source_dir / "alembic").exists():
+        print(f"Warning: 'alembic' directory not found at {source_dir / 'alembic'}", file=sys.stderr)
+    
+    # Copy template files
+    copy_template_files(source_dir, target_dir, project_name)
+    
+    print("\n✓ Project created successfully!")
+    print(f"\nNext steps:")
+    print(f"  1. cd {target_dir}")
+    print(f"  2. Create a .env file with your configuration")
+    print(f"  3. Run: uv sync")
+    print(f"  4. Run: uv run alembic upgrade head")
+    print(f"  5. Run: uv run uvicorn app.main:app --reload")
+
+
+def main() -> None:
+    """
+    Main CLI entry point.
+    Handles command-line arguments and dispatches to appropriate functions.
+    """
+    parser = argparse.ArgumentParser(
+        description="FastAPI Auth Starter - Scaffold new FastAPI projects",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  fastapi-auth-starter init my-api
+  fastapi-auth-starter init my-api --dir /path/to/projects
+        """
+    )
+    
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # Init command
+    init_parser = subparsers.add_parser("init", help="Initialize a new FastAPI project")
+    init_parser.add_argument(
+        "project_name",
+        help="Name of the new project"
+    )
+    init_parser.add_argument(
+        "--dir",
+        type=Path,
+        help="Target directory (defaults to current directory/project_name)"
+    )
+    
+    args = parser.parse_args()
+    
+    if args.command == "init":
+        target_dir = args.dir / args.project_name if args.dir else None
+        init_project(args.project_name, target_dir)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+

fastapi_auth_starter-0.1.3.data/data/README.md

@@ -0,0 +1,247 @@
+# FastAPI Auth Starter
+
+A clean architecture FastAPI project starter with PostgreSQL and Alembic migrations.
+
+## Project Structure
+
+```
+fastapi_auth_starter/
+├── app/
+│   ├── __init__.py
+│   ├── main.py              # FastAPI application entry point
+│   ├── api/
+│   │   └── v1/
+│   │       ├── api.py       # API router aggregation
+│   │       └── routes/
+│   │           └── health.py  # Health check endpoint
+│   ├── core/
+│   │   ├── config.py        # Application configuration
+│   │   └── database.py      # Database connection and session management
+│   ├── models/              # SQLAlchemy database models
+│   ├── services/            # Business logic services
+│   └── db/                  # Database utilities
+├── alembic/                 # Database migration scripts
+├── alembic.ini              # Alembic configuration
+├── pyproject.toml           # Project dependencies (uv)
+└── README.md
+```
+
+## Features
+
+- ✅ Clean architecture with separation of concerns
+- ✅ FastAPI with async SQLAlchemy
+- ✅ PostgreSQL database support
+- ✅ Alembic for database migrations
+- ✅ Health check endpoint
+- ✅ Dependency injection with FastAPI
+- ✅ Environment-based configuration
+
+## Prerequisites
+
+- Python 3.12+ (3.13 for local dev, 3.12 for Vercel deployment)
+- [uv](https://github.com/astral-sh/uv) package manager
+- PostgreSQL database (local or remote)
+
+## Setup
+
+### 1. Install Dependencies
+
+Dependencies are managed with `uv`. They are automatically installed when you run commands with `uv run`.
+
+### 2. Configure Environment Variables
+
+**Important:** Copy the example environment file and configure your settings:
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env` with your configuration:
+
+```bash
+# Database Configuration
+DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/fastapi_auth
+
+# API Configuration (optional - defaults are fine)
+API_V1_PREFIX=/api/v1
+PROJECT_NAME=FastAPI Auth Starter
+VERSION=0.1.0
+```
+
+**Note:** 
+- The `.env` file is gitignored and should not be committed
+- The application uses `asyncpg` for async operations, but Alembic uses `psycopg2` for migrations (sync driver)
+- All sensitive configuration should be in `.env` file, not hardcoded
+
+### 3. Initialize Database
+
+First, ensure PostgreSQL is running and create the database:
+
+```bash
+createdb fastapi_auth
+```
+
+Or using PostgreSQL client:
+
+```sql
+CREATE DATABASE fastapi_auth;
+```
+
+### 4. Run Migrations
+
+```bash
+# Create initial migration (if needed)
+uv run alembic revision --autogenerate -m "Initial migration"
+
+# Apply migrations
+uv run alembic upgrade head
+```
+
+## Running the Application
+
+### Development Server
+
+```bash
+uv run uvicorn app.main:app --reload
+```
+
+The API will be available at:
+- API: http://localhost:8000
+- Docs: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+### Health Check
+
+Test the health endpoint:
+
+```bash
+curl http://localhost:8000/api/v1/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "message": "Service is running"
+}
+```
+
+## Development
+
+### Adding New Routes
+
+1. Create a new route file in `app/api/v1/routes/`
+2. Import and include the router in `app/api/v1/api.py`
+
+Example:
+```python
+# app/api/v1/routes/users.py
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+@router.get("/")
+async def get_users():
+    return {"users": []}
+```
+
+Then add to `app/api/v1/api.py`:
+```python
+from app.api.v1.routes import users
+api_router.include_router(users.router)
+```
+
+### Adding Database Models
+
+1. Create model in `app/models/`
+2. Import in `app/models/__init__.py`
+3. Import in `alembic/env.py` (for autogenerate)
+
+Example:
+```python
+# app/models/user.py
+from sqlalchemy import Column, Integer, String
+from app.core.database import Base
+
+class User(Base):
+    __tablename__ = "users"
+    
+    id = Column(Integer, primary_key=True)
+    email = Column(String, unique=True, index=True)
+```
+
+### Creating Migrations
+
+```bash
+# Auto-generate migration from model changes
+uv run alembic revision --autogenerate -m "Description of changes"
+
+# Create empty migration
+uv run alembic revision -m "Description of changes"
+```
+
+### Applying Migrations
+
+```bash
+# Apply all pending migrations
+uv run alembic upgrade head
+
+# Rollback one migration
+uv run alembic downgrade -1
+
+# Rollback to specific revision
+uv run alembic downgrade <revision>
+```
+
+## Architecture
+
+### Layers
+
+- **API Layer** (`app/api/`): Route handlers, request/response models
+- **Service Layer** (`app/services/`): Business logic, domain operations
+- **Model Layer** (`app/models/`): SQLAlchemy database models
+- **Core Layer** (`app/core/`): Configuration, database setup, utilities
+
+### Dependency Injection
+
+FastAPI's dependency injection is used throughout:
+- Database sessions via `get_db()` dependency
+- Configuration via `settings` object
+- Custom dependencies in `app/core/dependencies.py` (create as needed)
+
+## Deployment
+
+### Vercel Deployment
+
+1. **Install Dev Dependencies Locally:**
+   ```bash
+   uv sync  # Installs all dependencies including dev
+   ```
+
+2. **Set Environment Variables in Vercel:**
+   - Go to your project settings in Vercel
+   - Add `DATABASE_URL` environment variable with your PostgreSQL connection string
+   - Format: `postgresql+asyncpg://user:password@host:port/database`
+
+3. **Deploy:**
+   ```bash
+   vercel --prod
+   ```
+
+**Note:** 
+- Runtime dependencies don't include `psycopg2-binary` or `alembic` (only needed for local migrations)
+- Python 3.12 is used (Vercel doesn't support 3.13 yet)
+- Make sure to run migrations on your database before deploying
+
+## References
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [SQLAlchemy Async Documentation](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
+- [Alembic Documentation](https://alembic.sqlalchemy.org/)
+- [uv Documentation](https://github.com/astral-sh/uv)
+- [Vercel Python Documentation](https://vercel.com/docs/functions/serverless-functions/runtimes/python)
+
+## License
+
+MIT
+

fastapi_auth_starter-0.1.3.data/data/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

fastapi_auth_starter-0.1.3.data/data/alembic/env.py

@@ -0,0 +1,100 @@
+"""
+Alembic environment configuration
+Handles database migrations with SQLAlchemy
+Reference: https://alembic.sqlalchemy.org/en/latest/tutorial.html
+"""
+from logging.config import fileConfig
+
+from sqlalchemy import engine_from_config, pool
+
+from alembic import context
+
+# Import application settings and Base
+from app.core.config import settings
+from app.core.database import Base
+
+# Import all models here so Alembic can detect them for autogenerate
+# As models are added, import them here
+from app.models import Task, User 
+# This is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Override sqlalchemy.url from settings if not set in alembic.ini
+# Convert asyncpg URL to psycopg2 URL for Alembic (Alembic uses sync drivers)
+# Reference: https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls
+if not config.get_main_option("sqlalchemy.url"):
+    # Convert asyncpg URL to psycopg2 URL (sync driver for migrations)
+    db_url = settings.DATABASE_URL.replace("postgresql+asyncpg://", "postgresql+psycopg2://")
+    # Escape % for ConfigParser (double % to prevent interpolation)
+    db_url = db_url.replace("%", "%%")
+    config.set_main_option("sqlalchemy.url", db_url)
+
+# Set target_metadata for autogenerate support
+# This tells Alembic what models exist in the application
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    """
+    Run migrations in 'offline' mode.
+    
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+    
+    Calls to context.execute() here emit the given string to the
+    script output.
+    """
+    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 run_migrations_online() -> None:
+    """
+    Run migrations in 'online' mode.
+    
+    In this scenario we need to create an Engine
+    and associate a connection with the context.
+    
+    Reference: https://alembic.sqlalchemy.org/en/latest/tutorial.html#run-a-migration
+    """
+    # Create sync engine from configuration
+    # Alembic uses sync SQLAlchemy operations
+    # We use psycopg2 (sync) for migrations, asyncpg (async) for the app
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,  # Don't pool connections for migrations
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,  # Compare column types when autogenerating
+            compare_server_default=True,  # Compare server defaults
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()