githubV3py 1.0.1
Python API for accessing GitHub
Requires Python: >=3.6
Keywords: [ github,api,REST,git ]

# Overview 

A python3 API for accessing github

# Build Status

![Linux, MacOSX, Windows](https://github.com/AndrewOfC/githubpy/actions/workflows/build_and_test.yml/badge.svg)

# Authentication

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

# Installation

```bash
$ pip install githubV3py
```

# [Examples](examples/README.md)



# Usage

```python

ghc = GitHubClient(token=githubtoken)

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

```

```raw

               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](docs/githubclient_methods.md)

# Pagination

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

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

[ResposListCommits](https://docs.github.com/rest/reference/repos#list-commits) 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.

```python
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:

```python

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:

```python
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:

```python
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](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) on the authentication you're using could be fully consumed. 

To this end another method is provided that provides a [generator object](https://wiki.python.org/moin/Generators) 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.

```python
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

```python
    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.

```python

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

```

## Download URL

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

```

# Quick Rate Limit Check:

```bash
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".