pywikibot.site package

Library module representing MediaWiki sites (wikis).

class pywikibot.site.APISite(code, fam=None, user=None)[source]

Bases: pywikibot.site._basesite.BaseSite, pywikibot.site._extensions.EchoMixin, pywikibot.site._extensions.FlowMixin, pywikibot.site._generators.GeneratorsMixin, pywikibot.site._extensions.GeoDataMixin, pywikibot.site._extensions.GlobalUsageMixin, pywikibot.site._extensions.LinterMixin, pywikibot.site._extensions.PageImagesMixin, pywikibot.site._extensions.ProofreadPageMixin, pywikibot.site._extensions.ThanksFlowMixin, pywikibot.site._extensions.ThanksMixin, pywikibot.site._extensions.UrlShortenerMixin, pywikibot.site._extensions.WikibaseClientMixin

API interface to MediaWiki site.

Do not instantiate directly; use pywikibot.Site function.

class OnErrorExc(exception, on_new_page)

Bases: tuple

Create new instance of OnErrorExc(exception, on_new_page)

exception

Alias for field number 0

on_new_page

Alias for field number 1

property article_path

Get the nice article path without $1.

static assert_valid_iter_params(msg_prefix, start, end, reverse, is_ts=True)[source]

Validate iterating API parameters.

Parameters
  • msg_prefix (str) – The calling method name

  • start – The start value to compare

  • end – The end value to compare

  • reverse (bool) – The reverse option

  • is_ts (bool) – When comparing timestamps (with is_ts=True) the start is usually greater than end. Comparing titles this is vice versa.

Raises

AssertionError – start/end values are in wrong order

blockuser(user, expiry, reason: str, anononly=True, nocreate=True, autoblock=True, noemail=False, reblock=False, allowusertalk=False)[source]

Block a user for certain amount of time and for a certain reason.

See

https://www.mediawiki.org/wiki/API:Block

Parameters
  • user (pywikibot.User) – The username/IP to be blocked without a namespace.

  • expiry (Timestamp/datetime (absolute), str (relative/absolute) or False ('never')) –

    The length or date/time when the block expires. If ‘never’, ‘infinite’, ‘indefinite’ it never does. If the value is given as a str it’s parsed by php’s strtotime function:

    The relative format is described there:

    It is recommended to not use a str if possible to be independent of the API.

  • reason – The reason for the block.

  • anononly (boolean) – Disable anonymous edits for this IP.

  • nocreate (boolean) – Prevent account creation.

  • autoblock (boolean) – Automatically block the last used IP address and all subsequent IP addresses from which this account logs in.

  • noemail (boolean) – Prevent user from sending email through the wiki.

  • reblock (boolean) – If the user is already blocked, overwrite the existing block.

  • allowusertalk (boolean) – Whether the user can edit their talk page while blocked.

Returns

The data retrieved from the API request.

Return type

dict

categoryinfo(category)[source]

Retrieve data on contents of category.

compare(old, diff)[source]

Corresponding method to the ‘action=compare’ API action.

See

https://www.mediawiki.org/wiki/API:Compare

See: https://en.wikipedia.org/w/api.php?action=help&modules=compare Use pywikibot.diff’s html_comparator() method to parse result. :param old: starting revision ID, title, Page, or Revision :type old: int, str, pywikibot.Page, or pywikibot.Page.Revision :param diff: ending revision ID, title, Page, or Revision :type diff: int, str, pywikibot.Page, or pywikibot.Page.Revision :return: Returns an HTML string of a diff between two revisions. :rtype: str

data_repository()[source]

Return the data repository connected to this site.

Returns

The data repository if one is connected or None otherwise.

Return type

pywikibot.site.DataSite or None

dbName()[source]

Return this site’s internal id.

delete(page, reason: str, *, oldimage: Optional[str] = None)[source]

Delete a page or a specific old version of a file from the wiki.

Requires appropriate privileges.

See

https://www.mediawiki.org/wiki/API:Delete

Page to be deleted can be given either as Page object or as pageid. To delete a specific version of an image the oldimage identifier must be provided.

Renamed in version 6.1.

New in version 6.1: keyword only parameter oldimage was added.

Parameters
  • page (pywikibot.page.BasePage or, for pageid, int or str) – Page to be deleted or its pageid.

  • reason – Deletion reason.

  • oldimage – oldimage id of the file version to be deleted. If a BasePage object is given with page parameter, it has to be a FilePage.

Raises

TypeError, ValueError – page has wrong type/value.

deleterevs(targettype: str, ids, *, hide=None, show=None, reason='', target=None)[source]

Delete or undelete specified page revisions, file versions or logs.

See

https://www.mediawiki.org/wiki/API:Revisiondelete

If more than one target id is provided, the same action is taken for all of them.

New in version 6.0.

