René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Unclear why iter_items should be favored over list_items","articleBody":"In [`git.util.IterableObj`](https://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1237-L1271), the [`list_items`](https://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1248-L1261) method recommends that [`iter_items`](https://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1263-L1271) be used instead, and begins to explain why, but it appears the actual explanation was never written:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1255-L1256\r\n\r\nThe deprecated [`git.util.Iterable`](https://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1201-L1233) class has the same note in its [`list_items`](https://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1209-L1224) docstring:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1218-L1219\r\n\r\nIn 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:\r\n\r\nhttps://github.com/gitpython-developers/GitPython/blob/4023f28660e3a78ca9a83f03ca10b39780d32b0e/git/util.py#L1250-L1258\r\n\r\nIt 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.\r\n\r\nThe 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.\r\n\r\nIn 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.\r\n\r\nMy 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.","author":{"url":"https://github.com/EliahKagan","@type":"Person","name":"EliahKagan"},"datePublished":"2023-12-21T00:28:43.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/1775/GitPython/issues/1775"}