Merge pull request #54 from prkumar/master

Release v0.3.0

.coveragerc

@@ -12,6 +12,7 @@ omit =
     uplink/__about__.py
     uplink/interfaces.py
     uplink/clients/interfaces.py
+    uplink/converters/interfaces.py
 
 [report]
 # When running a summary report, show missing lines.

.travis.yml

@@ -12,7 +12,7 @@ before_script:
 script:
   - tox -e py
 after_success:
-  - pip install python-coveralls
+  - pip install coveralls
   - coveralls
 deploy:
   provider: pypi

AUTHORS.rst

@@ -5,3 +5,5 @@ Maintainers
 Contributors
 ************
 - Kareem Moussa (`@itstehkman <https://github.com/itstehkman>`_)
+- Brandon Milton (`@brandonio21 <https://github.com/brandonio21>`_)
+- Fabio Rosado (`@fabiorosado <https://github.com/fabiorosado>`_)

CHANGELOG.rst

@@ -6,12 +6,34 @@ All notable changes to this project will be documented in this file.
 The format is based on `Keep a Changelog`_, and this project adheres to the
 `Semantic Versioning`_ scheme.
 
+0.3.0_ - 2018-1-09
+==================
+Added
+-----
+- HTTP HEAD request decorator by `@brandonio21`_
+- Support for returning deserialized response objects using ``marshmallow``
+  schemas.
+- Constructor parameter for ``uplink.Query`` and ``uplink.QueryMap`` to
+  support already encoded URL parameters
+- Support for using ``requests.Session`` and ``aiohttp.ClientSession``
+  instances with the ``client`` parameter of the ``uplink.Consumer`` constructor.
+
+Changed
+-------
+- ``aiohttp`` and ``twisted`` are now optional dependencies/extras.
+
+Fixed
+-----
+- Fix issue with calling a request method with ``super``.
+- Fix issue where method decorators would incorrectly decorate inherited
+  request methods.
+
 0.2.2_ - 2017-11-23
 ===================
 Fixed
 -----
 - Fix error raised when an object that is not a class is passed into the 
-  ``client`` parameter of the ``Consumer`` constructor.
+  ``client`` parameter of the ``Consumer`` constructor, by `@kadrach`_.
 
 0.2.0_ - 2017-11-03
 ===================
@@ -66,10 +88,17 @@ Added
 - README that contains GitHub API v3 example, installation instructions with
   ``pip``, and link to online documentation.
 
+.. General Links
 .. _Retrofit: http://square.github.io/retrofit/
 .. _`Keep a Changelog`: http://keepachangelog.com/en/1.0.0/
 .. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred
 
+.. Releases
+.. _0.3.0: https://github.com/prkumar/uplink/compare/v0.2.2...v0.3.0
 .. _0.2.2: https://github.com/prkumar/uplink/compare/v0.2.0...v0.2.2
 .. _0.2.0: https://github.com/prkumar/uplink/compare/v0.1.1...v0.2.0
 .. _0.1.1: https://github.com/prkumar/uplink/compare/v0.1.0...v0.1.1
+
+.. Contributors
+.. _@brandonio21: https://github.com/brandonio21
+.. _@kadrach: https://github.com/kadrach

CONTRIBUTING.rst

