pygithub / pygithub

Typed interactions with the GitHub API v3

PyGitHub

PyGitHub is a Python library to access the GitHub REST API. This library enables you to manage GitHub resources such as repositories, user profiles, and organizations in your Python applications.

Install

pip install PyGithub

Simple Demo

from github import Github

# Authentication is defined via github.Auth
from github import Auth

# using an access token
auth = Auth.Token("access_token")

# First create a Github instance:

# Public Web Github
g = Github(auth=auth)

# Github Enterprise with custom hostname
g = Github(base_url="https://{hostname}/api/v3", auth=auth)

# Then play with your Github objects:
for repo in g.get_user().get_repos():
    print(repo.name)

# To close connections after use
g.close()

Documentation

More information can be found on the PyGitHub documentation site.

Development

Contributing

Long-term discussion and bug reports are maintained via GitHub Issues. Code review is done via GitHub Pull Requests.

For more information read CONTRIBUTING.md.

Maintainership

We're actively seeking maintainers that will triage issues and pull requests and cut releases. If you work on a project that leverages PyGitHub and have a vested interest in keeping the code alive and well, send an email to someone in the MAINTAINERS file.

pygithub's Issues

Issue also created by PyGithub

Body created by PyGithub

Rework GitTree.recursive

List project(s) using PyGithub

List known clients.

First known client: http://pypi.python.org/pypi/tratihubis/ (cf #24)

Implement https://api.github.com/hooks

https://api.github.com/hooks is not documented, but it is referred by http://developer.github.com/v3/repos/hooks/#create-a-hook

Rate limiting?

Hi!

I tried to find a function which returns the number of API requests I have remaining due to rate limiting. Is this somewhere in the library and I can't find it? If not, I think it would be a great feature to have, to be able to keep track of how many requests certain actions use up.

Rework BaseUrl to use tuples instead of string concatenation

UnknownGithubObject on get_download() with invalid key

This is probably user error (I don't really know what I'm doing) but if I execute repo.get_download(1) or repo.get_download('foobar') (I'm not sure what the proper id for a download is), I get the following error trace:

Traceback (most recent call last):
  File "/Applications/WingIDE.app/Contents/MacOS/src/debug/tserver/_sandbox.py", line 1, in <module>
# Used internally for debug sandbox under external interpreter
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 77, in <lambda>
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/List.py", line 114, in __execute
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/TypePolicies.py", line 25, in createNonLazy
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 73, in __init__
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 103, in __fetchAttribute
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/GithubObjects/GithubObject/Basic.py", line 62, in updateAttributes
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/Github.py", line 10, in _dataRequest
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/Requester.py", line 17, in dataRequest
  File "/Library/Python/2.6/site-packages/PyGithub-0.6-py2.6.egg/github/Requester.py", line 39, in __statusCheckedRequest
github.Requester.UnknownGithubObject:

Also possibly related: repo.get_download() (what weird things users do, eh?) causes a shorter trace ending in Type Error.

Facilitate IDE autocompletion

As per discussion in 6945921

I have observed that autocompletion (using PyDev+Eclipse in my case) is pretty erratic.
For example, in the tutorial from the readme, g.get_u gets autocompleted correctly, but g.get_user().get_r (or any method or attribute applicable to NamedUsers/AuthenticatedUser, really) does not show autocompletion to g.get_user().get_repo().

This makes exploring the library/API a bit cumbersome.

Deduce mandatory parameters

Type all parameters

Type all attributes

Improve error messages on broken requests

Thanks for PyGithub, it is easy to use and very complete. I just successfully used it to convert Trac tickets to Guthub issues.

But I had to learn the hard way that create_issue() expectes the milestone as number instead of a title. To track this down, I added the following print statement to Requester.py:

def __statusCheckedRequest( self, verb, url, parameters, input ):
    status, headers, output = self.__rawRequest( verb, url, parameters, input )
    if status < 200 or status >= 300:
        print output # <--- Added by me.
        raise UnknownGithubObject() # <--- sadly lacks any error details
    return headers, output

As output already contains all the information needed (as JSON dump), it would be helpful if the exception raised here would include this information in the exception message.

Gitub -> Github everywhere

Check that there is no more `todo`s in code

Remove the _repo hugly hack

Review exceptions policy when receiving error HTTP status

get_issues() returns max. 250 items

As the title says, get_issues() seems to return a max of 250 items.
It can't be a pagination thing I think because a page is max. 100 items long as per http://developer.github.com/v3/#pagination

Repro:

from github import Github
g = Github()
test=g.get_user('openframeworks').get_repo('openFrameworks').get_issues()
len(test)

This repo hast 940 closed and 340 open issues.

Make all attributes either optional or mandatory

Issue created by PyGithub to test issue #50

Implement alternative inputs

Add copyright and license notice

data_files install location

Installing on OS X 10.7 via:
$ pip install PyGithub

(Using the Python 2.7 package from python.org, and not OS X's python2.6 flavour)

Got an error message:
running install_data
copying ReadMe.md -> /System/Library/Frameworks/Python.framework/Versions/2.7/
error: /System/Library/Frameworks/Python.framework/Versions/2.7/ReadMe.md: Permission denied

While I can use sudo to make the error message go away, I don't think /System/Library/Frameworks/Python.framework/Versions/2.7/ is the correct location for the documentation. I don't know much about writing setup.py files, but after looking at gunicorn, flask, and numpy, it doesn't look like any of them use data_files for installing documentation.

Generate a docs.python.org-like documentation

It would be good to have a doc that is more like other documentations of Python libraries.

Issue created by PyGithub

Body edited by PyGithub

Support new Search API

New API ported from v2 but i have trouble with adopting ask's library for v2 API to support v3 style for searching.
http://developer.github.com/v3/search/

Its not described in the page about parameters that search for repos API supports.
They are same as in v2 API, you can look them in ask's library.
In v2 was like that https://github.com/api/v2/json/repos/search/testing?start_page=2&language=Python
In v3 is https://api.github.com/legacy/repos/search/testing?start_page=2&language=Python

Review public interface homogeneity

All attributes and method parameters must have an identified and documented type

Docs seem to be out of sync with code?

Hi!
Back again. :-) I started playing around with 1.1, and it seems many things happened in the meantime.
For one, the docs seem to be out of sync with the code. For example, get_issues seems to return a PaginatedList, but I can't find a mention of that class in the /doc folder.

Background: With the old version, I got a list of all the issues (open & closed) by saying

 Issues=repo.get_issues(state='open') + repo.get_issues(state='closed')

This worked perfectly well with the method returning normal lists, but running my code now, it complains about TypeError: unsupported operand type(s) for +: 'instance' and 'instance'
Also, later on I hit the issue that PaginatedList instance has no attribute '__len__' when I want to count the number of issues with len(Issues) as worked before.

I realize that this is maybe not a proper issue report, since I'm asking how to do stuff, but I don't see where/how else I can find out to do these things "properly" because the docs don't seem to offer this information. Those two errors are probably only symptoms of the changes in the library, and I'm of course willing to fix those myself, but I don't know where to find info about that, if not in the doc folder.
Thanks for any help anyway! :-)

