"""Stores all the session information.

def __init__(self, login='', password='', token=''):

super(GitHub, self).__init__({})

if token:

self.login(login, token=token)

elif login and password:

self.login(login, password)

def __repr__(self):

if self._session.auth:

return '<GitHub [{0[0]}]>'.format(self._session.auth)

return '<GitHub at 0x{0:x}>'.format(id(self))

def __enter__(self):

return self

def __exit__(self, *args):

pass

@requires_auth

def _iter_follow(self, which, number, etag):

url = self._build_url('user', which)

return self._iter(number, url, User, etag=etag)

@requires_basic_auth

def authorization(self, id_num):

"""Get information about authorization ``id``.

json = None

if int(id_num) > 0:

url = self._build_url('authorizations', str(id_num))

json = self._json(self._get(url), 200)

return Authorization(json, self) if json else None

def authorize(self, login, password, scopes=None, note='', note_url='',

client_id='', client_secret=''):

"""Obtain an authorization token from the GitHub API for the GitHub

json = None

auth = self._session.auth or (login and password)

if auth:

url = self._build_url('authorizations')

data = {'note': note, 'note_url': note_url,

'client_id': client_id, 'client_secret': client_secret}

if scopes:

data['scopes'] = scopes

if self._session.auth:

json = self._json(self._post(url, data=data), 201)

else:

ses = session()

ses.auth = (login, password)

json = self._json(ses.post(url, data=dumps(data)), 201)

return Authorization(json, self) if json else None

def check_authorization(self, access_token):

"""OAuth applications can use this method to check token validity

p = self._session.params

auth = (p.get('client_id'), p.get('client_secret'))

if access_token and auth:

url = self._build_url('applications', str(auth[0]), 'tokens',

str(access_token))

resp = self._get(url, auth=auth, params={

'client_id': None, 'client_secret': None

})

return self._boolean(resp, 200, 404)

return False

def create_gist(self, description, files, public=True):

"""Create a new gist.

new_gist = {'description': description, 'public': public,

'files': files}

url = self._build_url('gists')

json = self._json(self._post(url, data=new_gist), 201)

return Gist(json, self) if json else None

@requires_auth

def create_issue(self,

owner,

repository,

title,

body=None,

assignee=None,

milestone=None,

labels=[]):

"""Create an issue on the project 'repository' owned by 'owner'

repo = None

if owner and repository and title:

repo = self.repository(owner, repository)

if repo:

return repo.create_issue(title, body, assignee, milestone, labels)

# Regardless, something went wrong. We were unable to create the

# issue

return None

@requires_auth

def create_key(self, title, key):

"""Create a new key for the authenticated user.

created = None

if title and key:

url = self._build_url('user', 'keys')

req = self._post(url, data={'title': title, 'key': key})

json = self._json(req, 201)

if json:

created = Key(json, self)

return created

@requires_auth

def create_repo(self,

name,

description='',

homepage='',

private=False,

has_issues=True,

has_wiki=True,

has_downloads=True,

auto_init=False,

gitignore_template=''):

"""Create a repository for the authenticated user.

url = self._build_url('user', 'repos')

data = {'name': name, 'description': description,

'homepage': homepage, 'private': private,

'has_issues': has_issues, 'has_wiki': has_wiki,

'has_downloads': has_downloads, 'auto_init': auto_init,

'gitignore_template': gitignore_template}

json = self._json(self._post(url, data=data), 201)

return Repository(json, self) if json else None

@requires_auth

def delete_key(self, key_id):

"""Delete user key pointed to by ``key_id``.

key = self.key(key_id)

if key:

return key.delete()

return False # (No coverage)

@requires_basic_auth

def feeds(self):

"""List GitHub's timeline resources in Atom format.

url = self._build_url('feeds')

json = self._json(self._get(url), 200)

del json['ETag']

del json['Last-Modified']

urls = [

'timeline_url', 'user_url', 'current_user_public_url',

'current_user_url', 'current_user_actor_url',

'current_user_organization_url',

]

for url in urls:

json[url] = URITemplate(json[url])

links = json.get('_links', {})

for d in links.values():

d['href'] = URITemplate(d['href'])

return json

@requires_auth

def follow(self, login):

"""Make the authenticated user follow login.

resp = False

if login:

url = self._build_url('user', 'following', login)

resp = self._boolean(self._put(url), 204, 404)

return resp

def gist(self, id_num):

"""Gets the gist using the specified id number.

url = self._build_url('gists', str(id_num))

json = self._json(self._get(url), 200)

return Gist(json, self) if json else None

def gitignore_template(self, language):

"""Returns the template for language.

url = self._build_url('gitignore', 'templates', language)

json = self._json(self._get(url), 200)

return json.get('source', '')

def gitignore_templates(self):

"""Returns the list of available templates.

url = self._build_url('gitignore', 'templates')

return self._json(self._get(url), 200) or []

@requires_auth

def is_following(self, login):

"""Check if the authenticated user is following login.

json = False

if login:

url = self._build_url('user', 'following', login)

json = self._boolean(self._get(url), 204, 404)

return json

@requires_auth

def is_starred(self, login, repo):

"""Check if the authenticated user starred login/repo.

