#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:
> 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.
New description:
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#comment:1>
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/0107019c0608a7bb-2854ed26-c41d-4f64-9e1a-d7f144d8389f-000000%40eu-central-1.amazonses.com.