Implement all authentication schemes

One would want to use the API without authentication, with login+password, and with OAuth token. Let's cover these use-cases.

Understand and implement POST /repos/:user/:repo/pulls/:number/comments with in_reply_to

Cf http://developer.github.com/v3/pulls/comments/#alternative-input, but my first tests did not succeed.

Re-implement url parameters

For example, in Organization.get_repos( type ), type should be added to the url, as described in http://developer.github.com/v3/repos/#list-organization-repositories

Publish version 0.4

Publish version 0.5

Use type datetime.datetime for appropriate attributes/arguments

TypeError when Attribute doesn't exist

Hi @jacquev6 When a github user's name has not been entered, I get a TypeError:
TypeError: coercing to Unicode: need string or buffer, NoneType found

Using:

user = gh.get_user('username')
print user.id
print user.login + ' -> ' + user.name

Also happens with getattr:

print getattr(user, u'login') + ' -> ' + getattr(user, u'name', u'No name entered')
#(or)
print getattr(user, 'login') + ' -> ' + getattr(user, 'name', 'No name entered')

Is this the expected behaviour for missing (non-mandatory) attributes? I used except TypeError: as a workaround.

Use objects instead of string for shas, ids, etc. arguments

Publish version 1.0

Check that there is no more todos in code
Check that we have 100% test coverage

Publish version 0.7

Remove _identity from the json description

Implement full API

Create enumerations for string attributes/arguments with a finite set of values

Publish version 1.2

Please clarify licensing

The project has both COPYING and COPYING.LESSER files, containing the GPL and LGPL respectively. The file headers seem to suggest the project is LGPL licensed, but the COPYING file suggests it is GPL licensed.

Could you please clarify your intent (for example, by removing an unneeded COPYING* file, or indicating in the license headers that you intend to dual license it [1]).

Thanks! PyGithub looks great, and I'd love to be able to use it!

[1] I personally do not recommend dual licensing under GPL and LGPL

Publish version 0.6

Remove _identity

_identity exists only in Label, NamedUser and Repository, and should be replaced by proper attribute (urlquote( self.name), self.login and self.full_name) in methods like AuthenticatedUser.add_to_following

Document issue reporting

Publish version 1.3

GitAuthor.date should return datetime, not string

Hi!

It's great that all date-like objects are datetime.datetime now, makes working with it so easy. However, I think you missed GitAuthor.date, it would be great if this would also return datetimes.

Background: To get the dates of tags, I did MyTag.commit.commit.committer.date, and expected this to return a datetime object (like all the others do), but it returns a string.

Rework Github.get_gists

In general, when you get a collection, you should get an iterable, and the pagination should be done only if needed. This is mandatory for Github.get_gists

Separate GithubObjects.py in several files

KeyError executing tutorial example?

Did easy_install on Mac OS 10.6 (python 2.6) and attempt to execute tutorial sequence:

>>> from github import Github
>>> gh = Github('tallforasmurf','<redacted>')
>>> au = gh.get_user()
>>> au.id
1137018
>>> r = au.get_repos()
Traceback (most recent call last):
  File "/Applications/WingIDE.app/Contents/MacOS/src/debug/tserver/_sandbox.py", line 1, in <module>
    # Used internally for debug sandbox under external interpreter
  File "/Library/Python/2.6/site-packages/PyGithub-0.5-    py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 77, in <lambda>
  File "/Library/Python/2.6/site-packages/PyGithub-0.5-py2.6.egg/github/GithubObjects/GithubObject/List.py", line 176, in __execute
  File "/Library/Python/2.6/site-packages/PyGithub-0.5-py2.6.egg/github/GithubObjects/GithubObject/TypePolicies.py", line 22, in createLazy
  File "/Library/Python/2.6/site-packages/PyGithub-0.5-py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 69, in __init__
  File "/Library/Python/2.6/site-packages/PyGithub-0.5-py2.6.egg/github/GithubObjects/GithubObject/GithubObject.py", line 87, in _updateAttributes
KeyError: u'permissions'

Same error on get_repo('name of existing repo')