cursor_iter() docstring could use more detail about parameters and behavior

[Muhammed irshad ismail]

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.

[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?

[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