Parameters
  • targettype – Type of target. One of “archive”, “filearchive”, “logging”, “oldimage”, “revision”.

  • ids (int, str, or list of int or str) – Identifiers for the revision, log, file version or archive.

  • hide (str or list of str) – What to delete. Can be “comment”, “content”, “user” or a combination of them in pipe-separate form such as “comment|user”.

  • show (str or list of str) – What to undelete. Can be “comment”, “content”, “user” or a combination of them in pipe-separate form such as “comment|user”.

  • reason – Deletion reason.

  • target – Page object or page title, if required for the type.

editpage(page, summary=None, minor=True, notminor=False, bot=True, recreate=True, createonly=False, nocreate=False, watch=None, **kwargs)bool[source]

Submit an edit to be saved to the wiki.

See

https://www.mediawiki.org/wiki/API:Edit

Parameters
  • page – The Page to be saved. By default its .text property will be used as the new text to be saved to the wiki

  • summary – the edit summary

  • minor – if True (default), mark edit as minor

  • notminor – if True, override account preferences to mark edit as non-minor

  • recreate – if True (default), create new page even if this title has previously been deleted

  • createonly – if True, raise an error if this title already exists on the wiki

  • nocreate – if True, raise an error if the page does not exist

  • watch – Specify how the watchlist is affected by this edit, set to one of “watch”, “unwatch”, “preferences”, “nochange”: * watch: add the page to the watchlist * unwatch: remove the page from the watchlist * preferences: use the preference settings (default) * nochange: don’t change the watchlist

  • bot – if True, mark edit with bot flag

Keyword Arguments
  • text – Overrides Page.text

  • section – Edit an existing numbered section or a new section (‘new’)

  • prependtext – Prepend text. Overrides Page.text

  • appendtext – Append text. Overrides Page.text.

  • undo – Revision id to undo. Overrides Page.text

Returns

True if edit succeeded, False if it failed

Raises
expand_text(text: str, title=None, includecomments=None, string='[deprecated name of text]')[source]

Parse the given text for preprocessing and rendering.

e.g expand templates and strip comments if includecomments parameter is not True. Keeps text inside <nowiki></nowiki> tags unchanges etc. Can be used to parse magic parser words like {{CURRENTTIMESTAMP}}.

Parameters
  • text (str) – text to be expanded

  • title (str) – page title without section

  • includecomments (bool) – if True do not strip comments

classmethod fromDBName(dbname, site=None)[source]

Create a site from a database name using the sitematrix.

Parameters
  • dbname (str) – database name

  • site (pywikibot.site.APISite) – Site to load sitematrix from. (Default meta.wikimedia.org)

Returns

site object for the database name

Return type

pywikibot.site.APISite

get_parsed_page(page)[source]

Retrieve parsed text of the page using action=parse.

See

https://www.mediawiki.org/wiki/API:Parse

get_property_names(force: bool = False)[source]

Get property names for pages_with_property().

See

https://www.mediawiki.org/wiki/API:Pagepropnames

Parameters

force – force to retrieve userinfo ignoring cache

get_searched_namespaces(force=False)[source]

Retrieve the default searched namespaces for the user.

If no user is logged in, it returns the namespaces used by default. Otherwise it returns the user preferences. It caches the last result and returns it, if the username or login status hasn’t changed.

Parameters

force – Whether the cache should be discarded.

Returns

The namespaces which are searched by default.

Return type

set of Namespace

get_tokens(types: list, all: bool = False)dict[source]

Preload one or multiple tokens.

For MediaWiki version 1.23, only one token can be retrieved at once. For MediaWiki versions since 1.24wmfXXX a new token system was introduced which reduced the amount of tokens available. Most of them were merged into the ‘csrf’ token. If the token type in the parameter is not known it will default to the ‘csrf’ token.

The other token types available are:
  • createaccount

  • deleteglobalaccount

  • login

  • patrol

  • rollback

  • setglobalaccountstatus

  • userrights

  • watch

See

https://www.mediawiki.org/wiki/API:Tokens

Parameters
  • types – the types of token (e.g., “edit”, “move”, “delete”); see API documentation for full list of types

  • all – load all available tokens, if None only if it can be done in one request.

return: a dict with retrieved valid tokens.

getcategoryinfo(category)[source]

Retrieve data on contents of category.

See

https://www.mediawiki.org/wiki/API:Categoryinfo

getcurrenttimestamp()[source]

Return the server time as a MediaWiki timestamp string.

It calls server_time first so it queries the server to get the current server time.

Returns

the server time

Return type

str (as ‘yyyymmddhhmmss’)

getmagicwords(word)[source]

Return list of localized “word” magic words for the site.

getredirtarget(page)[source]

Return page object for the redirect target of page.

Parameters

page (pywikibot.page.BasePage) – page to search redirects for

Returns

redirect target of page

Return type

pywikibot.Page

Raises
property globaluserinfo

Retrieve globaluserinfo from site and cache it.

self._globaluserinfo will be a dict with the following keys and values:

  • id: user id (numeric str)

  • home: dbname of home wiki

  • registration: registration date as Timestamp

  • groups: list of groups (could be empty)

  • rights: list of rights (could be empty)

  • editcount: global editcount

