dev.py
Rama main · réplica de lectura del repositorio original.
#!/usr/bin/env python3
"""
Development helper script for the my-practice Django project.
"""
import glob
import inspect
import os
import re
import shutil
import subprocess
import sys
import time
CONTAINER_NAME = "my-practice-django"
COMPOSE = ["docker", "compose"]
# Python that lives outside ./app and so is invisible to the container's
# `ruff format .` (docker-compose mounts only ./app at /app). These are piped
# through the container's ruff over stdin instead — see _ruff_root_python —
# so they're held to the same pinned ruff version as the app.
#
# Their *config* has to differ in one respect, though: these files run on the
# host Python, not the container's 3.14, and the app's target-version = "py314"
# makes the formatter rewrite `except (A, B):` into 3.14's bracketless form —
# a SyntaxError on 3.13 and older, which would make ./dev.py itself unrunnable.
# The repo-root ruff.toml sets the lower target, but the container can't see it
# (only ./app is mounted), so it's passed through as an inline --config below.
ROOT_PYTHON_GLOBS = ("dev.py", "prod.py", "scripts/*.py")
ROOT_RUFF_CONFIG = os.path.join(os.path.dirname(os.path.abspath(__file__)), "ruff.toml")
def _root_ruff_target_version():
"""Read target-version out of the repo-root ruff.toml.
Parsed rather than duplicated so the value can't drift from the config CI
and a native `ruff` run both use.
"""
try:
with open(ROOT_RUFF_CONFIG, encoding="utf-8") as fh:
for line in fh:
match = re.match(r'\s*target-version\s*=\s*"([^"]+)"', line)
if match:
return match.group(1)
except OSError:
pass
return None
def run_docker_command(args, interactive=False, **run_kwargs):
"""Run a command in the Django container.
run_kwargs go to subprocess.run; passing `input` keeps the container's stdin
open (-i) so it can be piped in.
"""
flags = ["-it"] if interactive else ["-i"] if "input" in run_kwargs else []
return subprocess.run(["docker", "exec", *flags, CONTAINER_NAME, *args], **run_kwargs)
def _root_python_files():
"""Repo-root Python files that the container can't see (see ROOT_PYTHON_GLOBS)."""
files = []
for pattern in ROOT_PYTHON_GLOBS:
files.extend(sorted(glob.glob(pattern)))
return files
def _run_ruff_stdin(ruff_args, source):
"""Run the container's ruff against source text piped over stdin.
--stdin-filename resolves against the container's /app, so ruff discovers
app/pyproject.toml for these files. That is right for everything except
target-version — see ROOT_PYTHON_GLOBS — which is overridden inline.
"""
cmd = ["python", "-m", "ruff", *ruff_args]
target_version = _root_ruff_target_version()
if target_version:
cmd.extend(["--config", f"target-version='{target_version}'"])
return run_docker_command(cmd, input=source, capture_output=True, text=True)
def _ruff_root_python(write=False, verbose=False):
"""Format-check (or rewrite) and lint the repo-root Python files.
Returns 0 if everything is clean, 1 otherwise. In write mode the formatted
output is written back, mirroring what `ruff format .` does inside /app.
"""
problems = []
for path in _root_python_files():
with open(path, encoding="utf-8") as fh:
source = fh.read()
if write:
result = _run_ruff_stdin(["format", "-", "--stdin-filename", path], source)
if result.returncode != 0:
problems.append(f"{path}: {result.stderr.strip()}")
elif result.stdout != source:
with open(path, "w", encoding="utf-8") as fh:
fh.write(result.stdout)
print(f" reformatted {path}")
else:
result = _run_ruff_stdin(["format", "--check", "-", "--stdin-filename", path], source)
if result.returncode != 0:
problems.append(f"{path}: needs formatting")
lint = _run_ruff_stdin(["check", "--stdin-filename", path, "-"], source)
if lint.returncode != 0:
problems.append(f"{path}: {lint.stdout.strip() or lint.stderr.strip()}")
if problems:
for problem in problems:
print(f" {problem}" if verbose else f" {problem.splitlines()[0]}")
return 1
return 0
# This and _confirm_metered_download are duplicated verbatim in prod.py. prod.py
# ships to self-hosters as a single stdlib-only file, so it cannot import a
# shared module, and the copies must stay identical —
# scripts/check_shared_helpers.py fails if they drift.
def _is_metered_connection():
"""Best-effort NetworkManager check for a metered connection (e.g. mobile hotspot).
Returns True/False when nmcli gives a definite answer, None when it can't be
determined (no NetworkManager, no default route, non-Linux host, ...).
Callers should treat None as "unknown" and not block on it.
"""
if not shutil.which("nmcli"):
return None
try:
route = subprocess.run(
["ip", "route", "show", "default"],
capture_output=True,
text=True,
timeout=3,
)
parts = route.stdout.split()
device = parts[parts.index("dev") + 1] if "dev" in parts else None
if not device:
return None
out = subprocess.run(
["nmcli", "-t", "-f", "GENERAL.METERED", "device", "show", device],
capture_output=True,
text=True,
timeout=3,
)
value = out.stdout.strip().split(":", 1)[-1]
return value.startswith("yes")
except Exception:
return None
def _confirm_metered_download(action):
"""Ask before a data-heavy operation if the active connection looks metered.
Returns True if it's fine to proceed (not metered, unknown, or user confirmed).
"""
if _is_metered_connection() is not True:
return True
print(
f"⚠️ Active network connection is metered (e.g. mobile hotspot). {action} can pull a lot of data."
)
if not sys.stdin.isatty():
print(" Not an interactive terminal — pass --yes to proceed anyway.")
return False
return input(" Continue anyway? [y/N] ").strip().lower() == "y"
def cmd_restart(args):
"""Restart the Django container (or do full restart with --force)"""
# Check if --force flag is present
if "--force" in args:
extra_args = [a for a in args if a not in ("--force", "--build")]
rebuild = "--build" in args
print("Forcing full restart (compose down/up) to reload environment variables...")
if rebuild:
print("Rebuilding image first...")
cmd_build(extra_args)
cmd_stop([])
return cmd_start(extra_args)
else:
print(f"Restarting {CONTAINER_NAME}...")
cmd = ["docker", "restart", CONTAINER_NAME]
return subprocess.run(cmd)
DROP_TEST_DB_CLONES = """
import os, re
import django
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
django.setup()
from django.db import connection
base = connection.creation._get_test_db_name()
with connection.cursor() as cursor:
cursor.execute("SELECT datname FROM pg_database WHERE datname LIKE %s", [base + "_%"])
for (name,) in cursor.fetchall():
if re.fullmatch(re.escape(base) + r"_\\d+", name):
cursor.execute("DROP DATABASE " + connection.ops.quote_name(name))
"""
def drop_parallel_test_db_clones():
"""Drop the per-worker test databases left behind by a previous parallel run.
With --keepdb, Django migrates the main test database but reuses any
existing worker clone (test_<name>_1, _2, ...) untouched, so after a new
migration every worker runs against the old schema and fails with
"relation ... does not exist". Re-cloning from the migrated template is
a cheap CREATE DATABASE ... TEMPLATE per worker.
"""
run_docker_command(["python", "-c", DROP_TEST_DB_CLONES])
def run_django_tests(test_args):
"""Run `manage.py test`, re-running serially if a parallel run fails.
Django's parallel runner pickles results back to the parent, and an errored
test whose traceback can't be pickled kills the whole run with "cannot
pickle 'traceback' object" at the first error — so any later failures stay
hidden. The serial re-run costs nothing on a green build and produces a
complete report when it matters. Mirrors the fallback in ci.yml.
"""
parallel = any(a.startswith("--parallel") for a in test_args)
if parallel and "--keepdb" in test_args:
drop_parallel_test_db_clones()
result = run_docker_command(test_args)
if result.returncode == 0 or not parallel:
return result
# Django accepts `--parallel`, `--parallel N` and `--parallel=N`.
serial_args = []
args_iter = iter(test_args)
for arg in args_iter:
if arg.startswith("--parallel="):
continue
if arg == "--parallel":
following = next(args_iter, None)
if following is not None and not following.isdigit():
serial_args.append(following)
continue
serial_args.append(arg)
print("\n⚠️ Parallel run failed — re-running serially for a complete report...")
return run_docker_command(serial_args)
def cmd_test(args):
"""Run Django tests and JavaScript tests
Speed optimizations:
- --smart: Only run tests affected by recent file changes (pytest + testmon).
First run builds a mapping; subsequent runs are very fast.
- --parallel N: Run tests in N parallel workers (default: auto-detect CPUs)
- --failfast: Stop on first failure
- --fast: Shortcut for --parallel --failfast
- --no-keepdb: Recreate test database (use when schema changed)
"""
results = []
# Check for --js-only flag
if "--js-only" in args:
args = [a for a in args if a != "--js-only"]
return cmd_test_js(args)
# The .mo files are gitignored build output, and ./app is bind-mounted over
# the image's freshly compiled copy, so after a pull that adds msgids the
# tests would otherwise run against a stale catalog and fail on German
# assertions. Up-to-date catalogs are skipped, so this costs well under a second.
run_docker_command(["python", "manage.py", "compilemessages", "-v", "0"])
# Check for --smart flag: pytest + testmon (only run tests affected by changes)
if "--smart" in args:
args = [a for a in args if a != "--smart"]
print("🎯 Smart mode: only running tests affected by recent changes...")
print(" (First run builds the mapping — all tests execute once.)")
pytest_args = ["python", "-m", "pytest", "--testmon", "-q"]
if args: # allow passing extra filters, e.g. a test path
pytest_args.extend(args)
return run_docker_command(pytest_args)
# Check for --django-only flag
django_only = "--django-only" in args
if django_only:
args = [a for a in args if a != "--django-only"]
# Check for --no-keepdb flag (recreate test database)
use_keepdb = "--no-keepdb" not in args
if not use_keepdb:
args = [a for a in args if a != "--no-keepdb"]
# Check for --fast shortcut (parallel + failfast)
fast_flags = []
if "--fast" in args:
args = [a for a in args if a != "--fast"]
# Store flags to add later (after positional arguments)
if not any(a.startswith("--parallel") for a in args):
fast_flags.append("--parallel")
if "--failfast" not in args:
fast_flags.append("--failfast")
# Note: Using --keepdb to reuse test database between runs
# This avoids the need for cleanup and speeds up tests
# Determine if specific Django tests were specified
has_specific_tests = (
args and "--all" not in args and any(not arg.startswith("--") for arg in args)
)
# Run Django tests
print("🐍 Running Django tests...")
test_args = ["python", "manage.py", "test"]
if use_keepdb:
test_args.append("--keepdb")
if args and "--all" not in args:
test_args.extend(args)
else:
test_args.extend(["-v", "2"])
# Add --fast flags after positional arguments
test_args.extend(fast_flags)
django_result = run_django_tests(test_args)
results.append(("Django", django_result.returncode))
# Only run JavaScript tests if no specific Django tests were requested and not django-only
if not has_specific_tests and not django_only:
print("\n📊 Running JavaScript tests...")
js_result = cmd_test_js([])
results.append(("JavaScript", js_result.returncode))
# Print summary
print("\n" + "=" * 50)
print("Test Summary:")
print("=" * 50)
for test_type, code in results:
status = "✓ PASSED" if code == 0 else "✗ FAILED"
print(f"{test_type:12} {status}")
print("=" * 50)
# Return non-zero if any test failed
failed = any(code != 0 for _, code in results if code is not None)
return subprocess.CompletedProcess(args=[], returncode=1 if failed else 0)
def cmd_test_js(args):
"""Run the Node.js JavaScript test suites (the same set CI runs)."""
print("📊 Running Node.js-based JS Tests...")
# Discovered, not listed. This used to be a hand-maintained list, and so
# did the copy in .github/workflows/ci.yml — which broke the build the
# first time a suite was deleted (global-search.test.js, P-047). Both
# sides glob now, so adding or removing a suite needs no edit here.
js_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "app", "static", "js")
suites = sorted(
os.path.basename(p)
for pattern in ("*.test.js", "*.test.extended.js")
for p in glob.glob(os.path.join(js_dir, pattern))
)
results = []
for suite in suites:
stem = suite.replace(".test.extended.js", " (extended)").replace(".test.js", "")
print(f"\n--- {suite} ---")
result = run_docker_command(["node", f"/app/static/js/{suite}"])
results.append((f"JS {stem}", result.returncode))
print("\n" + "=" * 50)
print("Node.js Test Summary:")
print("=" * 50)
for test_type, code in results:
status = "✓ PASSED" if code == 0 else "✗ FAILED"
print(f"{test_type:12} {status}")
print("=" * 50)
failed = any(code != 0 for _, code in results)
return subprocess.CompletedProcess(args=[], returncode=1 if failed else 0)
def cmd_manage(args):
"""Run Django management commands"""
if not args:
print("Usage: dev.py manage <command>")
return subprocess.CompletedProcess(args=[], returncode=1)
# If --odt-file points to a host path that isn't already inside the container,
# copy it into the container's /tmp/ first and rewrite the argument.
args = list(args)
container_tmp_path = None
for i, arg in enumerate(args):
if arg == "--odt-file" and i + 1 < len(args):
host_path = os.path.expanduser(args[i + 1])
if not host_path.startswith("/app"):
filename = os.path.basename(host_path)
container_tmp_path = f"/tmp/{filename}"
cp_cmd = ["docker", "cp", host_path, f"{CONTAINER_NAME}:{container_tmp_path}"]
print(f"Copying {host_path} → container:{container_tmp_path}")
result = subprocess.run(cp_cmd)
if result.returncode != 0:
return result
args[i + 1] = container_tmp_path
break
interactive = args[0] in ("createsuperuser", "shell") if args else False
result = run_docker_command(["python", "manage.py"] + args, interactive=interactive)
# Clean up the temporary file from the container.
if container_tmp_path:
run_docker_command(
["rm", "-f", container_tmp_path], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
)
return result
def cmd_python(args):
"""Run Python in the container"""
if args:
return run_docker_command(["python"] + args)
else:
return run_docker_command(["python"], interactive=True)
def cmd_shell(args):
"""Open Django shell or execute command with -c"""
# Check for -c flag (execute command)
if args and args[0] == "-c":
if len(args) < 2:
print("Error: -c requires a command to execute")
print(
'Example: ./dev.py shell -c "from my_practice.models import Client; print(Client.objects.count())"'
)
return subprocess.CompletedProcess(args=[], returncode=1)
command = " ".join(args[1:])
return run_docker_command(["python", "manage.py", "shell"], input=command.encode())
else:
# Interactive shell
return run_docker_command(["python", "manage.py", "shell"], interactive=True)
def cmd_bash(args):
"""Open bash shell in container"""
return run_docker_command(["bash"], interactive=True)
def cmd_build(args):
"""Rebuild Docker image(s) via compose build.
Options:
--no-cache Force full rebuild (ignore layer cache)
--yes Skip the metered-connection confirmation prompt
<service> Build only a specific service (default: all)
"""
skip_confirm = "--yes" in args
args = [a for a in args if a != "--yes"]
if not skip_confirm and not _confirm_metered_download("Rebuilding the image"):
print("Aborted.")
return subprocess.CompletedProcess(args=[], returncode=1)
print("Building Docker image(s)...")
return subprocess.run([*COMPOSE, "build", *args])
def cmd_start(args):
"""Start all containers with compose."""
print("Starting containers with compose...")
result = subprocess.run([*COMPOSE, "up", "-d", *args])
if result.returncode != 0:
return result
# Wait for Django to finish migrating and start serving requests.
print("Waiting for Django to be ready...", end="", flush=True)
wait_cmd = ["docker", "inspect", "--format", "{{.State.Health.Status}}", CONTAINER_NAME]
for _ in range(60):
out = subprocess.run(wait_cmd, capture_output=True, text=True)
status = out.stdout.strip()
if status == "healthy":
print(" ready.")
break
if status == "unhealthy":
print(" unhealthy — check logs with: ./dev.py logs -f")
break
print(".", end="", flush=True)
time.sleep(2)
else:
print(" timed out — check logs with: ./dev.py logs -f")
return result
def cmd_stop(args):
"""Stop all containers with compose."""
print("Stopping containers with compose...")
return subprocess.run([*COMPOSE, "down", *args])
def cmd_logs(args):
"""Show container logs: all services, or the container named first."""
all_services = not args or args[0].startswith("-")
prefix = [*COMPOSE, "logs"] if all_services else ["docker", "logs"]
tail = [] if "-f" in args or "--follow" in args else ["--tail", "100"]
return subprocess.run([*prefix, *tail, *args])
def cmd_ps(args):
"""Show container status"""
return subprocess.run([*COMPOSE, "ps", *args])
def cmd_migrate(args):
"""Run migrations"""
return run_docker_command(["python", "manage.py", "migrate"] + args)
def cmd_makemigrations(args):
"""Create new migrations"""
return run_docker_command(["python", "manage.py", "makemigrations"] + args)
def _container_running():
"""Whether the Django container is up (`docker exec` would fail otherwise)."""
cmd = ["docker", "inspect", "--format", "{{.State.Running}}", CONTAINER_NAME]
try:
out = subprocess.run(cmd, capture_output=True, text=True)
except FileNotFoundError:
# No docker CLI on PATH (e.g. a host shell outside the dev environment):
# there's no container to compile in either, so skip like a stopped one.
return False
return out.returncode == 0 and out.stdout.strip() == "true"
def cmd_i18n(args):
"""Extract and compile translation strings.
Usage:
./dev.py i18n # extract + compile (default)
./dev.py i18n makemessages # extract only
./dev.py i18n compilemessages # compile only
--if-running skips quietly when the container is down, for the post-merge
and post-checkout hooks: a `git pull` shouldn't fail because Docker isn't up,
and the container compiles the catalogs itself on start.
"""
if "--if-running" in args:
args = [a for a in args if a != "--if-running"]
if not _container_running():
print("ℹ️ Django container not running — catalogs compile on next start.")
return subprocess.CompletedProcess(args=[], returncode=0)
sub = args[0] if args else None
if sub not in (None, "makemessages", "compilemessages"):
print(f"Error: unknown i18n step '{sub}' (expected makemessages or compilemessages)")
return subprocess.CompletedProcess(args=[], returncode=1)
if sub in (None, "makemessages"):
result = run_docker_command(
["python", "manage.py", "makemessages", "-l", "de", "-l", "en", "--no-wrap"]
)
if result.returncode != 0:
return result
if sub in (None, "compilemessages"):
result = run_docker_command(["python", "manage.py", "compilemessages"])
return result
def cmd_quality(args):
"""Run code quality checks (ruff format, ruff lint, Tailwind CSS build, tests)
Options:
--no-tests: Skip test execution
--only-format: Run only ruff format + ruff lint
--only-tests: Run only tests
--verbose: Show full output (default: minimal)
Note: vulture and mypy are skipped by default due to many false positives.
Run them manually if needed:
docker exec my-practice-django python -m vulture my_practice
docker exec my-practice-django python -m mypy my_practice
"""
results = []
verbose = "--verbose" in args
run_tests = "--no-tests" not in args
only_format = "--only-format" in args
only_tests = "--only-tests" in args
# Determine which checks to run
run_format = not only_tests
run_tests = run_tests and not only_format
print("🔍 Code Quality Checks")
print("=" * 50)
if not verbose:
print("💡 Use --verbose for full output")
print()
# Ruff format check
if run_format:
print("1️⃣ Ruff format (code formatter)")
print("-" * 30)
cmd = ["python", "-m", "ruff", "format", ".", "--check"]
if not verbose:
cmd.append("--quiet")
fmt_result = run_docker_command(cmd)
# ./app is all the container can see; check the repo-root scripts too.
root_result = _ruff_root_python(verbose=verbose)
if fmt_result.returncode == 0 and root_result == 0:
print("✅ Ruff format OK")
results.append(("Ruff format", 0))
else:
print("❌ Code needs formatting")
if not verbose:
print(" Run: ./dev.py format")
results.append(("Ruff format", 1))
print()
# Ruff linter
if run_format:
print("2️⃣ Ruff lint")
print("-" * 30)
cmd = ["python", "-m", "ruff", "check", "."]
if not verbose:
cmd.extend(["--quiet"])
ruff_result = run_docker_command(cmd)
results.append(("Ruff lint", ruff_result.returncode))
if ruff_result.returncode == 0:
print("✅ Ruff lint passed")
else:
print("❌ Ruff found issues")
if not verbose:
print(" Run with --verbose to see details")
print()
# Runs on the host Python, not in the container: that mounts just ./app,
# and this reads dev.py and prod.py from the repo root.
print("2️⃣ ½ Duplicated helpers (dev.py ↔ prod.py)")
print("-" * 30)
dup_result = subprocess.run([sys.executable, "scripts/check_shared_helpers.py"])
results.append(("Duplicated helpers", dup_result.returncode))
if dup_result.returncode == 0:
print("✅ Duplicated helpers in sync")
else:
print("❌ Duplicated helpers have drifted")
print()
# Same reasoning as above, for the other pair of files that duplicate
# content on purpose: requirements.txt and requirements-dev.txt.
print("2️⃣ ¾ Requirements pins (requirements.txt ↔ requirements-dev.txt)")
print("-" * 30)
req_result = subprocess.run([sys.executable, "scripts/check_requirements_sync.py"])
results.append(("Requirements sync", req_result.returncode))
if req_result.returncode == 0:
print("✅ Runtime pins in sync")
else:
print("❌ Runtime pins have drifted")
print()
# Tailwind CSS build
if run_format:
print("3️⃣ Tailwind CSS build")
print("-" * 30)
css_result = run_docker_command(["npm", "run", "build:css"])
results.append(("Tailwind CSS", css_result.returncode))
if css_result.returncode == 0:
print("✅ Tailwind CSS built")
else:
print("❌ Tailwind CSS build failed")
print()
# Django tests (optional)
if run_tests:
print("4️⃣ Django Tests")
print("-" * 30)
# Note: Using --keepdb to reuse test database between runs
cmd = ["python", "manage.py", "test", "my_practice", "--keepdb", "--parallel"]
if not verbose:
cmd.append("--verbosity=1")
test_result = run_django_tests(cmd)
results.append(("Tests", test_result.returncode))
print()
else:
print("4️⃣ Django Tests")
print("-" * 30)
print("⏭️ Skipped (--no-tests flag)")
print()
# Summary
print()
print("=" * 50)
print("Quality Check Summary:")
print("=" * 50)
for name, code in results:
status = "✅ PASSED" if code == 0 else "❌ FAILED"
print(f"{name:<20} {status}")
print("=" * 50)
if not results:
print("⚠️ No checks were run")
print(" Use --only-format or --only-tests")
return subprocess.CompletedProcess(args=[], returncode=0)
# Return overall status
overall_status = 0 if all(code == 0 for _, code in results) else 1
if overall_status == 0:
print("✅ All checks passed")
else:
print("❌ Some checks failed")
if not verbose:
print("\n💡 Tip: Run with --verbose to see detailed output")
return subprocess.CompletedProcess(args=[], returncode=overall_status)
def _print_outdated_dev_packages():
"""Print outdated host packages that appear in requirements-dev.txt."""
import json
dev_req = os.path.join(os.path.dirname(__file__), "app", "requirements-dev.txt")
try:
with open(dev_req) as f:
# Extract bare package names, normalise to lowercase with hyphens
dev_names = set()
for line in f:
line = line.strip()
if not line or line.startswith("#"):
continue
name = re.split(r"[>=<!;\[]", line)[0].strip().lower().replace("_", "-")
if name:
dev_names.add(name)
except FileNotFoundError:
print(" (requirements-dev.txt not found)")
return
cmd = ["pip3", "list", "--outdated", "--format", "json"]
result = subprocess.run(cmd, capture_output=True, text=True)
if result.returncode != 0 or not result.stdout.strip():
print(" (could not run pip3 on host)")
return
try:
packages = json.loads(result.stdout)
except json.JSONDecodeError:
print(" (failed to parse pip3 output)")
return
relevant = [p for p in packages if p["name"].lower().replace("_", "-") in dev_names]
if relevant:
print(f" {'Package':<30} {'Version':<16} {'Latest':<16} Type")
print(f" {'-' * 30} {'-' * 16} {'-' * 16} ----")
for p in relevant:
print(
f" {p['name']:<30} {p['version']:<16} {p['latest_version']:<16} {p['latest_filetype']}"
)
else:
print(" All dev packages up to date")
def cmd_review(args):
"""Periodic codebase health review (monthly/quarterly).
Runs automated checks and prints the manual checklist.
Options:
--full Quarterly mode: also runs complexity analysis (radon) and
lists files over the long-file threshold
--verbose Show full tool output instead of summaries
--no-tests Skip the test-coverage step (faster, no DB required)
-h, --help Show this help message
"""
if "-h" in args or "--help" in args:
print(inspect.getdoc(cmd_review))
return subprocess.CompletedProcess(args=[], returncode=0)
full = "--full" in args
verbose = "--verbose" in args
no_tests = "--no-tests" in args
results = []
mode = "Quarterly" if full else "Monthly"
print(f"🔬 Codebase Health Review — {mode}")
print("=" * 55)
if not verbose:
print("💡 Use --verbose for full tool output")
print()
# --- 1. Dead code (vulture) ---
print("1️⃣ Dead code (vulture)")
print("-" * 30)
vulture_result = run_docker_command(
["python", "-m", "vulture", "my_practice", "--min-confidence", "80"]
)
results.append(("Dead code (vulture)", vulture_result.returncode))
if vulture_result.returncode == 0:
print("✅ No dead code found")
else:
print("⚠️ Potential dead code above")
print()
# --- 2. Unused imports / variables (ruff F401/F841) ---
print("2️⃣ Unused imports & variables (ruff)")
print("-" * 30)
ruff_cmd = ["python", "-m", "ruff", "check", ".", "--select", "F401,F841"]
if not verbose:
ruff_cmd.append("--quiet")
ruff_result = run_docker_command(ruff_cmd)
results.append(("Unused symbols (ruff)", ruff_result.returncode))
if ruff_result.returncode == 0:
print("✅ No unused imports or variables")
else:
print("⚠️ Unused symbols found above")
print()
# --- 3. Security: known CVEs (pip-audit + npm audit) ---
print("3️⃣ Dependency security (pip-audit + npm audit)")
print("-" * 30)
# Check if pip-audit is available before running
check = run_docker_command(["python", "-c", "import pip_audit"])
if check.returncode != 0:
print("⏭️ pip-audit not installed — skipping Python CVE check")
print(" Install: pip install pip-audit")
results.append(("CVE audit (pip-audit)", None))
else:
audit_result = run_docker_command(
["python", "-m", "pip_audit", "--progress-spinner", "off"]
)
results.append(("CVE audit (pip-audit)", audit_result.returncode))
if audit_result.returncode == 0:
print("✅ No known Python CVEs")
else:
print("⚠️ Python vulnerabilities found above")
npm_audit = run_docker_command(["npm", "audit", "--prefix", "/app"])
results.append(("CVE audit (npm audit)", npm_audit.returncode))
if npm_audit.returncode == 0:
print("✅ No known JS CVEs")
else:
print("⚠️ JS vulnerabilities found above")
print()
# --- 4. Outdated packages ---
print("4️⃣ Outdated packages (pip list --outdated)")
print("-" * 30)
print("App (container / requirements.txt):")
run_docker_command(["pip", "list", "--outdated", "--format", "columns"])
print("Dev tools (host / requirements-dev.txt):")
_print_outdated_dev_packages()
results.append(("Outdated packages", 0)) # informational only
print()
# --- 5. Test coverage ---
print("5️⃣ Test coverage (coverage report)")
print("-" * 30)
if no_tests:
print("⏭️ Skipped (--no-tests)")
results.append(("Coverage", None))
else:
# source/omit/skip flags and the fail_under floor all live in
# app/pyproject.toml, so a `coverage report` run by hand reports the
# same thing this does.
run_docker_command(
[
"python",
"-m",
"coverage",
"run",
"manage.py",
"test",
"my_practice",
"--keepdb",
"--verbosity=0",
]
)
cov_cmd = ["python", "-m", "coverage", "report"]
if not verbose:
cov_cmd.extend(["--sort=miss"])
cov_result = run_docker_command(cov_cmd)
results.append(("Coverage", cov_result.returncode))
if cov_result.returncode != 0:
print("❌ Coverage is below the floor in app/pyproject.toml")
print()
# --- 6. Complexity (quarterly only) ---
if full:
print("6️⃣ Complexity hotspots (radon cc)")
print("-" * 30)
check = run_docker_command(["python", "-c", "import radon"])
if check.returncode != 0:
print("⏭️ radon not installed in container — skipping complexity check")
print(" Rebuild the container to install it: ./dev.py build")
results.append(("Complexity (radon)", None))
else:
radon_result = run_docker_command(
[
"python",
"-m",
"radon",
"cc",
"my_practice",
"--min",
"C", # C = complex, D/E/F = very complex
"--show-complexity",
"--average",
]
)
results.append(("Complexity (radon)", radon_result.returncode))
print()
# --- 7. Long files (quarterly only) ---
# Same threshold and pathspecs as the generated metrics page, so the two
# never disagree; that page has the month-by-month trend, this is the list.
print("7️⃣ Long files (scripts/codebase_metrics.py --largest)")
print("-" * 30)
long_result = subprocess.run(
[sys.executable, "scripts/codebase_metrics.py", "--largest"],
cwd=os.path.dirname(os.path.abspath(__file__)),
)
results.append(("Long files", long_result.returncode))
print()
# --- Summary ---
print("=" * 55)
print("Automated Check Summary:")
print("=" * 55)
for name, code in results:
status = "⏭️ Skipped" if code is None else ("✅ OK" if code == 0 else "⚠️ Review")
print(f" {name:<30} {status}")
print()
# --- Manual checklist ---
print("=" * 55)
print(f"Manual Checklist — {mode}:")
print("=" * 55)
monthly_items = [
"git log: repeated fixes in same area? (design smell)",
"German comments/identifiers in touched files? (P-038)",
"GH issues: close stale items inactive >2 months",
"New views bypassing mixins/builders? Consolidate",
]
quarterly_items = [
"Similar blocks across views/utils? Extract a helper",
"Django/Python/WeasyPrint/psycopg major versions?",
"New builder/helper patterns followed by recent code?",
"PROJECTS.md: stale WIPs → done/cancelled?",
"docs/architecture/CODE_STRUCTURE.md still accurate?",
"New language features that simplify existing code?",
]
for item in monthly_items:
print(f" [ ] {item}")
if full:
print()
print(" Quarterly extras:")
for item in quarterly_items:
print(f" [ ] {item}")
print()
print(
"See docs/guides/CODEBASE_STANDARDS.md for the full scan checklist and canonical patterns."
)
return subprocess.CompletedProcess(args=[], returncode=0)
def cmd_format(args):
"""Format code with ruff format (Black-compatible formatter only).
Note: does NOT run ruff check --fix. Auto-fixing lint rules can silently
introduce syntax regressions (e.g. UP034 stripping parens from
`except (A, B):` → Python 2 syntax). Use `./dev.py lint` to review
lint issues and fix them manually.
"""
print("🎨 Formatting code with ruff...")
result = run_docker_command(["python", "-m", "ruff", "format", "."])
# ./app is all the container can see; format the repo-root scripts too.
_ruff_root_python(write=True)
return result
def cmd_lint(args):
"""Run ruff format check + ruff lint only (fast, no tests).
Use this during development for quick feedback.
Use ./dev.py quality to run the full suite before a release.
"""
return cmd_quality(["--only-format"] + args)
def cmd_calendar_auth(_args):
"""Open the page that re-authorizes Google Calendar in the default browser.
Use this when the calendar token has expired (invalid_grant error).
Opens the import page because /calendar/authorize/ only accepts POST: without
a usable token, the import page shows the form that starts the OAuth2/PKCE flow.
The app must be running (./dev.py start) before calling this.
"""
url = "http://localhost:8000/calendar/import/"
print(f"Opening {url} in your browser...")
print("Click 'Connect with Google' and complete the sign-in to refresh the token.")
print("If the page lists calendars or events instead, the token still works.")
result = subprocess.run(["xdg-open", url])
if result.returncode != 0:
print(f"xdg-open failed. Open this URL manually in your browser:\n {url}")
return result
def cmd_smoke(args):
"""Smoke-test a released GHCR image in a contained fashion (issue #202).
Pulls ghcr.io/dholbach/my-practice:<version>, boots it against a throwaway
postgres under an isolated compose project (my-practice-smoke), waits for
migrations + gunicorn via the healthcheck, verifies the image reports the
expected version and serves the login page, then tears everything down.
Runs safely alongside the dev stack: no shared container names, volumes,
ports, or bind mounts.
Usage:
./dev.py smoke [vX.Y.Z] [--keep] [--no-pull]
./dev.py smoke --down
Options:
vX.Y.Z Image tag to test (default: version.py of this checkout)
--keep Leave the stack running for manual inspection
--no-pull Skip the explicit pull (use a locally cached image)
--down Tear down a stack left running by a previous --keep run
--yes Skip the metered-connection confirmation prompt
"""
import base64
import secrets as pysecrets
import tempfile
keep = "--keep" in args
no_pull = "--no-pull" in args
down_only = "--down" in args
skip_confirm = "--yes" in args
positional = [a for a in args if not a.startswith("-")]
if (
not no_pull
and not down_only
and not skip_confirm
and not _confirm_metered_download("Pulling the smoke-test image")
):
print("Aborted.")
return subprocess.CompletedProcess(args=[], returncode=1)
repo_dir = os.path.dirname(os.path.abspath(__file__))
if positional:
version = positional[0]
else:
version_py = os.path.join(repo_dir, "app", "my_practice", "version.py")
with open(version_py) as fh:
version = re.search(r'VERSION\s*=\s*"([^"]+)"', fh.read()).group(1)
project = "my-practice-smoke"
compose_file = os.path.join(repo_dir, "docker-compose.smoke.yml")
def compose(*extra, capture=False):
cmd = [*COMPOSE, "-p", project, "-f", compose_file, "--env-file", env_file, *extra]
return subprocess.run(cmd, capture_output=capture, text=capture)
def fail(result, message):
print(f"\n❌ {message}")
print("── last 50 log lines ──")
compose("logs", "--tail", "50")
if not keep:
compose("down", "-v", "--remove-orphans")
result.returncode = result.returncode or 1
return result
# Throwaway secrets, passed via a private --env-file (never written to .env)
tmp_dir = tempfile.mkdtemp(prefix="my-practice-smoke-")
env_file = os.path.join(tmp_dir, "smoke.env")
with open(env_file, "w") as fh:
fh.write(f"SMOKE_VERSION={version}\n")
fh.write(f"POSTGRES_PASSWORD={pysecrets.token_urlsafe(32)}\n")
fh.write(f"DJANGO_SECRET_KEY={pysecrets.token_urlsafe(50)}\n")
fh.write(f"FERNET_KEY={base64.urlsafe_b64encode(os.urandom(32)).decode()}\n")
if down_only:
print("Tearing down the smoke stack...")
try:
result = compose("down", "-v", "--remove-orphans")
finally:
os.remove(env_file)
os.rmdir(tmp_dir)
return result
print(f"🔥 Smoke-testing ghcr.io/dholbach/my-practice:{version}")
try:
if not no_pull:
print("── pulling image ──")
result = compose("pull", "django")
if result.returncode != 0:
return fail(result, f"Could not pull image for {version}.")
print("── booting stack (migrate + collectstatic + gunicorn) ──")
result = compose("up", "-d", "--wait", "--quiet-pull")
if result.returncode != 0:
return fail(result, "Stack did not become healthy.")
print("── verifying ──")
result = compose(
"exec",
"-T",
"django",
"python",
"-c",
"from my_practice.version import VERSION; print(VERSION)",
capture=True,
)
reported = result.stdout.strip()
if result.returncode != 0 or reported != version:
return fail(result, f"Image reports version {reported!r}, expected {version!r}.")
print(f" ✓ image reports {reported}")
result = compose(
"exec",
"-T",
"django",
"curl",
"-sf",
"http://localhost:8000/accounts/login/",
capture=True,
)
if result.returncode != 0 or "csrfmiddlewaretoken" not in result.stdout:
return fail(result, "Login page did not render.")
print(" ✓ login page renders (migrations ran, gunicorn serving)")
port = compose("port", "django", "8000", capture=True).stdout.strip()
print(f"\n✅ {version} passed the smoke test.")
if keep:
print(f" Stack left running at http://{port}")
print(" Tear down with: ./dev.py smoke --down")
return subprocess.CompletedProcess(args=[], returncode=0)
finally:
if not keep:
compose("down", "-v", "--remove-orphans", capture=True)
try:
os.remove(env_file)
os.rmdir(tmp_dir)
except OSError:
pass
def cmd_install_hooks(_args):
"""Install the pre-commit hooks from .pre-commit-config.yaml.
Run once after cloning. The hooks run ruff, gitleaks, the PII guard and the
file-sync checks before each commit (host tools, no Docker needed).
"""
repo_root = os.path.dirname(os.path.abspath(__file__))
if shutil.which("pre-commit") is None:
print("❌ pre-commit is not installed on the host.")
print(" Install it, then re-run this command:")
print(" pip install pre-commit # or: pipx install pre-commit")
print(" (it is pinned in app/requirements-dev.txt)")
return subprocess.CompletedProcess(args=[], returncode=1)
# An earlier version of this command pointed git at a committed .githooks/
# directory. core.hooksPath overrides .git/hooks/ wholesale, so leaving it
# set makes `pre-commit install` refuse — and, worse, silently bypasses
# every hook below on a clone where it was set before the migration.
existing = subprocess.run(
["git", "config", "--get", "core.hooksPath"],
cwd=repo_root,
capture_output=True,
text=True,
)
if existing.returncode == 0 and existing.stdout.strip():
print(f"ℹ️ Clearing core.hooksPath (was: {existing.stdout.strip()})")
subprocess.run(["git", "config", "--unset", "core.hooksPath"], cwd=repo_root)
result = subprocess.run(["pre-commit", "install"], cwd=repo_root)
if result.returncode == 0:
print("✅ Hooks installed — .pre-commit-config.yaml runs on every commit.")
print(" Run them over the whole tree: pre-commit run --all-files")
print(" To skip the hooks for one commit: git commit --no-verify")
return result
def cmd_run(args):
"""Run a Python script in the container with Django environment loaded"""
if not args:
print("Error: Please specify a Python script to run")
print("Example: ./dev.py run check_df.py")
return subprocess.CompletedProcess(args=[], returncode=1)
script_path = args[0]
# Check if script exists
if not os.path.exists(script_path):
print(f"Error: Script not found: {script_path}")
return subprocess.CompletedProcess(args=[], returncode=1)
# Read script content
with open(script_path, "r") as f:
script_content = f.read()
return run_docker_command(["python", "manage.py", "shell"], input=script_content.encode())
def cmd_exec(args):
"""Execute arbitrary command in container"""
if not args:
print("Error: Please specify a command to execute")
print("Example: ./dev.py exec ls -la")
return subprocess.CompletedProcess(args=[], returncode=1)
return run_docker_command(args)
def cmd_sql(args):
"""Execute SQL query in PostgreSQL database"""
if not args:
print("Error: Please specify SQL query or file")
print("Examples:")
print(' ./dev.py sql "SELECT * FROM my_practice_client LIMIT 5"')
print(" ./dev.py sql query.sql")
return subprocess.CompletedProcess(args=[], returncode=1)
query = args[0]
# Check if it's a file
if os.path.exists(query):
with open(query, "r") as f:
query = f.read()
return run_docker_command(["psql", "-U", "my_practice", "-d", "my_practice", "-c", query])
def cmd_psql(args):
"""Open interactive PostgreSQL shell"""
print("Opening PostgreSQL shell...")
return run_docker_command(["psql", "-U", "my_practice", "-d", "my_practice"], interactive=True)
def cmd_backup(args):
"""Back up database + media via scripts/backup.sh (the implementation is prod.py's)."""
script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "scripts", "backup.sh")
return subprocess.run(["bash", script, *args])
COMMANDS = {
"backup": cmd_backup,
"build": cmd_build,
"start": cmd_start,
"stop": cmd_stop,
"restart": cmd_restart,
"test": cmd_test,
"test-js": cmd_test_js,
"manage": cmd_manage,
"python": cmd_python,
"shell": cmd_shell,
"bash": cmd_bash,
"logs": cmd_logs,
"ps": cmd_ps,
"migrate": cmd_migrate,
"makemigrations": cmd_makemigrations,
"i18n": cmd_i18n,
"quality": cmd_quality,
"lint": cmd_lint,
"review": cmd_review,
"format": cmd_format,
"calendar-auth": cmd_calendar_auth,
"smoke": cmd_smoke,
"install-hooks": cmd_install_hooks,
"run": cmd_run,
"exec": cmd_exec,
"sql": cmd_sql,
"psql": cmd_psql,
}
def print_help():
"""Print usage information"""
print("Usage: dev.py <command> [args...]")
print("\nAvailable commands:")
print(" start - Start all containers (compose up -d)")
print(" stop - Stop all containers (compose down)")
print(" build [--no-cache] - Rebuild Docker image(s)")
print(" restart [--force] - Restart the Django container (--force: full down/up)")
print(" test [args] - Run tests (default: Django + JS)")
print(" test --js-only - Run only JavaScript tests (Node.js)")
print(" test --django-only - Run only Django tests")
print(" test-js - Run JavaScript tests (Node.js-based)")
print(" manage <cmd> [args] - Run Django management commands")
print(" python [args] - Run Python in the container")
print(' shell [-c "cmd"] - Open Django shell or execute command with -c')
print(" bash - Open bash shell in container")
print(" run <script> - Run a Python script with Django environment")
print(" exec <cmd> [args] - Execute arbitrary command in container")
print(" sql <query|file> - Execute SQL query or file")
print(" psql - Open interactive PostgreSQL shell")
print(" backup - Back up database + media (verified, 30-day rotation)")
print(" logs [args] - Show container logs (default: all services, last 100 lines)")
print(" ps - Show container status")
print(" migrate [args] - Run migrations")
print(" makemigrations [args]- Create new migrations")
print(" i18n [sub] - Extract/compile translations (makemessages + compilemessages)")
print(" lint - Fast lint check: ruff format + ruff check (no tests, ~seconds)")
print(" lint --verbose - Lint with full output")
print(" quality - Full pre-release check: lint + full test suite (~minutes)")
print(" quality --no-tests - Run quality checks without tests")
print(" quality --only-tests - Run only tests")
print(" quality --verbose - Show full output from all tools")
print(" review - Monthly codebase health check (dead code, CVEs, coverage)")
print(" review --full - Quarterly review (adds complexity analysis)")
print(" review --verbose - Show full tool output during review")
print(" format - Auto-format code with ruff format")
print(" calendar-auth - Open the calendar import page to re-authorize an expired token")
print(
" smoke [vX.Y.Z] - Boot a released GHCR image with a throwaway DB and verify it serves"
)
print(" smoke --keep - Leave the smoke stack running for manual inspection")
print(" smoke --down - Tear down a smoke stack left running by --keep")
print(" install-hooks - Install the pre-commit hooks (run once after clone)")
print("\nExamples:")
print(" ./dev.py start # Start all containers")
print(" ./dev.py start --build # Rebuild and start")
print(" ./dev.py build # Rebuild image (cached)")
print(" ./dev.py build --no-cache # Full rebuild (no cache)")
print(" ./dev.py restart --force # Full restart (reloads .env)")
print(" ./dev.py restart --force --build # Rebuild + full restart")
print(" ./dev.py stop # Stop all containers")
print(" ./dev.py stop -v # Stop and remove volumes")
print(" ./dev.py ps # Show container status")
print(" ./dev.py logs -f # Follow all logs")
print(" ./dev.py logs --tail 50 django # Last 50 lines of Django")
print(" ./dev.py test # Run all tests")
print(" ./dev.py test --django-only # Run only Django tests")
print(" ./dev.py test --js-only # Run only JavaScript tests")
print(" ./dev.py test-js # Run Node.js JS tests")
print(" ./dev.py test my_practice.tests.test_imports # Run specific tests")
print(" ./dev.py manage createsuperuser # Create superuser")
print(" ./dev.py shell # Open Django shell")
print(" ./dev.py shell -c \"print('Hello')\" # Execute command in Django shell")
print(" ./dev.py run check_df.py # Run Python script with Django")
print(" ./dev.py exec ls -la /app # Execute command in container")
print(' ./dev.py sql "SELECT COUNT(*) FROM ..." # Execute SQL query')
print(" ./dev.py psql # Open PostgreSQL shell")
def main():
if len(sys.argv) < 2 or sys.argv[1] in ["-h", "--help", "help"]:
print_help()
return 0
command = sys.argv[1]
args = sys.argv[2:]
if command not in COMMANDS:
print(f"Unknown command: {command}")
print("")
print_help()
return 1
result = COMMANDS[command](args)
return result.returncode
if __name__ == "__main__":
sys.exit(main())