@@ -87,7 +87,8 @@ feature branch, which contains work for the next or some distant
 release. To start a feature branch, branch off of ``master``. Preferably,
 prefix the branch name with ``feature/`` (or ``feature/v{version}/``, where
 {version} is the feature's target release version -- e.g., ``feature/v1.0
-.0/*``) for clarity. Make your changes on this branch.
+.0/*``) for clarity. Make your changes on this branch, then when ready
+to merge, open a `pull request`_ against ``master``.
 
 Importantly, if your changes are not targeted for the next immediate
 release, keep them on the feature branch until ``master`` is bumped to

MANIFEST.in

@@ -1,2 +1,2 @@
-include README.rst CHANGELOG.rst LICENSE requirements.txt
+include AUTHORS.rst README.rst CHANGELOG.rst LICENSE requirements.txt
 recursive-include tests *.py

README.rst

@@ -1,91 +1,63 @@
 Uplink
 ******
-|PyPI Version| |Build Status| |Coverage Status| |Documentation Status|
+|PyPI Version| |Build Status| |Coverage Status| |Code Climate| |Documentation Status|
+|Gitter|
 
 - Builds Reusable Objects for Consuming Web APIs.
 - Works with Requests, asyncio, and Twisted.
-- Inspired by `Retrofit <http://square.github io/retrofit/>`__.
+- Inspired by `Retrofit <http://square.github.io/retrofit/>`__.
 
 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:
+Uplink turns your HTTP API into a Python class.
 
 .. code-block:: python
 
-    from uplink import *
+   from uplink import Consumer, get, headers, Path, Query
 
-    # 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):
+   @headers({"Accept": "application/vnd.github.v3.full+json"})
+   class GitHub(Consumer):
 
-        @get("/users/{username}")
-        def get_user(self, username):
-            """Get a single user."""
+      @get("users/{user}/repos")
+      def list_repos(self, user: Path, sort_by: Query("sort")):
+         """Get user's public repositories."""
 
-        @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 ``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 ``update_user``:
+Build an instance to interact with the webservice.
 
 .. code-block:: python
 
-    response = github.update_user(oauth_token, bio="Beam me up, Scotty!")
+   github = GitHub(base_url="https://api.github.com/")
 
-*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
-<http://docs.python-requests.org/en/master/>`_ library. So, the
-returned ``response`` is simply a ``requests.Response`` (`documentation
-<http://docs.python-requests.org/en/master/api/#requests.Response>`__):
+Then, executing an HTTP request is as simply as invoking a method.
 
 .. 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 ☺️.
+   repos = github.list_repos("octocat", sort_by="created")
 
-Asynchronous Requests
----------------------
-Uplink includes support for concurrent requests with asyncio (for Python 3.4+)
-and Twisted (for all supported Python versions).
+The returned object is a friendly |requests.Response|_:
 
-For example, let's create an instance of our GitHub API consumer that
-returns awaitable responses using ``aiohttp``:
+.. |requests.Response| replace:: ``requests.Response``
+.. _requests.Response: http://docs.python-requests.org/en/master/api/#requests.Response
 
 .. code-block:: python
 
-   github = GitHub("https://api.github.com/", client=uplink.AiohttpClient())
+   print(repos.json())
+   # Output: [{'id': 64778136, 'name': 'linguist', ...
 
-Then, given a list of GitHub ``usernames``, we can use the ``get_user`` method
-to fetch users concurrently with an ``asyncio`` event loop:
+For sending non-blocking requests, Uplink comes with support for
+|aiohttp and twisted|_.
 
-.. code-block:: python
+.. |aiohttp and twisted| replace:: ``aiohttp`` and ``twisted``
+.. _`aiohttp and twisted`: https://github.com/prkumar/uplink/tree/master/examples/async-requests
+
+Use decorators and function annotations to describe the HTTP request:
 
-   futures = map(github.get_user, usernames)
-   loop = asyncio.get_event_loop()
-   print(loop.run_until_complete(asyncio.gather(*futures)))
+* URL parameter replacement and query parameter support
+* Convert responses into Python objects (e.g., |using marshmallow|_)
+* JSON, URL-encoded, and multipart request body and file upload
 
-To learn more about Uplink's support for asynchronous requests, checkout
-the `documentation
-<http://uplink.readthedocs.io/en/latest/advanced.html#making-non-blocking-requests>`_.
-Also, `this Gist
-<https://gist.github.com/prkumar/4e905edb988bc3d3d95e680ef043f934>`_
-provides short examples for using Uplink with asyncio and Twisted.
+.. |using marshmallow| replace:: using ``marshmallow``
+.. _`using marshmallow`: https://github.com/prkumar/uplink/tree/master/examples/marshmallow
 
 Installation
 ============
@@ -95,35 +67,64 @@ To install the latest stable release, you can use ``pip``:
 
 ::
 
-    $ pip install uplink
-
+    $ 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
 
+Extra! Extra!
+-------------
+
+Further, uplink has optional integrations and features, such as
+`sending non-blocking requests with <examples/async-requests>`__
+``aiohttp`` and `deserializing JSON responses using <examples/marshmallow>`__
+``marshmallow``. You can view a full list of available extras `here
+<http://uplink.readthedocs.io/en/latest/install.html#extras>`_.
+
+When installing Uplink with ``pip``, you can specify any of number of 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]
+
+
 Documentation
 =============
-For more details, check out the documentation at http://uplink.readthedocs.io/.
+For more details, check out the documentation at https://uplink.readthedocs.io/.
 
 Contributing
 ============
 Want to report a bug, request a feature, or contribute code to Uplink?
-Checkout the `Contribution Guide <CONTRIBUTING.rst>`_ for where to start.
+Checkout the `Contribution Guide`_ for where to start.
 Thank you for taking the time to improve an open source project 💜
 
 .. |Build Status| image:: https://travis-ci.org/prkumar/uplink.svg?branch=master
    :target: https://travis-ci.org/prkumar/uplink
-.. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master
+.. |Code Climate| image:: https://img.shields.io/codeclimate/maintainability/prkumar/uplink.svg
+   :target: https://codeclimate.com/github/prkumar/uplink/maintainability
+   :alt: Maintainability
+.. |Coverage Status| image:: https://coveralls.io/repos/github/prkumar/uplink/badge.svg?branch=master&service=github
    :target: https://coveralls.io/github/prkumar/uplink?branch=master
 .. |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
-.. |Python Version| image:: https://img.shields.io/pypi/pyversions/uplink.svg
-   :target: https://pypi.python.org/pypi/uplink
+
+.. _`Contribution Guide`: https://github.com/prkumar/uplink/blob/master/CONTRIBUTING.rst

docs/source/clients.rst

@@ -0,0 +1,25 @@
+HTTP Clients
+************
+
+The ``client`` parameter of the :py:class:`Consumer` constructor offers a way
+to swap out Requests with another HTTP client, including those listed here:
+
+.. code-block:: python
+
+    github = GitHub(BASE_URL, client=...)
+
+
+Requests
+========
+
+.. autoclass:: uplink.RequestsClient
+
+Aiohttp
+=======
+
+.. autoclass:: uplink.AiohttpClient
+
+Twisted
+=======
+
+.. autoclass:: uplink.TwistedClient

docs/source/conf.py

@@ -101,10 +101,12 @@
     "description": "A Declarative HTTP Client for Python, inspired by Retrofit.",
     "github_user": "prkumar",
     "github_repo": "uplink",
-    "github_button": "false",
+    "github_button": "true",
     "github_banner": "true",
     "travis_button": "true",
-    "show_powered_by": "false"
+    "show_powered_by": "false",
+    "fixed_sidebar": "true",
+    "github_type": "star"
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -184,8 +186,11 @@
      'Miscellaneous'),
 ]
 
-
-
-
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/', None),
+    'requests': ('http://docs.python-requests.org/en/master/', None),
+    'aiohttp': ('https://aiohttp.readthedocs.io/en/stable/', None),
+    'marshmallow': ('https://marshmallow.readthedocs.io/en/latest/', None),
+    'twisted': ('http://twistedmatrix.com/documents/current/api/', None)
+}

docs/source/converters.rst

@@ -0,0 +1,14 @@
+Converters
+**********
+
+The ``converter`` parameter of the :py:class:`uplink.Consumer` constructor
+accepts an adapter class that handles deserialization of HTTP response objects:
+
+.. code-block:: python
+
+    github = GitHub(BASE_URL, converter=...)
+
+Marshmallow
+===========
+
+.. autoclass:: uplink.MarshmallowConverter