has_all_mediawiki_messages(keys, lang=None)[source]

Confirm that the site defines a set of MediaWiki messages.

Parameters
  • keys (iterable of str) – names of MediaWiki messages

  • lang (str or None) – a language code, default is self.lang

Return type

bool

property has_data_repository

Return True if site has a shared data repository like Wikidata.

has_extension(name)[source]

Determine whether extension name is loaded.

Parameters

name (str) – The extension to check for, case sensitive

Returns

If the extension is loaded

Return type

bool

has_group(group)[source]

Return true if and only if the user is a member of specified group.

Possible values of ‘group’ may vary depending on wiki settings, but will usually include bot. https://www.mediawiki.org/wiki/API:Userinfo

property has_image_repository

Return True if site has a shared image repository like Commons.

has_mediawiki_message(key, lang=None)[source]

Determine if the site defines a MediaWiki message.

Parameters
  • key (str) – name of MediaWiki message

  • lang (str or None) – a language code, default is self.lang

Return type

bool

has_right(right)[source]

Return true if and only if the user has a specific right.

Possible values of ‘right’ may vary depending on wiki settings. https://www.mediawiki.org/wiki/API:Userinfo

Parameters

right (str) – a specific right to be validated

image_repository()[source]

Return Site object for image repository e.g. commons.

interwiki(prefix)[source]

Return the site for a corresponding interwiki prefix.

Raises
interwiki_prefix(site)[source]

Return the interwiki prefixes going to that site.

The interwiki prefixes are ordered first by length (shortest first) and then alphabetically. interwiki(prefix) is not guaranteed to equal site (i.e. the parameter passed to this function).

Parameters

site (BaseSite) – The targeted site, which might be it’s own.

Returns

The interwiki prefixes

Return type

list (guaranteed to be not empty)

Raises

KeyError – if there is no interwiki prefix for that site.

isBot(username)[source]

Return True is username is a bot user.

is_blocked()[source]

Return True when logged in user is blocked.

To check whether a user can perform an action, the method has_right should be used. https://www.mediawiki.org/wiki/API:Userinfo

Return type

bool

is_data_repository()[source]

Return True if its data repository is itself.

is_image_repository()[source]

Return True if Site object is the image repository.

is_oauth_token_available()[source]

Check whether OAuth token is set for this site.

Return type

bool

is_uploaddisabled()[source]

Return True if upload is disabled on site.

When the version is at least 1.27wmf9, uses general siteinfo. If not called directly, it is cached by the first attempted upload action.

property lang

Return the code for the language of this Site.

list_to_text(args: Iterable[str])str[source]

Convert a list of strings into human-readable text.

The MediaWiki messages ‘and’ and ‘word-separator’ are used as separator between the last two arguments. If more than two arguments are given, other arguments are joined using MediaWiki message ‘comma-separator’.

Parameters

args – text to be expanded

loadimageinfo(page, history=False, url_width=None, url_height=None, url_param=None)[source]

Load image info from api and save in page attributes.

Parameters correspond to iiprops in: [1] https://www.mediawiki.org/wiki/API:Imageinfo

Parameters validation and error handling left to the API call.

Parameters
  • history – if true, return the image’s version history

  • url_width – see iiurlwidth in [1]

  • url_height – see iiurlheigth in [1]

  • url_param – see iiurlparam in [1]

loadpageinfo(page, preload=False)[source]

Load page info from api and store in page attributes.

See

https://www.mediawiki.org/wiki/API:Info

loadpageprops(page)[source]

Load page props for the given page.

local_interwiki(prefix)[source]

Return whether the interwiki prefix is local.

A local interwiki prefix is handled by the target site like a normal link. So if that link also contains an interwiki link it does follow it as long as it’s a local link.

Raises
logged_in()[source]

Verify the bot is logged into the site as the expected user.

The expected usernames are those provided as the user parameter at instantiation.

Return type

bool

login(autocreate: bool = False, user: Optional[str] = None)[source]

Log the user in if not already logged in.

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

  • user – bot user name. Overrides the username set by BaseSite initializer parameter or user-config.py setting

Raises

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

See

https://www.mediawiki.org/wiki/API:Login

logout()[source]

Logout of the site and load details for the logged out user.

Also logs out of the global account if linked to the user. https://www.mediawiki.org/wiki/API:Logout

Raises

APIError – Logout is not available when OAuth enabled.

property logtypes

Return a set of log types available on current site.

mediawiki_message(key, lang=None, forceReload=NotImplemented)[source]

Fetch the text for a MediaWiki message.

Parameters
  • key (str) – name of MediaWiki message

  • lang (str or None) – a language code, default is self.lang

mediawiki_messages(keys, lang: Optional[str] = None)[source]

Fetch the text of a set of MediaWiki messages.

The returned dict uses each key to store the associated message.

See

https://www.mediawiki.org/wiki/API:Allmessages

Parameters
  • keys (iterable of str) – MediaWiki messages to fetch

  • lang – a language code, default is self.lang

Return type

OrderedDict

