Python Flask & SQLite Best Practices

A comprehensive rule set for Python development with Flask, SQLite, Docker, and modern development practices. Enforces git commits, Docker healthchecks, and industry-standard patterns.

What This Skill Does

This skill enforces best practices for Python development with Flask applications, SQLite databases, and containerized deployments. It ensures proper project structure, code quality, security, testing, and operational reliability through mandatory git workflows and Docker healthchecks.

Instructions

CRITICAL: Git Commit Workflow (MANDATORY)

**YOU MUST commit ALL changes to git.** This is NON-NEGOTIABLE.

After making ANY file modifications:

1. **Stage changes**: Run `git add <modified-files>` or `git add .`

2. **Commit immediately**: Run `git commit -m "type: descriptive message"`

3. **Verify success**: Confirm the commit succeeded with no errors

4. **Use conventional commit format**:

- `fix:` for bug fixes

- `feat:` for new features

- `refactor:` for code refactoring

- `docs:` for documentation changes

- `chore:` for maintenance tasks

- `test:` for test changes

**Example**: `git commit -m "feat: add user authentication with Google OAuth"`

**NEVER** skip commits. **NEVER** summarize changes without committing. Every modification must be committed before the task is complete.

CRITICAL: Docker Healthcheck Requirements (MANDATORY)

**ALL Docker services MUST have comprehensive healthchecks.**

**FORBIDDEN practices:**

❌ Disabling healthchecks

❌ Commenting out healthchecks

❌ Using TCP-only checks (nc -z) without application-level validation

❌ Removing healthchecks to resolve issues

**REQUIRED practices:**

✅ Full HTTP/HTTPS endpoint checks that validate actual service functionality

✅ Proper intervals (30s), timeouts (10s), retries (3), and start_period (30s)

✅ Test real service endpoints, not just port availability

✅ Add self-healing labels: `deunhealth.restart.on.unhealthy: "true"`

✅ Install healthcheck tools (curl/wget) in containers if missing

✅ Use comprehensive checks like `wget --spider` or `curl -f` with endpoint validation

**Proper healthcheck example:**

```yaml

healthcheck:

test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://127.0.0.1:8080/health || exit 1"]

interval: 30s

timeout: 10s

retries: 3

start_period: 30s

labels:

deunhealth.restart.on.unhealthy: "true"

```

**If disabling healthchecks seems like a "fix", find the ROOT CAUSE instead.**

Project Structure Standards

Organize projects using modern Python src-layout:

```

project/

├── src/

│ └── package_name/

│ ├── __init__.py

│ ├── app.py (Flask factory)

│ ├── models.py

│ ├── routes/

│ │ ├── __init__.py

│ │ ├── auth.py (Blueprint)

│ │ └── api.py (Blueprint)

│ ├── types.py

│ └── utils.py

├── tests/

│ ├── __init__.py

│ ├── conftest.py

│ └── test_routes.py

├── config/

│ └── settings.py

├── static/

├── templates/

├── requirements.txt

├── pyproject.toml

└── README.md

```

**Key principles:**

Use `src/` layout for better packaging

Separate tests in parallel `tests/` directory

Store configuration in `config/` or environment variables

Keep static assets in `static/`, templates in `templates/`

Define dependencies in `requirements.txt` or `pyproject.toml`

Code Style & Formatting

**Apply Black formatting and follow PEP 8:**

Use **Black** for code formatting (88-character line limit)

Use **isort** for import sorting

Naming conventions:

- `snake_case` for functions and variables

- `PascalCase` for classes

- `UPPER_CASE` for constants

Prefer absolute imports over relative imports

**Example:**

```python

from typing import Optional

from flask import Blueprint, request

Constants

MAX_RETRY_COUNT = 3

Class

class UserService:

def get_user_by_id(self, user_id: int) -> Optional[dict]:

pass

```

Type Hints

**Use comprehensive type hints:**

Add type hints to ALL function parameters and return values

Import types from `typing` module

