Overview

A python3 API for accessing github

Build Status

Authentication

Access tokens are generated by github at this link https://github.com/settings/tokens/new

Installation

$ pip install githubV3py

Examples

Usage

from githubV3py import GitHubClient

ghc = GitHubClient(token=githubtoken)

ascii_art = ghc.MetaGetOctocat("Hello World").data.decode('utf-8')
    
print(ascii_art)
    
print(f"rate-limit remaining={ghc.rateLimitRemaining}")

               MMM.           .MMM
               MMMMMMMMMMMMMMMMMMM
               MMMMMMMMMMMMMMMMMMM      _____________
              MMMMMMMMMMMMMMMMMMMMM    |             |
             MMMMMMMMMMMMMMMMMMMMMMM   | Hello World |
            MMMMMMMMMMMMMMMMMMMMMMMM   |_   _________|
            MMMM::- -:::::::- -::MMMM    |/
             MM~:~ 00~:::::~ 00~:~MM
        .. MMMMM::.00:::+:::.00::MMMMM ..
              .MM::::: ._. :::::MM.
                 MMMM;:::::;MMMM
          -MM        MMMMMMM
          ^  M+     MMMMMMMMM
              MMMMMMM MM MM MM
                   MM MM MM MM
                   MM MM MM MM
                .~~MM~MM~MM~MM~~.
             ~~~~MM:~MM~~~MM~:MM~~~~
            ~~~~~~==~==~~~==~==~~~~~~
             ~~~~~~==~==~==~==~~~~~~
                 :~==~==~==~==~~

rate-limit remaining=4998

GitHubClient Methods

GitHubClient Methods

Pagination

Many of github's api calls return a collection of results as a list. For example:

commits = ghc.ReposListCommits("owner", "repo", per_page=30, page=1)    

ResposListCommits returns a list of commits for the specified repository. However, it will only return the first 'per_page' entries. To get the next set of commits, increment 'page' by 1.

commits = ghc.ReposListCommits("owner", "repo", per_page=30, page=2)    

Automatic Pagination

Given that in many cases all of a particular set of a data is desired, a convenient class method is provided for instance methods that do pagination:

commits = GitHubClient.paginate(ghc.ReposListCommits, "owner", "repo", pagination_limit=1000)

The first parameter is the paginating instance method and the remaining parameters are the parameters you would supply the method if calling it discretely. The optional 'pagination_limit' parameter can be specified to put a limit on the amount of data retrieved. If not specified GitHubClient.paginate will attempt to retrieve every record.

An 'extractor' method may be provided for responses that contain a list, as opposed to a list itself, for example: GitHubClient.ActionsListArtifactsForRepo returns and instance of:

class ActionsListArtifactsForRepoSuccess(ResponseBase):
    def __init__(self, artifacts:list, total_count:int):
        ResponseBase.__init__(self)
        self._artifacts = artifacts
        self._total_count = total_count
        return
        
    def _getartifacts(self):
        return self._artifacts and [ entry and Artifact(**entry) for entry in self._artifacts ]
        
    artifacts = property(_getartifacts)

In order to paginate the result, the artifacts property must be extracted:

from operator import attrgetter

artifacts = GitHubClient.paginate(ghc.ActionsListArtifactsForRepo, 
                                  owner, reponame, 
                                  extractor=attrgetter('artifacts'))

USE THIS METHOD WITH CAUTION. Have some situational awareness of how much data you will be asking for. Otherwise the rate-limit on the authentication you're using could be fully consumed.

To this end another method is provided that provides a generator object instead. Iterating over it will still appear as if it were one 'list' but the list is broken up into discrete queries, so that if you're scanning for something you can stop, without having to download the entire collection.

for repo in GitHubClient.generate(ghc.ReposListForAuthenticatedUser, type=None):
    print(f"{repo.name}")

Downloads

Several methods download data(Build Artifacts, Logs, tarballs). The data can be downloaded in several ways:

Downloading all at once

    data = ghc.ActionsDownloadArtifact(owner,
                                       repository,
                                       artifact_id, 'zip')
    

Downloading in chunks

This is recommended for very large files. Specify a 'chunk_size' to a size appropriate for your application.

    out = open(fname, "wb")
    for chunk in ghc.ActionsDownloadArtifact(owner,
                                             repository,
                                             artifact_id,
                                             'zip', chunk_size=1024):
      out.write(chunk)

Download URL

    url = ghc.ActionsDownloadArtifact(owner,
                                      repsitory,
                                      artifact_id,
                                      'zip', fetch_url=True)
        
    url = urllib.parse.urlparse(url)

Quick Rate Limit Check:

python -c "import githubV3py ;  print(githubV3py.GitHubClient(token='_token_').RateLimitGet().rate.remaining)"

Troubleshooting

Intellisense not working in WingIDE

In order for intellisense to work under WingIDE, the 'main entry point' must import the githubV3py package or import another package/module that does.

Corrective Action:

right click the file you wish to execute in the 'Project' tab/tool and select "Set as Main Entry Point".