json = False

if login and repo:

url = self._build_url('user', 'starred', login, repo)

json = self._boolean(self._get(url), 204, 404)

return json

@requires_auth

def is_subscribed(self, login, repo):

"""Check if the authenticated user is subscribed to login/repo.

json = False

if login and repo:

url = self._build_url('user', 'subscriptions', login, repo)

json = self._boolean(self._get(url), 204, 404)

return json

def issue(self, owner, repository, number):

"""Fetch issue #:number: from https://github.com/:owner:/:repository:

repo = self.repository(owner, repository)

if repo:

return repo.issue(number)

return None

def iter_all_repos(self, number=-1, since=None, etag=None, per_page=None):

"""Iterate over every repository in the order they were created.

url = self._build_url('repositories')

return self._iter(int(number), url, Repository,

params={'since': since, 'per_page': per_page},

etag=etag)

def iter_all_users(self, number=-1, etag=None, per_page=None):

"""Iterate over every user in the order they signed up for GitHub.

url = self._build_url('users')

return self._iter(int(number), url, User,

params={'per_page': per_page}, etag=etag)

@requires_basic_auth

def iter_authorizations(self, number=-1, etag=None):

"""Iterate over authorizations for the authenticated user. This will

url = self._build_url('authorizations')

return self._iter(int(number), url, Authorization, etag=etag)

@requires_auth

def iter_emails(self, number=-1, etag=None):

"""Iterate over email addresses for the authenticated user.

url = self._build_url('user', 'emails')

return self._iter(int(number), url, dict, etag=etag)

def iter_events(self, number=-1, etag=None):

"""Iterate over public events.

url = self._build_url('events')

return self._iter(int(number), url, Event, etag=etag)

def iter_followers(self, login=None, number=-1, etag=None):

"""If login is provided, iterate over a generator of followers of that

if login:

return self.user(login).iter_followers()

return self._iter_follow('followers', int(number), etag=etag)

def iter_following(self, login=None, number=-1, etag=None):

"""If login is provided, iterate over a generator of users being

if login:

return self.user(login).iter_following()

return self._iter_follow('following', int(number), etag=etag)

def iter_gists(self, username=None, number=-1, etag=None):

"""If no username is specified, GET /gists, otherwise GET

if username:

url = self._build_url('users', username, 'gists')

else:

url = self._build_url('gists')

return self._iter(int(number), url, Gist, etag=etag)

@requires_auth

def iter_notifications(self, all=False, participating=False, number=-1,

etag=None):

"""Iterate over the user's notification.

params = None

if all:

params = {'all': all}

elif participating:

params = {'participating': participating}

url = self._build_url('notifications')

return self._iter(int(number), url, Thread, params, etag=etag)

@requires_auth

def iter_org_issues(self, name, filter='', state='', labels='', sort='',

direction='', since=None, number=-1, etag=None):

"""Iterate over the organnization's issues if the authenticated user

url = self._build_url('orgs', name, 'issues')

# issue_params will handle the since parameter

params = issue_params(filter, state, labels, sort, direction, since)

return self._iter(int(number), url, Issue, params, etag)

@requires_auth

def iter_issues(self, filter='', state='', labels='', sort='',

direction='', since=None, number=-1, etag=None):

"""List all of the authenticated user's (and organization's) issues.

url = self._build_url('issues')

# issue_params will handle the since parameter

params = issue_params(filter, state, labels, sort, direction, since)

return self._iter(int(number), url, Issue, params, etag)

@requires_auth

def iter_user_issues(self, filter='', state='', labels='', sort='',

direction='', since=None, number=-1, etag=None):

"""List only the authenticated user's issues. Will not list

url = self._build_url('user', 'issues')

# issue_params will handle the since parameter

params = issue_params(filter, state, labels, sort, direction, since)

return self._iter(int(number), url, Issue, params, etag)

def iter_repo_issues(self, owner, repository, milestone=None,

state=None, assignee=None, mentioned=None,

labels=None, sort=None, direction=None, since=None,

number=-1, etag=None):

"""List issues on owner/repository. Only owner and repository are

if owner and repository:

repo = self.repository(owner, repository)

return repo.iter_issues(milestone, state, assignee, mentioned,

labels, sort, direction, since, number,

etag)

return iter([])

@requires_auth

def iter_keys(self, number=-1, etag=None):

"""Iterate over public keys for the authenticated user.

url = self._build_url('user', 'keys')

return self._iter(int(number), url, Key, etag=etag)

def iter_orgs(self, login=None, number=-1, etag=None):

"""Iterate over public organizations for login if provided; otherwise

if login:

url = self._build_url('users', login, 'orgs')

else:

url = self._build_url('user', 'orgs')

return self._iter(int(number), url, Organization, etag=etag)

@requires_auth

def iter_repos(self, type=None, sort=None, direction=None, number=-1,

etag=None):

"""List public repositories for the authenticated user.

url = self._build_url('user', 'repos')

params = {}

