Merge pull request #6 from saaspegasus/pegasus-2026.7.1-1785249993.303172

Pegasus update to version 2026.7.1

Author: czue

CLAUDE.md

@@ -138,6 +138,18 @@ make uv run 'pegasus startapp <app_name> <Model1> <Model2Name>'  # Start a new D
 - Try to use type hints in new code. However, strict type-checking is not enforced and you can leave them out if it's burdensome.
   There is no need to add type hints to existing code if it does not already use them.
 
+### Type annotation conventions
+
+Type checking runs with mypy + django-stubs (`make type-check`). Conventions:
+
+- **Routed views leave `request` unannotated** (all of them, even views that don't touch `request.user`).
+  mypy can't see the guarantees made by `@login_required` and similar decorators, so annotating
+  `request: HttpRequest` makes accesses like `request.user.<related>` fail type checking.
+  Everything that isn't a routed view — middleware, context processors, signal handlers, forms,
+  internal helpers — should annotate `request: HttpRequest` normally.
+- **In DRF views where a permission class guarantees authentication**, get the typed user via
+  `apps.users.helpers.get_authenticated_user(request)` rather than casting `request.user` inline.
+
 ### Python 3.14 syntax notes
 
 - **Unparenthesized `except` with multiple exception types is valid** (PEP 758, Python 3.14+).

apps/users/apps.py

@@ -6,5 +6,5 @@ class UserConfig(AppConfig):
     label = "users"
     default_auto_field = "django.db.models.BigAutoField"
 
-    def ready(self):
+    def ready(self) -> None:
         from . import signals  # noqa F401

apps/users/forms.py

@@ -20,10 +20,10 @@ class TurnstileSignupForm(SignupForm):
 
     turnstile_token = forms.CharField(widget=forms.HiddenInput(), required=False)
 
-    def clean_turnstile_token(self):
+    def clean_turnstile_token(self) -> str | None:
         if not settings.TURNSTILE_SECRET:
             logging.info("No turnstile secret found, not checking captcha")
-            return
+            return None
 
         turnstile_token = self.cleaned_data.get("turnstile_token", None)
         if not turnstile_token:

apps/users/helpers.py

@@ -1,25 +1,42 @@
 import os
+from typing import TYPE_CHECKING, cast
 
 from allauth.account import app_settings
 from allauth.account.models import EmailAddress
 from django.conf import settings
 from django.core.exceptions import ValidationError
+from django.http import HttpRequest
 from django.utils.translation import gettext as _
 
+if TYPE_CHECKING:
+    from apps.users.models import CustomUser
 
-def require_email_confirmation():
+
+def require_email_confirmation() -> bool:
     return settings.ACCOUNT_EMAIL_VERIFICATION == app_settings.EmailVerificationMethod.MANDATORY
 
 
-def user_has_confirmed_email_address(user, email):
+def user_has_confirmed_email_address(user: CustomUser, email: str) -> bool:
     try:
         email_obj = EmailAddress.objects.get_for_user(user, email)
         return email_obj.verified
     except EmailAddress.DoesNotExist:
         return False
 
 
-def validate_profile_picture(value):
+def get_authenticated_user(request: HttpRequest) -> CustomUser:
+    """
+    Get the authenticated user, resolving API-key auth if needed.
+
+    Callers must guarantee authentication (e.g. via permission classes or login_required).
+    """
+    if request.user.is_anonymous:
+        raise ValueError("get_authenticated_user requires an authenticated user")
+    else:
+        return cast("CustomUser", request.user)
+
+
+def validate_profile_picture(value) -> None:
     valid_extensions = {
         ".jpg",
         ".jpeg",

apps/users/management/commands/promote_user_to_superuser.py

@@ -1,15 +1,17 @@
-from django.core.management.base import BaseCommand, CommandError
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError, CommandParser
 
 from apps.users.models import CustomUser
 
 
 class Command(BaseCommand):
     help = "Promotes the given user to a superuser and provides admin access."
 
-    def add_arguments(self, parser):
+    def add_arguments(self, parser: CommandParser) -> None:
         parser.add_argument("username", type=str)
 
-    def handle(self, username, **options):
+    def handle(self, username: str, **options: Any) -> None:
         try:
             user = CustomUser.objects.get(username=username)
         except CustomUser.DoesNotExist:

apps/users/models.py

@@ -9,7 +9,7 @@
 from apps.users.helpers import validate_profile_picture
 
 
-def _get_avatar_filename(instance, filename):
+def _get_avatar_filename(instance: CustomUser, filename: str) -> str:
     """Use random filename prevent overwriting existing files & to fix caching issues."""
     return f"profile-pictures/{uuid.uuid4()}.{filename.split('.')[-1]}"
 
@@ -21,7 +21,7 @@ class CustomUser(AbstractUser):
 
     avatar = models.FileField(upload_to=_get_avatar_filename, blank=True, validators=[validate_profile_picture])
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.get_full_name()} <{self.email or self.username}>"
 
     def get_display_name(self) -> str:
@@ -42,5 +42,5 @@ def gravatar_id(self) -> str:
         return hashlib.md5(self.email.lower().strip().encode("utf-8")).hexdigest()
 
     @cached_property
-    def has_verified_email(self):
+    def has_verified_email(self) -> bool:
         return EmailAddress.objects.filter(user=self, verified=True).exists()

apps/users/signals.py

@@ -1,23 +1,27 @@
+from typing import Any
+
+from allauth.account.models import EmailAddress
 from allauth.account.signals import email_confirmed, user_signed_up
 from django.conf import settings
 from django.core.files.storage import default_storage
 from django.core.mail import mail_admins
 from django.db.models.signals import post_delete, pre_save
 from django.dispatch import receiver
+from django.http import HttpRequest
 
 from apps.users.models import CustomUser
 
 
 @receiver(user_signed_up)
-def handle_sign_up(request, user, **kwargs):
+def handle_sign_up(request: HttpRequest, user: CustomUser, **kwargs: Any) -> None:
     # customize this function to do custom logic on sign up, e.g. send a welcome email
     # or subscribe them to your mailing list.
     # This example notifies the admins, in case you want to keep track of sign ups
     _notify_admins_of_signup(user)
 
 
 @receiver(email_confirmed)
-def update_user_email(sender, request, email_address, **kwargs):
+def update_user_email(sender: Any, request: HttpRequest, email_address: EmailAddress, **kwargs: Any) -> None:
     """
     When an email address is confirmed make it the primary email.
     """
@@ -26,7 +30,7 @@ def update_user_email(sender, request, email_address, **kwargs):
     email_address.set_as_primary()
 
 
-def _notify_admins_of_signup(user):
+def _notify_admins_of_signup(user: CustomUser) -> None:
     mail_admins(
         f"Yowsers, someone signed up for {settings.PROJECT_METADATA['NAME']}!",
         f"Email: {user.email}",
@@ -35,20 +39,20 @@ def _notify_admins_of_signup(user):
 
 
 @receiver(pre_save, sender=CustomUser)
-def remove_old_profile_picture_on_change(sender, instance, **kwargs):
+def remove_old_profile_picture_on_change(sender: type[CustomUser], instance: CustomUser, **kwargs: Any) -> None:
     if not instance.pk:
-        return False
+        return
 
     try:
         old_file = sender.objects.get(pk=instance.pk).avatar
     except sender.DoesNotExist:
-        return False
+        return
 
-    if old_file and old_file.name != instance.avatar.name and default_storage.exists(old_file.name):
+    if old_file.name and old_file.name != instance.avatar.name and default_storage.exists(old_file.name):
         default_storage.delete(old_file.name)
 
 
 @receiver(post_delete, sender=CustomUser)
-def remove_profile_picture_on_delete(sender, instance, **kwargs):
-    if instance.avatar and default_storage.exists(instance.avatar.name):
+def remove_profile_picture_on_delete(sender: type[CustomUser], instance: CustomUser, **kwargs: Any) -> None:
+    if instance.avatar.name and default_storage.exists(instance.avatar.name):
         default_storage.delete(instance.avatar.name)

apps/users/views.py

@@ -12,7 +12,7 @@
 
 
 @login_required
-def profile(request):
+def profile(request) -> HttpResponse:
     if request.method == "POST":
         form = CustomUserChangeForm(request.POST, instance=request.user)
         if form.is_valid():
@@ -57,7 +57,7 @@ def profile(request):
 
 @login_required
 @require_POST
-def upload_profile_image(request):
+def upload_profile_image(request) -> HttpResponse:
     user = request.user
     form = UploadAvatarForm(request.POST, request.FILES)
     if form.is_valid():

apps/web/context_processors.py

@@ -1,11 +1,13 @@
 from copy import copy
+from typing import Any
 
 from django.conf import settings
+from django.http import HttpRequest
 
 from .meta import absolute_url, get_server_root
 
 
-def project_meta(request):
+def project_meta(request: HttpRequest) -> dict[str, Any]:
     # modify these values as needed and add whatever else you want globally available here
     project_data = copy(settings.PROJECT_METADATA)
     project_data["TITLE"] = "{} | {}".format(project_data["NAME"], project_data["DESCRIPTION"])
@@ -20,7 +22,7 @@ def project_meta(request):
     }
 
 
-def csrf_settings(request):
+def csrf_settings(request: HttpRequest) -> dict[str, str]:
     """
     Exposes the configured CSRF cookie name to templates so front-end JS can
     read the correct cookie regardless of how CSRF_COOKIE_NAME is set. See
@@ -31,7 +33,7 @@ def csrf_settings(request):
     }
 
 
-def google_analytics_id(request):
+def google_analytics_id(request: HttpRequest) -> dict[str, str]:
     """
     Adds google analytics id to all requests
     """

apps/web/management/commands/bootstrap_celery_tasks.py

@@ -1,20 +1,22 @@
+from typing import Any
+
 from django.conf import settings
-from django.core.management.base import BaseCommand
+from django.core.management.base import BaseCommand, CommandParser
 from django_celery_beat.models import PeriodicTask
 from django_celery_beat.schedulers import ModelEntry
 
 
 class Command(BaseCommand):
     help = "Bootstrap Celery periodic tasks for the environment."
 
-    def add_arguments(self, parser):
+    def add_arguments(self, parser: CommandParser) -> None:
         parser.add_argument(
             "--remove-stale",
             action="store_true",
             help="Remove tasks that are not defined in this command",
         )
 
-    def handle(self, *args, **options):
+    def handle(self, *args: Any, **options: Any) -> None:
         created_task_names = []
         for task_name, task_config in settings.SCHEDULED_TASKS.items():
             schedule_spec = task_config.pop("schedule")