[Django] #36889: cursor_iter() docstring could use more detail about parameters and behavior

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Type:
ismail | Cleanup/optimization
Status: new | Component:
| Uncategorized
Version: 6.0 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
While reading through django/db/models/sql/compiler.py, I came across the
cursor_iter() helper. The implementation itself is quite small, but some
important details aren’t obvious from the current docstring.

Here is the current implementation:

{{{
def cursor_iter(cursor, sentinel, col_count, itersize):
"""
Yield blocks of rows from a cursor and ensure the cursor is closed when
done.
"""
try:
for rows in iter((lambda: cursor.fetchmany(itersize)), sentinel):
yield rows if col_count is None else [r[:col_count] for r in rows]
finally:
cursor.close()
}}}

While reading this, a few things were not immediately clear without
stepping
through the code:

what the {{{sentinel}}} value represents and how it is used to stop
iteration

* why {{{col_count}}} is needed and when rows are sliced

* what the function actually yields (an iterator yielding batches of rows)

* that the cursor is always closed via {{{finally}}}, even if iteration
stops
early or an error occurs

Expanding the docstring to briefly explain:

* each parameter

* the return value

* and the cursor-closing guarantee

would make this helper easier to understand for contributors working on
the SQL
compiler internals, without changing any behavior.

This would be a documentation-only improvement.
--
Ticket URL: <https://code.djangoproject.com/ticket/36889>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------

Reporter: Muhammed irshad | Owner: (none)
ismail |
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Muhammed irshad ismail):

* component: Uncategorized => Documentation


Old description:

New description:

While reading through {{{django/db/models/sql/compiler.py}}}, I came

--
Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:1>

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Owner: (none)
ismail |
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Description changed by Muhammed irshad ismail:

Old description:

Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:2>

[Django]

Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:3>

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Owner: (none)
ismail |
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Description changed by Natalia Bidart:

{{{#!python

Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:4>

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Owner: (none)
ismail |
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Natalia Bidart):

Hello Muhammed irshad ismail, thank you for your interest in making Django
better. I understand and value your proposal, but given Django's code base
size and maturity, having a carefully curated git history is a must. With
that spirit, it's hard to justify the `git commit` entry for extending
this docstring, since `cursor_iter` is a private, undocumented, internal
API.

Could you please share the use case/path that prompted you to read this
function? You mentioned "contributors working on the SQL compiler
internals" but is there any wider picture to share?
--
Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:5>

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Owner: (none)
ismail |

Type: | Status: closed

Cleanup/optimization |
Component: Documentation | Version: 6.0

Severity: Normal | Resolution: needsinfo

Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls):

* resolution: => needsinfo
* status: new => closed

--
Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:6>

[Django]

#36889: cursor_iter() docstring could use more detail about parameters and behavior
-------------------------------------+-------------------------------------
Reporter: Muhammed irshad | Owner: (none)
ismail |
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution: needsinfo
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Muhammed irshad ismail):

Thank you for the thoughtful feedback and for explaining the concern
around keeping Django’s git history focused and intentional.

The reason I ended up reading cursor_iter() was while following the
execution path for queryset evaluation and SQL compilation, specifically
when tracing how rows are fetched in batches during query execution. While
stepping through the code, I encountered cursor_iter() and had to read its
implementation to understand the role of sentinel, the purpose of
col_count, and the guarantee around closing the cursor.

I understand that cursor_iter() is a private, internal helper and not part
of the public API. My motivation was mainly from a contributor’s
perspective: when navigating the SQL compiler internals for debugging or
learning purposes, having a slightly more descriptive docstring can reduce
the need to reverse- engineer intent from the implementation.

That said, I completely understand the concern about adding commit history
for internal helpers, and I’m happy to defer to maintainers’ judgment on
whether this level of documentation is appropriate for a private function.

Thanks again for taking the time to review and explain the reasoning
--
Ticket URL: <https://code.djangoproject.com/ticket/36889#comment:7>