Add typing

Author: stephane

src/webstack_django_sorting/common.py

@@ -3,14 +3,21 @@
 """
 
 from operator import attrgetter
+from typing import Any, Literal, Sequence
 
-from django.db.models import F
-from django.http import Http404
+from django.db.models import F, QuerySet
+from django.http import Http404, HttpRequest
 
 from . import settings
 
 
-def render_sort_anchor(request, field_name, title, default_direction):
+def render_sort_anchor(
+    request: HttpRequest,
+    field_name: str,
+    title: str,
+    default_direction: Literal["asc", "desc"],
+) -> str:
+    """Render an HTML anchor tag for sorting a column."""
     get_params = request.GET.copy()
     sort_by = get_params.get("sort", None)
     if sort_by == field_name:
@@ -41,9 +48,9 @@ def render_sort_anchor(request, field_name, title, default_direction):
     return f'<a href="{request.path}{url_append}" title="{title}">{title}{icon}</a>'
 
 
-def get_order_by_from_request(request):
+def get_order_by_from_request(request: HttpRequest) -> str:
     """
-    Retrieve field used for sorting a queryset
+    Retrieve field used for sorting a queryset.
 
     :param request: HTTP request
     :return: the sorted field name, prefixed with "-" if ordering is descending
@@ -54,7 +61,8 @@ def get_order_by_from_request(request):
     return f"{sort_sign}{field_name}"
 
 
-def need_python_sorting(queryset, order_by):
+def need_python_sorting(queryset: QuerySet[Any], order_by: str) -> bool:
+    """Check if Python sorting is needed (for non-database fields)."""
     if order_by.find("__") >= 0:
         # Python can't sort order_by with '__'
         return False
@@ -65,9 +73,19 @@ def need_python_sorting(queryset, order_by):
     return field not in field_names
 
 
-def sort_queryset(queryset, order_by, null_ordering):
-    """order_by is an Django ORM order_by argument"""
+def sort_queryset(
+    queryset: QuerySet[Any],
+    order_by: str,
+    null_ordering: dict[str, bool],
+) -> QuerySet[Any] | Sequence[Any]:
+    """
+    Sort a queryset by the given field.
 
+    :param queryset: The queryset to sort
+    :param order_by: Django ORM order_by argument (e.g., "name" or "-name")
+    :param null_ordering: Dict with nulls_first or nulls_last setting
+    :return: Sorted queryset or list (if Python sorting is used)
+    """
     if not order_by:
         # In this case the queryset can't be ordered (no field name specified)
         # even though nulls ordering is set
@@ -79,7 +97,7 @@ def sort_queryset(queryset, order_by, null_ordering):
     if order_by[0] == "-":
         if len(order_by) == 1:
             # Prefix without field name
-            raise ValueError
+            raise ValueError("Order by prefix without field name")
 
         reverse = True
         name = order_by[1:]
@@ -91,13 +109,23 @@ def sort_queryset(queryset, order_by, null_ordering):
         # Fallback on pure Python sorting (much slower on large data)
         if hasattr(queryset[0], name):
             return sorted(queryset, key=attrgetter(name), reverse=reverse)
-        raise AttributeError
+        raise AttributeError(f"Object has no attribute '{name}'")
 
     ordering_exp = (F(name).desc if reverse else F(name).asc)(**null_ordering)
     return queryset.order_by(ordering_exp)
 
 
-def get_null_ordering(request, default_template_ordering=None):
+def get_null_ordering(
+    request: HttpRequest,
+    default_template_ordering: str | None = None,
+) -> dict[str, bool]:
+    """
+    Get null ordering configuration from request or template default.
+
+    :param request: HTTP request
+    :param default_template_ordering: Default ordering from template ("first" or "last")
+    :return: Dict with nulls_first or nulls_last setting, or empty dict
+    """
     # Prioritize changes in URL parameter over the default template variable
     nulls_value = request.GET.get("nulls", default_template_ordering)
     if nulls_value:

