mirror of
https://github.com/status-im/PyGithub.git
synced 2026-08-31 10:51:14 +00:00
Improve documentation
This commit is contained in:
Vincent Jacques
@@ -1,31 +0,0 @@
|
||||
Issues
|
||||
======
|
||||
|
||||
A good issue includes a [short, self contained, correct example](http://sscce.org/) of the problem, something like:
|
||||
|
||||
assert github.Github().get_user("jacquev6").name == "Vincent Jacques"
|
||||
|
||||
It is even better if you provide the debug logs associated with your issue.
|
||||
Enable them with `github.enable_console_debug_logging()` and copy them in the body of the issue.
|
||||
Warning, you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages)
|
||||
|
||||
If for any reason you are not able to do that, open your issue anyway and we will see what is needed to solve your problem.
|
||||
|
||||
Pull requests
|
||||
=============
|
||||
|
||||
Please do your pull requests on the `develop` branch.
|
||||
|
||||
PyGithub follows [pep8 Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/) except for line length.
|
||||
So if you do heavy modifications, please check your code with [pep8 Python style guide checker](http://pypi.python.org/pypi/pep8), by running `pep8 --ignore=E501 github`.
|
||||
|
||||
Automated tests
|
||||
---------------
|
||||
|
||||
You can run the tests through `python -m github.tests`. Run a specific test with `python -m github.tests TestCase` or `python -m github.tests TestCase.testMethod`.
|
||||
|
||||
If you add a new test, for example `Issue139.testCompletion`, you must add an import in github/tests/AllTests.py. Then, you have to run `python -m github.tests Issue139.testCompletion --record` to create the github/tests/ReplayData/*.txt files needed for you new test. Check them and commit them as well. You will need a GithubCredentials.py file at the root of the project with the following contents:
|
||||
|
||||
login = "my_login"
|
||||
password = "my_password"
|
||||
oauth_token = "my_token" # Can be left empty if not used
|
||||
@@ -0,0 +1,37 @@
|
||||
Contributing
|
||||
============
|
||||
|
||||
Issues
|
||||
------
|
||||
|
||||
A good issue includes a `short, self contained, correct example <http://sscce.org/>`_ of the problem, something like::
|
||||
|
||||
assert github.Github().get_user("jacquev6").name == "Vincent Jacques"
|
||||
|
||||
It is even better if you provide the debug logs associated with your issue.
|
||||
Enable them with :func:`github.enable_console_debug_logging` and copy them in the body of the issue.
|
||||
Warning, you may want to remove some private information (authentication information is removed, but there may be private stuff in the messages)
|
||||
|
||||
If for any reason you are not able to do that, open your issue anyway and we will see what is needed to solve your problem.
|
||||
|
||||
Pull requests
|
||||
-------------
|
||||
|
||||
Please do your pull requests on the ``develop`` branch.
|
||||
|
||||
Automated tests
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
You can run the tests through ``python -m github.tests``. Run a specific test with ``python -m github.tests TestCase`` or ``python -m github.tests TestCase.testMethod``.
|
||||
|
||||
If you add a new test, for example ``Issue139.testCompletion``, you must add an import in ``github/tests/AllTests.py``. Then, you have to run ``python -m github.tests Issue139.testCompletion --record`` to create the ``github/tests/ReplayData/*.txt`` files needed for you new test. Check them and commit them as well. You will need a ``GithubCredentials.py`` file at the root of the project with the following contents::
|
||||
|
||||
login = "my_login"
|
||||
password = "my_password"
|
||||
oauth_token = "my_token" # Can be left empty if not used
|
||||
|
||||
Coding conventions
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
PyGithub follows `pep8 Style Guide for Python Code <http://www.python.org/dev/peps/pep-0008/>`_ except for line length.
|
||||
Please check your code with `pep8 Python style guide checker <http://pypi.python.org/pypi/pep8>`_, by running ``pep8 --ignore=E501 github``.
|
||||
+7
-46
@@ -1,5 +1,4 @@
|
||||
This is a Python (2 and 3) library to access the `Github API v3 <http://developer.github.com/v3>`_.
|
||||
|
||||
With it, you can manage your `Github <http://github.com>`_ resources (repositories, user profiles, organizations, etc.) from Python scripts.
|
||||
|
||||
It covers the **full** API, and all methods are tested against the real Github site.
|
||||
@@ -11,53 +10,15 @@ PyGithub is stable. I will maintain it up to date with the API, and fix bugs if
|
||||
What's new?
|
||||
===========
|
||||
|
||||
`] <http://travis-ci.org/jacquev6/PyGithub>`_
|
||||
`] <http://travis-ci.org/jacquev6/PyGithub>`_
|
||||
|
||||
Next version
|
||||
------------
|
||||
`Version 1.12.0 <https://github.com/jacquev6/PyGithub/issues?milestone=22&state=closed>`_ (February 17th, 2013)
|
||||
---------------------------------------------------------------------------------------------------------------
|
||||
|
||||
* Much better documentation http://jacquev6.github.com/PyGithub.
|
||||
* Much better documentation: http://jacquev6.github.com/PyGithub
|
||||
* `Implement <https://github.com/jacquev6/PyGithub/issues/140>`_ :meth:`github.Repository.Repository.get_gir_contents`. Thank you `ksookocheff-va <https://github.com/ksookocheff-va>`_ for asking
|
||||
|
||||
Previous versions
|
||||
-----------------
|
||||
|
||||
See `ChangeLog <https://github.com/jacquev6/PyGithub/blob/master/doc/ChangeLog.md>`_.
|
||||
|
||||
Dcumentation
|
||||
============
|
||||
Documentation
|
||||
=============
|
||||
|
||||
All the documentation is here: http://jacquev6.github.com/PyGithub.
|
||||
|
||||
Licensing
|
||||
=========
|
||||
|
||||
PyGithub is distributed under the GNU Lesser General Public Licence.
|
||||
See files COPYING and COPYING.LESSER, as requested by `GNU <http://www.gnu.org/licenses/gpl-howto.html>`_.
|
||||
|
||||
Contributing
|
||||
============
|
||||
|
||||
Please see `Contributing.md <https://github.com/jacquev6/PyGithub/blob/master/doc/Contributing.md>`_.
|
||||
|
||||
Projects using PyGithub
|
||||
=======================
|
||||
|
||||
(`Open an issue <https://github.com/jacquev6/PyGithub/issues>`_ if you want to be listed here, I'll be glad to add your project)
|
||||
|
||||
* `Upverter <https://upverter.com>`_ is a web-based schematic capture and PCB layout tool for people who design electronics. Designers can attach a Github project to an Upverter project.
|
||||
* `Notifico <http://n.tkte.ch>`_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github.
|
||||
* `Tratihubis <http://pypi.python.org/pypi/tratihubis/>`_ converts Trac tickets to Github issues
|
||||
* https://github.com/CMB/cligh
|
||||
* https://github.com/natduca/quickopen uses PyGithub to automaticaly create issues
|
||||
* https://gist.github.com/3433798
|
||||
* https://github.com/zsiciarz/aquila-dsp.org
|
||||
* https://github.com/robcowie/virtualenvwrapper.github
|
||||
|
||||
They talk about PyGithub
|
||||
========================
|
||||
|
||||
* http://stackoverflow.com/questions/10625190/most-suitable-python-library-for-github-api-v3
|
||||
* http://stackoverflow.com/questions/12379637/django-social-auth-github-authentication
|
||||
* http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/py-pygithub/
|
||||
* http://oddshocks.com/blog/2012/08/02/developing-charsheet/
|
||||
* https://bugzilla.redhat.com/show_bug.cgi?id=910565
|
||||
|
||||
@@ -1,2 +1,3 @@
|
||||
/build/
|
||||
github_objects.rst
|
||||
contributing.rst
|
||||
|
||||
+1
-1
@@ -3,7 +3,7 @@ APIs
|
||||
|
||||
* ``/authorizations``
|
||||
|
||||
* GET: :func:`github.AuthenticatedUser.AuthenticatedUser.get_authorizations`
|
||||
* GET: :meth:`github.AuthenticatedUser.AuthenticatedUser.get_authorizations`
|
||||
* POST: :meth:`github.AuthenticatedUser.AuthenticatedUser.create_authorization`
|
||||
|
||||
* ``/authorizations/:id``
|
||||
|
||||
+8
-8
@@ -13,23 +13,23 @@ Stable versions
|
||||
--------------------------------------------------------------------------------------------------------------
|
||||
|
||||
* Fix bug in PaginatedList without url parameters. Thank you `llimllib <https://github.com/llimllib>`_ for the `contribution <https://github.com/jacquev6/PyGithub/pull/133>`_
|
||||
* `Implement <https://github.com/jacquev6/PyGithub/issues/130>`_ `NamedUser.get_keys`
|
||||
* `Support PubSubHub <https://github.com/jacquev6/PyGithub/issues/129>`_: `Repository.subscribe_to_hub` and `Repository.unsubscribe_from_hub`
|
||||
* `Publish the oauth scopes <https://github.com/jacquev6/PyGithub/issues/134>`_ in Github.oauth_scopes, thank you `bilderbuchi <https://github.com/bilderbuchi>`_ for asking
|
||||
* `Implement <https://github.com/jacquev6/PyGithub/issues/130>`_ :meth:`github.NamedUser.NamedUser.get_keys`
|
||||
* `Support PubSubHub <https://github.com/jacquev6/PyGithub/issues/129>`_: :meth:`github.Repository.Repository.subscribe_to_hub` and :meth:`github.Repository.Repository.unsubscribe_from_hub`
|
||||
* `Publish the oauth scopes <https://github.com/jacquev6/PyGithub/issues/134>`_ in :attr:`github.Github.Github.oauth_scopes`, thank you `bilderbuchi <https://github.com/bilderbuchi>`_ for asking
|
||||
|
||||
`Version 1.10.0 <https://github.com/jacquev6/PyGithub/issues?milestone=16&state=closed>`_ (December 25th, 2012) (Christmas 2012 edition)
|
||||
----------------------------------------------------------------------------------------------------------------------------------------
|
||||
|
||||
* Major improvement: support Python 3! PyGithub is automaticaly tested on `Travis <http://travis-ci.org/jacquev6/PyGithub>`_ with versions 2.5, 2.6, 2.7, 3.1 and 3.2 of Python
|
||||
* Add a shortcut function 'Github.get_repo' to get a repo directly from its full name. thank you `lwc <https://github.com/lwc>`_ for the contribution
|
||||
* 'Github.get_gitignore_templates' and 'Github.get_gitignore_template' for APIs '/gitignore/templates'
|
||||
* Add the optional 'ref' parameter to 'Repository.get_contents' and 'get_readme'. Thank you `fixxxeruk <https://github.com/fixxxeruk>`_ for the contribution
|
||||
* Get comments for all issues and all pull requests on a repository ('GET /repos/:user/:repo/pulls/comments': 'Repository.get_pulls_comments' or 'Repository.get_pulls_review_comments'; 'GET /repos/:user/:repo/issues/comments': 'Repository.get_issues_comments')
|
||||
* Add a shortcut function :meth:`github.Github.Github.get_repo` to get a repo directly from its full name. thank you `lwc <https://github.com/lwc>`_ for the contribution
|
||||
* :meth:`github.Github.Github.get_gitignore_templates` and :meth:`github.Github.Github.get_gitignore_template` for APIs ``/gitignore/templates``
|
||||
* Add the optional ``ref`` parameter to :meth:`github.Repository.Repository.get_contents` and :meth:`github.Repository.Repository.get_readme`. Thank you `fixxxeruk <https://github.com/fixxxeruk>`_ for the contribution
|
||||
* Get comments for all issues and all pull requests on a repository (``GET /repos/:user/:repo/pulls/comments``: :meth:`github.Repository.Repository.get_pulls_comments` or :meth:`github.Repository.Repository.get_pulls_review_comments`; ``GET /repos/:user/:repo/issues/comments``: :meth:`github.Repository.Repository.get_issues_comments`)
|
||||
|
||||
`Version 1.9.1 <https://github.com/jacquev6/PyGithub/issues?milestone-17&state-closed>`_ (November 20th, 2012)
|
||||
--------------------------------------------------------------------------------------------------------------
|
||||
|
||||
* Fix an assertion failure when integers returned by Github do not fit in a Python `int`
|
||||
* Fix an assertion failure when integers returned by Github do not fit in a Python ``int``
|
||||
|
||||
`Version 1.9.0 <https://github.com/jacquev6/PyGithub/issues?milestone-14&state-closed>`_ (November 19th, 2012)
|
||||
--------------------------------------------------------------------------------------------------------------
|
||||
|
||||
+3
-1
@@ -11,7 +11,7 @@
|
||||
# All configuration values have a default; values that are commented out
|
||||
# serve to show the default.
|
||||
|
||||
import sys, os
|
||||
import sys, os, shutil
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
@@ -259,3 +259,5 @@ with open("github_objects.rst", "w") as github_objects:
|
||||
github_object.write("=" * len(obj) + "\n")
|
||||
github_object.write("\n")
|
||||
github_object.write(".. autoclass:: github." + obj + "." + obj + "()\n")
|
||||
|
||||
shutil.copyfile("../Contributing.rst", "contributing.rst")
|
||||
|
||||
@@ -7,3 +7,4 @@ PyGithub
|
||||
introduction
|
||||
reference
|
||||
changes
|
||||
contributing
|
||||
|
||||
+25
-2
@@ -15,13 +15,13 @@ First create a Github instance::
|
||||
|
||||
from github import Github
|
||||
|
||||
g = Github( "user", "password" )
|
||||
g = Github("user", "password")
|
||||
|
||||
Then play with your Github objects::
|
||||
|
||||
for repo in g.get_user().get_repos():
|
||||
print repo.name
|
||||
repo.edit( has_wiki = False )
|
||||
repo.edit(has_wiki=False)
|
||||
|
||||
Download and install
|
||||
--------------------
|
||||
@@ -42,3 +42,26 @@ What next?
|
||||
You need to use a Github API and wonder which class implements it? `Reference of APIs <todo internal link>`_
|
||||
|
||||
You want all the details about PyGithub classes? `Reference of classes <todo internal link>`_
|
||||
|
||||
Projects using PyGithub
|
||||
-----------------------
|
||||
|
||||
(`Open an issue <https://github.com/jacquev6/PyGithub/issues>`_ if you want to be listed here, I'll be glad to add your project)
|
||||
|
||||
* `Upverter <https://upverter.com>`_ is a web-based schematic capture and PCB layout tool for people who design electronics. Designers can attach a Github project to an Upverter project.
|
||||
* `Notifico <http://n.tkte.ch>`_ receives messages (such as commits and issues) from services and scripts and delivers them to IRC channels. It can import/sync from Github.
|
||||
* `Tratihubis <http://pypi.python.org/pypi/tratihubis/>`_ converts Trac tickets to Github issues
|
||||
* https://github.com/CMB/cligh
|
||||
* https://github.com/natduca/quickopen uses PyGithub to automaticaly create issues
|
||||
* https://gist.github.com/3433798
|
||||
* https://github.com/zsiciarz/aquila-dsp.org
|
||||
* https://github.com/robcowie/virtualenvwrapper.github
|
||||
|
||||
They talk about PyGithub
|
||||
------------------------
|
||||
|
||||
* http://stackoverflow.com/questions/10625190/most-suitable-python-library-for-github-api-v3
|
||||
* http://stackoverflow.com/questions/12379637/django-social-auth-github-authentication
|
||||
* http://www.freebsd.org/cgi/cvsweb.cgi/ports/devel/py-pygithub/
|
||||
* http://oddshocks.com/blog/2012/08/02/developing-charsheet/
|
||||
* https://bugzilla.redhat.com/show_bug.cgi?id=910565
|
||||
|
||||
+1
-1
@@ -34,7 +34,7 @@ DEFAULT_TIMEOUT = 10
|
||||
|
||||
class Github(object):
|
||||
"""
|
||||
This class represents Githubs as returned for example by http://developer.github.com/v3/todo
|
||||
This is the main class you instanciate to access the Github API v3. Optional parameters allow different authentication methods.
|
||||
"""
|
||||
|
||||
def __init__(self, login_or_token=None, password=None, base_url=DEFAULT_BASE_URL, timeout=DEFAULT_TIMEOUT, client_id=None, client_secret=None, user_agent=None):
|
||||
|
||||
@@ -16,7 +16,6 @@
|
||||
|
||||
class InputFileContent(object):
|
||||
"""
|
||||
This class represents InputFileContents as returned for example by http://developer.github.com/v3/todo
|
||||
"""
|
||||
|
||||
def __init__(self, content):
|
||||
|
||||
@@ -16,7 +16,6 @@
|
||||
|
||||
class InputGitAuthor(object):
|
||||
"""
|
||||
This class represents InputGitAuthors as returned for example by http://developer.github.com/v3/todo
|
||||
"""
|
||||
|
||||
def __init__(self, name, email, date):
|
||||
|
||||
@@ -18,7 +18,6 @@ import github.GithubObject
|
||||
|
||||
class InputGitTreeElement(object):
|
||||
"""
|
||||
This class represents InputGitTreeElements as returned for example by http://developer.github.com/v3/todo
|
||||
"""
|
||||
|
||||
def __init__(self, path, mode, type, content=github.GithubObject.NotSet, sha=github.GithubObject.NotSet):
|
||||
|
||||
@@ -70,19 +70,19 @@ class PaginatedListBase:
|
||||
|
||||
class PaginatedList(PaginatedListBase):
|
||||
"""
|
||||
This class abstracts the `pagination of the API <http://developer.github.com/v3/todo>`_.
|
||||
This class abstracts the `pagination of the API <http://developer.github.com/v3/#pagination>`_.
|
||||
|
||||
You can simply enumerate through instances of this class:
|
||||
You can simply enumerate through instances of this class::
|
||||
|
||||
for repo in user.get_repos():
|
||||
print repo.name
|
||||
|
||||
You can also index them or take slices:
|
||||
You can also index them or take slices::
|
||||
|
||||
second_repo = user.get_repos()[1]
|
||||
first_repos = user.get_repos()[:10]
|
||||
|
||||
And if you really need it, you can explicitely access a specific page:
|
||||
And if you really need it, you can explicitely access a specific page::
|
||||
|
||||
some_repos = user.get_repos().get_page(0)
|
||||
some_other_repos = user.get_repos().get_page(3)
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
import setuptools
|
||||
import textwrap
|
||||
|
||||
version = "1.11.1",
|
||||
version = "1.11.1"
|
||||
|
||||
if __name__ == "__main__":
|
||||
setuptools.setup(
|
||||
@@ -26,26 +26,26 @@ if __name__ == "__main__":
|
||||
description="Use the full Github API v3",
|
||||
author="Vincent Jacques",
|
||||
author_email="vincent@vincent-jacques.net",
|
||||
url="http://vincent-jacques.net/PyGithub",
|
||||
url="http://jacquev6.github.com/PyGithub",
|
||||
long_description=textwrap.dedent("""\
|
||||
Tutorial
|
||||
========
|
||||
(Very short) Tutorial
|
||||
=====================
|
||||
|
||||
First create a Gihub instance::
|
||||
First create a Github instance::
|
||||
|
||||
from github import Github
|
||||
|
||||
g = Github( "user", "password" )
|
||||
g = Github("user", "password")
|
||||
|
||||
Then play with your Github objects::
|
||||
|
||||
for repo in g.get_user().get_repos():
|
||||
print repo.name
|
||||
repo.edit( has_wiki = False )
|
||||
repo.edit(has_wiki=False)
|
||||
|
||||
You can also create a Github instance with an OAuth token::
|
||||
|
||||
g = Github( token )
|
||||
g = Github(token)
|
||||
|
||||
Or without authentication::
|
||||
|
||||
@@ -54,7 +54,7 @@ if __name__ == "__main__":
|
||||
Reference documentation
|
||||
=======================
|
||||
|
||||
See http://vincent-jacques.net/PyGithub"""),
|
||||
See http://jacquev6.github.com/PyGithub"""),
|
||||
packages=[
|
||||
"github",
|
||||
"github.tests",
|
||||
|
||||
Reference in New Issue
Block a user