Unclear why iter_items should be favored over list_items · Issue #1775 · gitpython-developers/GitPython (original) (raw)
In git.util.IterableObj, the list_items method recommends that iter_items be used instead, and begins to explain why, but it appears the actual explanation was never written:
| :note: Favor the iter_items method as it will |
|---|
The deprecated git.util.Iterable class has the same note in its list_items docstring:
| :note: Favor the iter_items method as it will |
|---|
In both cases, the subsequent non-blank line in the docstring documents what the list_items method itself returns, so the continuation truly is missing. The intended continuation does not seem to me to be something that can be inferred from the docstring as a whole. For example, here's the whole IterableObj.list_items docstring:
| """ |
|---|
| Find all items of this type - subclasses can specify args and kwargs differently. |
| If no args are given, subclasses are obliged to return all items if no additional |
| arguments arg given. |
| :note: Favor the iter_items method as it will |
| :return: list(Item,...) list of item instances |
| """ |
It may seem odd that, unlike #1712, I did not notice this when working on #1725. But I think the reason is not that the docstrings had made sense to me at that time, but instead that I had noticed the more minor (really, almost trivial) issue that perhaps the first paragraph should be split so that only its first sentence would be its summary line, decided to return to it later to consider that further, and then forgot about it.
The text "Favor the iter_items method as it will" appears to have been present, and its continuation absent, for as long as the surrounding code has been in GitPython. It was introduced in f4fa1cb along with the Iterable class itself.
In general, it may sometimes be preferable to obtain an iterator rather than a list or other sequence because it may not be necessary to materialize a collection just to iterate over it, and because unnecessary materialization can sometimes increase space usage. On the other hand, materialization guards against mutation of the original collection during iteration. But these are completely general ideas, not informed by the list_items docstrings nor even by any consideration specific to GitPython.
My guess is that the docstring intended to say something more specific, or at least to identify which general benefit of iter_items serves to recommend it. So I don't think I could propose a specific improvement to that documentation without insight into what was originally intended.