src/webstack_django_sorting/jinja2_globals.py

@@ -1,13 +1,28 @@
+from typing import Any, Literal, Sequence
+
+from django.db.models import QuerySet
+from django.http import HttpRequest
 from markupsafe import Markup
 
 from . import common
 
 
-def sorting_anchor(request, field_name, title, default_sort_order="asc"):
+def sorting_anchor(
+    request: HttpRequest,
+    field_name: str,
+    title: str,
+    default_sort_order: Literal["asc", "desc"] = "asc",
+) -> Markup:
+    """Render a sorting anchor link for Jinja2 templates."""
     return Markup(common.render_sort_anchor(request, field_name, title, default_sort_order))
 
 
-def sort_queryset(request, queryset, **context_var):
+def sort_queryset(
+    request: HttpRequest,
+    queryset: QuerySet[Any],
+    **context_var: str | None,
+) -> QuerySet[Any] | Sequence[Any]:
+    """Sort a queryset based on request parameters for Jinja2 templates."""
     order_by = common.get_order_by_from_request(request)
     null_ordering = common.get_null_ordering(request, context_var.get("nulls"))
     return common.sort_queryset(queryset, order_by, null_ordering)

src/webstack_django_sorting/templatetags/sorting_tags.py

@@ -1,13 +1,17 @@
+from typing import Literal
+
 from django import template
 from django.http import Http404
+from django.template import Context
+from django.template.base import Parser, Token
 from django.utils.translation import gettext_lazy as _
 
 from .. import common, settings
 
 register = template.Library()
 
 
-def anchor(parser, token):
+def anchor(parser: Parser, token: Token) -> SortAnchorNode:
     """
     Parses a tag that's supposed to be in this format '{% anchor field title %}'
     Title may be a "string", _("trans string"), or variable
@@ -59,14 +63,21 @@ class SortAnchorNode(template.Node):
 
     """
 
-    def __init__(self, field, title, title_is_var, title_is_translatable, default_sort_order):
+    def __init__(
+        self,
+        field: str,
+        title: str,
+        title_is_var: bool,
+        title_is_translatable: bool,
+        default_sort_order: Literal["asc", "desc"],
+    ) -> None:
         self.field = field
         self.title = title
         self.title_is_var = title_is_var
         self.title_is_translatable = title_is_translatable
         self.default_sort_order = default_sort_order
 
-    def render(self, context):
+    def render(self, context: Context) -> str:
         if self.title_is_var:
             display_title = context[self.title]
         elif self.title_is_translatable:
@@ -79,17 +90,18 @@ def render(self, context):
         )
 
 
-def autosort(parser, token):
+def autosort(parser: Parser, token: Token) -> SortedDataNode:
+    """Parse the autosort template tag."""
     bits = [b.strip("\"'") for b in token.split_contents()]
     help_msg = "autosort tag synopsis: {%% autosort queryset [as context_variable] %%}"
-    context_var = None
+    context_var: str | None = None
 
     # Check if their is some optional parameter (as new_context_var, nulls)
     if 2 > len(bits) > 7:
         raise template.TemplateSyntaxError(help_msg)
 
     context_var = None
-    null_ordering = None
+    null_ordering: str | None = None
 
     for index, bit in enumerate(bits):
         if index > 1:
@@ -107,12 +119,17 @@ class SortedDataNode(template.Node):
     Automatically sort a queryset with {% autosort queryset %}
     """
 
-    def __init__(self, queryset_var, null_ordering, context_var=None):
+    def __init__(
+        self,
+        queryset_var: str,
+        null_ordering: str | None,
+        context_var: str | None = None,
+    ) -> None:
         self.queryset_var = template.Variable(queryset_var)
         self.context_var = context_var
         self.null_ordering = null_ordering
 
-    def render(self, context):
+    def render(self, context: Context) -> str:
         if self.context_var is not None:
             key = self.context_var
         else: