Add and expose auth types: MultiAuth ApiToken*

[cognifloyd]

This adds more auth classes designed to be used when initializing a
Consumer subclass. There are two generic AuthToken types that may
be used directly or may be subclassed by API library authors to define
the relevant query parameter or header.
There is also a MultiAuth type which allows for passing in a list of auth
methods, so that they all take effect.

The purpose of the generic AuthToken types is to make it simple for
uplink-based libraries to provide a standardized way to authenticate
with their api.

The purpose of MultiAuth is to allow for multiple auth methods. This may
be required when ProxyAuth needs to be combined with another auth
method, or when an API requires multiple auth tokens.

[prkumar]

@cognifloyd - Looks like one unit test is failing the CI build:

=================================== FAILURES ===================================
______________________________ test_bearer_token _______________________________
request_builder = <MagicMock spec='RequestBuilder' id='140036067042416'>
    def test_bearer_token(request_builder):
        # Setup
        bearer_token = auth.BearerToken("bearer-token")
    
        # Verify
        bearer_token(request_builder)
>       auth_str = bearer_token._auth_str
E       AttributeError: 'BearerToken' object has no attribute '_auth_str'
tests/unit/test_auth.py:51: AttributeError

Thanks for contributing, by the way!

[cognifloyd]

@prkumar Yeah. I haven't looked at the tests yet. I will do that hopefully this week.

Conceptually, are you okay with the direction of this PR? eg I'm exporting the auth classes in __all__ now.

[prkumar]

Overall, this looks good. I think ApiTokenParam and ApiTokenHeader are great additions to the library, and we exposing the auth classes is a good move too. I just have a few suggestions, which I've added below.

[prkumar]

I haven't had experience with APIs that use a multi-auth strategy, so I'm interested to see an example: do you know of any public APIs that support this sort of authentication?

[cognifloyd]

I don't think very many (if any) APIs require multiple forms of auth on the server side.

I'm designing an API that might require multiple tokens on the server side, not just for intermediary auth, but it's a very specific use-case peculiar to our internal infrastructure. I don't know of any generally available APIs that require multiple forms of auth on the server side.

However, many clients require multiple forms of auth to, for example, authenticate to an HTTP proxy and to the API server.

[cognifloyd]

Maybe instead of subclassing, we could create some kind of auth meta class, or add a decorator that turns a class into an auth class?
Or should API libraries have some kind of factory function that their consumers would use to pass in the token?

[codecov]

Codecov Report

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

@@          Coverage Diff          @@
##           master   #137   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          41     41           
  Lines        2052   2083   +31     
  Branches      163    167    +4     
=====================================
+ Hits         2052   2083   +31

Impacted Files	Coverage Δ
uplink/auth.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 0179c2a...27803a2. Read the comment docs.

[cognifloyd]

@prkumar done including tests (codecov @ 100%).

• expanded the MultiAuth to make it act more like a list, allowing for building it in whatever way makes sense to the API library consumer.
• expanded the generic ApiTokenParam and ApiTokenHeader classes to allow using them directly ApiTokenParam(param="api_token", token="****") as well as by subclassing with class attributes. (See my comments and commit messages above).
• refactored BasicAuth and ProxyAuth to reuse the ApiTokenHeader.
• added/adjusted tests for all of the above.

What do you think? I can revert the changes to BasicAuth and ProxyAuth if you'd like (changing that made it more consistent in internal implementation details, but is otherwise unnecessary).

I can also squash my commits if you'd like.

[prkumar]

@cognifloyd - This looks great! Thanks so much for adding coverage and for extending the ApiTokenParam and ApiTokenHeader classes to be used directly, too. I'll go ahead approve the changes and merge this in ASAP.

After merging, I'll also make a separate commit to add you to the AUTHORS.rst file. Please let me know what name and/or public handle (e.g., @cognifloyd) that you'd like me to append to the file .Typically, I'd use the name and handle of your GitHub account, but I can use a different account/name if you'd prefer. For example, using your GitHub, here's what I'd add to AUTHORS.rst:

Jacob Floyd (@cognifloyd)

Alternatively, you could make a separate commit to this PR with that change. Whatever works best for you! Thanks for contributing!

[cognifloyd]

I added myself to AUTHORS.rst

[cognifloyd]

Squashed and rebased on master.