merge_history(source, dest, timestamp=None, reason: Optional[str] = None)[source]

Merge revisions from one page into another.

See

https://www.mediawiki.org/wiki/API:Mergehistory

Revisions dating up to the given timestamp in the source will be moved into the destination page history. History merge fails if the timestamps of source and dest revisions overlap (all source revisions must be dated before the earliest dest revision).

Parameters
  • source (pywikibot.Page) – Source page from which revisions will be merged

  • dest (pywikibot.Page) – Destination page to which revisions will be merged

  • timestamp (pywikibot.Timestamp) – Revisions from this page dating up to this timestamp will be merged into the destination page (if not given or False, all revisions will be merged)

  • reason – Optional reason for the history merge

messages()[source]

Return true if the user has new messages, and false otherwise.

property months_names

Obtain month names from the site messages.

The list is zero-indexed, ordered by month in calendar, and should be in the original site language.

Returns

list of tuples (month name, abbreviation)

Return type

list

movepage(page, newtitle: str, summary, movetalk=True, noredirect=False)[source]

Move a Page to a new title.

See

https://www.mediawiki.org/wiki/API:Move

Parameters
  • page – the Page to be moved (must exist)

  • newtitle – the new title for the Page

  • summary – edit summary (required!)

  • movetalk – if True (default), also move the talk page if possible

  • noredirect – if True, suppress creation of a redirect from the old title to the new one

Returns

Page object with the new title

Return type

pywikibot.Page

property mw_version

Return self.version() as a MediaWikiVersion object.

Cache the result for 24 hours. :rtype: MediaWikiVersion

namespace(num, all=False)[source]

Return string containing local name of namespace ‘num’.

If optional argument ‘all’ is true, return all recognized values for this namespace.

Parameters
  • num (int) – Namespace constant.

  • all – If True return a Namespace object. Otherwise return the namespace name.

Returns

local name or Namespace object

Return type

str or Namespace

nice_get_address(title)[source]

Return shorter URL path to retrieve page titled ‘title’.

page_can_be_edited(page, action='edit')[source]

Determine if the page can be modified.

Return True if the bot has the permission of needed restriction level for the given action type.

Parameters
  • page (pywikibot.Page) – a pywikibot.Page object

  • action (str) – a valid restriction type like ‘edit’, ‘move’

Return type

bool

Raises

ValueError – invalid action parameter

page_from_repository(item)[source]

Return a Page for this site object specified by Wikibase item.

Parameters

item (str) – id number of item, “Q###”,

Returns

Page, or Category object given by Wikibase item number for this site object.

Return type

pywikibot.Page or None

Raises
page_isredirect(page)[source]

Return True if and only if page is a redirect.

page_restrictions(page)[source]

Return a dictionary reflecting page protections.

pagename2codes()[source]

Return list of localized PAGENAMEE tags for the site.

pagenamecodes()[source]

Return list of localized PAGENAME tags for the site.

protect(page, protections: dict, reason: str, expiry=None, summary='[deprecated name of reason]', **kwargs)[source]

(Un)protect a wiki page. Requires administrator status.

See

https://www.mediawiki.org/wiki/API:Protect

Parameters
  • protections – A dict mapping type of protection to protection level of that type. Valid restriction types are ‘edit’, ‘create’, ‘move’ and ‘upload’. Valid restriction levels are ‘’ (equivalent to ‘none’ or ‘all’), ‘autoconfirmed’, and ‘sysop’. If None is given, however, that protection will be skipped.

  • reason – Reason for the action

  • expiry (pywikibot.Timestamp, string in GNU timestamp format (including ISO 8601)) – When the block should expire. This expiry will be applied to all protections. If None, ‘infinite’, ‘indefinite’, ‘never’, or ‘’ is given, there is no expiry.

protection_levels()[source]

Return the protection levels available on this site.

Returns

protection types available

Return type

set of str instances

See

Siteinfo._get_default()

protection_types()[source]

Return the protection types available on this site.

Returns

protection types available

Return type

set of str instances

See

Siteinfo._get_default()

purgepages(pages, forcelinkupdate: bool = False, forcerecursivelinkupdate: bool = False, converttitles: bool = False, redirects: bool = False)bool[source]

Purge the server’s cache for one or multiple pages.

Parameters
  • pages – list of Page objects

  • redirects (bool) – Automatically resolve redirects.

  • converttitles – Convert titles to other variants if necessary. Only works if the wiki’s content language supports variant conversion.

  • forcelinkupdate – Update the links tables.

  • forcerecursivelinkupdate – Update the links table, and update the links tables for any page that uses this page as a template.

Returns

True if API returned expected response; False otherwise

redirect()[source]

Return the localized #REDIRECT keyword.

property redirect_regex

Return a compiled regular expression matching on redirect pages.

Group 1 in the regex match object will be the target title.

rollbackpage(page, **kwargs)[source]

Roll back page to version before last user’s edits.

See

https://www.mediawiki.org/wiki/API:Rollback

The keyword arguments are those supported by the rollback API.

