.. Uplink documentation master file, created by
sphinx-quickstart on Sun Sep 24 19:40:30 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Uplink 📡
*********
A Declarative HTTP Client for Python. Inspired by `Retrofit
`__.
|Release| |Python Version| |License| |Coverage Status|
.. note::
Uplink is currently in initial development and, therefore, not
production ready at the moment. Furthermore, as the package follows a
`semantic versioning `__
scheme, the public API outlined in this documentation should be
considered tentative until the :code:`v1.0.0` release.
However, while Uplink is under construction, we invite eager users
to install early and provide open feedback, which can be as simple as
opening a GitHub issue when you notice a missing feature, latent defect,
documentation oversight, etc.
Moreover, for those interested in contributing, checkout the `Contribution
Guide on GitHub`_!
.. _`Contribution Guide on GitHub`: https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.rst
.. _Hacktoberfest: https://hacktoberfest.digitalocean.com/
A Quick Walkthrough, with GitHub API v3:
========================================
Turn a Python class into a self-describing consumer of your favorite HTTP
webservice, using method decorators and function annotations:
.. code-block:: python
from uplink import *
# To define common request metadata, you can decorate the class
# rather than each method separately.
@headers({"Accept": "application/vnd.github.v3.full+json"})
class GitHub(Consumer):
@get("/users/{username}")
def get_user(self, username):
"""Get a single user."""
@json
@patch("/user")
def update_user(self, access_token: Query, **info: Body):
"""Update an authenticated user."""
Let's build an instance of this GitHub API consumer for the main site!
(Notice that I can use this same consumer class to also access any
GitHub Enterprise instance by simply changing the :py:attr:`base_url`.):
.. code-block:: python
github = GitHub(base_url="https://api.github.com/")
To access the GitHub API with this instance, we can invoke any of the
methods that we defined in our class definition above. To illustrate,
let's update my GitHub profile bio with :py:meth:`update_user`:
.. code-block:: python
response = github.update_user(token, bio="Beam me up, Scotty!")
*Voila*, the method seamlessly builds the request (using the decorators
and annotations from the method's definition) and executes it in the same call.
And, by default, Uplink uses the powerful `Requests
`_ library. So, the returned
:py:obj:`response` is simply a :py:class:`requests.Response` (`documentation
`__):
.. code-block:: python
print(response.json()) # {u'disk_usage': 216141, u'private_gists': 0, ...
In essence, Uplink delivers reusable and self-sufficient objects for
accessing HTTP webservices, with minimal code and user pain ☺️ .
The User Manual
===============
Follow this guide to get up and running with Uplink.
.. toctree::
:maxdepth: 2
install.rst
introduction.rst
getting_started.rst
advanced.rst
..
The Public API
==============
.. todo::
Most of this guide is unfinished and completing it is a planned
deliverable for the ``v0.3.0`` release. At the least, this work will
necessitate adding docstrings to the classes enumerated below.
.. toctree::
:maxdepth: 2
decorators.rst
types.rst
changes.rst
.. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master
:target: https://coveralls.io/github/prkumar/uplink?branch=master
.. |License| image:: https://img.shields.io/github/license/prkumar/uplink.svg
:target: https://github.com/prkumar/uplink/blob/master/LICENSE
.. |Python Version| image:: https://img.shields.io/pypi/pyversions/uplink.svg
:target: https://pypi.python.org/pypi/uplink
.. |Release| image:: https://img.shields.io/github/release/prkumar/uplink/all.svg
:target: https://github.com/prkumar/uplink