Documentation doesn't talk about exceptions

[meetmangukiya]

I think while using API wrappers in scripts we have many places where things could go wrong. Wrong authorizations, not enough permissions, etc.

It'd nice to know if github3 accounts for the status of an API call, to know if it was successful or not, if not raise appropriate exceptions, document those exceptions, so they can be put to use.

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[TansyArron]

I use github3 as part of a webhook handler for triggering builds on CI. The most frequent issue I run into is that when the github api call fails to return json, the github3 object is created anyway. As an example, the following code

pull_request = self.repo.pull_request(issue_number)

sometimes results in the following error:

INFO:github3:Building a url from ('https://api.github.com/repos/foursquare/foursquare.web', 'pulls', '803')
INFO:github3:Missed the cache building the url
INFO:requests.packages.urllib3.connectionpool:Resetting dropped connection: api.github.com
INFO:github3:JSON was not returned
INFO:__main__:Checking message Jenkins: rebuild for keywords
INFO:requests.packages.urllib3.connectionpool:Starting new HTTPS connection (1): api.github.com
ERROR:__main__:Failed to process webhook.
Traceback (most recent call last):
  File "src/python/foursquare/jenkins/ec2/consume_events.py", line 204, in main
    handler.run(message=message)
  File "src/python/foursquare/jenkins/ec2/consume_events.py", line 178, in run
    self.process_comment(body)
  File "src/python/foursquare/jenkins/ec2/consume_events.py", line 66, in process_comment
    self.handle_pull_request(pull_request)
  File "src/python/foursquare/jenkins/ec2/consume_events.py", line 122, in handle_pull_request
    ref = '+refs/pull/{0}/head:refs/remotes/origin/pr/{0}/head'.format(pull_request.number)
AttributeError: 'NoneType' object has no attribute 'number'

There are two things I think would make vast improvements here:

1. Add a retry when fetching from github. Retries are supported by the python requests lib already, and the change would make this class of errors occur less frequently.

2. If the request fails, raise an exception rather than returning an empty object. This would make the stack trace more useful.