Custom Iterator Structures
Many of the methods in github3.py that return iterators of another object areactually returning one of the iterators below. These iterators effectivelyallow users to ignore GitHub’s API pagination of large sets of data. In allsenses, they behave like a normal Python iterator. Their difference is thatthey have extra logic around making API requests and coercing the JSON intopredefined objects.
- classgithub3.structs.GitHubIterator(count:int,url:str,cls:Type[GitHubCore],session:session.GitHubSession,params:MutableMapping[str,str|int|None]|None=None,etag:str|None=None,headers:Mapping[str,str]|None=None,list_key:str|None=None)
The
GitHubIteratorclass 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[models.GitHubCore]
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
- classmethodfrom_dict(json_dict,session)
Return an instance of this class formed from
json_dict.
- classmethodfrom_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:t.Optional['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: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:
- original:Final[int]
Original number of items requested
- params:t.MutableMapping[str,t.Optional[t.Union[str,int]]]
Parameters of the query string
- propertyratelimit_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()forring.repositories_by('kennethreitz')]
Without the return value, that would be an array of
None’s and youwould otherwise have to do:repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]
Which is really an anti-pattern.
Changed in version 0.5.
- Parameters:
conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs
- Returns:
self
- url:str
URL the class used to make it’s first GET
- classgithub3.structs.SearchIterator(count:int,url:str,cls:Type[GitHubCore],session:session.GitHubSession,params:MutableMapping[str,str|int|None]|None=None,etag:str|None=None,headers:Mapping[str,str]|None=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 thisclass. 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[models.GitHubCore]
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
- classmethodfrom_dict(json_dict,session)
Return an instance of this class formed from
json_dict.
- classmethodfrom_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:t.Optional['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: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:
- original:Final[int]
Original number of items requested
- params:t.MutableMapping[str,t.Optional[t.Union[str,int]]]
Parameters of the query string
- propertyratelimit_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()forring.repositories_by('kennethreitz')]
Without the return value, that would be an array of
None’s and youwould otherwise have to do:repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]
Which is really an anti-pattern.
Changed in version 0.5.
- Parameters:
conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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