.. 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`_ ('tis `Hacktoberfest`__, after all)!
.. _`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:
----------------------------------------
Using decorators and function annotations, you can turn any plain old Python
class into a self-describing consumer of your favorite HTTP webservice:
.. code-block:: python
from uplink import *
# To register entities that are common to all API requests, you can
# decorate the enclosing class rather than each method separately:
@headers({"Accept": "application/vnd.github.v3.full+json"})
class GitHub(object):
@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."""
To construct a consumer instance, use the helper function :py:func:`uplink.build`:
.. code-block:: python
github = build(GitHub, base_url="https://api.github.com/")
To access the GitHub API with this instance, we simply invoke any of the methods
that we defined in the interface above. To illustrate, let's update my GitHub
profile bio:
.. code-block:: python
r = github.update_user(token, bio="Beam me up, Scotty!").execute()
*Voila*, :py:meth:`update_user` builds the request seamlessly (using the
decorators and annotations from the method's definition), and
:py:meth:`execute` sends that synchronously over the network. Furthermore,
the returned response :py:obj:`r` is simply a :py:class:`requests.Response`
(`documentation
`__):
.. code-block:: python
print(r.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
..
The Public API
--------------
.. todo::
Most of this guide is unfinished and completing it is a planned
deliverable for the ``v0.2.0`` release. At the least, this work will
necessitate adding docstrings to the classes enumerated below.
.. toctree::
:maxdepth: 3
decorators.rst
types.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