comment edits

Author: timgraham

django_mongodb_backend/compiler.py

@@ -843,7 +843,7 @@ def _compile_window_sort_by(self, order_by_list, sort_fields):
         Compile Window.order_by to a MongoDB sortBy document and any pre-sort
         $addFields.
 
-        sort_fields is a shared dict (expr_mql_key → field_name) across all
+        sort_fields is a shared dict {expr_mql_key: field_name} across all
         windows in the same query, so that identical expressions reuse the same
         field name and different expressions get distinct names.
         """
@@ -877,7 +877,7 @@ def _compile_window_sort_by(self, order_by_list, sort_fields):
                 # so {ind: 0, val: v} vs {ind: 1, val: null} is decided by
                 # "ind" before "val", giving clean null positioning.
                 # null_ind=1 puts null AFTER non-null in ASC / BEFORE in DESC.
-                # nulls_last!=descending means we want null last in ASC or
+                # nulls_last != descending means nulls will be last in ASC or
                 # first in DESC — both require the higher ind value (1).
                 null_ind = int(bool(item.nulls_last) != bool(item.descending))
                 null_field = f"__wsort{len(sort_fields) + 1}"
@@ -961,7 +961,7 @@ def _prepare_window_annotations_for_pipeline(self):
         """
         Build $setWindowFields pipeline stages for window annotations.
 
-        Returns (stages, replacements) where stages is a list of pipeline dicts
+        Return (stages, replacements) where stages is a list of pipeline dicts
         and replacements maps Window sub-expressions and full over-clause
         annotations to Ref objects for use in $project.
         """
@@ -997,7 +997,7 @@ def _collect_windows_from_expr(expr, target=None):
         # $setWindowFields.
         groups = {}
         pre_add_fields = {}
-        sort_fields = {}  # shared across all windows: expr_mql_key → field_name
+        sort_fields = {}  # shared across all windows, expr_mql_key: field_name
         for alias, window in window_list:
             partition_mql = self._compile_window_partition_by(window.partition_by)
             sort_doc, pre_add_fields_ = self._compile_window_sort_by(window.order_by, sort_fields)

django_mongodb_backend/functions/window.py

@@ -114,8 +114,6 @@ def ntile(self, compiler, connection, alias, idx, default_frame):  # noqa: ARG00
     }
     # SQL NTILE: rows 1..extra*(per+1) go to the first `extra` buckets (each
     # gets per+1 rows); remaining rows are distributed evenly across the rest.
-    # `$max [$$per, 1]` guards against division by zero in the else branch when
-    # num_buckets > total (per==0), which is unreachable but may be evaluated.
     add_fields = {
         alias: {
             "$let": {
@@ -156,6 +154,9 @@ def ntile(self, compiler, connection, alias, idx, default_frame):  # noqa: ARG00
                                                             {"$add": ["$$thr", 1]},
                                                         ]
                                                     },
+                                                    # Guard against division by
+                                                    # zero when num_buckets >
+                                                    # total (per==0).
                                                     {"$max": ["$$per", 1]},
                                                 ]
                                             }
@@ -174,8 +175,8 @@ def ntile(self, compiler, connection, alias, idx, default_frame):  # noqa: ARG00
 
 
 def percent_rank(self, compiler, connection, alias, idx, default_frame):  # noqa: ARG001
-    # Use document-position rank ($sum:1 docs unbounded-to-current)
-    # instead of $rank, which MongoDB limits to a single sort field.
+    # Use document-position rank ($sum:1 docs unbounded-to-current) instead of
+    # $rank, which MongoDB limits to a single sort field.
     row_num_alias = f"__wtemp{next(idx)}"
     count_alias = f"__wtemp{next(idx)}"
     output = {