#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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019c06074383-00b8beb4-f9c4-462c-a114-376b24f0748c-000000%40eu-central-1.amazonses.com.