Use `Optional[Type]` instead of `Type | None`

Define custom types in `types.py`

Use `Protocol` for duck typing

Use `TypeVar` for generic types

**Example:**

```python

from typing import Optional, Protocol

def fetch_user(user_id: int) -> Optional[dict]:

"""Fetch user by ID."""

pass

```

Flask Application Structure

**Use Flask factory pattern with Blueprints:**

Implement Flask factory pattern in `app.py`

Organize routes using **Blueprints**

Use **Flask-SQLAlchemy** for database ORM

Implement proper error handlers (404, 500, etc.)

Use **Flask-Login** for authentication

Separate concerns (routes, models, services)

**Factory pattern example:**

```python

from flask import Flask

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

def create_app():

app = Flask(__name__)

app.config.from_object('config.settings')

db.init_app(app)

from .routes import auth_bp, api_bp

app.register_blueprint(auth_bp, url_prefix='/auth')

app.register_blueprint(api_bp, url_prefix='/api')

return app

```

Database (SQLAlchemy)

**Use SQLAlchemy ORM with proper practices:**

Define models in separate `models.py` modules

Implement database migrations with **Alembic**

Use proper connection pooling

Define relationships correctly (one-to-many, many-to-many)

Add proper indexes for performance

Use transactions where needed

**Model example:**

```python

from flask_sqlalchemy import SQLAlchemy

db = SQLAlchemy()

class User(db.Model):

__tablename__ = 'users'

id = db.Column(db.Integer, primary_key=True)

email = db.Column(db.String(120), unique=True, nullable=False, index=True)

password_hash = db.Column(db.String(255), nullable=False)

```

Authentication

**Implement secure authentication:**

Use **Flask-Login** for session management

Implement **Google OAuth** using Flask-OAuth

Hash passwords with **bcrypt**

Use proper session security (secure cookies, HTTPS)

Implement **CSRF protection**

Use role-based access control (RBAC)

**Example:**

```python

from flask_login import LoginManager, UserMixin

from werkzeug.security import generate_password_hash, check_password_hash

login_manager = LoginManager()

class User(UserMixin, db.Model):

def set_password(self, password: str) -> None:

self.password_hash = generate_password_hash(password)

def check_password(self, password: str) -> bool:

return check_password_hash(self.password_hash, password)

```

API Design

**Build RESTful APIs with proper standards:**

Use **Flask-RESTful** for REST APIs

Implement request validation

Use proper HTTP status codes (200, 201, 400, 401, 404, 500)

Handle errors consistently

Return JSON responses

Implement rate limiting

**Example:**

```python

from flask import Blueprint, jsonify, request

api_bp = Blueprint('api', __name__)

@api_bp.route('/users/<int:user_id>', methods=['GET'])

def get_user(user_id: int):

user = User.query.get_or_404(user_id)

return jsonify({'id': user.id, 'email': user.email}), 200

```

Testing

**Write comprehensive tests with pytest:**

Use **pytest** for all tests

Write tests for all routes and edge cases

Use **pytest-cov** for coverage reports

Implement proper fixtures in `conftest.py`

Use **pytest-mock** for mocking

Test error scenarios and validation

**Example:**

```python

import pytest

from src.app import create_app

@pytest.fixture

def client():

app = create_app()

app.config['TESTING'] = True

with app.test_client() as client:

yield client

def test_home(client):

response = client.get('/')

assert response.status_code == 200

```

Security

**Follow OWASP and Flask security best practices:**

Use **HTTPS** in production

Implement proper **CORS** with Flask-CORS

Sanitize all user inputs (prevent XSS, SQL injection)

Use secure session configuration (httponly, secure, samesite)

Implement proper logging (no sensitive data in logs)

Follow **OWASP Top 10** guidelines

**Example:**

```python

from flask import Flask

from flask_cors import CORS

app = create_app()

CORS(app, resources={r"/api/*": {"origins": "https://example.com"}})

app.config['SESSION_COOKIE_SECURE'] = True

app.config['SESSION_COOKIE_HTTPONLY'] = True

app.config['SESSION_COOKIE_SAMESITE'] = 'Lax'

```

