Custom Iterator Structures

Many of the methods in github3.py that return iterators of another object are actually returning one of the iterators below. These iterators effectively allow users to ignore GitHub’s API pagination of large sets of data. In all senses, they behave like a normal Python iterator. Their difference is that they have extra logic around making API requests and coercing the JSON into predefined objects.

class github3.structs.GitHubIterator(count: int, url: str, cls: Type[T], session: session.GitHubSession, params: Optional[Mapping[str, Optional[str]]] = None, etag: Optional[str] = None, headers: Optional[Mapping[str, str]] = None, list_key: Optional[str] = None)

The GitHubIterator class powers all of the iter_* methods.

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns

this object’s attributes serialized to a dictionary

Return type

dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns

this object’s attributes as a JSON string

Return type

str

cls: t.Type[T]

Class for constructing an item to return

count: int

Number of items left in the iterator

etag: t.Optional[str]

The ETag Header value returned by GitHub

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

headers: t.Dict[str, str]

Headers generated for the GET request

last_response: requests.models.Response

The last response seen

last_status: int

Last status code received

last_url: t.Optional[str]

Last URL that was requested

list_key: t.Final[t.Optional[str]]

Key to get the list of items in case a dict is returned

new_session()

Generate a new session.

Returns

A brand new session

Return type

GitHubSession

original: t.Final[int]

Original number of items requested

params: t.Mapping[str, t.Optional[str]]

Parameters of the query string

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → GitHubIterator

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters

conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs

Returns

self

url: str

URL the class used to make it’s first GET

class github3.structs.SearchIterator(count: int, url: str, cls: Type[T], session: session.GitHubSession, params: Optional[Mapping[str, Optional[str]]] = None, etag: Optional[str] = None, headers: Optional[Mapping[str, str]] = None)

This is a special-cased class for returning iterable search results.

It inherits from GitHubIterator. All members and methods documented here are unique to instances of this class. For other members and methods, check its parent class.

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns

this object’s attributes serialized to a dictionary

Return type

dict

as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns

this object’s attributes as a JSON string

Return type

str

cls: t.Type[T]

Class for constructing an item to return

count: int

Number of items left in the iterator

etag: t.Optional[str]

The ETag Header value returned by GitHub

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

headers: t.Dict[str, str]

Headers generated for the GET request

items: t.List[t.Mapping[str, t.Any]]

Items array returned in the last request

last_response: requests.models.Response

The last response seen

last_status: int

Last status code received

last_url: t.Optional[str]

Last URL that was requested

list_key: t.Final[t.Optional[str]]

Key to get the list of items in case a dict is returned

new_session()

Generate a new session.

Returns

A brand new session

Return type

GitHubSession

original: t.Final[int]

Original number of items requested

params: t.Mapping[str, t.Optional[str]]

Parameters of the query string

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → GitHubIterator

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters

conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs

Returns

self

total_count: int

Total count returned by GitHub

url: str

URL the class used to make it’s first GET