Connecting to your site¶

Begin by importing the Site class:

>>> from mwclient import Site

Then try to connect to a site:

>>> site = mwclient.Site('test.wikipedia.org')

By default, mwclient will connect using https. If your site doesn’t support https, you need to explicitly request http like so:

>>> site = mwclient.Site(('http', 'test.wikipedia.org'))

The API endpoint location¶

The API endpoint location on a MediaWiki site depends on the configurable $wgScriptPath. Mwclient defaults to the script path ‘/w/’ used by the Wikimedia wikis. If you get a 404 Not Found or a mwclient.errors.InvalidResponse error upon connecting, your site might use a different script path. You can specify it using the path argument:

>>> site = mwclient.Site('my-awesome-wiki.org', path='/wiki/', )

Specifying a user agent¶

If you are connecting to a Wikimedia site, you should follow the Wikimedia User-Agent policy and identify your tool like so:

>>> ua = 'MyCoolTool/0.2 run by User:Xyz'
>>> site = mwclient.Site('test.wikipedia.org', clients_useragent=ua)

Note that Mwclient appends ‘ - MwClient/{version} ({url})’ to your string.

Authenticating¶

Mwclient supports several methods for authentication described below. By default it will also protect you from editing when not authenticated by raising a mwclient.errors.LoginError. If you actually do want to edit unauthenticated, just set

>>> site.force_login = False

OAuth¶

On Wikimedia wikis, the recommended authentication method is to authenticate as a owner-only consumer. Once you have obtained the consumer token (also called consumer key), the consumer secret, the access token and the access secret, you can authenticate like so:

>>> site = mwclient.Site('test.wikipedia.org',
                         consumer_token='my_consumer_token',
                         consumer_secret='my_consumer_secret',
                         access_token='my_access_token',
                         access_secret='my_access_secret')

HTTP authentication¶

If your server is configured to use HTTP authentication, you can authenticate using the httpauth parameter. For Basic HTTP authentication:

>>> site = mwclient.Site('awesome.site', httpauth=('my_username', 'my_password'))

You can also pass in any other authentication mechanism based on the requests.auth.AuthBase, such as Digest authentication:

>>> from requests.auth import HTTPDigestAuth
>>> site = mwclient.Site('awesome.site', httpauth=HTTPDigestAuth('my_username', 'my_password'))

SSL client certificate authentication¶

If your server requires a SSL client certifiate to authenticate, you can pass the client_certificate parameter:

>>> site = mwclient.Site('awesome.site', client_certificate='/path/to/client-and-key.pem')

This parameter being a proxy to requests‘ cert parameter, you can also specify a tuple (certificate, key) like:

>>> site = mwclient.Site('awesome.site', client_certificate=('client.pem', 'key.pem'))

Please note that the private key must not be encrypted.