Update authentication documentation page

[AdamWill]

The info on authenticating in the docs doesn't cover clientlogin(), and - as suggested in #315 - could make it clearer that the options that allow HTTP authentication aren't alternatives for logging into mediawiki itself.

[marcfrederick]

I've created a PR (#324) trying to clarify this a bit.

---

Honestly, looking at the relevant code, the current implementation is unnecessarily complex and confusing in my opinion. We have the httpauth parameter, which supports both a requests.auth.AuthBase object and a tuple[str, str]/list[str]. Additionally, we have OAuth parameters¹, which are used to initialize a requests_oauthlib.OAuth1 object.

Dropping the OAuth1 parameters would simplify the constructor and eliminate unexpected behavior when a user passes those parameters in addition to httpauth². This change would also allow us to remove the dependency on requests_oauthlib and depend directly on requests.

import mwclient
import requests_oauthlib

# Current
client = mwclient.Site(
    'en.wikipedia.org',
    consumer_token='foo',
    consumer_secret='bar',
    access_token='baz',
    access_secret='qux'
)

# Suggested
auth = requests_oauthlib.OAuth1('foo', 'bar', 'baz', 'qux')
client = mwclient.Site('en.wikipedia.org', httpauth=auth)

This would still leave some potential confusion around the difference between Site.login() and passing httpauth to the constructor, but might remove at least some complexity from the whole thing.

Footnotes

1. consumer_token, consumer_secret, access_token, and access_secret ↩

2. httpauth is silently ignored when consumer_token is not None. ↩

[AdamWill]

#332 is a follow-up to document clientlogin.

[AdamWill]

edit: nope, I was wrong, I think marc's right...