Merge pull request #163 from prkumar/master

Release v0.9.0

Author: prkumar

.travis.yml

@@ -1,21 +1,13 @@
 language: python
 python:
   - '2.7'
-  - '3.3'
   - '3.4'
   - '3.5'
   - '3.6'
   - '3.6-dev'
   - '3.7-dev'
 before_script:
-  - |
-    if [[ $TRAVIS_PYTHON_VERSION == 3.3 ]]; then
-      # virtualenv 16.0.0 bundles wheel 0.31.1, which drops python 3.3.* support
-      # tox 3.0.0 drops python 3.3.* support
-      pip install virtualenv==15.2.0 tox==2.9.1
-    else
-      pip install tox
-    fi
+  - pip install tox
   - if [[ $TRAVIS_PYTHON_VERSION == 3.6 ]]; then pip install flake8 flake8-bugbear; fi
 script:
   - tox -e py

AUTHORS.rst

@@ -14,3 +14,4 @@ Contributors
 - Nils Philippsen (`@nphilipp <https://github.com/nphilipp>`_)
 - Alexander Duryagin (`@daa <https://github.com/daa>`_)
 - Sakorn Waungwiwatsin (`@SakornW <https://github.com/SakornW>`_)
+- Jacob Floyd (`@cognifloyd <https://github.com/cognifloyd>`_)

CHANGELOG.rst

@@ -6,6 +6,31 @@ 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.9.0_ - 2019-06-05
+===================
+Added
+-----
+- Create consumer method templates to reduce boilerplate in request
+  definitions. (`#151`_, `#159`_)
+- ``Context`` argument annotation to pass request-specific information to
+  middleware. (`#143`_, `#155`_)
+- ``Session.context`` property to pass session-specific information to
+  middleware. (`#143`_, `#155`_)
+- Built-in authentication support for API tokens in the querystring
+  and header, Bearer tokens, and multi-auth. (`#137`_)
+
+Fixed
+-----
+- Schema defined using ``@returns.*`` decorators should override the
+  consumer method's return annotation. (`#144`_, `#154`_)
+- ``@returns.*`` decorators should propagate to all consumer method when used
+  as a class decorator. (`#145`_, `#154`_)
+- Decorating a ``Consumer`` subclass no longer affects other subclasses. (`#152`_)
+
+Changed
+-------
+- Renamed ``uplink.retry.stop.DISABLE`` to ``uplink.retry.stop.NEVER``
+
 0.8.0_ - 2019-02-16
 ===================
 Added
@@ -269,6 +294,7 @@ Added
 .. _`Semantic Versioning`: https://packaging.python.org/tutorials/distributing-packages/#semantic-versioning-preferred
 
 .. Releases
+.. _0.9.0: https://github.com/prkumar/uplink/compare/v0.8.0...v0.9.0
 .. _0.8.0: https://github.com/prkumar/uplink/compare/v0.7.0...v0.8.0
 .. _0.7.0: https://github.com/prkumar/uplink/compare/v0.6.1...v0.7.0
 .. _0.6.1: https://github.com/prkumar/uplink/compare/v0.6.0...v0.6.1
@@ -286,11 +312,20 @@ Added
 .. _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
 
-.. Pull Requests
+.. Issues & Pull Requests
 .. _#132: https://github.com/prkumar/uplink/pull/132
 .. _#133: https://github.com/prkumar/uplink/pull/133
 .. _#134: https://github.com/prkumar/uplink/pull/134
+.. _#137: https://github.com/prkumar/uplink/pull/137
 .. _#138: https://github.com/prkumar/uplink/pull/138
+.. _#143: https://github.com/prkumar/uplink/issues/143
+.. _#144: https://github.com/prkumar/uplink/issues/144
+.. _#145: https://github.com/prkumar/uplink/issues/145
+.. _#151: https://github.com/prkumar/uplink/issues/151
+.. _#152: https://github.com/prkumar/uplink/pull/152
+.. _#154: https://github.com/prkumar/uplink/pull/154
+.. _#155: https://github.com/prkumar/uplink/pull/155
+.. _#159: https://github.com/prkumar/uplink/pull/159
 
 .. Contributors
 .. _@daa: https://github.com/daa

README.rst

@@ -13,14 +13,15 @@ Uplink turns your HTTP API into a Python class.
 
 .. code-block:: python
 
-   from uplink import Consumer, get, headers, Path, Query
+   from uplink import Consumer, get, Path, Query
+
 
    class GitHub(Consumer):
-      """A Python Client for the GitHub API."""
+       """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."""
+       @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.
 
@@ -157,11 +158,24 @@ User Testimonials
 
 Documentation
 =============
-For more details, check out the documentation at
-https://uplink.readthedocs.io/.
+
+Check out the library's documentation at https://uplink.readthedocs.io/.
+
+For new users, a good place to start is this `quick tutorial`_.
+
+
+Community
+=========
+
+Join the conversation on `Gitter`_ to ask questions, provide feedback,
+and meet other users!
+
+.. _Gitter: https://gitter.im/python-uplink/Lobby
+
 
 Contributing
 ============
+
 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:

docs/source/dev/auth.rst