As a precaution against errors, this method will fail unless the page history contains at least two revisions, and at least one that is not by the same user who made the last edit.

Parameters

page – the Page to be rolled back (must exist)

Keyword Arguments

user – the last user to be rollbacked; default is page.latest_revision.user

server_time()[source]

Return a Timestamp object representing the current server time.

It uses the ‘time’ property of the siteinfo ‘general’. It’ll force a reload before returning the time.

Returns

the current server time

Return type

Timestamp

property siteinfo

Site information dict.

stash_info(file_key, props=None)[source]

Get the stash info for a given file key.

See

https://www.mediawiki.org/wiki/API:Stashimageinfo

unblockuser(user, reason: Optional[str] = None)[source]

Remove the block for the user.

See

https://www.mediawiki.org/wiki/API:Block

Parameters
  • user (pywikibot.User) – The username/IP without a namespace.

  • reason – Reason for the unblock.

undelete(page, reason: str, *, revisions=None, fileids=None)[source]

Undelete page from the wiki. Requires appropriate privilege level.

See

https://www.mediawiki.org/wiki/API:Undelete

Renamed in version 6.1.

New in version 6.1: fileids parameter was added.

Changed in verson 6.1: keyword argument required for revisions.

Parameters
  • page (pywikibot.BasePage) – Page to be deleted.

  • reason – Undeletion reason.

  • revisions (list) – List of timestamps to restore. If None, restores all revisions.

  • fileids (list) – List of fileids to restore.

upload(filepage, imagepage='[deprecated name of filepage]', *, source_filename: Optional[str] = None, source_url: Optional[str] = None, comment: Optional[str] = None, text: Optional[str] = None, watch: bool = False, ignore_warnings=False, chunk_size: int = 0, asynchronous: bool = False, _file_key: Optional[str] = None, _offset: Union[bool, int] = 0, _verify_stash: Optional[bool] = None, report_success: Optional[bool] = None)[source]

Upload a file to the wiki.

See

https://www.mediawiki.org/wiki/API:Upload

Either source_filename or source_url, but not both, must be provided.

Changed in version 6.0: keyword arguments required for all parameters except filepage.

Changed in version 6.2: asynchronous upload is used if asynchronous parameter is set.

