{"action":"created","issue":{"url":"https://api.github.com/repos/globus/globus-sdk-python/issues/215","repository_url":"https://api.github.com/repos/globus/globus-sdk-python","labels_url":"https://api.github.com/repos/globus/globus-sdk-python/issues/215/labels{/name}","comments_url":"https://api.github.com/repos/globus/globus-sdk-python/issues/215/comments","events_url":"https://api.github.com/repos/globus/globus-sdk-python/issues/215/events","html_url":"https://github.com/globus/globus-sdk-python/issues/215","id":234013041,"number":215,"title":"How should we improve PaginatedResource documentation to clarify that second iteration is empty? Are new/additional behaviors desirable or required?","user":{"login":"sirosen","id":1300022,"avatar_url":"https://avatars0.githubusercontent.com/u/1300022?v=3","gravatar_id":"","url":"https://api.github.com/users/sirosen","html_url":"https://github.com/sirosen","followers_url":"https://api.github.com/users/sirosen/followers","following_url":"https://api.github.com/users/sirosen/following{/other_user}","gists_url":"https://api.github.com/users/sirosen/gists{/gist_id}","starred_url":"https://api.github.com/users/sirosen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sirosen/subscriptions","organizations_url":"https://api.github.com/users/sirosen/orgs","repos_url":"https://api.github.com/users/sirosen/repos","events_url":"https://api.github.com/users/sirosen/events{/privacy}","received_events_url":"https://api.github.com/users/sirosen/received_events","type":"User","site_admin":false},"labels":[{"id":337675854,"url":"https://api.github.com/repos/globus/globus-sdk-python/labels/question","name":"question","color":"cc317c","default":true}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2017-06-06T20:23:19Z","updated_at":"2017-06-06T22:01:57Z","closed_at":null,"body":"In various forms, we've seen confusion over the fact that a PaginatedResource does not record the results of paging and yields the results as it gets them.\r\nUsually, this is manifest in the form of someone trying to walk a PaginatedResource multiple times, and being surprised that the second iteration is empty.\r\n\r\nSo, first and foremost:\r\nHow do we make this clearer in the docs?\r\n\r\nSecondly, which, if any, of the following behaviors would help resolve the issue?\r\n- Have paginated calls accept `store_results=True`, enabling the use of a list to record the results as they are iterated\r\n- Add a method, `PaginatedResource.reset()` which restarts paging, and which can document that it's discouraged but useful for fetching fresh results\r\n- On repeat iterations (i.e. after the first `StopIteration`), have `PaginatedResource` _raise an error_ which explains how to do multiple iterations correctly (either listify, or make a fresh call)\r\n- On repeat iterations, have `PaginatedResource` restart paging, even though it's inefficient (optionally log a warning)"},"comment":{"url":"https://api.github.com/repos/globus/globus-sdk-python/issues/comments/306630344","html_url":"https://github.com/globus/globus-sdk-python/issues/215#issuecomment-306630344","issue_url":"https://api.github.com/repos/globus/globus-sdk-python/issues/215","id":306630344,"user":{"login":"aaschaer","id":6373786,"avatar_url":"https://avatars1.githubusercontent.com/u/6373786?v=3","gravatar_id":"","url":"https://api.github.com/users/aaschaer","html_url":"https://github.com/aaschaer","followers_url":"https://api.github.com/users/aaschaer/followers","following_url":"https://api.github.com/users/aaschaer/following{/other_user}","gists_url":"https://api.github.com/users/aaschaer/gists{/gist_id}","starred_url":"https://api.github.com/users/aaschaer/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aaschaer/subscriptions","organizations_url":"https://api.github.com/users/aaschaer/orgs","repos_url":"https://api.github.com/users/aaschaer/repos","events_url":"https://api.github.com/users/aaschaer/events{/privacy}","received_events_url":"https://api.github.com/users/aaschaer/received_events","type":"User","site_admin":false},"created_at":"2017-06-06T22:01:57Z","updated_at":"2017-06-06T22:01:57Z","body":"We should probably make it clear in the docs that PaginatedResources are designed to make several lazy network calls and handle potentially very large amounts of response data, and thus don't record their results. Putting it in a NOTE: might get people's attention.\r\n\r\nHowever, I feel like many users don't read the docs until they run into a problem, so I am very in favor of option 3. We should at the very least let people know they are doing something wrong if they are looking for more results at the end of a PaginatedResource.\r\n\r\nAdding options 1 and/or 2 would be nice, but might be misused. Would need notes about proper usage.\r\nIf we do both, calling reset with `store_results=True` should raise an error.\r\n\r\nNot a huge fan of 4, would rather make the user call `reset()` than make it easy for them to use inefficient behavior, lest we get complaints about the \"SDK being slow\" or something."}}
{"actor":{"display_login":"aaschaer"}}