A Declarative HTTP Client for Python.
Uplink
|PyPI Version| |Build Status| |Coverage Status| |Code Climate| |Documentation Status| |GitHub Discussions| |Gitter| |Code Style|
Retrofit <http://square.github.io/retrofit/>
__.Uplink turns your HTTP API into a Python class.
.. code-block:: python
from uplink import Consumer, get, Path, Query
class GitHub(Consumer): """A Python Client for the GitHub API."""
@get("users/{user}/repos")
def get_repos(self, user: Path, sort_by: Query("sort")):
"""Retrieves the user's public repositories."""
Build an instance to interact with the webservice.
.. code-block:: python
github = GitHub(base_url="https://api.github.com/")
Then, executing an HTTP request is as simply as invoking a method.
.. code-block:: python
repos = github.get_repos(user="octocat", sort_by="created")
The returned object is a friendly |requests.Response|_:
.. |requests.Response| replace:: requests.Response
.. _requests.Response: http://docs.python-requests.org/en/master/api/#requests.Response
.. code-block:: python
print(repos.json())
For sending non-blocking requests, Uplink comes with support for |aiohttp and twisted|_.
.. |aiohttp and twisted| replace:: aiohttp
and twisted
.. _aiohttp and twisted
: https://github.com/prkumar/uplink/tree/master/examples/async-requests
Ready to launch your first API client with Uplink? Start with this quick tutorial
_!
Quickly Define Structured API Clients
Bring Your Own HTTP Library
Non-blocking I/O support
_ for Aiohttp and TwistedSupply your own session
_ (e.g., requests.Session
) for greater controlEasy and Transparent Deserialization/Serialization
custom converters
_ for your own objectshandling collections
_ (e.g., list of Users)Extendable
protobuf support
_)custom response and error handling
_ functions as middlewareAuthentication
Basic Authentication
_Uplink officially supports Python 2.7 and 3.5+.
Note: Python 2.7 suport will be removed in v0.10.0.
.. |marshmallow| replace:: marshmallow
.. |pydantic| replace:: pydantic
.. |requests-oauthlib| replace:: requests-oauthlib
.. _Non-blocking I/O support
: https://github.com/prkumar/uplink/tree/master/examples/async-requests
.. _Supply your own session
: https://uplink.readthedocs.io/en/latest/user/clients.html#swapping-out-the-default-http-session
.. _marshmallow
: https://github.com/prkumar/uplink/tree/master/examples/marshmallow
.. _custom converters
: https://uplink.readthedocs.io/en/latest/user/serialization.html#custom-json-deserialization
.. _handling collections
: https://uplink.readthedocs.io/en/latest/user/serialization.html#converting-collections
.. _custom response and error handling
: https://uplink.readthedocs.io/en/latest/user/quickstart.html#response-and-error-handling
.. _protobuf support
: https://github.com/prkumar/uplink-protobuf
.. _requests-oauthlib
: https://github.com/requests/requests-oauthlib
.. _Basic Authentication
: https://uplink.readthedocs.io/en/latest/user/auth.html#basic-authentication
.. _pydantic
: https://pydantic-docs.helpmanual.io/
To install the latest stable release, you can use pip
(or pipenv
):
::
$ pip install -U uplink
If you are interested in the cutting-edge, preview the upcoming release with:
::
$ pip install https://github.com/prkumar/uplink/archive/master.zip
Further, uplink has optional integrations and features. You can view a full list
of available extras here <https://uplink.readthedocs.io/en/latest/user/install.html#extras>
_.
When installing Uplink with pip
, you can select extras using the format:
::
$ pip install -U uplink[extra1, extra2, ..., extraN]
For instance, to install aiohttp
and marshmallow
support:
::
$ pip install -U uplink[aiohttp, marshmallow]
Michael Kennedy (@mkennedy
), host of Talk Python
and Python Bytes
_ podcasts-
Of course our first reaction when consuming HTTP resources in Python is to
reach for Requests. But for *structured* APIs, we often want more than ad-hoc
calls to Requests. We want a client-side API for our apps. Uplink is
the quickest and simplest way to build just that client-side API.
Highly recommended.
.. _@mkennedy: https://twitter.com/mkennedy
.. _Talk Python
: https://twitter.com/TalkPython
.. _Python Bytes
: https://twitter.com/pythonbytes
Or Carmi (@liiight
), notifiers maintainer-
Uplink's intelligent usage of decorators and typing leverages the most
pythonic features in an elegant and dynamic way. If you need to create an
API abstraction layer, there is really no reason to look elsewhere.
.. _@liiight: https://github.com/liiight .. _notifiers: https://github.com/notifiers/notifiers
Check out the library's documentation at https://uplink.readthedocs.io/.
For new users, a good place to start is this quick tutorial
_.
Use the Discussions
_ tab on GitHub to join the conversation! Ask questions, provide feedback,
and meet other users!
We're migrating our community from Gitter
_ to GitHub Discussions
_. Feel free to search our
Gitter lobby for past questions and answers. However, to help us transition, please start new
threads/posts in GitHub Discussions instead of Gitter.
.. _Discussions: https://github.com/prkumar/uplink/discussions .. _Gitter: https://gitter.im/python-uplink/Lobby
Want to report a bug, request a feature, or contribute code to Uplink?
Checkout the Contribution Guide
_ for where to start.
Thank you for taking the time to improve an open source project :purple_heart:
.. |GitHub Discussions| image:: https://img.shields.io/github/discussions/prkumar/uplink.png :target: https://github.com/prkumar/uplink/discussions .. |Build Status| image:: https://travis-ci.com/prkumar/uplink.svg?branch=master :target: https://travis-ci.com/prkumar/uplink .. |Code Climate| image:: https://api.codeclimate.com/v1/badges/d5c5666134763ff1d6c0/maintainability :target: https://codeclimate.com/github/prkumar/uplink/maintainability :alt: Maintainability .. |Code Style| image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/ambv/black :alt: Code style: black .. |Coverage Status| image:: https://img.shields.io/codecov/c/github/prkumar/uplink.svg :alt: Codecov :target: https://codecov.io/gh/prkumar/uplink .. |Documentation Status| image:: https://readthedocs.org/projects/uplink/badge/?version=latest :target: http://uplink.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status .. |Gitter| image:: https://badges.gitter.im/python-uplink/Lobby.svg :target: https://gitter.im/python-uplink/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge :alt: Join the chat at https://gitter.im/python-uplink/Lobby .. |License| image:: https://img.shields.io/github/license/prkumar/uplink.svg :target: https://github.com/prkumar/uplink/blob/master/LICENSE .. |PyPI Version| image:: https://img.shields.io/pypi/v/uplink.svg :target: https://pypi.python.org/pypi/uplink
.. _Contribution Guide
: https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.rst
.. _quick tutorial
: https://uplink.readthedocs.io/en/latest/user/quickstart.html