@@ -0,0 +1,44 @@
+.. _auth_methods:
+
+Auth Methods
+************
+
+
+The ``auth`` parameter of the :py:class:`Consumer` constructor offers a way
+to define an auth method to use for all requests.
+
+.. code-block:: python
+
+    auth_method = SomeAuthMethod(...)
+    github = GitHub(BASE_URL, auth=auth_method)
+
+
+BasicAuth
+=========
+
+.. autoclass:: uplink.auth.BasicAuth
+
+ProxyAuth
+=========
+
+.. autoclass:: uplink.auth.ProxyAuth
+
+BearerToken
+===========
+
+.. autoclass:: uplink.auth.BearerToken
+
+MultiAuth
+=========
+
+.. autoclass:: uplink.auth.MultiAuth
+
+ApiTokenParam
+=============
+
+.. autoclass:: uplink.auth.ApiTokenParam
+
+ApiTokenHeader
+==============
+
+.. autoclass:: uplink.auth.ApiTokenHeader

docs/source/dev/decorators.rst

@@ -188,9 +188,13 @@ Use the ``|`` operator to logically combine strategies:
 .. automodule:: uplink.retry.stop
     :members:
 
+.. autodata:: uplink.retry.stop.NEVER
+   :annotation:
+
 ratelimit
 =========
 
 .. autoclass:: uplink.ratelimit
 
+
 .. autoclass:: uplink.ratelimit.RateLimitExceeded

docs/source/dev/index.rst

@@ -10,4 +10,5 @@ This guide details the classes and methods in Uplink's public API.
    decorators.rst
    types.rst
    clients.rst
-   converters.rst
+   converters.rst
+   auth.rst

docs/source/dev/types.rst

@@ -67,3 +67,8 @@ Timeout
 =======
 
 .. autoclass:: uplink.Timeout
+
+Context
+=======
+
+.. autoclass:: uplink.Context

docs/source/index.rst

@@ -22,14 +22,15 @@ Uplink turns your HTTP API into a Python class.
 
 .. code-block:: python
 
-   from uplink import Consumer, get, headers, Path, Query
+   from uplink import Consumer, get, Path, Query
+
 
    class GitHub(Consumer):
-      """A Python Client for the GitHub API."""
+       """A Python Client for the GitHub API."""
 
-      @get("users/{user}/repos")
-      def get_repos(self, user: Path, sort_by: Query("sort")):
-         """Get user's public repositories."""
+       @get("users/{user}/repos")
+       def get_repos(self, user: Path, sort_by: Query("sort")):
+          """Get user's public repositories."""
 
 Build an instance to interact with the webservice.
 

docs/source/user/auth.rst

@@ -3,21 +3,50 @@ Authentication
 
 This section covers how to do authentication with Uplink.
 
+In v0.4, we added the :py:attr:`auth` parameter to the
+:py:class:`uplink.Consumer` constructor which allowed for
+sending HTTP Basic Authentication with all requests.
+
+In v0.9, we added more auth methods which can be used in the
+:py:attr:`auth` parameter of the :py:class:`uplink.Consumer`
+constructor. If you are using an uplink-based API library,
+the library might extend these methods with additional
+API-specific auth methods.
+
+Some common auth methods are described below, but for a
+complete list of auth methods provided with Uplink, see
+the :ref:`auth_methods` reference.
+
 .. _basic_authentication:
 
 Basic Authentication
 --------------------
 
-In v0.4, we added the :py:attr:`auth` parameter to the
-:py:class:`uplink.Consumer` constructor.
-
-Now it's simple to construct a consumer that uses HTTP Basic
+It's simple to construct a consumer that uses HTTP Basic
 Authentication with all requests:
 
 .. code-block:: python
 
     github = GitHub(BASE_URL, auth=("user", "pass"))
 
+Proxy Authentication
+--------------------
+
+If you need to supply credentials for an intermediate proxy
+in addition to the API's HTTP Basic Authentication, use
+:py:class:`uplink.auth.MultiAuth` with :py:class:`uplink.auth.ProxyAuth`
+and :py:class:`uplink.auth.BasicAuth`.
+
+.. code-block:: python
+
+    from uplink.auth import BasicAuth, MultiAuth, ProxyAuth
+
+    auth_methods = MultiAuth(
+        ProxyAuth("proxy_user", "proxy_pass"),
+        BasicAuth("user", "pass")
+    )
+    github = GitHub(BASE_URL, auth=auth_methods)
+
 Other Authentication
 --------------------
 
@@ -39,10 +68,31 @@ through the consumer's :obj:`session <uplink.Consumer.session>` property:
 
     class GitHub(Consumer):
 
-        def __init__(self, access_token):
+        def __init__(self, base_url, access_token):
+            super(GitHub, self).__init__(base_url=base_url)
             self.session.params["access_token"] = access_token
             ...
 
+As of v0.9, you can also supply these tokens via the :py:attr:`auth`
+parameter of the :py:class:`uplink.Consumer` constructor. This is
+like adding the token to the session (above) so that the token is
+sent as part of every request.
+
+.. code-block:: python
+
+    from uplink.auth import ApiTokenParam, ApiTokenHeader, BearerToken
+
+    # Passing an auth token as a query parameter
+    token_auth = ApiTokenParam("access_token", access_token)
+    github = GitHub(BASE_URL, auth=token_auth)
+
+    # Passing the token as a header value
+    token_auth = ApiTokenHeader("Access-Token", access_token)
+    github = GitHub(BASE_URL, auth=token_auth)
+
+    # Passing a Bearer auth token
+    bearer_auth = BearerToken(access_token)
+    github = GitHub(BASE_URL, auth=bearer_auth)
 
 Using Auth Support for Requests and aiohttp
 -------------------------------------------