if type in ('all', 'owner', 'public', 'private', 'member'):

params.update(type=type)

if sort in ('created', 'updated', 'pushed', 'full_name'):

params.update(sort=sort)

if direction in ('asc', 'desc'):

params.update(direction=direction)

return self._iter(int(number), url, Repository, params, etag)

def iter_starred(self, login=None, sort=None, direction=None, number=-1,

etag=None):

"""Iterate over repositories starred by ``login`` or the authenticated

if login:

return self.user(login).iter_starred(sort, direction)

params = {'sort': sort, 'direction': direction}

self._remove_none(params)

url = self._build_url('user', 'starred')

return self._iter(int(number), url, Repository, params, etag)

def iter_subscriptions(self, login=None, number=-1, etag=None):

"""Iterate over repositories subscribed to by ``login`` or the

if login:

return self.user(login).iter_subscriptions()

url = self._build_url('user', 'subscriptions')

return self._iter(int(number), url, Repository, etag=etag)

def iter_user_repos(self, login, type=None, sort=None, direction=None,

number=-1, etag=None):

"""List public repositories for the specified ``login``.

url = self._build_url('users', login, 'repos')

params = {}

if type in ('all', 'owner', 'member'):

params.update(type=type)

if sort in ('created', 'updated', 'pushed', 'full_name'):

params.update(sort=sort)

if direction in ('asc', 'desc'):

params.update(direction=direction)

return self._iter(int(number), url, Repository, params, etag)

@requires_auth

def key(self, id_num):

"""Gets the authenticated user's key specified by id_num.

json = None

if int(id_num) > 0:

url = self._build_url('user', 'keys', str(id_num))

json = self._json(self._get(url), 200)

return Key(json, self) if json else None

def login(self, username=None, password=None, token=None,

two_factor_callback=None):

"""Logs the user into GitHub for protected API calls.

if username and password:

self._session.basic_auth(username, password)

elif token:

self._session.token_auth(token)

# The Session method handles None for free.

self._session.two_factor_auth_callback(two_factor_callback)

def markdown(self, text, mode='', context='', raw=False):

"""Render an arbitrary markdown document.

data = None

json = False

headers = {}

if raw:

url = self._build_url('markdown', 'raw')

data = text

headers['content-type'] = 'text/plain'

else:

url = self._build_url('markdown')

data = {}

if text:

data['text'] = text

if mode in ('markdown', 'gfm'):

data['mode'] = mode

if context:

data['context'] = context

json = True

if data:

req = self._post(url, data=data, json=json, headers=headers)

if req.ok:

return req.content

return '' # (No coverage)

def meta(self):

"""Returns a dictionary with arrays of addresses in CIDR format

url = self._build_url('meta')

return self._json(self._get(url), 200)

def octocat(self, say=None):

"""Returns an easter egg of the API.

url = self._build_url('octocat')

req = self._get(url, params={'s': say})

return req.content if req.ok else ''

# TODO: Switch to req.text. Unicode is better.

def organization(self, login):

"""Returns a Organization object for the login name

url = self._build_url('orgs', login)

json = self._json(self._get(url), 200)

return Organization(json, self) if json else None

@requires_auth

def pubsubhubbub(self, mode, topic, callback, secret=''):

"""Create/update a pubsubhubbub hook.

from re import match

m = match('https://[\w\d\-\.\:]+/\w+/[\w\._-]+/events/\w+', topic)

status = False

if mode and topic and callback and m:

data = [('hub.mode', mode), ('hub.topic', topic),

('hub.callback', callback)]

if secret:

data.append(('hub.secret', secret))

url = self._build_url('hub')

# This is not JSON data. It is meant to be form data

# application/x-www-form-urlencoded works fine here, no need for

# multipart/form-data

status = self._boolean(self._post(url, data=data, json=False), 204,

404)

return status

def pull_request(self, owner, repository, number):

"""Fetch pull_request #:number: from :owner:/:repository

r = self.repository(owner, repository)

return r.pull_request(number) if r else None

def repository(self, owner, repository):

"""Returns a Repository object for the specified combination of

json = None

if owner and repository:

url = self._build_url('repos', owner, repository)

json = self._json(self._get(url), 200)

return Repository(json, self) if json else None

def search_issues(self, owner, repo, state, keyword, start_page=0):

"""Find issues by state and keyword.

params = {'start_page': int(start_page)} if int(start_page) > 0 else {}

url = self._build_url('legacy', 'issues', 'search', owner, repo,

state, keyword)

json = self._json(self._get(url, params=params), 200)

issues = json.get('issues', [])

return [LegacyIssue(l, self) for l in issues]

def search_repos(self, keyword, language=None, start_page=None,

sort=None, order=None):

"""Search all repositories by keyword.

url = self._build_url('legacy', 'repos', 'search', keyword)

params = {'language': language, 'start_page': start_page}

if sort in ('stars', 'forks', 'updated'):

params['sort'] = sort

if order in ('asc', 'desc') and not sort:

params['order'] = order

json = self._json(self._get(url, params=params), 200)

repos = json.get('repositories', [])