mirror of
https://github.com/khornberg/octokit.py
synced 2026-05-10 00:00:25 +03:00
Kyle Hornberg
245 lines
5.2 KiB
ReStructuredText
245 lines
5.2 KiB
ReStructuredText
========
|
|
Overview
|
|
========
|
|
|
|
.. start-badges
|
|
|
|
.. list-table::
|
|
:stub-columns: 1
|
|
|
|
* - tests
|
|
| |codeclimate| |codeclimate-tests|
|
|
* - package
|
|
- | |version| |wheel|
|
|
| |supported-versions| |supported-implementations|
|
|
* - docs
|
|
- |docs|
|
|
|
|
.. |docs| image:: http://octokitpy.readthedocs.io/en/latest/?badge=latest
|
|
:target: https://readthedocs.org/projects/octokitpy
|
|
:alt: Documentation Status
|
|
|
|
.. |codeclimate| image:: https://codeclimate.com/github/khornberg/octokit.py/badges/gpa.svg
|
|
:target: https://codeclimate.com/github/khornberg/octokit.py
|
|
:alt: CodeClimate Quality Status
|
|
|
|
.. |codeclimate-tests| image:: https://api.codeclimate.com/v1/badges/7954d60682bc6d6c15cd/test_coverage
|
|
:target: https://codeclimate.com/github/khornberg/octokit.py
|
|
:alt: Test Coverage
|
|
|
|
.. |version| image:: https://img.shields.io/pypi/v/octokitpy.svg
|
|
:alt: PyPI Package latest release
|
|
:target: https://pypi.org/project/octokitpy/
|
|
|
|
.. |wheel| image:: https://img.shields.io/pypi/wheel/octokitpy.svg
|
|
:alt: PyPI Wheel
|
|
:target: https://pypi.org/project/octokitpy/
|
|
|
|
.. |supported-versions| image:: https://img.shields.io/pypi/pyversions/octokitpy.svg
|
|
:alt: Supported versions
|
|
:target: https://pypi.org/project/octokitpy/
|
|
|
|
.. |supported-implementations| image:: https://img.shields.io/pypi/implementation/octokitpy.svg
|
|
:alt: Supported implementations
|
|
:target: https://pypi.org/project/octokitpy/
|
|
|
|
|
|
.. end-badges
|
|
|
|
Python client for GitHub API
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
*Note octokit and octokit.py were already taken in the cheese shop*
|
|
|
|
::
|
|
|
|
pip install octokitpy
|
|
|
|
Documentation
|
|
=============
|
|
|
|
https://octokitpy.readthedocs.io/en/latest/
|
|
|
|
|
|
Examples
|
|
--------
|
|
|
|
REST API::
|
|
|
|
from octokit import Octokit
|
|
repos = Octokit().repos.list_for_user(username="octokit")
|
|
for repo in repos.json:
|
|
print(repo["name"])
|
|
# Make an unauthenticated request for octokit's public repositories
|
|
|
|
Webhooks::
|
|
|
|
from octokit import webhook
|
|
webhook.verify(headers, payload, secret, events=['push'])
|
|
|
|
:code:`octokit.py` provides a function to verify `webhooks <https://developer.github.com/webhooks/>`_ sent to your application.
|
|
|
|
headers
|
|
dictionary of request headers
|
|
|
|
payload
|
|
string; payload of request
|
|
|
|
secret
|
|
string; secret provided to GitHub to sign webhook
|
|
|
|
events
|
|
list; events that you want to receive
|
|
|
|
verify_user_agent
|
|
boolean; whether or not you want to verify the user agent string of the request
|
|
|
|
return_app_id
|
|
boolean; whether or not you want to return the app id from the ping event for GitHub applications. This will only return the ``id`` if the event is the ``ping`` event. Otherwise the return value will be boolean.
|
|
|
|
|
|
Note that webhook names are available at :code:`from octokit_routes import webhook_names`
|
|
|
|
Authentication
|
|
--------------
|
|
|
|
Instantiate a client with the authentication scheme and credentials that you want to use.
|
|
|
|
basic::
|
|
|
|
octokit = Octokit(auth='basic', username='myuser', password='mypassword')
|
|
|
|
token::
|
|
|
|
response = Octokit(auth='token', token='yak').authorization.get(id=100)
|
|
|
|
app::
|
|
|
|
octokit = Octokit(auth='app', app_id='42', private_key=private_key)
|
|
|
|
app installation::
|
|
|
|
octokit = Octokit(auth='installation', app_id='42', private_key=private_key)
|
|
|
|
For applications, provide the application id either from the ping webhook or the application's page on GitHub.
|
|
The :code:`private_key` is a string of your private key provided for the application.
|
|
The :code:`app` scheme will use the application id and private key to get a token for the first installation id of the application.
|
|
|
|
API Schema/Routes/Specifications
|
|
--------------------------------
|
|
|
|
One can instantiate the ``Octokit`` with ``routes=specification`` where the ``specification`` is one of ``api.github.com``, ``ghe-2.15``, etc.
|
|
|
|
Data
|
|
----
|
|
|
|
The :code:`octokit` client based on the available `route data <https://github.com/khornberg/octokitpy-routes>`_ and `webhook data <https://github.com/khornberg/octokitpy-routes>`_
|
|
|
|
TODOs
|
|
===========
|
|
|
|
GitHub APIs
|
|
-----------
|
|
|
|
::
|
|
|
|
[-] REST (see best practices, integration tests, and errors)
|
|
|
|
[ ] GraphQL client
|
|
|
|
[x] GitHub Apps
|
|
|
|
[ ] OAuth Apps
|
|
|
|
[x] Webhooks
|
|
|
|
|
|
|
|
|
|
Tests
|
|
-----
|
|
|
|
::
|
|
|
|
[x] unit tests
|
|
|
|
[ ] integration tests - need fixtures to assert against
|
|
|
|
[x] coverage uploaded to code climate
|
|
|
|
Errors
|
|
------
|
|
|
|
::
|
|
|
|
[ ] Raise `OctokitValidationError` for param validation error
|
|
|
|
[ ] Raise `OctokitAuthenticationError` for auth error
|
|
|
|
[ ] Raise `OctokitRateLimitError` for rate limiting errors
|
|
|
|
Best Practices
|
|
--------------
|
|
|
|
::
|
|
|
|
[ ] throttling
|
|
|
|
[ ] handles rate limiting
|
|
|
|
[x] pagination
|
|
|
|
Generated Documentation
|
|
-----------------------
|
|
|
|
::
|
|
|
|
[ ] Auto generated documentation
|
|
|
|
Deployment
|
|
----------
|
|
|
|
::
|
|
|
|
[x] Deploy wheels
|
|
|
|
[ ] GitHub releases
|
|
|
|
|
|
**Check box guide**
|
|
|
|
::
|
|
|
|
[ ] Incomplete
|
|
|
|
[-] Partially completed
|
|
|
|
[x] Completed
|
|
|
|
Development
|
|
===========
|
|
|
|
To run the all tests run::
|
|
|
|
tox
|
|
|
|
Contributing
|
|
============
|
|
|
|
Pull requests are very welcome!
|
|
|
|
Please see CONTRIBUTING.md for more information.
|
|
|
|
Credits
|
|
=======
|
|
|
|
Package based on `cookiecutter-pylibrary <https://github.com/ionelmc/cookiecutter-pylibrary>`_
|
|
|
|
License
|
|
=======
|
|
|
|
MIT
|