login module

Pywikibot supports several login methods to authenticate with MediaWiki-based wikis. Here is an overview of Pywikibot login methods:

Method	Secure	Auto login	Use Cases / Notes	API References
BotPassword	✅✅	✅	Preferred for most bots; safe, scoped credentials	login.ClientLoginManager login.BotPassword
OAuth	✅✅	✅	For complex bots, shared apps, or broader API access	login.OauthLoginManager
2FA Login	✅✅	❌	2FA support e.g for interactive admin scripts	login.ClientLoginManager
Login with email token	✅	❌	Email token login e.g. for semi-automated bots or user supporting scripts	login.ClientLoginManager
Manual login	❌	❌	No longer supported on Wikimedia sites	login.ClientLoginManager
Cookie-based login	➖	✅	Session reuse ogin; not a standalone method	comms.http.PywikibotCookieJar
CentralAuth SUL login	➖	✅	Automatic across Wikimedia projects once logged in

See also

• pywikibot.scripts.login

• pywikibot.scripts.generate_user_files

• BotPasswords

• API:Login

Library to log the bot in to a wiki account.

class login.BotPassword(suffix, password)

Bases: object

BotPassword object for storage in password file.

BotPassword function by using a separate password paired with a suffixed username of the form <username>@<suffix>.

Parameters:

• suffix (str) – Suffix of the login name

• password (str) – bot password

Raises:

_PasswordFileWarning – suffix improperly specified

login_name(username)

Construct the login name from the username and suffix.

Parameters:

username (str) – username (without suffix)

Return type:

str

class login.ClientLoginManager(password=None, site=None, user=None)

Bases: LoginManager

Supply login_to_site method to use API interface.

Changed in version 8.0: 2FA login was enabled. LoginManager was moved from data.api to login module and renamed to ClientLoginManager.

Changed in version 10.2: Secondary authentication via email was enabled.

See also

• https://www.mediawiki.org/wiki/Extension:OATHAuth

• https://www.mediawiki.org/wiki/Extension:EmailAuth

All parameters default to defaults in user-config.

Parameters:

• site (pywikibot.site.BaseSite | None) – Site object to log into

• user (str | None) – username to use. If user is None, the username is loaded from config.usernames.

• password (str | None) – password to use

Raises:

pywikibot.exceptions.NoUsernameError – No username is configured for the requested site.

keyword(key)

Get API keyword from mapping.

login_to_site()

Login to the site.

Note, this doesn’t do anything with cookies. The http module takes care of all the cookie stuff. Throws exception on failure.

Changed in version 8.0: 2FA login was implemented.

Changed in version 10.2: Secondary authentication via email was implemented.

Raises:

• RuntimeError – Unexpected API login response key or unexpected API login requests response

• APIError – API login error

Return type:

None

mapping = {'fail': ('Failed', 'FAIL'), 'ldap': ('lgdomain', 'domain'), 'password': ('lgpassword', 'password'), 'reason': ('reason', 'message'), 'result': ('result', 'status'), 'success': ('Success', 'PASS'), 'token': ('lgtoken', 'logintoken'), 'user': ('lgname', 'username')}

class login.LoginManager(password=None, site=None, user=None)

Bases: object

Site login manager.

All parameters default to defaults in user-config.

Parameters:

• site (pywikibot.site.BaseSite | None) – Site object to log into

• user (str | None) – username to use. If user is None, the username is loaded from config.usernames.

• password (str | None) – password to use

Raises:

pywikibot.exceptions.NoUsernameError – No username is configured for the requested site.

botAllowed()

Check whether the bot is listed on a specific page.

This allows bots to comply with the policy on the respective wiki.

Return type:

bool

check_user_exists()

Check that the username exists on the site.

See also

API:Users

Raises:

pywikibot.exceptions.NoUsernameError – Username doesn’t exist in user list.

Return type:

None

login(retry=False, autocreate=False)

Attempt to log into the server.

See also

API:Login

Parameters:

• retry (bool) – infinitely retry if the API returns an unknown error

• autocreate (bool) – if true, allow auto-creation of the account using unified login

Raises:

pywikibot.exceptions.NoUsernameError – Username is not recognised by the site.

Return type:

bool

login_to_site()

Login to the site.

Return type:

None

readPassword()

Read passwords from a file.

Warning

Do not forget to remove read access for other users! Use chmod 600 for password-file.

All lines below should be valid Python tuples in the form (code, family, username, password), (family, username, password) or (username, password) to set a default password for an username. The last matching entry will be used, so default usernames should occur above specific usernames.

Note

For BotPasswords the password should be given as a BotPassword object.

The file must be either encoded in ASCII or UTF-8.

Example:

('my_username', 'my_default_password')
('wikipedia', 'my_wikipedia_user', 'my_wikipedia_pass')
('en', 'wikipedia', 'my_en_wikipedia_user', 'my_en_wikipedia_pass')
('my_username', BotPassword('my_suffix', 'my_password'))

Changed in version 10.2: raises ValueError instead of AttributeError if password_file is not set

Raises:

• ValueError – password_file is not set in the user-config.py

• FileNotFoundError – password file does not exist

Return type:

None

storecookiedata()

Store cookie data.

Return type:

None

class login.LoginStatus(*values)

Bases: IntEnum

Enum for Login statuses.

>>> LoginStatus.NOT_ATTEMPTED
LoginStatus(-3)
>>> LoginStatus.IN_PROGRESS.value
-2
>>> LoginStatus.NOT_LOGGED_IN.name
'NOT_LOGGED_IN'
>>> int(LoginStatus.AS_USER)
0
>>> LoginStatus(-3).name
'NOT_ATTEMPTED'
>>> LoginStatus(0).name
'AS_USER'

AS_USER = 0

IN_PROGRESS = -2

NOT_ATTEMPTED = -3

NOT_LOGGED_IN = -1

class login.OauthLoginManager(password=None, site=None, user=None)

Bases: LoginManager

Site login manager using OAuth.

All parameters default to defaults in user-config.

Parameters:

• site (pywikibot.site.BaseSite | None) – Site object to log into

• user (str | None) – consumer key

• password (str | None) – consumer secret

Raises:

• pywikibot.exceptions.NoUsernameError – No username is configured for the requested site.

• ImportError – mwoauth isn’t installed

property access_token: tuple[str, str] | None

OAuth access key token and secret token.

See also

API:Tokens

Getter:

Return OAuth access key token and secret token.

Setter:

Add OAuth access key token and secret token. Implemented to discard user interaction token fetching, usually for tests.

Added in version 10.0.

property consumer_token: tuple[str, str]

Return OAuth consumer key token and secret token.

See also

API:Tokens

property identity: dict[str, Any] | None

Get identifying information about a user via an authorized token.

Changed in version 9.6: leeway parameter for mwoauth.identify function was increased to 30.0 seconds.

login(retry=False, force=False)

Attempt to log into the server.

See also

API:Login

Parameters:

• retry (bool) – infinitely retry if exception occurs during authentication.

• force (bool) – force to re-authenticate

Return type:

bool