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.