Parameters
  • filepage – a FilePage object from which the wiki-name of the file will be obtained.

  • source_filename – path to the file to be uploaded

  • source_url – URL of the file to be uploaded

  • comment – Edit summary; if this is not provided, then filepage.text will be used. An empty summary is not permitted. This may also serve as the initial page text (see below).

  • text – Initial page text; if this is not set, then filepage.text will be used, or comment.

  • watch – If true, add filepage to the bot user’s watchlist

  • ignore_warnings (bool or callable or iterable of str) – It may be a static boolean, a callable returning a boolean or an iterable. The callable gets a list of UploadError instances and the iterable should contain the warning codes for which an equivalent callable would return True if all UploadError codes are in thet list. If the result is False it’ll not continue uploading the file and otherwise disable any warning and reattempt to upload the file. NOTE: If report_success is True or None it’ll raise an UploadError exception if the static boolean is False.

  • chunk_size – The chunk size in bytes for chunked uploading (see https://www.mediawiki.org/wiki/API:Upload#Chunked_uploading). It will only upload in chunks, if the chunk size is positive but lower than the file size.

  • asynchronous – Make potentially large file operations asynchronous on the server side when possible.

  • _file_key – Reuses an already uploaded file using the filekey. If None (default) it will upload the file.

  • _offset – When file_key is not None this can be an integer to continue a previously canceled chunked upload. If False it treats that as a finished upload. If True it requests the stash info from the server to determine the offset. By default starts at 0.

  • _verify_stash – Requests the SHA1 and file size uploaded and compares it to the local file. Also verifies that _offset is matching the file size if the _offset is an int. If _offset is False if verifies that the file size match with the local file. If None it’ll verifies the stash when a file key and offset is given.

  • report_success – If the upload was successful it’ll print a success message and if ignore_warnings is set to False it’ll raise an UploadError if a warning occurred. If it’s None (default) it’ll be True if ignore_warnings is a bool and False otherwise. If it’s True or None ignore_warnings must be a bool.

Returns

It returns True if the upload was successful and False otherwise.

property userinfo

Retrieve userinfo from site and store in _userinfo attribute.

To force retrieving userinfo ignoring cache, just delete this property.

self._userinfo will be a dict with the following keys and values:

  • id: user id (numeric str)

  • name: username (if user is logged in)

  • anon: present if user is not logged in

  • groups: list of groups (could be empty)

  • rights: list of rights (could be empty)

  • message: present if user has a new message on talk page

  • blockinfo: present if user is blocked (dict)

https://www.mediawiki.org/wiki/API:Userinfo

validate_tokens(types: list)list[source]

Validate if requested tokens are acceptable.

Valid tokens depend on mw version.

version()str[source]

Return live project version number as a string.

Use pywikibot.site.mw_version to compare MediaWiki versions.

watch(pages, unwatch: bool = False)bool[source]

Add or remove pages from watchlist.

See

https://www.mediawiki.org/wiki/API:Watch

Parameters
  • pages (A page object, a page-title string, or sequence of them. Also accepts a single pipe-separated string like 'title1|title2'.) – A single page or a sequence of pages.

  • unwatch – If True, remove pages from watchlist; if False add them (default).

Returns

True if API returned expected response; False otherwise

Raises

KeyError – ‘watch’ isn’t in API response

class pywikibot.site.BaseSite(code: str, fam=None, user=None)[source]

Bases: pywikibot.tools.ComparableMixin

Site methods that are independent of the communication interface.

Parameters
  • code (str) – the site’s language code

  • fam (str or pywikibot.family.Family) – wiki family name (optional)

  • user (str) – bot user name (optional)

category_on_one_line()[source]

Return True if this site wants all category links on one line.

property code

The identifying code for this Site equal to the wiki prefix.

By convention, this is usually an ISO language code, but it does not have to be.

disambcategory()[source]

Return Category in which disambig pages are listed.

property doc_subpage

Return the documentation subpage for this Site.

Return type

tuple

property family

The Family object for this Site’s wiki family.

getSite(code)[source]

Return Site object for language ‘code’ in this Family.

interwiki_putfirst()[source]

Return list of language codes for ordering of interwiki links.

Return True if text is in the form of an interwiki link.

If a link object constructed using “text” as the link text parses as belonging to a different site, this method returns True.

property lang

The ISO language code for this Site.

Presumed to be equal to the site code, but this can be overridden.

languages()[source]

Return list of all valid language codes for this site’s Family.

lock_page(page, block=True)[source]

Lock page for writing. Must be called before writing any page.

We don’t want different threads trying to write to the same page at the same time, even to different sections.

Parameters
  • page (pywikibot.Page) – the page to be locked

  • block – if true, wait until the page is available to be locked; otherwise, raise an exception if page can’t be locked

property namespaces

Return dict of valid namespaces on this wiki.

ns_normalize(value)[source]

Return canonical local form of namespace name.

Parameters

value (str) – A namespace name

pagename2codes()[source]

Return list of localized PAGENAMEE tags for the site.

pagenamecodes()[source]

Return list of localized PAGENAME tags for the site.

redirect()[source]

Return list of localized redirect tags for the site.

redirectRegex(pattern=None)[source]

Return a compiled regular expression matching on redirect pages.

Group 1 in the regex match object will be the target title.

sametitle(title1: str, title2: str)bool[source]

Return True if title1 and title2 identify the same wiki page.

title1 and title2 may be unequal but still identify the same page, if they use different aliases for the same namespace.

property sitename

String representing this Site’s name and code.

property throttle

Return this Site’s throttle. Initialize a new one if needed.

unlock_page(page)[source]

Unlock page. Call as soon as a write operation has completed.

Parameters

page (pywikibot.Page) – the page to be locked

user()[source]

Return the currently-logged in bot username, or None.

username()[source]

Return the username used for the site.

Return list of language codes to be used in interwiki links.

class pywikibot.site.ClosedSite(code, fam, user=None)[source]

Bases: pywikibot.site._apisite.APISite

Site closed to read-only mode.

is_uploaddisabled()[source]

Return True if upload is disabled on site.

newfiles(**kwargs)[source]

An error instead of pointless API call.

newpages(**kwargs)[source]

An error instead of pointless API call.

page_restrictions(page)[source]

Return a dictionary reflecting page protections.

recentchanges(**kwargs)[source]

An error instead of pointless API call.

class pywikibot.site.DataSite(*args, **kwargs)[source]

Bases: pywikibot.site._apisite.APISite

Wikibase data capable site.

addClaim(entity, claim, bot=True, summary=None)[source]

Add a claim.

Parameters
  • entity (WikibaseEntity) – Entity to modify

  • claim (pywikibot.Claim) – Claim to be added

  • bot (bool) – Whether to mark the edit as a bot edit

  • summary (str) – Edit summary

changeClaimTarget(claim, snaktype='value', bot=True, summary=None)[source]

Set the claim target to the value of the provided claim target.

Parameters
  • claim (pywikibot.Claim) – The source of the claim target value

  • snaktype (str ('value', 'novalue' or 'somevalue')) – An optional snaktype. Default: ‘value’

  • bot (bool) – Whether to mark the edit as a bot edit

  • summary (str) – Edit summary

property concept_base_uri

Return the base uri for concepts/entities.

Returns

concept base uri

Return type

str

editEntity(entity, data, bot=True, identification='[deprecated name of entity]', **kwargs)[source]

Edit entity.

Note: This method is unable to create entities other than ‘item’ if dict with API parameters was passed to ‘entity’ parameter.

Parameters
  • entity (WikibaseEntity or dict) – Page to edit, or dict with API parameters to use for entity identification

  • data (dict) – data updates

  • bot (bool) – Whether to mark the edit as a bot edit

Returns

New entity data

Return type

dict

geo_shape_repository()[source]

Return Site object for the geo-shapes repository e.g. commons.

getPropertyType(prop)[source]

Obtain the type of a property.

This is used specifically because we can cache the value for a much longer time (near infinite).

get_entity_for_entity_id(entity_id)[source]

Return a new instance for given entity id.

Raises

pywikibot.exceptions.NoWikibaseEntityError – there is no entity with the id

Returns

a WikibaseEntity subclass

Return type

WikibaseEntity

get_namespace_for_entity_type(entity_type)[source]

Return namespace for given entity type.

Returns

corresponding namespace

Return type

Namespace

property item_namespace

Return namespace for items.

Returns

item namespace

Return type

Namespace

linkTitles(page1, page2, bot=True)[source]

Link two pages together.

Parameters
  • page1 (pywikibot.Page) – First page to link

  • page2 (pywikibot.Page) – Second page to link

  • bot (bool) – Whether to mark the edit as a bot edit

Returns

dict API output

Return type

dict

loadcontent(identification, *props)[source]

Fetch the current content of a Wikibase item.

This is called loadcontent since wbgetentities does not support fetching old revisions. Eventually this will get replaced by an actual loadrevisions.

Parameters
  • identification (dict) – Parameters used to identify the page(s)

  • props – the optional properties to fetch.

mergeItems(from_item, to_item, ignore_conflicts=None, summary=None, bot=True, ignoreconflicts='[deprecated name of ignore_conflicts]', fromItem='[deprecated name of from_item]', toItem='[deprecated name of to_item]')[source]

Merge two items together.

Parameters
  • from_item (pywikibot.ItemPage) – Item to merge from

  • to_item (pywikibot.ItemPage) – Item to merge into

  • ignore_conflicts (list of str) – Which type of conflicts (‘description’, ‘sitelink’, and ‘statement’) should be ignored

  • summary (str) – Edit summary

  • bot (bool) – Whether to mark the edit as a bot edit

Returns

dict API output

Return type

dict

preload_entities(pagelist, groupsize=50)[source]

Yield subclasses of WikibaseEntity’s with content prefilled.

Note that pages will be iterated in a different order than in the underlying pagelist.

Parameters
  • pagelist – an iterable that yields either WikibaseEntity objects, or Page objects linked to an ItemPage.

  • groupsize (int) – how many pages to query at a time

property property_namespace

Return namespace for properties.

Returns

property namespace

Return type

Namespace

save_claim(claim, summary=None, bot=True)[source]

Save the whole claim to the wikibase site.

Parameters
  • claim (pywikibot.Claim) – The claim to save

  • bot (bool) – Whether to mark the edit as a bot edit

  • summary (str) – Edit summary

search_entities(search: str, language: str, total: Optional[int] = None, limit='[deprecated name of total]', **kwargs)[source]

Search for pages or properties that contain the given text.

Parameters
  • search – Text to find.

  • language – Language to search in.

  • total – Maximum number of pages to retrieve in total, or None in case of no limit.

Returns

‘search’ list from API output.

Return type

Generator

set_redirect_target(from_item, to_item, bot=True)[source]

Make a redirect to another item.

Parameters
  • to_item (pywikibot.ItemPage) – title of target item.

  • from_item (pywikibot.ItemPage) – Title of the item to be redirected.

  • bot (bool) – Whether to mark the edit as a bot edit

property sparql_endpoint

Return the sparql endpoint url, if any has been set.

Returns

sparql endpoint url

Return type

str|None

tabular_data_repository()[source]

Return Site object for the tabular-datas repository e.g. commons.

wbsetaliases(itemdef, aliases, **kwargs)[source]

Set aliases for a single Wikibase entity.

See self._wbset_action() for parameters

wbsetdescription(itemdef, description, **kwargs)[source]

Set description for a single Wikibase entity.

See self._wbset_action()

wbsetlabel(itemdef, label, **kwargs)[source]

Set label for a single Wikibase entity.

See self._wbset_action() for parameters

Set, remove or modify a sitelink on a Wikibase item.

See self._wbset_action() for parameters

class pywikibot.site.Namespace(id, canonical_name: Optional[str] = None, custom_name: Optional[str] = None, aliases: Optional[list] = None, **kwargs)[source]

Bases: collections.abc.Iterable, pywikibot.tools.ComparableMixin

Namespace site data object.

This is backwards compatible with the structure of entries in site._namespaces which were a list of:

[customised namespace,
 canonical namespace name?,
 namespace alias*]

If the canonical_name is not provided for a namespace between -2 and 15, the MediaWiki built-in names are used. Image and File are aliases of each other by default.

If only one of canonical_name and custom_name are available, both properties will have the same value.

Parameters
  • canonical_name – Canonical name

  • custom_name – Name defined in server LocalSettings.php

  • aliases – Aliases

CATEGORY = 14
CATEGORY_TALK = 15
FILE = 6
FILE_TALK = 7
HELP = 12
HELP_TALK = 13
MAIN = 0
MEDIA = -2
MEDIAWIKI = 8
MEDIAWIKI_TALK = 9
PROJECT = 4
PROJECT_TALK = 5
SPECIAL = -1
TALK = 1
TEMPLATE = 10
TEMPLATE_TALK = 11
USER = 2
USER_TALK = 3
classmethod builtin_namespaces(case='first-letter')[source]

Return a dict of the builtin namespaces.

canonical_namespaces = {-2: 'Media', -1: 'Special', 0: '', 1: 'Talk', 2: 'User', 3: 'User talk', 4: 'Project', 5: 'Project talk', 6: 'File', 7: 'File talk', 8: 'MediaWiki', 9: 'MediaWiki talk', 10: 'Template', 11: 'Template talk', 12: 'Help', 13: 'Help talk', 14: 'Category', 15: 'Category talk'}
canonical_prefix()[source]

Return the canonical name with required colons.

custom_prefix()[source]

Return the custom name with required colons.

static default_case(id, default_case=None)[source]

Return the default fixed case value for the namespace ID.

static normalize_name(name)[source]

Remove an optional colon before and after name.

TODO: reject illegal characters.

class pywikibot.site.NamespacesDict(namespaces)[source]

Bases: collections.abc.Mapping, pywikibot.tools.SelfCallMixin

An immutable dictionary containing the Namespace instances.

It adds a deprecation message when called as the ‘namespaces’ property of APISite was callable.

Create new dict using the given namespaces.

lookup_name(name: str)Optional[pywikibot.site._namespace.Namespace][source]

Find the Namespace for a name also checking aliases.

Parameters

name – Name of the namespace.

lookup_normalized_name(name: str)Optional[pywikibot.site._namespace.Namespace][source]

Find the Namespace for a name also checking aliases.

The name has to be normalized and must be lower case.

Parameters

name – Name of the namespace.

resolve(identifiers)list[source]

Resolve namespace identifiers to obtain Namespace objects.

Identifiers may be any value for which int() produces a valid namespace id, except bool, or any string which Namespace.lookup_name successfully finds. A numerical string is resolved as an integer.

Parameters

identifiers (iterable of str or Namespace key, or a single instance of those types) – namespace identifiers

Returns

list of Namespace objects in the same order as the identifiers

Raises
  • KeyError – a namespace identifier was not resolved

  • TypeError – a namespace identifier has an inappropriate type such as NoneType or bool

class pywikibot.site.RemovedSite(code: str, fam=None, user=None)[source]

Bases: pywikibot.site._basesite.BaseSite

Site removed from a family.

Parameters
  • code (str) – the site’s language code

  • fam (str or pywikibot.family.Family) – wiki family name (optional)

  • user (str) – bot user name (optional)

class pywikibot.site.Siteinfo(site)[source]

Bases: collections.abc.Container

A ‘dictionary’ like container for siteinfo.

This class queries the server to get the requested siteinfo property. Optionally it can cache this directly in the instance so that later requests don’t need to query the server.

All values of the siteinfo property ‘general’ are directly available.

Initialise it with an empty cache.

BOOLEAN_PROPS = {'general': ['imagewhitelistenabled', 'langconversion', 'titleconversion', 'rtl', 'readonly', 'writeapi', 'variantarticlepath', 'misermode', 'uploadsenabled'], 'magicwords': ['case-sensitive'], 'namespaces': ['subpages', 'content', 'nonincludable']}
WARNING_REGEX = re.compile('Unrecognized values? for parameter ["\\\']siprop["\\\']: (.+?)\\.?$')
get(key: str, get_default: bool = True, cache: bool = True, expiry=False)[source]

Return a siteinfo property.

It will never throw an APIError if it only stated, that the siteinfo property doesn’t exist. Instead it will use the default value.

Parameters
  • key – The name of the siteinfo property.

  • get_default – Whether to throw an KeyError if the key is invalid.

  • cache – Caches the result internally so that future accesses via this method won’t query the server.

  • expiry (int/float (days), datetime.timedelta, False (never expired), True (always expired)) – If the cache is older than the expiry it ignores the cache and queries the server to get the newest value.

Returns

The gathered property

Return type

various

Raises

KeyError – If the key is not a valid siteinfo property and the get_default option is set to False.

See

_get_siteinfo

get_requested_time(key: str)[source]

Return when ‘key’ was successfully requested from the server.

If the property is actually in the siprop ‘general’ it returns the last request from the ‘general’ siprop.

Parameters

key – The siprop value or a property of ‘general’.

Returns

The last time the siprop of ‘key’ was requested.

Return type

None (never), False (default), datetime.datetime (cached)

is_recognised(key: str)Optional[bool][source]

Return if ‘key’ is a valid property name. ‘None’ if not cached.

class pywikibot.site.TokenWallet(site)[source]

Bases: object

Container for tokens.

load_tokens(types, all=False)[source]

Preload one or multiple tokens.

Parameters
  • types (iterable) – the types of token.

  • all (bool) – load all available tokens, if None only if it can be done in one request.