Package: agithub
The Agnostic GitHub APIIt doesn't know, and you don't care!agithubis a REST API client with transparent syntax which facilitates
rapid prototyping — onanyREST API!Originally tailored to the GitHub REST API, AGitHub has grown up to
support many other REST APIs:DigitalOceanFacebookGitHubOpenWeatherMapSalesForceAdditionally, you can addfull supportfor another REST API with very
little new code!  To see how, check out theFacebook client, which has
about 30 lines of code.This works because AGithub knows everything it needs to about protocol
(REST, HTTP, TCP), but assumes nothing about your upstream API.UseThe most striking quality of AGitHub is how closely its syntax emulates
HTTP. In fact, you might find it even more convenient than HTTP, and
almost as general (as far as REST APIs go, anyway). The examples below
tend to use the GitHub API as a reference point, but it is no less easy to
useagithubwith, say, the Facebook Graph.Create a clientfromagithub.GitHubimportGitHubclient=GitHub()GETHere's how to do aGETrequest, with properly-encoded url parameters:client.issues.get(filter='subscribed')That is equivalent to the following:GET /issues/?filter=subscribedPOSTHere's how to send a request body along with your request:some_object={'foo':'bar'}client.video.upload.post(body=some_object,tags="social devcon")This will send the following request, withsome_objectserialized as
the request body:*POST /video/upload?tags=social+devcon{"foo": "bar"}Thebodyparameter is reserved and is used to define the request body to be
POSTed.tagsis an example query parameter, showing that you can pass both
an object to send as the request body as well as query parameters.*For now, the request body is limited to JSON data; but
we plan to add support for other types as wellParametersheadersPass custom http headers in your ruquest with the reserved parameterheaders.fromagithub.GitHubimportGitHubg=GitHub()headers={'Accept':'application/vnd.github.symmetra-preview+json'}status,data=g.search.labels.get(headers=headers,repository_id=401025,q='¯\_(ツ)_/¯')print(data['items'][0]){u'default': False, u'name': u'\xaf\\_(\u30c4)_/\xaf', u'url': u'https://api.github.com/repos/github/hub/labels/%C2%AF%5C_(%E3%83%84)_/%C2%AF', u'color': u'008672', u'node_id': u'MDU6TGFiZWwxMTcwNjYzNTM=', u'score': 43.937515, u'id': 117066353, u'description': u''}bodyIf you're usingPOST,PUT, orPATCH(post(),put(), orpatch()),
then you should include the body as thebody=argument. The body is
serialized to JSON before sending it out on the wire.fromagithub.GitHubimportGitHubg=GitHub()# This Content-Type header is only required in this example due to a GitHub# requirement for this specific markdown.raw API endpointheaders={'Content-Type':'text/plain'}body='# This should be my header'status,data=g.markdown.raw.post(body=body,headers=headers)print(data)<h1>
<a id="user-content-this-should-be-my-header" class="anchor" href="#this-should-be-my-header" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>This should be my header</h1>Example AppFirst, instantiate aGitHubobject.fromagithub.GitHubimportGitHubg=GitHub()When you make a request, the status and response body are passed back
as a tuple.status,data=g.users.octocat.get()print(data['name'])print(status)The Octocat
200If you forget the request method,agithubwill complain that you
haven't provided enough information to complete the request.g.users<class 'agithub.github.IncompleteRequest'>: /usersSometimes, it is inconvenient (or impossible) to refer to a URL as a
chain of attributes, so indexing syntax is provided as well. It
behaves exactly the same. In these examples we use indexing syntax because
you can't have a python function namestarting with a digit :1containing a dash (-) character :Spoon-Knifeg.repos.github.hub.issues[1].get()g.repos.octocat['Spoon-Knife'].branches.get()(200, { 'id': '#blah', ... })
(200, [ list, of, branches ])You can also pass query parameter to the API as function parameters to the
method function (e.g.get).status,data=g.repos.octocat['Spoon-Knife'].issues.get(state='all',creator='octocat')print(data[0].keys())print(status)[u'labels', u'number', … , u'assignees']
200Notice the syntax here:<API-object>.<URL-path>.<request-method>(<query-parameters>)API-object:gURL-path:repos.octocat['Spoon-Knife'].issuesrequest-method:getquery-parameters:state='all', creator='octocat'As a weird quirk of the implementation, you may build a partial call
to the upstream API, and use it later.deffollowing(self,user):returnself.user.following[user].getmyCall=following(g,'octocat')if204==myCall()[0]:print'You are following octocat'You are following octocatYou may find this useful — or not.Finally,agithubknows nothing at all about the GitHub API, and it
won't second-guess you.g.funny.I.donna.remember.that.one.head()(404, {'message': 'Not Found'})The error message you get is directly from GitHub's API. This gives
you all of the information you need to survey the situation.If you need more information, the response headers of the previous
request are available via thegetheaders()method.g.getheaders()[('status', '404 Not Found'),
 ('x-ratelimit-remaining', '54'),
 …
 ('server', 'GitHub.com')]Note that the headers are standardized to all lower case. So though, in this
