Extend Consumer Methods to Reduce Boilerplate

[prkumar]

Fixes #151

Consumer methods are methods decorated with Uplink's HTTP method decorators,
such as @get or @post (see
here for more background).

Consumer methods can be used as decorators to minimize duplication across similar
consumer method definitions.

For example, you can define consumer method templates like so:

from uplink import Consumer, get, json

@returns.json
@json
@get
def get_json():
     """Template for GET request that consumes and produces JSON."""

class GitHub(Consumer):
    @get_json("/users/{user}")
    def get_user(self, user):
        """Fetches a specific GitHub user."""

Further, you can use this technique to remove duplication across definitions
of similar consumer methods, whether or not the methods are defined in the same
class:

from uplink import Consumer, get, params, timeout

class GitHub(Consumer):
    @timeout(10)
    @get("/users/{user}/repos")
    def get_user_repos(self, user):
        """Retrieves the repos that the user owns."""

    # Extends the above method to define a variant:
    @params(type="member")
    @get_user_repos
    def get_team_repos_for_user(self, user):
        """
        Retrieves the repos that are owned by teams
        that the user holds membership in.
        """

class EnhancedGitHub(Github):
    # Updates the return type of an inherited method.
    @GitHub.get_user_repos
    def get_user_repos(self, user) -> List[Repo]:
        """Retrieves the repos that the user owns."""

CC: @liiight

[codecov]

Codecov Report

Merging #159 into master will not change coverage.
The diff coverage is 100%.

@@          Coverage Diff          @@
##           master   #159   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          41     41           
  Lines        2149   2164   +15     
  Branches      172    173    +1     
=====================================
+ Hits         2149   2164   +15

Impacted Files	Coverage Δ
uplink/decorators.py	100% <100%> (ø)	⬆️
uplink/commands.py	100% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0d29483...527e8e4. Read the comment docs.

[prkumar]

TODO: Found an issue when this is used in conjunction with @returns.* decorators:

    from uplink import Consumer, get, json, returns

    @returns.json
    @json
    @get
    def get_json():
        """Template for GET request that consumes and produces JSON."""

    class GitHub(Consumer):
        @get_json("/users/{user}")
        def get_user(self, user):
             """Fetches a specific GitHub user."""

Get the following traceback:

Traceback (most recent call last):
  File "/Users/prkumar/Library/Preferences/PyCharm2018.3/scratches/scratch_12.py", line 17, in <module>
    print(github.get_user("prkumar"))
  File "/Users/prkumar/Developer/uplink/uplink/builder.py", line 99, in __call__
    self._request_definition.define_request(request_builder, args, kwargs)
  File "/Users/prkumar/Developer/uplink/uplink/commands.py", line 326, in define_request
    self._method_handler.handle_builder(request_builder)
  File "/Users/prkumar/Developer/uplink/uplink/decorators.py", line 62, in handle_builder
    annotation.modify_request(request_builder)
  File "/Users/prkumar/Developer/uplink/uplink/returns.py", line 61, in modify_request
    if not return_type.is_applicable(self):
AttributeError: 'NoneType' object has no attribute 'is_applicable'