Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'feat/pep_257'

* feat/pep_257:
  Use class docstring with autodoc.
  Added some more missing docstrings.
  [QA] Use imperative form as per PEP 257.
  [QA] Use PEP 257 punctuation guidelines.
  [QA] Follow PEP 257 whitespace rules.
  • Loading branch information...
commit d8f4d6c500b7e23def619753c54bec722b56bb18 2 parents 3a82036 + 031018e
@JNRowe JNRowe authored
View
2  doc/conf.py
@@ -229,7 +229,7 @@
[u'Ask Solem'], 1)
]
-autoclass_content = "init"
+autoclass_content = "class"
autodoc_default_flags = ['members', ]
intersphinx_mapping = {
View
2  github2/__init__.py
@@ -1,4 +1,4 @@
-"Github API v2 library for Python"
+"GitHub API v2 library for Python."
from github2 import _version
View
10 github2/bin/manage_collaborators.py
@@ -24,9 +24,11 @@
def print_(text):
- """Python 2 & 3 compatible print function
+ """Python 2 & 3 compatible print function.
- We support <2.6, so can't use __future__.print_function"""
+ We support <2.6, so can't use __future__.print_function
+
+ """
if PY3K:
print(text)
else:
@@ -34,7 +36,7 @@ def print_(text):
def parse_commandline():
- """Parse the comandline and return parsed options."""
+ """Parse the command line and return parsed options."""
parser = OptionParser()
parser.description = __doc__
@@ -73,7 +75,7 @@ def parse_commandline():
def main():
- """This implements the actual program functionality"""
+ """Implement the actual program functionality."""
options, args = parse_commandline()
View
10 github2/bin/search_repos.py
@@ -17,9 +17,11 @@
def print_(text):
- """Python 2 & 3 compatible print function
+ """Python 2 & 3 compatible print function.
- We support <2.6, so can't use __future__.print_function"""
+ We support <2.6, so can't use __future__.print_function
+
+ """
if PY3K:
print(text)
else:
@@ -27,7 +29,7 @@ def print_(text):
def parse_commandline():
- """Parse the comandline and return parsed options."""
+ """Parse the command line and return parsed options."""
parser = OptionParser()
parser.description = __doc__
@@ -46,7 +48,7 @@ def parse_commandline():
def main():
- """This implements the actual program functionality"""
+ """Implement the actual program functionality."""
return_value = 0
options, term = parse_commandline()
View
25 github2/client.py
@@ -10,12 +10,12 @@
class Github(object):
+ """Interface to GitHub's API v2."""
+
def __init__(self, username=None, api_token=None, requests_per_second=None,
access_token=None, cache=None, proxy_host=None,
proxy_port=8080, github_url=None):
- """
- An interface to GitHub's API:
- http://develop.github.com/
+ """Setup GitHub API object.
.. versionadded:: 0.2.0
The ``requests_per_second`` parameter
@@ -42,6 +42,7 @@ def __init__(self, username=None, api_token=None, requests_per_second=None,
default to 8080 if a proxy_host is set and no port is set).
:param str github_url: the hostname to connect to, for GitHub
Enterprise support
+
"""
self.request = GithubRequest(username=username, api_token=api_token,
@@ -59,59 +60,65 @@ def __init__(self, username=None, api_token=None, requests_per_second=None,
self.pull_requests = PullRequests(self.request)
def project_for_user_repo(self, user, repo):
- """Return GitHub identifier for a user's repository
+ """Return GitHub identifier for a user's repository.
:param str user: repository owner
:param str repo: repository name
+
"""
return "/".join([user, repo])
def get_all_blobs(self, project, tree_sha):
- """Get a list of all blobs for a specific tree
+ """Get a list of all blobs for a specific tree.
.. versionadded:: 0.3.0
:param str project: GitHub project
:param str tree_sha: object ID of tree
+
"""
blobs = self.request.get("blob/all", project, tree_sha)
return blobs.get("blobs")
def get_blob_info(self, project, tree_sha, path):
- """Get the blob for a file within a specific tree
+ """Get the blob for a file within a specific tree.
:param str project: GitHub project
:param str tree_sha: object ID of tree
:param str path: path within tree to fetch blob for
+
"""
blob = self.request.get("blob/show", project, tree_sha, path)
return blob.get("blob")
def get_tree(self, project, tree_sha):
- """Get tree information for a specifc tree
+ """Get tree information for a specifc tree.
:param str project: GitHub project
:param str tree_sha: object ID of tree
+
"""
tree = self.request.get("tree/show", project, tree_sha)
return tree.get("tree", [])
def get_network_meta(self, project):
- """Get GitHub metadata associated with a project
+ """Get GitHub metadata associated with a project.
:param str project: GitHub project
+
"""
return self.request.raw_request("/".join([self.request.github_url,
project,
"network_meta"]), {})
def get_network_data(self, project, nethash, start=None, end=None):
- """Get chunk of GitHub network data
+ """Get chunk of GitHub network data.
:param str project: GitHub project
:param str nethash: identifier provided by :meth:`get_network_meta`
:param int start: optional start point for data
:param int stop: optional end point for data
+
"""
data = {"nethash": nethash}
if start:
View
12 github2/commits.py
@@ -3,6 +3,9 @@
class Commit(BaseData):
+
+ """Commit container."""
+
message = Attribute("Commit message.")
parents = Attribute("List of parents for this commit.")
url = Attribute("Canonical URL for this commit.")
@@ -25,10 +28,13 @@ def __repr__(self):
class Commits(GithubCommand):
+
+ """GitHub API commits functionality."""
+
domain = "commits"
def list(self, project, branch="master", file=None, page=1):
- """List commits on a project
+ """List commits on a project.
.. warning::
Not all projects use ``master`` as their default branch, you can
@@ -39,15 +45,17 @@ def list(self, project, branch="master", file=None, page=1):
:param str branch: branch name, or ``master`` if not given
:param str file: optional file filter
:param int page: optional page number
+
"""
return self.get_values("list", project, branch, file, filter="commits",
datatype=Commit, page=page)
def show(self, project, sha):
- """Get a specific commit
+ """Get a specific commit.
:param str project: project name
:param str sha: commit id
+
"""
return self.get_value("show", project, sha,
filter="commit", datatype=Commit)
View
69 github2/core.py
@@ -27,9 +27,10 @@
def string_to_datetime(string):
- """Convert a string to Python datetime
+ """Convert a string to Python datetime.
:param str github_date: date string to parse
+
"""
parsed = parser.parse(string)
if NAIVE:
@@ -38,9 +39,10 @@ def string_to_datetime(string):
def _handle_naive_datetimes(f):
- """Decorator to make datetime arguments use GitHub timezone
+ """Decorator to make datetime arguments use GitHub timezone.
:param func f: Function to wrap
+
"""
def wrapper(datetime_):
if not datetime_.tzinfo:
@@ -59,18 +61,20 @@ def wrapper(datetime_):
@_handle_naive_datetimes
def datetime_to_ghdate(datetime_):
- """Convert Python datetime to GitHub date string
+ """Convert Python datetime to GitHub date string.
:param datetime datetime_: datetime object to convert
+
"""
return datetime_.strftime(GITHUB_DATE_FORMAT)
@_handle_naive_datetimes
def datetime_to_commitdate(datetime_):
- """Convert Python datetime to GitHub date string
+ """Convert Python datetime to GitHub date string.
:param datetime datetime_: datetime object to convert
+
"""
date_without_tz = datetime_.strftime(COMMIT_DATE_FORMAT)
utcoffset = GITHUB_TZ.utcoffset(datetime_)
@@ -80,12 +84,11 @@ def datetime_to_commitdate(datetime_):
def datetime_to_isodate(datetime_):
- """Convert Python datetime to GitHub date string
-
- .. note:: Supports naive and timezone-aware datetimes
+ """Convert Python datetime to GitHub date string.
:param str datetime_: datetime object to convert
+ .. note:: Supports naive and timezone-aware datetimes
"""
if not datetime_.tzinfo:
datetime_ = datetime_.replace(tzinfo=tz.tzutc())
@@ -95,16 +98,18 @@ def datetime_to_isodate(datetime_):
class AuthError(Exception):
- """Requires authentication"""
+
+ """Requires authentication."""
def requires_auth(f):
- """Decorate to check a function call for authentication
+ """Decorate to check a function call for authentication.
Sets a ``requires_auth`` attribute on functions, for use in introspection.
:param func f: Function to wrap
:raises AuthError: If function called without an authenticated session
+
"""
# When Python 2.4 support is dropped move straight to functools.wraps,
# don't pass go and don't collect $200.
@@ -123,12 +128,13 @@ def wrapper(self, *args, **kwargs):
def enhanced_by_auth(f):
- """Decorator to mark a function as enhanced by authentication
+ """Decorator to mark a function as enhanced by authentication.
Sets a ``enhanced_by_auth`` attribute on functions, for use in
introspection.
:param func f: Function to wrap
+
"""
f.enhanced_by_auth = True
f.__doc__ += """\n.. note:: This call is enhanced with authentication"""
@@ -137,15 +143,18 @@ def enhanced_by_auth(f):
class GithubCommand(object):
+ """Main API binding interface."""
+
def __init__(self, request):
- """Main API binding interface
+ """Setup command object.
:param github2.request.GithubRequest request: HTTP request handler
+
"""
self.request = request
def make_request(self, command, *args, **kwargs):
- """Make an API request
+ """Make an API request.
Various options are supported if they exist in ``kwargs``:
@@ -155,6 +164,7 @@ def make_request(self, command, *args, **kwargs):
data
* The value of a ``page`` argument will be used to fetch a specific
page of results, default of 1 is assumed if not given
+
"""
filter = kwargs.get("filter")
post_data = kwargs.get("post_data") or {}
@@ -178,10 +188,11 @@ def make_request(self, command, *args, **kwargs):
return response
def get_value(self, *args, **kwargs):
- """Process a single-value response from the API
+ """Process a single-value response from the API.
If a ``datatype`` parameter is given it defines the
:class:`BaseData`-derived class we should build from the provided data
+
"""
datatype = kwargs.pop("datatype", None)
value = self.make_request(*args, **kwargs)
@@ -197,9 +208,10 @@ def get_value(self, *args, **kwargs):
return value
def get_values(self, *args, **kwargs):
- """Process a multi-value response from the API
+ """Process a multi-value response from the API.
:see: :meth:`get_value`
+
"""
datatype = kwargs.pop("datatype", None)
values = self.make_request(*args, **kwargs)
@@ -217,10 +229,11 @@ def get_values(self, *args, **kwargs):
def doc_generator(docstring, attributes):
- """Utility function to augment BaseDataType docstring
+ """Utility function to augment BaseDataType docstring.
:param str docstring: docstring to augment
:param dict attributes: attributes to add to docstring
+
"""
docstring = docstring or ""
@@ -233,10 +246,14 @@ def bullet(title, text):
class Attribute(object):
+
+ """Generic object attribute for use with :class:`BaseData`."""
+
def __init__(self, help):
- """Generic object attribute for use with :class:`BaseData`
+ """Setup Attribute object.
:param str help: Attribute description
+
"""
self.help = help
@@ -247,6 +264,9 @@ def to_python(self, value):
class DateAttribute(Attribute):
+
+ """Date handling attribute for use with :class:`BaseData`."""
+
format = "github"
converter_for_format = {
"github": datetime_to_ghdate,
@@ -256,10 +276,11 @@ class DateAttribute(Attribute):
}
def __init__(self, *args, **kwargs):
- """Date handling attribute for use with :class:`BaseData`
+ """Setup DateAttribute object.
:param str format: The date format to support, see
:data:`convertor_for_format` for supported options
+
"""
self.format = kwargs.pop("format", self.format)
super(DateAttribute, self).__init__(*args, **kwargs)
@@ -313,17 +334,21 @@ def iterate(self):
# Ugly base class definition for Python 2 and 3 compatibility, where metaclass
# syntax is incompatible
class BaseData(BaseDataType('BaseData', (object, ), {})):
- """Wrapper for API responses
+
+ """Wrapper for API responses.
.. warning::
Supports subscript attribute access purely for backwards compatibility,
you shouldn't rely on that functionality in new code
+
"""
+
def __getitem__(self, key):
- """Access objects's attribute using subscript notation
+ """Access objects's attribute using subscript notation.
This is here purely to maintain compatibility when switching ``dict``
responses to ``BaseData`` derived objects.
+
"""
LOGGER.warning("Subscript access on %r is deprecated, use object "
"attributes" % self.__class__.__name__,
@@ -333,9 +358,10 @@ def __getitem__(self, key):
return getattr(self, key)
def __setitem__(self, key, value):
- """Update object's attribute using subscript notation
+ """Update object's attribute using subscript notation.
:see: :meth:`BaseData.__getitem__`
+
"""
LOGGER.warning("Subscript access on %r is deprecated, use object "
"attributes" % self.__class__.__name__,
@@ -346,10 +372,11 @@ def __setitem__(self, key, value):
def repr_string(string):
- """Shorten string for use in repr() output
+ """Shorten string for use in repr() output.
:param str string: string to operate on
:return: string, with maximum length of 20 characters
+
"""
if len(string) > 20:
string = string[:17] + '...'
View
39 github2/issues.py
@@ -8,6 +8,9 @@
class Issue(BaseData):
+
+ """Issue container."""
+
position = Attribute("The position of this issue in a list.")
number = Attribute("The issue number (unique for project).")
votes = Attribute("Number of votes for this issue.")
@@ -28,6 +31,9 @@ def __repr__(self):
class Comment(BaseData):
+
+ """Comment container."""
+
created_at = DateAttribute("The date this comment was created.")
updated_at = DateAttribute("The date when this comment was last updated.")
body = Attribute("The full text of this comment.")
@@ -39,6 +45,9 @@ def __repr__(self):
class Issues(GithubCommand):
+
+ """GitHub API issues functionality."""
+
domain = "issues"
def search(self, project, term, state="open"):
@@ -48,7 +57,8 @@ def search(self, project, term, state="open"):
:param str project: GitHub project
:param str term: term to search issues for
- :param str state: can be either ``open`` or ``closed``.
+ :param str state: can be either ``open`` or ``closed``
+
"""
return self.get_values("search", project, state, quote_plus(term),
filter="issues", datatype=Issue)
@@ -57,7 +67,8 @@ def list(self, project, state="open"):
"""Get all issues for project with given state.
:param str project: GitHub project
- :param str state: can be either ``open`` or ``closed``.
+ :param str state: can be either ``open`` or ``closed``
+
"""
return self.get_values("list", project, state, filter="issues",
datatype=Issue)
@@ -68,7 +79,8 @@ def list_by_label(self, project, label):
.. versionadded:: 0.3.0
:param str project: GitHub project
- :param str label: a string representing a label (e.g., ``bug``).
+ :param str label: a string representing a label (e.g., ``bug``)
+
"""
return self.get_values("list", project, "label", label,
filter="issues", datatype=Issue)
@@ -79,6 +91,7 @@ def list_labels(self, project):
.. versionadded:: 0.3.0
:param str project: GitHub project
+
"""
return self.get_values("labels", project, filter="labels")
@@ -87,6 +100,7 @@ def show(self, project, number):
:param str project: GitHub project
:param int number: issue number in the GitHub database
+
"""
return self.get_value("show", project, str(number),
filter="issue", datatype=Issue)
@@ -98,6 +112,7 @@ def open(self, project, title, body):
:param str project: GitHub project
:param str title: title for issue
:param str body: body for issue
+
"""
issue_data = {"title": title, "body": body}
return self.get_value("open", project, post_data=issue_data,
@@ -105,29 +120,31 @@ def open(self, project, title, body):
@requires_auth
def close(self, project, number):
- """Close an issue
+ """Close an issue.
:param str project: GitHub project
:param int number: issue number in the GitHub database
+
"""
return self.get_value("close", project, str(number), filter="issue",
datatype=Issue, method="POST")
@requires_auth
def reopen(self, project, number):
- """Reopen a closed issue
+ """Reopen a closed issue.
.. versionadded:: 0.3.0
:param str project: GitHub project
:param int number: issue number in the GitHub database
+
"""
return self.get_value("reopen", project, str(number), filter="issue",
datatype=Issue, method="POST")
@requires_auth
def edit(self, project, number, title, body):
- """Edit an existing issue
+ """Edit an existing issue.
.. versionadded:: 0.3.0
@@ -135,6 +152,7 @@ def edit(self, project, number, title, body):
:param int number: issue number in the GitHub database
:param str title: title for issue
:param str body: body for issue
+
"""
issue_data = {"title": title, "body": body}
return self.get_value("edit", project, str(number),
@@ -143,22 +161,24 @@ def edit(self, project, number, title, body):
@requires_auth
def add_label(self, project, number, label):
- """Add a label to an issue
+ """Add a label to an issue.
:param str project: GitHub project
:param int number: issue number in the GitHub database
:param str label: label to attach to issue
+
"""
return self.get_values("label/add", project, label, str(number),
filter="labels", method="POST")
@requires_auth
def remove_label(self, project, number, label):
- """Remove an existing label from an issue
+ """Remove an existing label from an issue.
:param str project: GitHub project
:param int number: issue number in the GitHub database
:param str label: label to remove from issue
+
"""
return self.get_values("label/remove", project, label, str(number),
filter="labels", method="POST")
@@ -170,6 +190,7 @@ def comment(self, project, number, comment):
:param str project: GitHub project
:param int number: issue number in the GitHub database
:param str comment: comment to attach to issue
+
"""
comment_data = {'comment': comment}
return self.get_value("comment", project, str(number),
@@ -180,7 +201,7 @@ def comments(self, project, number):
"""View comments on an issue.
:param str project: GitHub project
- :param int number: issue number in the GitHub database
+
"""
return self.get_values("comments", project, str(number),
filter="comments", datatype=Comment)
View
36 github2/organizations.py
@@ -6,7 +6,13 @@
class Organization(BaseData):
- """.. versionadded:: 0.4.0"""
+
+ """Organization container.
+
+ .. versionadded:: 0.4.0
+
+ """
+
id = Attribute("The organization id.")
name = Attribute("The full name of the organization.")
blog = Attribute("The organization's blog.")
@@ -35,65 +41,77 @@ def __repr__(self):
class Organizations(GithubCommand):
- """.. versionadded:: 0.4.0"""
+
+ """GitHub API organizations functionality.
+
+ .. versionadded:: 0.4.0
+
+ """
+
domain = "organizations"
def show(self, organization):
- """Get information on organization
+ """Get information on organization.
:param str organization: organization to show
+
"""
return self.get_value(organization, filter="organization",
datatype=Organization)
def list(self):
- """Get list of all of your organizations"""
+ """Get list of all of your organizations."""
return self.get_values('', filter="organizations",
datatype=Organization)
def repositories(self, organization=''):
- """Get list of all repositories in an organization
+ """Get list of all repositories in an organization.
If organization is not given, or is empty, then this will list
repositories for all organizations the authenticated user belongs to.
:param: str organization: organization to list repositories for
+
"""
return self.get_values(organization, 'repositories',
filter="repositories", datatype=Repository)
def public_repositories(self, organization):
- """Get list of public repositories in an organization
+ """Get list of public repositories in an organization.
:param str organization: organization to list public repositories for
+
"""
return self.get_values(organization, 'public_repositories',
filter="repositories", datatype=Repository)
def public_members(self, organization):
- """Get list of public members in an organization
+ """Get list of public members in an organization.
:param str organization: organization to list members for
+
"""
return self.get_values(organization, 'public_members', filter="users",
datatype=User)
def teams(self, organization):
- """Get list of teams in an organization
+ """Get list of teams in an organization.
:param str organization: organization to list teams for
+
"""
return self.get_values(organization, 'teams', filter="teams",
datatype=Team)
@requires_auth
def add_team(self, organization, name, permission='pull', projects=None):
- """Add a team to an organization
+ """Add a team to an organization.
:param str organization: organization to add team to
:param str team: name of team to add
:param str permission: permissions for team(push, pull or admin)
:param list projects: optional GitHub projects for this team
+
"""
team_data = {'team[name]': name, 'team[permission]': permission}
if projects:
View
19 github2/pull_requests.py
@@ -3,10 +3,13 @@
class PullRequest(BaseData):
- """Pull request encapsulation
+
+ """Pull request container.
.. versionadded:: 0.5.0
+
"""
+
state = Attribute("The pull request state")
base = Attribute("The base repo")
head = Attribute("The head of the pull request")
@@ -40,14 +43,17 @@ def __repr__(self):
class PullRequests(GithubCommand):
- """Operations on pull requests
+
+ """GitHub API pull request functionality.
.. versionadded:: 0.5.0
+
"""
+
domain = "pulls"
def create(self, project, base, head, title=None, body=None, issue=None):
- """Create a new pull request
+ """Create a new pull request.
Pull requests can be created from scratch, or attached to an existing
issue. If an ``issue`` parameter is supplied the pull request is
@@ -59,6 +65,7 @@ def create(self, project, base, head, title=None, body=None, issue=None):
:param str title: title for pull request
:param str body: optional body for pull request
:param str issue: existing issue to attach pull request to
+
"""
post_data = {"base": base, "head": head}
if issue:
@@ -76,20 +83,22 @@ def create(self, project, base, head, title=None, body=None, issue=None):
filter="pull", datatype=PullRequest)
def show(self, project, number):
- """Show a single pull request
+ """Show a single pull request.
:param str project: GitHub project
:param int number: pull request number in the GitHub database
+
"""
return self.get_value(project, str(number), filter="pull",
datatype=PullRequest)
def list(self, project, state="open", page=1):
- """List all pull requests for a project
+ """List all pull requests for a project.
:param str project: GitHub project
:param str state: can be either ``open`` or ``closed``
:param int page: optional page number
+
"""
return self.get_values(project, state, filter="pulls",
datatype=PullRequest, page=page)
View
60 github2/repositories.py
@@ -5,6 +5,9 @@
class Repository(BaseData):
+
+ """Repository container."""
+
name = Attribute("Name of repository.")
description = Attribute("Repository description.")
forks = Attribute("Number of forks of this repository.")
@@ -35,6 +38,8 @@ def __repr__(self):
class Repositories(GithubCommand):
+ """GitHub API repository functionality."""
+
domain = "repos"
def search(self, query):
@@ -44,6 +49,7 @@ def search(self, query):
Returns at most 100 repositories
:param str query: term to search issues for
+
"""
return self.get_values("search", query, filter="repositories",
datatype=Repository)
@@ -52,6 +58,7 @@ def show(self, project):
"""Get repository object for project.
:param str project: GitHub project
+
"""
return self.get_value("show", project, filter="repository",
datatype=Repository)
@@ -61,6 +68,7 @@ def pushable(self):
"""Return a list of repos you can push to that are not your own.
.. versionadded:: 0.3.0
+
"""
return self.get_values("pushable", filter="repositories",
datatype=Repository)
@@ -75,6 +83,7 @@ def list(self, user=None, page=1):
:param str user: GitHub user name to list repositories for
:param int page: optional page number
+
"""
user = user or self.request.username
return self.get_values("show", user, filter="repositories",
@@ -82,39 +91,43 @@ def list(self, user=None, page=1):
@requires_auth
def watch(self, project):
- """Watch a project
+ """Watch a project.
:param str project: GitHub project
+
"""
return self.get_value("watch", project, filter='repository',
datatype=Repository)
@requires_auth
def unwatch(self, project):
- """Unwatch a project
+ """Unwatch a project.
:param str project: GitHub project
+
"""
return self.get_value("unwatch", project, filter='repository',
datatype=Repository)
@requires_auth
def fork(self, project):
- """Fork a project
+ """Fork a project.
:param str project: GitHub project
+
"""
return self.get_value("fork", project, filter="repository",
datatype=Repository)
@requires_auth
def create(self, project, description=None, homepage=None, public=True):
- """Create a repository
+ """Create a repository.
:param str project: new project name
:param str description: optional project description
:param str homepage: optional project homepage
:param bool public: whether to make a public project
+
"""
repo_data = {"name": project, "description": description,
"homepage": homepage, "public": str(int(public))}
@@ -123,9 +136,10 @@ def create(self, project, description=None, homepage=None, public=True):
@requires_auth
def delete(self, project):
- """Delete a repository
+ """Delete a repository.
:param str project: project name to delete
+
"""
# Two-step delete mechanism. We must echo the delete_token value back
# to GitHub to actually delete a repository
@@ -134,99 +148,111 @@ def delete(self, project):
@requires_auth
def set_private(self, project):
- """Mark repository as private
+ """Mark repository as private.
:param str project: project name to set as private
+
"""
return self.make_request("set/private", project)
@requires_auth
def set_public(self, project):
- """Mark repository as public
+ """Mark repository as public.
:param str project: project name to set as public
+
"""
return self.make_request("set/public", project)
def list_collaborators(self, project):
- """Lists all the collaborators in a project
+ """List all the collaborators in a project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "collaborators",
filter="collaborators")
@requires_auth
def add_collaborator(self, project, username):
- """Adds an add_collaborator to a repo
+ """Add an add_collaborator to a repo.
:param str project: GitHub project
:param str username: GitHub user to add as collaborator
+
"""
return self.make_request("collaborators", project, "add", username,
method="POST")
@requires_auth
def remove_collaborator(self, project, username):
- """Removes an add_collaborator from a repo
+ """Remove a collaborator from a repo.
:param str project: GitHub project
:param str username: GitHub user to add as collaborator
+
"""
return self.make_request("collaborators", project, "remove",
username, method="POST")
def network(self, project):
- """Get network data for project
+ """Get network data for project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "network", filter="network",
datatype=Repository)
def languages(self, project):
- """Get programming language data for project
+ """Get programming language data for project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "languages",
filter="languages")
def tags(self, project):
- """Get tags for project
+ """Get tags for project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "tags", filter="tags")
def branches(self, project):
- """Get branch names for project
+ """Get branch names for project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "branches", filter="branches")
def watchers(self, project):
- """Get list of watchers for project
+ """Get list of watchers for project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "watchers", filter="watchers")
def watching(self, for_user=None, page=None):
- """Lists all the repos a user is watching
+ """List all the repos a user is watching.
:param str for_user: optional GitHub user name to list repositories for
:param int page: optional page number
+
"""
for_user = for_user or self.request.username
return self.get_values("watched", for_user, filter="repositories",
datatype=Repository, page=page)
def list_contributors(self, project):
- """Lists all the contributors in a project
+ """List all the contributors in a project.
:param str project: GitHub project
+
"""
return self.get_values("show", project, "contributors",
filter="contributors", datatype=User)
View
20 github2/request.py
@@ -67,10 +67,11 @@
def charset_from_headers(headers):
- """Parse charset from headers
+ """Parse charset from headers.
:param httplib2.Response headers: Request headers
:return: Defined encoding, or default to ASCII
+
"""
match = re.search("charset=([^ ;]+)", headers.get('content-type', ""))
if match:
@@ -81,17 +82,21 @@ def charset_from_headers(headers):
class GithubError(Exception):
+
"""An error occurred when making a request to the GitHub API."""
class HttpError(RuntimeError):
+
"""A HTTP error occured when making a request to the GitHub API."""
+
def __init__(self, message, content, code):
- """Create a HttpError exception
+ """Create a HttpError exception.
:param str message: Exception string
:param str content: Full content of HTTP request
:param int code: HTTP status code
+
"""
self.args = (message, content, code)
self.message = message
@@ -106,6 +111,13 @@ def __init__(self, message, content, code):
class GithubRequest(object):
+
+ """Make an API request.
+
+ :see: :class:`github2.client.Github`
+
+ """
+
url_format = "%(github_url)s/api/%(api_version)s/%(api_format)s"
api_version = "v2"
api_format = "json"
@@ -115,10 +127,6 @@ def __init__(self, username=None, api_token=None, url_prefix=None,
requests_per_second=None, access_token=None,
cache=None, proxy_host=None, proxy_port=None,
github_url=None):
- """Make an API request.
-
- :see: :class:`github2.client.Github`
- """
self.username = username
self.api_token = api_token
self.access_token = access_token
View
34 github2/teams.py
@@ -4,7 +4,13 @@
class Team(BaseData):
- """.. versionadded:: 0.4.0"""
+
+ """Team container.
+
+ .. versionadded:: 0.4.0
+
+ """
+
id = Attribute("The team id")
name = Attribute("Name of the team")
permission = Attribute("Permissions of the team")
@@ -14,49 +20,60 @@ def __repr__(self):
class Teams(GithubCommand):
- """.. versionadded:: 0.4.0"""
+
+ """GitHub API teams functionality.
+
+ .. versionadded:: 0.4.0
+
+ """
+
domain = "teams"
def show(self, team_id):
- """Get information on team_id
+ """Get information on team_id.
:param int team_id: team to get information for
+
"""
return self.get_value(str(team_id), filter="team", datatype=Team)
def members(self, team_id):
- """Get list of all team members
+ """Get list of all team members.
:param int team_id: team to get information for
+
"""
return self.get_values(str(team_id), "members", filter="users",
datatype=User)
@requires_auth
def add_member(self, team_id, username):
- """Add a new member to a team
+ """Add a new member to a team.
:param int team_id: team to add new member to
:param str username: GitHub username to add to team
+
"""
return self.get_values(str(team_id), 'members', method='POST',
post_data={'name': username}, filter='users',
datatype=User)
def repositories(self, team_id):
- """Get list of all team repositories
+ """Get list of all team repositories.
:param int team_id: team to get information for
+
"""
return self.get_values(str(team_id), "repositories",
filter="repositories", datatype=Repository)
@requires_auth
def add_project(self, team_id, project):
- """Add a project to a team
+ """Add a project to a team.
:param int team_id: team to add repository to
:param str project: GitHub project
+
"""
if isinstance(project, Repository):
project = project.project
@@ -66,10 +83,11 @@ def add_project(self, team_id, project):
@requires_auth
def remove_project(self, team_id, project):
- """Remove a project to a team
+ """Remove a project to a team.
:param int team_id: team to remove project from
:param str project: GitHub project
+
"""
if isinstance(project, Repository):
project = project.project
View
45 github2/users.py
@@ -8,6 +8,9 @@
class Key(BaseData):
+
+ """SSH key container."""
+
id = Attribute('The key id')
key = Attribute('The SSH key data')
title = Attribute('The title for the SSH key')
@@ -17,6 +20,9 @@ def __repr__(self):
class User(BaseData):
+
+ """GitHub user container."""
+
id = Attribute("The user id")
login = Attribute("The login username")
name = Attribute("The users full name")
@@ -41,9 +47,11 @@ class User(BaseData):
format="user")
def is_authenticated(self):
- """Test for user authentication
+ """Test for user authentication.
+
+ :return bool: ``True`` if user is authenticated
- :return bool: ``True`` if user is authenticated"""
+ """
return self.plan is not None
def __repr__(self):
@@ -51,78 +59,88 @@ def __repr__(self):
class Users(GithubCommand):
+
+ """GitHub API user functionality."""
+
domain = "user"
def search(self, query):
- """Search for users
+ """Search for users.
.. warning:
Returns at most 100 users
:param str query: term to search for
+
"""
return self.get_values("search", quote_plus(query), filter="users",
datatype=User)
def search_by_email(self, query):
- """Search for users by email address
+ """Search for users by email address.
:param str query: email to search for
+
"""
return self.get_value("email", query, filter="user", datatype=User)
@enhanced_by_auth
def show(self, username):
- """Get information on GitHub user
+ """Get information on GitHub user.
if ``username`` is ``None`` or an empty string information for the
currently authenticated user is returned.
- :param str username: GitHub user name
+
"""
return self.get_value("show", username, filter="user", datatype=User)
def followers(self, username):
- """Get list of GitHub user's followers
+ """Get list of GitHub user's followers.
:param str username: GitHub user name
+
"""
return self.get_values("show", username, "followers", filter="users")
def following(self, username):
- """Get list of users a GitHub user is following
+ """Get list of users a GitHub user is following.
:param str username: GitHub user name
+
"""
return self.get_values("show", username, "following", filter="users")
@requires_auth
def follow(self, other_user):
- """Follow a GitHub user
+ """Follow a GitHub user.
:param str other_user: GitHub user name
+
"""
return self.get_values("follow", other_user, method="POST")
@requires_auth
def unfollow(self, other_user):
- """Unfollow a GitHub user
+ """Unfollow a GitHub user.
:param str other_user: GitHub user name
+
"""
return self.get_values("unfollow", other_user, method="POST")
@requires_auth
def list_keys(self):
- """Get list of SSH keys for the authenticated user"""
+ """Get list of SSH keys for the authenticated user."""
return self.get_values('keys', filter='public_keys', datatype=Key)
@requires_auth
def add_key(self, key, title=''):
- """Add a SSH key for the authenticated user
+ """Add a SSH key for the authenticated user.
:param str key: SSH key identifier
:param str title: Optional title for the SSH key
+
"""
return self.get_values("key/add",
post_data={'key': key, 'title': title},
@@ -131,9 +149,10 @@ def add_key(self, key, title=''):
@requires_auth
def remove_key(self, key_id):
- """Remove a SSH key for the authenticated user
+ """Remove a SSH key for the authenticated user.
:param int key_id: SSH key's GitHub identifier
+
"""
return self.get_values('key/remove', post_data={'id': str(key_id)},
filter='public_keys', datatype=Key)
Please sign in to comment.
Something went wrong with that request. Please try again.