Performance

**Optimize application performance:**

Use **Flask-Caching** for caching

Optimize database queries (use `.join()`, avoid N+1)

Implement proper connection pooling

Add pagination to large result sets

Use background tasks (Celery) for heavy operations

Monitor performance with APM tools

**Caching example:**

```python

from flask_caching import Cache

cache = Cache(config={'CACHE_TYPE': 'simple'})

@cache.cached(timeout=60)

def get_users():

return User.query.all()

```

Error Handling

**Implement robust error handling:**

Create custom exception classes

Use try-except blocks appropriately

Implement proper logging (use `logging` module)

Return proper error responses with status codes

Handle edge cases (null checks, validation)

Use descriptive error messages

**Example:**

```python

import logging

logger = logging.getLogger(__name__)

@app.errorhandler(404)

def not_found(error):

logger.warning(f"404 error: {request.url}")

return jsonify({'error': 'Not found'}), 404

```

Documentation

**Maintain comprehensive documentation:**

Use **Google-style docstrings** for all functions/classes

Document all public APIs

Keep **README.md** updated with setup instructions

Add inline comments for complex logic

Generate API documentation (Sphinx, mkdocs)

Document environment variables and configuration

**Docstring example:**

```python

def fetch_user(user_id: int) -> Optional[dict]:

"""Fetch user by ID from the database.

Args:

user_id: The unique identifier for the user.

Returns:

A dictionary containing user data, or None if not found.

Raises:

DatabaseError: If the database connection fails.

"""

pass

```

Development Workflow

**Follow modern development practices:**

Use **virtual environments** (venv/virtualenv)

Implement **pre-commit hooks** (Black, isort, flake8)

Use proper **Git workflow** (feature branches, pull requests)

Follow **semantic versioning** (MAJOR.MINOR.PATCH)

Implement **CI/CD pipelines** (GitHub Actions, GitLab CI)

Use proper logging levels (DEBUG, INFO, WARNING, ERROR)

**Virtual environment setup:**

```bash

python -m venv venv

source venv/bin/activate # On Windows: venv\Scripts\activate

pip install -r requirements.txt

```

Dependency Management

**Manage dependencies properly:**

Pin dependency versions in `requirements.txt`

Separate dev dependencies (`requirements-dev.txt`)

Use proper package versions (avoid wildcards)

Regularly update dependencies

Check for security vulnerabilities (`safety check`)

Use `pip-tools` for dependency resolution

**Example `requirements.txt`:**

```

Flask==2.3.2

Flask-SQLAlchemy==3.0.5

Flask-Login==0.6.2

bcrypt==4.0.1

pytest==7.4.0

```

Summary

This skill enforces production-ready Python Flask development with:

**Mandatory git commits** after every change

**Comprehensive Docker healthchecks** for reliability

**Modern project structure** with src-layout

**Type hints** and Black formatting

**Flask factory pattern** with Blueprints

**SQLAlchemy ORM** with migrations

**Secure authentication** (Flask-Login, OAuth, bcrypt)

**RESTful API design** with proper error handling

**pytest-based testing** with coverage

**OWASP security standards**

**Performance optimization** (caching, query optimization)

**Comprehensive documentation** (Google-style docstrings)

**Remember:** Every code change MUST be committed to git, and every Docker service MUST have working healthchecks. No exceptions.

Python Flask & SQLite Best Practices

Python Flask & SQLite Best Practices

What This Skill Does

Instructions

CRITICAL: Git Commit Workflow (MANDATORY)

CRITICAL: Docker Healthcheck Requirements (MANDATORY)

Project Structure Standards

Code Style & Formatting

Constants

Class

Type Hints

Flask Application Structure

Database (SQLAlchemy)

Authentication

API Design

Testing

Security

Performance

Error Handling

Documentation

Development Workflow

Dependency Management

Summary

Reviews (0)