Skip to content
This repository
Browse code

Document PaginatedList.get_page (issue #77)

  • Loading branch information...
commit 70c875fa991c1ba698a144093d10da04ac6a568e 1 parent 8ad0acc
Vincent Jacques authored

Showing 1 changed file with 84 additions and 79 deletions. Show diff stats Hide diff stats

  1. +84 79 doc/ReferenceOfClasses.md
163 doc/ReferenceOfClasses.md
Source Rendered
... ... @@ -1,13 +1,6 @@
1 1 You don't normaly create instances of any class but `Github`.
2 2 You obtain instances through calls to `search_`, `get_` and `create_` methods.
3 3
4   -Methods returning an "iterator of `SomeType`" return an iterator which yields instances of `SomeType`.
5   -This implements lazy [pagination requests](http://developer.github.com/v3/#pagination).
6   -You can use this iterator in a `for f in user.get_followers():` loop or with any [itertools](http://docs.python.org/library/itertools.html) functions,
7   -but you cannot know the number of objects returned before the end of the iteration.
8   -If that's really what you need, you cant use `len( list( user.get_followers() ) )`, which does all the requests needed to enumerate the user's followers.
9   -Note that there is often an attribute giving this value (in that case `user.followers`).
10   -
11 4 Class `Github`
12 5 ==============
13 6
@@ -31,12 +24,12 @@ Methods
31 24 * `get_organization( login )`: `Organization`
32 25 * `get_gist( id )`: `Gist`
33 26 * `id`: string
34   -* `get_gists()`: iterator of `Gist`
35   -* `get_hooks()`: iterator of `HookDescription`
36   -* `legacy_search_repos( keyword, [language] )`: iterator of `Repository`
  27 +* `get_gists()`: `PaginatedList` of `Gist`
  28 +* `get_hooks()`: `PaginatedList` of `HookDescription`
  29 +* `legacy_search_repos( keyword, [language] )`: `PaginatedList` of `Repository`
37 30 * `keyword`: string
38 31 * `language`: string
39   -* `legacy_search_users( keyword )`: iterator of `NamedUser`
  32 +* `legacy_search_users( keyword )`: `PaginatedList` of `NamedUser`
40 33 * `keyword`: string
41 34 * `legacy_search_user_by_email( email )`: `NamedUser`
42 35 * `email`: string
@@ -44,6 +37,18 @@ Methods
44 37 * `text`: string
45 38 * `context`: `Repository`
46 39
  40 +Class `PaginatedList`
  41 +=====================
  42 +
  43 +This class implements lazy [pagination requests](http://developer.github.com/v3/#pagination) and hides pagination from you. It is the return type of `get_` methods that return a collection.
  44 +
  45 +You can iterate on it in a `for f in user.get_followers():` loop or with any [itertools](http://docs.python.org/library/itertools.html) functions.
  46 +
  47 +You cannot know the number of objects returned before the end of the iteration. If that's *really* what you need, you cant use `len( list( user.get_followers() ) )`,
  48 +which does all the requests needed to enumerate the user's followers. Note that there is often an attribute giving this value (in that case `user.followers`).
  49 +
  50 +You can also call `get_page( page )` where `page` is an integer starting at 0, to explicitely get a specific page if you don't want to hide pagination.
  51 +
47 52 Class `GithubException`
48 53 =======================
49 54
@@ -91,7 +96,7 @@ Authorizations
91 96 * `note_url`: string
92 97 * `get_authorization( id )`: `Authorization`
93 98 * `id`: integer
94   -* `get_authorizations()`: iterator of `Authorization`
  99 +* `get_authorizations()`: `PaginatedList` of `Authorization`
95 100
96 101 Emails
97 102 ------
@@ -103,19 +108,19 @@ Emails
103 108
104 109 Events
105 110 ------
106   -* `get_events()`: iterator of `Event`
107   -* `get_organization_events( org )`: iterator of `Event`
  111 +* `get_events()`: `PaginatedList` of `Event`
  112 +* `get_organization_events( org )`: `PaginatedList` of `Event`
108 113 * `org`: `Organization`
109 114
110 115 Followers
111 116 ---------
112   -* `get_followers()`: iterator of `NamedUser`
  117 +* `get_followers()`: `PaginatedList` of `NamedUser`
113 118
114 119 Following
115 120 ---------
116 121 * `add_to_following( following )`
117 122 * `following`: `NamedUser`
118   -* `get_following()`: iterator of `NamedUser`
  123 +* `get_following()`: `PaginatedList` of `NamedUser`
119 124 * `has_in_following( following )`: bool
120 125 * `following`: `NamedUser`
121 126 * `remove_from_following( following )`
@@ -132,12 +137,12 @@ Gists
132 137 * `public`: bool
133 138 * `files`: dict of string to `InputFileContent`
134 139 * `description`: string
135   -* `get_gists()`: iterator of `Gist`
136   -* `get_starred_gists()`: iterator of `Gist`
  140 +* `get_gists()`: `PaginatedList` of `Gist`
  141 +* `get_starred_gists()`: `PaginatedList` of `Gist`
137 142
138 143 Issues
139 144 ------
140   -* `get_issues()`: iterator of `Issue`
  145 +* `get_issues()`: `PaginatedList` of `Issue`
141 146
142 147 Keys
143 148 ----
@@ -146,7 +151,7 @@ Keys
146 151 * `key`: string
147 152 * `get_key( id )`: `UserKey`
148 153 * `id`: integer
149   -* `get_keys()`: iterator of `UserKey`
  154 +* `get_keys()`: `PaginatedList` of `UserKey`
150 155
151 156 Modification
152 157 ------------
@@ -161,7 +166,7 @@ Modification
161 166
162 167 Orgs
163 168 ----
164   -* `get_orgs()`: iterator of `Organization`
  169 +* `get_orgs()`: `PaginatedList` of `Organization`
165 170
166 171 Repos
167 172 -----
@@ -175,7 +180,7 @@ Repos
175 180 * `has_downloads`: bool
176 181 * `get_repo( name )`: `Repository`
177 182 * `name`: string
178   -* `get_repos( [type, sort, direction] )`: iterator of `Repository`
  183 +* `get_repos( [type, sort, direction] )`: `PaginatedList` of `Repository`
179 184 * `type`: string
180 185 * `sort`: string
181 186 * `direction`: string
@@ -184,7 +189,7 @@ Starred
184 189 -------
185 190 * `add_to_starred( starred )`
186 191 * `starred`: `Repository`
187   -* `get_starred()`: iterator of `Repository`
  192 +* `get_starred()`: `PaginatedList` of `Repository`
188 193 * `has_in_starred( starred )`: bool
189 194 * `starred`: `Repository`
190 195 * `remove_from_starred( starred )`
@@ -194,7 +199,7 @@ Subscriptions
194 199 -------------
195 200 * `add_to_subscriptions( subscription )`
196 201 * `subscription`: `Repository`
197   -* `get_subscriptions()`: iterator of `Repository`
  202 +* `get_subscriptions()`: `PaginatedList` of `Repository`
198 203 * `has_in_subscriptions( subscription )`: bool
199 204 * `subscription`: `Repository`
200 205 * `remove_from_subscriptions( subscription )`
@@ -204,7 +209,7 @@ Watched
204 209 -------
205 210 * `add_to_watched( watched )`
206 211 * `watched`: `Repository`
207   -* `get_watched()`: iterator of `Repository`
  212 +* `get_watched()`: `PaginatedList` of `Repository`
208 213 * `has_in_watched( watched )`: bool
209 214 * `watched`: `Repository`
210 215 * `remove_from_watched( watched )`
@@ -275,7 +280,7 @@ Comments
275 280 * `line`: integer
276 281 * `path`: string
277 282 * `position`: integer
278   -* `get_comments()`: iterator of `CommitComment`
  283 +* `get_comments()`: `PaginatedList` of `CommitComment`
279 284
280 285 Statuses
281 286 --------
@@ -283,7 +288,7 @@ Statuses
283 288 * `state`: string
284 289 * `target_url`: string
285 290 * `description`: string
286   -* `get_statuses()`: iterator of `CommitStatus`
  291 +* `get_statuses()`: `PaginatedList` of `CommitStatus`
287 292
288 293 Class `CommitComment`
289 294 =====================
@@ -450,7 +455,7 @@ Comments
450 455 * `body`: string
451 456 * `get_comment( id )`: `GistComment`
452 457 * `id`: integer
453   -* `get_comments()`: iterator of `GistComment`
  458 +* `get_comments()`: `PaginatedList` of `GistComment`
454 459
455 460 Deletion
456 461 --------
@@ -691,18 +696,18 @@ Comments
691 696 * `body`: string
692 697 * `get_comment( id )`: `IssueComment`
693 698 * `id`: integer
694   -* `get_comments()`: iterator of `IssueComment`
  699 +* `get_comments()`: `PaginatedList` of `IssueComment`
695 700
696 701 Events
697 702 ------
698   -* `get_events()`: iterator of `IssueEvent`
  703 +* `get_events()`: `PaginatedList` of `IssueEvent`
699 704
700 705 Labels
701 706 ------
702 707 * `add_to_labels( label, ... )`
703 708 * `label`: `Label`
704 709 * `delete_labels()`
705   -* `get_labels()`: iterator of `Label`
  710 +* `get_labels()`: `PaginatedList` of `Label`
706 711 * `remove_from_labels( label )`
707 712 * `label`: `Label`
708 713 * `set_labels( label, ... )`
@@ -803,7 +808,7 @@ Deletion
803 808
804 809 Labels
805 810 ------
806   -* `get_labels()`: iterator of `Label`
  811 +* `get_labels()`: `PaginatedList` of `Label`
807 812
808 813 Modification
809 814 ------------
@@ -847,18 +852,18 @@ Attributes
847 852
848 853 Events
849 854 ------
850   -* `get_events()`: iterator of `Event`
851   -* `get_public_events()`: iterator of `Event`
852   -* `get_received_events()`: iterator of `Event`
853   -* `get_public_received_events()`: iterator of `Event`
  855 +* `get_events()`: `PaginatedList` of `Event`
  856 +* `get_public_events()`: `PaginatedList` of `Event`
  857 +* `get_received_events()`: `PaginatedList` of `Event`
  858 +* `get_public_received_events()`: `PaginatedList` of `Event`
854 859
855 860 Followers
856 861 ---------
857   -* `get_followers()`: iterator of `NamedUser`
  862 +* `get_followers()`: `PaginatedList` of `NamedUser`
858 863
859 864 Following
860 865 ---------
861   -* `get_following()`: iterator of `NamedUser`
  866 +* `get_following()`: `PaginatedList` of `NamedUser`
862 867
863 868 Gists
864 869 -----
@@ -866,30 +871,30 @@ Gists
866 871 * `public`: bool
867 872 * `files`: dict of string to `InputFileContent`
868 873 * `description`: string
869   -* `get_gists()`: iterator of `Gist`
  874 +* `get_gists()`: `PaginatedList` of `Gist`
870 875
871 876 Orgs
872 877 ----
873   -* `get_orgs()`: iterator of `Organization`
  878 +* `get_orgs()`: `PaginatedList` of `Organization`
874 879
875 880 Repos
876 881 -----
877 882 * `get_repo( name )`: `Repository`
878 883 * `name`: string
879   -* `get_repos( [type] )`: iterator of `Repository`
  884 +* `get_repos( [type] )`: `PaginatedList` of `Repository`
880 885 * `type`: string
881 886
882 887 Starred
883 888 -------
884   -* `get_starred()`: iterator of `Repository`
  889 +* `get_starred()`: `PaginatedList` of `Repository`
885 890
886 891 Subscriptions
887 892 -------------
888   -* `get_subscriptions()`: iterator of `Repository`
  893 +* `get_subscriptions()`: `PaginatedList` of `Repository`
889 894
890 895 Watched
891 896 -------
892   -* `get_watched()`: iterator of `Repository`
  897 +* `get_watched()`: `PaginatedList` of `Repository`
893 898
894 899 Class `Organization`
895 900 ====================
@@ -923,7 +928,7 @@ Attributes
923 928
924 929 Events
925 930 ------
926   -* `get_events()`: iterator of `Event`
  931 +* `get_events()`: `PaginatedList` of `Event`
927 932
928 933 Forking
929 934 -------
@@ -932,7 +937,7 @@ Forking
932 937
933 938 Members
934 939 -------
935   -* `get_members()`: iterator of `NamedUser`
  940 +* `get_members()`: `PaginatedList` of `NamedUser`
936 941 * `has_in_members( member )`: bool
937 942 * `member`: `NamedUser`
938 943 * `remove_from_members( member )`
@@ -952,7 +957,7 @@ Public_members
952 957 --------------
953 958 * `add_to_public_members( public_member )`
954 959 * `public_member`: `NamedUser`
955   -* `get_public_members()`: iterator of `NamedUser`
  960 +* `get_public_members()`: `PaginatedList` of `NamedUser`
956 961 * `has_in_public_members( public_member )`: bool
957 962 * `public_member`: `NamedUser`
958 963 * `remove_from_public_members( public_member )`
@@ -971,7 +976,7 @@ Repos
971 976 * `team_id`: `Team`
972 977 * `get_repo( name )`: `Repository`
973 978 * `name`: string
974   -* `get_repos( [type] )`: iterator of `Repository`
  979 +* `get_repos( [type] )`: `PaginatedList` of `Repository`
975 980 * `type`: string
976 981
977 982 Teams
@@ -982,7 +987,7 @@ Teams
982 987 * `permission`: string
983 988 * `get_team( id )`: `Team`
984 989 * `id`: integer
985   -* `get_teams()`: iterator of `Team`
  990 +* `get_teams()`: `PaginatedList` of `Team`
986 991
987 992 Class `Permissions`
988 993 ===================
@@ -1044,15 +1049,15 @@ Review comments
1044 1049 * `position`: integer
1045 1050 * `get_comment( id )` or `get_review_comment( id )`: `PullRequestComment`
1046 1051 * `id`: integer
1047   -* `get_comments()` or `get_review_comments()`: iterator of `PullRequestComment`
  1052 +* `get_comments()` or `get_review_comments()`: `PaginatedList` of `PullRequestComment`
1048 1053
1049 1054 Commits
1050 1055 -------
1051   -* `get_commits()`: iterator of `Commit`
  1056 +* `get_commits()`: `PaginatedList` of `Commit`
1052 1057
1053 1058 Files
1054 1059 -----
1055   -* `get_files()`: iterator of `File`
  1060 +* `get_files()`: `PaginatedList` of `File`
1056 1061
1057 1062 Issue_comments
1058 1063 --------------
@@ -1060,7 +1065,7 @@ Issue_comments
1060 1065 * `body`: string
1061 1066 * `get_issue_comment( id )`: `IssueComment`
1062 1067 * `id`: integer
1063   -* `get_issue_comments()`: iterator of `IssueComment`
  1068 +* `get_issue_comments()`: `PaginatedList` of `IssueComment`
1064 1069
1065 1070 Merging
1066 1071 -------
@@ -1165,7 +1170,7 @@ Comparison
1165 1170
1166 1171 Assignees
1167 1172 ---------
1168   -* `get_assignees()`: iterator of `NamedUser`
  1173 +* `get_assignees()`: `PaginatedList` of `NamedUser`
1169 1174 * `has_in_assignees( assignee )`: bool
1170 1175 * `assignee`: `NamedUser`
1171 1176
@@ -1173,13 +1178,13 @@ Branches
1173 1178 --------
1174 1179 * `get_branch( branch )`: `Branch`
1175 1180 * `branch`: string
1176   -* `get_branches()`: iterator of `Branch`
  1181 +* `get_branches()`: `PaginatedList` of `Branch`
1177 1182
1178 1183 Collaborators
1179 1184 -------------
1180 1185 * `add_to_collaborators( collaborator )`
1181 1186 * `collaborator`: `NamedUser`
1182   -* `get_collaborators()`: iterator of `NamedUser`
  1187 +* `get_collaborators()`: `PaginatedList` of `NamedUser`
1183 1188 * `has_in_collaborators( collaborator )`: bool
1184 1189 * `collaborator`: `NamedUser`
1185 1190 * `remove_from_collaborators( collaborator )`
@@ -1189,13 +1194,13 @@ Comments
1189 1194 --------
1190 1195 * `get_comment( id )`: `CommitComment`
1191 1196 * `id`: integer
1192   -* `get_comments()`: iterator of `CommitComment`
  1197 +* `get_comments()`: `PaginatedList` of `CommitComment`
1193 1198
1194 1199 Commits
1195 1200 -------
1196 1201 * `get_commit( sha )`: `Commit`
1197 1202 * `sha`: string
1198   -* `get_commits( [sha, path] )`: iterator of `Commit`
  1203 +* `get_commits( [sha, path] )`: `PaginatedList` of `Commit`
1199 1204 * `sha`: string
1200 1205 * `path`: string
1201 1206
@@ -1210,7 +1215,7 @@ Contents
1210 1215
1211 1216 Contributors
1212 1217 ------------
1213   -* `get_contributors()`: iterator of `NamedUser`
  1218 +* `get_contributors()`: `PaginatedList` of `NamedUser`
1214 1219
1215 1220 Deletion
1216 1221 --------
@@ -1225,16 +1230,16 @@ Downloads
1225 1230 * `content_type`: string
1226 1231 * `get_download( id )`: `Download`
1227 1232 * `id`: integer
1228   -* `get_downloads()`: iterator of `Download`
  1233 +* `get_downloads()`: `PaginatedList` of `Download`
1229 1234
1230 1235 Events
1231 1236 ------
1232   -* `get_events()`: iterator of `Event`
1233   -* `get_network_events()`: iterator of `Event`
  1237 +* `get_events()`: `PaginatedList` of `Event`
  1238 +* `get_network_events()`: `PaginatedList` of `Event`
1234 1239
1235 1240 Forks
1236 1241 -----
1237   -* `get_forks()`: iterator of `Repository`
  1242 +* `get_forks()`: `PaginatedList` of `Repository`
1238 1243
1239 1244 Git_blobs
1240 1245 ---------
@@ -1262,7 +1267,7 @@ Git_refs
1262 1267 * `sha`: string
1263 1268 * `get_git_ref( ref )`: `GitRef`
1264 1269 * `ref`: string
1265   -* `get_git_refs()`: iterator of `GitRef`
  1270 +* `get_git_refs()`: `PaginatedList` of `GitRef`
1266 1271
1267 1272 Git_tags
1268 1273 --------
@@ -1293,7 +1298,7 @@ Hooks
1293 1298 * `active`: bool
1294 1299 * `get_hook( id )`: `Hook`
1295 1300 * `id`: integer
1296   -* `get_hooks()`: iterator of `Hook`
  1301 +* `get_hooks()`: `PaginatedList` of `Hook`
1297 1302
1298 1303 Issues
1299 1304 ------
@@ -1305,7 +1310,7 @@ Issues
1305 1310 * `labels`: list of `Label`
1306 1311 * `get_issue( number )`: `Issue`
1307 1312 * `number`: integer
1308   -* `get_issues( [milestone, state, assignee, mentioned, labels, sort, direction, since] )`: iterator of `Issue`
  1313 +* `get_issues( [milestone, state, assignee, mentioned, labels, sort, direction, since] )`: `PaginatedList` of `Issue`
1309 1314 * `milestone`: `Milestone` or "none" or "*"
1310 1315 * `state`: string
1311 1316 * `assignee`: `NamedUser` or "none" or "*"
@@ -1314,7 +1319,7 @@ Issues
1314 1319 * `sort`: string
1315 1320 * `direction`: string
1316 1321 * `since`: datetime.datetime
1317   -* `legacy_search_issues( state, keyword )`: iterator of `Issue`
  1322 +* `legacy_search_issues( state, keyword )`: `PaginatedList` of `Issue`
1318 1323 * `state`: "open" or "closed"
1319 1324 * `keyword`: string
1320 1325
@@ -1322,7 +1327,7 @@ Issues_events
1322 1327 -------------
1323 1328 * `get_issues_event( id )`: `IssueEvent`
1324 1329 * `id`: integer
1325   -* `get_issues_events()`: iterator of `IssueEvent`
  1330 +* `get_issues_events()`: `PaginatedList` of `IssueEvent`
1326 1331
1327 1332 Keys
1328 1333 ----
@@ -1331,7 +1336,7 @@ Keys
1331 1336 * `key`: string
1332 1337 * `get_key( id )`: `RepositoryKey`
1333 1338 * `id`: integer
1334   -* `get_keys()`: iterator of `RepositoryKey`
  1339 +* `get_keys()`: `PaginatedList` of `RepositoryKey`
1335 1340
1336 1341 Labels
1337 1342 ------
@@ -1340,7 +1345,7 @@ Labels
1340 1345 * `color`: string
1341 1346 * `get_label( name )`: `Label`
1342 1347 * `name`: string
1343   -* `get_labels()`: iterator of `Label`
  1348 +* `get_labels()`: `PaginatedList` of `Label`
1344 1349
1345 1350 Languages
1346 1351 ---------
@@ -1362,7 +1367,7 @@ Milestones
1362 1367 * `due_on`: date
1363 1368 * `get_milestone( number )`: `Milestone`
1364 1369 * `number`: integer
1365   -* `get_milestones( [state, sort, direction] )`: iterator of `Milestone`
  1370 +* `get_milestones( [state, sort, direction] )`: `PaginatedList` of `Milestone`
1366 1371 * `state`: string
1367 1372 * `sort`: string
1368 1373 * `direction`: string
@@ -1388,28 +1393,28 @@ Pulls
1388 1393 * `head`: string
1389 1394 * `get_pull( number )`: `PullRequest`
1390 1395 * `number`: integer
1391   -* `get_pulls( [state] )`: iterator of `PullRequest`
  1396 +* `get_pulls( [state] )`: `PaginatedList` of `PullRequest`
1392 1397 * `state`: string
1393 1398
1394 1399 Stargazers
1395 1400 ----------
1396   -* `get_stargazers()`: iterator of `NamedUser`
  1401 +* `get_stargazers()`: `PaginatedList` of `NamedUser`
1397 1402
1398 1403 Subscribers
1399 1404 -----------
1400   -* `get_subscribers()`: iterator of `NamedUser`
  1405 +* `get_subscribers()`: `PaginatedList` of `NamedUser`
1401 1406
1402 1407 Tags
1403 1408 ----
1404   -* `get_tags()`: iterator of `Tag`
  1409 +* `get_tags()`: `PaginatedList` of `Tag`
1405 1410
1406 1411 Teams
1407 1412 -----
1408   -* `get_teams()`: iterator of `Team`
  1413 +* `get_teams()`: `PaginatedList` of `Team`
1409 1414
1410 1415 Watchers
1411 1416 --------
1412   -* `get_watchers()`: iterator of `NamedUser`
  1417 +* `get_watchers()`: `PaginatedList` of `NamedUser`
1413 1418
1414 1419 Class `RepositoryKey`
1415 1420 =====================
@@ -1462,7 +1467,7 @@ Members
1462 1467 -------
1463 1468 * `add_to_members( member )`
1464 1469 * `member`: `NamedUser`
1465   -* `get_members()`: iterator of `NamedUser`
  1470 +* `get_members()`: `PaginatedList` of `NamedUser`
1466 1471 * `has_in_members( member )`: bool
1467 1472 * `member`: `NamedUser`
1468 1473 * `remove_from_members( member )`
@@ -1478,7 +1483,7 @@ Repos
1478 1483 -----
1479 1484 * `add_to_repos( repo )`
1480 1485 * `repo`: `Repository`
1481   -* `get_repos()`: iterator of `Repository`
  1486 +* `get_repos()`: `PaginatedList` of `Repository`
1482 1487 * `has_in_repos( repo )`: bool
1483 1488 * `repo`: `Repository`
1484 1489 * `remove_from_repos( repo )`

0 comments on commit 70c875f

Please sign in to comment.
Something went wrong with that request. Please try again.