example, GitHub returns a header ofX-RateLimit-Remainingthe header is
returned fromgetheadersasx-ratelimit-remainingError handlingErrors are handled in the most transparent way possible: they are passed
on to you for further scrutiny. There are two kinds of errors that can
crop up:Networking Exceptions (from thehttplibrary). Catch these withtry .. catchblocks, as you otherwise would.GitHub API errors. These mean you're doing something wrong with the
API, and they are always evident in the response's status. The API
considerately returns a helpful error message in the JSON body.Specific REST APIsagithubincludes a handful of implementations for specific REST APIs. The
example above uses the GitHub API but only for demonstration purposes. It
doesn't include any GitHub specific functionality (for example, authentication).Here is a summary of additional functionality available for each distinct REST
API with support included inagithub. Keep in mind,agithubis designed
to be extended to any REST API and these are just an initial collection of APIs.GitHub :agithub/GitHub.pyGitHub AuthenticationTo initiate an authenticatedGitHubobject, pass it your username and password
or atoken.fromagithub.GitHubimportGitHubg=GitHub('user','pass')fromagithub.GitHubimportGitHubg=GitHub(token='token')GitHub PaginationWhen calling the GitHub API with a query that returns many results, GitHub willpaginatethe response, requiring
you to request each page of results with separate API calls. If you'd like to
automatically fetch all pages, you can enable pagination in theGitHubobject
by settingpaginatetoTrue.fromagithub.GitHubimportGitHubg=GitHub(paginate=True)status,data=g.repos.octocat['Spoon-Knife'].issues.get()status,data=g.users.octocat.repos.get(per_page=1)print(len(data))8(added in v2.2.0)GitHub Rate LimitingBy default, if GitHub returns a response indicating that a request was refused
due torate limiting, agithub
will wait until the point in time when the rate limit is lifted and attempt
the call again.If you'd like to disable this behavior and instead just return the error
response from GitHub setsleep_on_ratelimittoFalse.fromagithub.GitHubimportGitHubg=GitHub(sleep_on_ratelimit=False)status,data=g.repos.octocat['Spoon-Knife'].issues.get()print(status)print(data['message'])403
API rate limit exceeded for 203.0.113.2. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)(added in v2.2.0)GitHub LoggingTo see log messages related to GitHub specific features like pagination and
rate limiting, you can use a root logger from the Python logging module.importlogginglogging.basicConfig()logger=logging.getLogger()# The root loggerlogger.setLevel(logging.DEBUG)fromagithub.GitHubimportGitHubg=GitHub(paginate=True)status,data=g.repos.octocat['Spoon-Knife'].issues.get()DEBUG:agithub.GitHub:No GitHub ratelimit remaining. Sleeping for 676 seconds until 14:22:43 before trying API call again.
DEBUG:agithub.GitHub:Fetching an additional paginated GitHub response page at https://api.github.com/repositories/1300192/issues?page=2
DEBUG:agithub.GitHub:Fetching an additional paginated GitHub response page at https://api.github.com/repositories/1300192/issues?page=3
…SemanticsHere's howagithubworks, under the hood:It translates a sequence of attribute look-ups into a URL; The
Python method you call at the end of the chain determines the
HTTP method to use for the request.The Python method also receivesname=valuearguments, which it
interprets as follows:headers=You can include custom headers as a dictionary supplied to theheaders=argument. Some headers are provided by default (such as
User-Agent). If these occur in the supplied dictionary, the default
value will be overridden.headers={'Accept':'application/vnd.github.loki-preview+json'}body=If you're usingPOST,PUT, orPATCH(post(),put(), andpatch()), then you should include the body as thebody=argument.
The body is serialized to JSON before sending it out on the wire.GET ParametersAny other arguments to the Python method become GET parameters, and are
tacked onto the end of the URL. They are, of course, url-encoded for
you.When the response is received,agithublooks at its content
type to determine how to handle it, possibly decoding it from the
given char-set to Python's Unicode representation, then converting to
an appropriate form, then passed to you along with the response
status code. (A JSON object is de-serialized into a Python object.)Extensibilityagithubhas been written in an extensible way. You can easily:Add new HTTP methods by extending theClientclass with
new Python methods of the same name (and adding them to thehttp_methodslist).Add new default headers to the_default_headersdictionary.
Just make sure that the header names are lower case.Add a new media-type (a.k.a. content-type a.k.a mime-type) by
inserting a new method into theResponseBodyclass, replacing'-'and'/'with'_'in the method name. That method will then be
responsible for converting the response body to a usable
form — and for callingdecode_bodyto do char-set
conversion, if required. For example to create a handler for the content-typeapplication/xmlyou'd extendResponseBodyand create a new method like thisimportxml.etree.ElementTreeasETclassCustomResponseBody(ResponseBody):def__init__(self):super(ChildB,self).__init__()defapplication_xml(self):# Handles Content-Type of "application/xml"returnET.fromstring(self.body)And if all else fails, you can strap in, and take 15 minutes to read and
become an expert on the code. From there, anything's possible.LicenseCopyright 2012–2016 Jonathan Paugh and contributors
SeeCOPYINGfor license details