hinbert-fastapi 0.1.0__tar.gz → 0.2.0__tar.gz

hinbert_fastapi-0.2.0/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: hinbert-fastapi
+Version: 0.2.0
+Summary: Professional FastAPI boilerplate with JWT auth, 2FA, PostgreSQL, Docker
+Author: Hinbert Engineering
+License: MIT
+Project-URL: Documentation, https://github.com/hinbert/hinbert-fastapi#readme
+Project-URL: Repository, https://github.com/hinbert/hinbert-fastapi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: uvicorn[standard]<1,>=0.30
+Requires-Dist: sqlalchemy[asyncio]<3,>=2.0
+Requires-Dist: asyncpg<1,>=0.29
+Requires-Dist: aiosqlite<1,>=0.20
+Requires-Dist: alembic<2,>=1.13
+Requires-Dist: pydantic<3,>=2.8
+Requires-Dist: pydantic-settings<3,>=2.4
+Requires-Dist: python-jose[cryptography]<4,>=3.3
+Requires-Dist: passlib[bcrypt]<2,>=1.7
+Requires-Dist: bcrypt<5,>=4.0
+Requires-Dist: pyotp<3,>=2.9
+Requires-Dist: slowapi<1,>=0.1.9
+Requires-Dist: loguru<1,>=0.7
+Requires-Dist: email-validator<3,>=2.2
+Requires-Dist: python-multipart<1,>=0.0.9
+Requires-Dist: redis<6,>=5
+Requires-Dist: aiosmtplib<4,>=3
+Requires-Dist: cryptography<46,>=42
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# Hinbert FastAPI
+
+A modern, production-oriented FastAPI backend foundation for secure web applications. Built for teams that want a clean architecture, strong authentication defaults, scalable API design, and quick deployment without starting from scratch.
+
+## Why this project?
+
+Hinbert FastAPI combines a pragmatic backend structure with security-first design patterns:
+
+- JWT-based authentication with refresh token rotation
+- Password reset and email verification flows
+- Optional TOTP multi-factor authentication
+- OAuth login for Google and Facebook
+- Async SQLAlchemy data layer with PostgreSQL support
+- Rate limiting, request logging, and structured error handling
+- Clean separation between API, services, repositories, and models
+- Docker-ready local environment and deployment support
+
+## Features
+
+- Secure user registration and login
+- Email verification and password recovery
+- Access token + refresh token issuance
+- Logout and refresh-token revocation
+- TOTP setup and validation
+- Social authentication hooks
+- Product CRUD endpoints with filtering, sorting, and pagination
+- Redis-backed rate limiting
+- Pydantic-based validation and environment configuration
+- Alembic migrations for database evolution
+- Python testing coverage for core business flows
+
+### Available Commands
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `hinbert init [PROJECT_NAME]` | Create a new FastAPI project | `hinbert init my_app` |
+| `hinbert init --help` | Show help and available options | `hinbert init --help` |
+| `hinbert init .` | Generate project in current directory | `hinbert init .` |
+| `hinbert init [PROJECT_NAME] --yes` | Skip prompts, use defaults | `hinbert init my_app --yes` |
+| `--db [postgresql|mysql|sqlite]` | Choose database | `--db postgresql` |
+| `--auth [jwt|oauth2|none]` | Choose authentication | `--auth jwt` |
+| `--no-2fa` | Skip two-factor authentication | `--no-2fa` |
+| `--no-email` | Skip email verification | `--no-email` |
+| `--no-rate-limit` | Skip rate limiting | `--no-rate-limit` |
+| `--no-docker` | Skip Docker configuration | `--no-docker` |
+| `--k8s` | Include Kubernetes/Helm | `--k8s` |
+| `--logging [loguru|structlog|none]` | Choose logging library | `--logging structlog` |
+| `-y, --yes` | Skip all confirmation prompts | `-y` |
+
+## Tech Stack
+
+- Python 3.12+
+- FastAPI
+- SQLAlchemy 2 with async support
+- PostgreSQL / SQLite compatibility
+- Pydantic v2
+- Redis
+- Alembic
+- JWT + bcrypt + pyotp
+- Docker and Docker Compose
+- pytest
+
+## Architecture
+
+```text
+app/
+├── api/
+│   ├── deps/
+│   └── v1/
+│       ├── endpoints/
+│       └── routers/
+├── core/
+│   ├── config/
+│   ├── exceptions/
+│   ├── middleware/
+│   └── security/
+├── db/
+│   └── migrations/
+├── models/
+│   ├── domain/
+│   └── schemas/
+├── repositories/
+├── services/
+├── tests/
+├── main.py
+├── __init__.py
+
+scripts/
+├── create_admin.py
+├── run_migrations.py
+├── seed_data.py
+
+docker/
+├── Dockerfile
+├── docker-compose.yml
+
+alembic.ini
+pyproject.toml
+requirements.txt
+requirements-dev.txt
+.env.example
+README.md
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- PostgreSQL or Docker
+- Redis or Docker
+- Git
+
+### 1. Clone the repository
+
+```bash
+git clone <repository-url>
+cd hinbert_fastapi
+```
+
+### 2. Create a virtual environment
+
+```bash
+python -m venv .venv
+```
+
+On Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+On macOS/Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+### 3. Install dependencies
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+### 4. Configure environment variables
+
+```bash
+copy .env.example .env
+```
+
+or:
+
+```bash
+cp .env.example .env
+```
+
+Update the values in `.env` for your database, Redis, JWT secret, SMTP settings, and OAuth credentials.
+
+### 5. Run database migrations
+
+```bash
+python -m scripts.run_migrations
+```
+
+### 6. Start the API
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Once running, the app is available at:
+
+- API: http://localhost:8000
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+- Health: http://localhost:8000/health
+
+## Docker Setup
+
+This project includes a Docker Compose setup for local development.
+
+```bash
+docker compose -f docker/docker-compose.yml up --build
+```
+
+To stop it:
+
+```bash
+docker compose -f docker/docker-compose.yml down
+```
+
+## API Highlights
+
+The application exposes a versioned API under `/api/v1`.
+
+### Auth endpoints
+
+- `/api/v1/auth/signup`
+- `/api/v1/auth/login`
+- `/api/v1/auth/refresh`
+- `/api/v1/auth/logout`
+- `/api/v1/auth/forgot-password`
+- `/api/v1/auth/reset-password`
+- `/api/v1/auth/totp/setup`
+- `/api/v1/auth/totp/verify`
+- `/api/v1/auth/google`
+- `/api/v1/auth/facebook`
+
+### Product endpoints
+
+- `/api/v1/products`
+- `/api/v1/products/{product_id}`
+
+### User endpoints
+
+- `/api/v1/users/me`
+- admin/user management routes where applicable
+
+## Example Authentication Flow
+
+```json
+{
+  "email": "user@example.com",
+  "password": "StrongPassword!123"
+}
+```
+
+The login response returns both an access token and refresh token:
+
+```http
+Authorization: Bearer <access_token>
+```
+
+## Environment Configuration
+
+The project reads configuration using Pydantic settings from `.env` and supports values such as:
+
+- `DATABASE_URL`
+- `REDIS_URL`
+- `SECRET_KEY`
+- `ALGORITHM`
+- `ACCESS_TOKEN_EXPIRE_MINUTES`
+- `REFRESH_TOKEN_EXPIRE_DAYS`
+- `SMTP_HOST`
+- `SMTP_PORT`
+- `EMAIL_FROM`
+- `GOOGLE_CLIENT_ID`
+- `FACEBOOK_CLIENT_ID`
+- `BACKEND_CORS_ORIGINS`
+
+## Testing
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+Targeted test folders:
+
+```bash
+pytest app/tests/unit
+pytest app/tests/integration
+```
+
+## Security Notes
+
+This project includes strong defaults for a starter backend, but production deployments should still:
+
+- replace the default JWT secret with a secure secret manager value
+- restrict CORS origins to trusted domains
+- protect database credentials and infrastructure endpoints
+- use HTTPS behind a reverse proxy or load balancer
+- configure valid SMTP and OAuth provider credentials
+- enable monitoring, backups, and secure deployment policies
+
+## Contributing
+
+Contributions are welcome. Please keep pull requests focused, add or update tests for behavior changes, and keep code consistent with the existing project structure.
+
+## License
+
+This project is licensed under the MIT License.

hinbert_fastapi-0.2.0/README.md

@@ -0,0 +1,284 @@
+# Hinbert FastAPI
+
+A modern, production-oriented FastAPI backend foundation for secure web applications. Built for teams that want a clean architecture, strong authentication defaults, scalable API design, and quick deployment without starting from scratch.
+
+## Why this project?
+
+Hinbert FastAPI combines a pragmatic backend structure with security-first design patterns:
+
+- JWT-based authentication with refresh token rotation
+- Password reset and email verification flows
+- Optional TOTP multi-factor authentication
+- OAuth login for Google and Facebook
+- Async SQLAlchemy data layer with PostgreSQL support
+- Rate limiting, request logging, and structured error handling
+- Clean separation between API, services, repositories, and models
+- Docker-ready local environment and deployment support
+
+## Features
+
+- Secure user registration and login
+- Email verification and password recovery
+- Access token + refresh token issuance
+- Logout and refresh-token revocation
+- TOTP setup and validation
+- Social authentication hooks
+- Product CRUD endpoints with filtering, sorting, and pagination
+- Redis-backed rate limiting
+- Pydantic-based validation and environment configuration
+- Alembic migrations for database evolution
+- Python testing coverage for core business flows
+
+### Available Commands
+
+| Command | Description | Example |
+| --- | --- | --- |
+| `hinbert init [PROJECT_NAME]` | Create a new FastAPI project | `hinbert init my_app` |
+| `hinbert init --help` | Show help and available options | `hinbert init --help` |
+| `hinbert init .` | Generate project in current directory | `hinbert init .` |
+| `hinbert init [PROJECT_NAME] --yes` | Skip prompts, use defaults | `hinbert init my_app --yes` |
+| `--db [postgresql|mysql|sqlite]` | Choose database | `--db postgresql` |
+| `--auth [jwt|oauth2|none]` | Choose authentication | `--auth jwt` |
+| `--no-2fa` | Skip two-factor authentication | `--no-2fa` |
+| `--no-email` | Skip email verification | `--no-email` |
+| `--no-rate-limit` | Skip rate limiting | `--no-rate-limit` |
+| `--no-docker` | Skip Docker configuration | `--no-docker` |
+| `--k8s` | Include Kubernetes/Helm | `--k8s` |
+| `--logging [loguru|structlog|none]` | Choose logging library | `--logging structlog` |
+| `-y, --yes` | Skip all confirmation prompts | `-y` |
+
+## Tech Stack
+
+- Python 3.12+
+- FastAPI
+- SQLAlchemy 2 with async support
+- PostgreSQL / SQLite compatibility
+- Pydantic v2
+- Redis
+- Alembic
+- JWT + bcrypt + pyotp
+- Docker and Docker Compose
+- pytest
+
+## Architecture
+
+```text
+app/
+├── api/
+│   ├── deps/
+│   └── v1/
+│       ├── endpoints/
+│       └── routers/
+├── core/
+│   ├── config/
+│   ├── exceptions/
+│   ├── middleware/
+│   └── security/
+├── db/
+│   └── migrations/
+├── models/
+│   ├── domain/
+│   └── schemas/
+├── repositories/
+├── services/
+├── tests/
+├── main.py
+├── __init__.py
+
+scripts/
+├── create_admin.py
+├── run_migrations.py
+├── seed_data.py
+
+docker/
+├── Dockerfile
+├── docker-compose.yml
+
+alembic.ini
+pyproject.toml
+requirements.txt
+requirements-dev.txt
+.env.example
+README.md
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- PostgreSQL or Docker
+- Redis or Docker
+- Git
+
+### 1. Clone the repository
+
+```bash
+git clone <repository-url>
+cd hinbert_fastapi
+```
+
+### 2. Create a virtual environment
+
+```bash
+python -m venv .venv
+```
+
+On Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+On macOS/Linux:
+
+```bash
+source .venv/bin/activate
+```
+
+### 3. Install dependencies
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements-dev.txt
+```
+
+### 4. Configure environment variables
+
+```bash
+copy .env.example .env
+```
+
+or:
+
+```bash
+cp .env.example .env
+```
+
+Update the values in `.env` for your database, Redis, JWT secret, SMTP settings, and OAuth credentials.
+
+### 5. Run database migrations
+
+```bash
+python -m scripts.run_migrations
+```
+
+### 6. Start the API
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Once running, the app is available at:
+
+- API: http://localhost:8000
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+- Health: http://localhost:8000/health
+
+## Docker Setup
+
+This project includes a Docker Compose setup for local development.
+
+```bash
+docker compose -f docker/docker-compose.yml up --build
+```
+
+To stop it:
+
+```bash
+docker compose -f docker/docker-compose.yml down
+```
+
+## API Highlights
+
+The application exposes a versioned API under `/api/v1`.
+
+### Auth endpoints
+
+- `/api/v1/auth/signup`
+- `/api/v1/auth/login`
+- `/api/v1/auth/refresh`
+- `/api/v1/auth/logout`
+- `/api/v1/auth/forgot-password`
+- `/api/v1/auth/reset-password`
+- `/api/v1/auth/totp/setup`
+- `/api/v1/auth/totp/verify`
+- `/api/v1/auth/google`
+- `/api/v1/auth/facebook`
+
+### Product endpoints
+
+- `/api/v1/products`
+- `/api/v1/products/{product_id}`
+
+### User endpoints
+
+- `/api/v1/users/me`
+- admin/user management routes where applicable
+
+## Example Authentication Flow
+
+```json
+{
+  "email": "user@example.com",
+  "password": "StrongPassword!123"
+}
+```
+
+The login response returns both an access token and refresh token:
+
+```http
+Authorization: Bearer <access_token>
+```
+
+## Environment Configuration
+
+The project reads configuration using Pydantic settings from `.env` and supports values such as:
+
+- `DATABASE_URL`
+- `REDIS_URL`
+- `SECRET_KEY`
+- `ALGORITHM`
+- `ACCESS_TOKEN_EXPIRE_MINUTES`
+- `REFRESH_TOKEN_EXPIRE_DAYS`
+- `SMTP_HOST`
+- `SMTP_PORT`
+- `EMAIL_FROM`
+- `GOOGLE_CLIENT_ID`
+- `FACEBOOK_CLIENT_ID`
+- `BACKEND_CORS_ORIGINS`
+
+## Testing
+
+Run the test suite with:
+
+```bash
+pytest
+```
+
+Targeted test folders:
+
+```bash
+pytest app/tests/unit
+pytest app/tests/integration
+```
+
+## Security Notes
+
+This project includes strong defaults for a starter backend, but production deployments should still:
+
+- replace the default JWT secret with a secure secret manager value
+- restrict CORS origins to trusted domains
+- protect database credentials and infrastructure endpoints
+- use HTTPS behind a reverse proxy or load balancer
+- configure valid SMTP and OAuth provider credentials
+- enable monitoring, backups, and secure deployment policies
+
+## Contributing
+
+Contributions are welcome. Please keep pull requests focused, add or update tests for behavior changes, and keep code consistent with the existing project structure.
+
+## License
+
+This project is licensed under the MIT License.

{hinbert_fastapi-0.1.0 → hinbert_fastapi-0.2.0}/app/api/deps/auth.py

@@ -1,40 +1,40 @@
-"""Bearer-token dependencies for protected routes."""
-
-from uuid import UUID
-
-from fastapi import Depends
-from fastapi.security import OAuth2PasswordBearer
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.core.exceptions.custom_exceptions import UnauthorizedError
-from app.core.security.jwt import decode_token
-from app.db.session import get_db
-from app.models.domain.user import User
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
-
-
-async def get_current_user(token: str = Depends(oauth2_scheme), session: AsyncSession = Depends(get_db)) -> User:
-    """Decode an access token and load its user, failing closed on any error."""
-    try:
-        subject = UUID(decode_token(token)["sub"])
-    except (ValueError, KeyError) as exc:
-        raise UnauthorizedError() from exc
-    user = await session.get(User, subject)
-    if user is None:
-        raise UnauthorizedError()
-    return user
-
-
-async def get_current_active_user(user: User = Depends(get_current_user)) -> User:
-    """Reject deactivated accounts before protected business operations."""
-    if not user.is_active:
-        raise UnauthorizedError("Inactive account")
-    return user
-
-
-async def get_current_admin(user: User = Depends(get_current_active_user)) -> User:
-    """Require an active account with administrator privileges."""
-    if not user.is_admin:
-        raise UnauthorizedError("Administrator privileges required")
-    return user
+"""Bearer-token dependencies for protected routes."""
+
+from uuid import UUID
+
+from fastapi import Depends
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.exceptions.custom_exceptions import UnauthorizedError
+from app.core.security.auth import decode_token
+from app.db.session import get_db
+from app.models.domain.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+
+async def get_current_user(token: str = Depends(oauth2_scheme), session: AsyncSession = Depends(get_db)) -> User:
+    """Decode an access token and load its user, failing closed on any error."""
+    try:
+        subject = UUID(decode_token(token)["sub"])
+    except (ValueError, KeyError) as exc:
+        raise UnauthorizedError() from exc
+    user = await session.get(User, subject)
+    if user is None:
+        raise UnauthorizedError()
+    return user
+
+
+async def get_current_active_user(user: User = Depends(get_current_user)) -> User:
+    """Reject deactivated accounts before protected business operations."""
+    if not user.is_active:
+        raise UnauthorizedError("Inactive account")
+    return user
+
+
+async def get_current_admin(user: User = Depends(get_current_active_user)) -> User:
+    """Require an active account with administrator privileges."""
+    if not user.is_admin:
+        raise UnauthorizedError("Administrator privileges required")
+    return user

hinbert_fastapi-0.2.0/app/core/middleware/__init__.py

@@ -0,0 +1,14 @@
+"""HTTP middleware and exception handling components."""
+
+import os
+from pathlib import Path
+
+
+def generate_init_files(project_path):
+    for root, dirs, files in os.walk(project_path / "app"):
+        existing_modules = [f[:-3] for f in files if f.endswith('.py') and f != '__init__.py']
+        init_path = Path(root) / "__init__.py"
+        if existing_modules:
+            init_path.write_text("\n".join([f"from . import {m}" for m in existing_modules]))
+        else:
+            init_path.touch()