Lethosor edited this page Apr 13, 2015 · 3 revisions
Clone this wiki locally

Site.login() logs in as a registered user to a MediaWiki site. Subsequent edits made using the same Site object will be associated with the logged-in account. This facilitates reviewing edits by a script and blocking your script if it malfunctions. The account must first be created manually through the normal web interface.

There is no corresponding logout method because merely exiting the script deletes all cookies, achieving the same effect. For the same reason, you must log in again each time your script starts.

If the Site object was initialized in Site.__init__ with do_init = False, any subsequent login() call will initialize the Site object.

Associated API: API:Login


  • (optional) username (str) (default None)
  • (optional) password (str) (default: None)
    • For behavior when username or password is None, see Examples.
  • (optional) cookies (dict): Specifies custom cookies to include with the log-in request.
  • (optional) domain (str): Sends domain name for authentication; used by some MediaWiki plug-ins like Extension:LDAP Authentication.


Returns only if log-in successful.


  • LoginError: Log-in failed. Reason can be obtained as e[1]['result'] (where e is the exception object) and will be one of the API:Login errors. The most common error is "WrongPass", indicating a bad password.
  • MaximumRetriesExceeded: API call to log in failed and was retried until all retries were exhausted. This will not occur if the credentials are merely incorrect. See MaximumRetriesExceeded for possible reasons.
  • APIError: An API error occurred. Rare, usually indicates an internal server error.

The following errors can only occur if the Site object was initialized with do_init False (default is True). See Site.__init__#Errors for more information on these errors.


A simple log-in:

site.login('username', 'password')

Printing the log-in error result:

    site.login('username', 'password')
except LoginError as e:
    print e[1]['result']

Multiple Site objects can be used to log on to the same site with multiple users simultaneously:

site1 = Site('')
site2 = Site('')
site1.login('username1', 'password1')
site2.login('username2', 'password2')

If you call login() for the first time with no parameters (or passing None for username or password), it will have no effect (except to initialize the Site if Site.__init__ was called with do_init = False).

If you call login() with username and password, and later call it with no parameters (or passing None for username or password), it will re-attempt the previous log-in:

    site.login('username', 'password')
except LoginError:
    site.login() # Try again with same username and password


This method sends your password in plaintext over HTTP (HTTPS is not supported). Wi-fi traffic sniffers on an open wi-fi network will be able to intercept it, and anyone who operates a network you connect to will also be able to intercept it. For best security, you should not reuse the password used in your mwclient script with any other user or on any other site.

Also, if your script is made publicly available, e.g. as an open-source release, you should not embed your credentials in the script. Instead, read them from a configuration file which is not included with the release. The following script uses Python's built-in ConfigParser to do this:

import mwclient, ConfigParser
site = mwclient.Site('')
config = ConfigParser.RawConfigParser()'credentials.txt')
site.login(config.get('mwclient', 'username'), config.get('mwclient', 'password'))

The file credentials.txt contains:


Periodically, or if you believe your credentials may have been exposed, you should change your password. Because script passwords are rarely entered by hand, it is recommended to use a long random password, which can be readily generated with the following Python script:

import string, random
print ''.join([random.choice(string.letters + string.digits) for i in range(16)])

This page was originally imported from the old mwclient wiki at SourceForge. The imported version was dated from 14:11, 14 November 2011, and its only editor was Derrickcoetzee (@dcoetzee).