pywikibot.site package

Library module representing MediaWiki sites (wikis).

BaseSite package

Objects with site methods independent of the communication interface.

class pywikibot.site._basesite.BaseSite(code, 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)

Return type

None

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: tuple

Return the documentation subpage for this Site.

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 (bool) – 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.

Parameters

pattern (Optional[str]) –

Return type

Pattern[str]

sametitle(title1, title2)[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.

Parameters
  • title1 (str) –

  • title2 (str) –

Return type

bool

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

Return type

None

user()[source]

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

Return type

Optional[str]

username()[source]

Return the username used for the site.

Return type

Optional[str]

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

APISite Package

Objects representing API interface to MediaWiki site.

class pywikibot.site._apisite.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.TextExtractsMixin, 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.

Parameters
Return type

None

class OnErrorExc(exception, on_new_page)

Bases: tuple

Create new instance of OnErrorExc(exception, on_new_page)

property exception

Alias for field number 0

property on_new_page

Alias for field number 1

property article_path: str

Get the nice article path without $1.

Deprecated since version 7.0: Replaced by articlepath()

property articlepath: str

Get the nice article path with placeholder.

New in version 7.0: Replaces article_path()

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 (Union[datetime.datetime, int, str]) – The start value to compare

  • end (Union[datetime.datetime, int, str]) – 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 not comparabel types or are in the wrong order

Return type

None

blockuser(user, expiry, reason, 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 also

API:Block

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

  • expiry (Union[datetime.datetime, str, bool]) –

    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 (str) – The reason for the block.

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

  • nocreate (bool) – Prevent account creation.

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

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

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

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

Returns

The data retrieved from the API request.

Return type

Dict[str, Any]

categoryinfo(category)[source]

Retrieve data on contents of category.

Parameters

category (pywikibot.page._pages.Category) –

Return type

Dict[str, int]

compare(old, diff)[source]

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

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 :param diff: ending revision ID, title, Page, or Revision :return: Returns an HTML string of a diff between two revisions.

Parameters
Return type

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

Optional[pywikibot.site._datasite.DataSite]

dbName()[source]

Return this site’s internal id.

Return type

str

delete(page, reason, *, deletetalk=False, oldimage=None)[source]

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

Requires appropriate privileges.

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.

New in version 6.1: renamed from deletepage

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

Changed in version 7.1: keyword only parameter deletetalk was added.

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

  • reason (str) – Deletion reason.

  • deletetalk (bool) – Also delete the talk page, if it exists.

  • oldimage (Optional[str]) – 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.

Return type

None

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

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

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

New in version 6.0.

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

  • ids (Union[int, str, List[Union[int, str]]]) – Identifiers for the revision, log, file version or archive.

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

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

  • reason (str) – Deletion reason.

  • target (Optional[Union[pywikibot.page.Page, str]]) – Page object or page title, if required for the type.

Return type

None

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

Submit an edit to be saved to the wiki.

See also

API:Edit

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

  • summary (Optional[str]) – the edit summary

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

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

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

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

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

  • watch (Optional[str]) – 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 (bool) – if True, mark edit with bot flag

  • kwargs (Any) –

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
Return type

bool

expand_text(text, title=None, includecomments=None)[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 (Optional[str]) – page title without section

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

Return type

str

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

Create a site from a database name using the sitematrix.

Parameters
Returns

site object for the database name

Return type

pywikibot.site._basesite.BaseSite

get_globaluserinfo(user=None, force=False)[source]

Retrieve globaluserinfo from site and cache it.

New in version 7.0.

Parameters
  • user (Optional[Union[int, str]]) – The user name or user ID whose global info is retrieved. Defaults to the current user.

  • force (bool) – Whether the cache should be discarded.

Returns

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

Raises

TypeError – Inappropriate argument type of ‘user’

Return type

Dict[str, Any]

get_parsed_page(page)[source]

Retrieve parsed text of the page using action=parse.

Changed in version 7.1: raises KeyError instead of AssertionError

Parameters

page (pywikibot.page._pages.BasePage) –

Return type

str

get_property_names(force=False)[source]

Get property names for pages_with_property().

Parameters

force (bool) – force to retrieve userinfo ignoring cache

Return type

List[str]

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 (bool) – Whether the cache should be discarded.

Returns

The namespaces which are searched by default.

Return type

Set[pywikibot.site._namespace.Namespace]

get_tokens(types, all=False)[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 also

API:Tokens

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

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

Return type

Dict[str, str]

return: a dict with retrieved valid tokens.

getcategoryinfo(category)[source]

Retrieve data on contents of category.

See also

API:Categoryinfo

Parameters

category (pywikibot.page._pages.Category) –

Return type

None

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 (as ‘yyyymmddhhmmss’)

Return type

str

getmagicwords(word)[source]

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

Parameters

word (str) –

Return type

List[str]

getredirtarget(page)[source]

Return page object for the redirect target of page.

Parameters

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

Returns

redirect target of page

Raises
Return type

pywikibot.page._pages.Page

property globaluserinfo: Dict[str, Any]

Retrieve globaluserinfo of the current user from site.

To get globaluserinfo for a given user or user ID use get_globaluserinfo() method instead

New in version 3.0.

has_all_mediawiki_messages(keys, lang=None)[source]

Confirm that the site defines a set of MediaWiki messages.

Parameters
  • keys (Iterable[str]) – names of MediaWiki messages

  • lang (Optional[str]) – a language code, default is self.lang

Return type

bool

property has_data_repository: bool

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.

See also

API:Userinfo

Parameters

group (str) –

Return type

bool

property has_image_repository: bool

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 (Optional[str]) – 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.

See also

API:Userinfo

Parameters

right (str) – a specific right to be validated

Return type

bool

image_repository()[source]

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

Return type

Optional[pywikibot.site._basesite.BaseSite]

interwiki(prefix)[source]

Return the site for a corresponding interwiki prefix.

Raises
Parameters

prefix (str) –

Return type

pywikibot.site._basesite.BaseSite

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 (pywikibot.site._basesite.BaseSite) – The targeted site, which might be it’s own.

Raises

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

Return type

List[str]

isBot(username)[source]

Return True is username is a bot user.

Parameters

username (str) –

Return type

bool

is_blocked(force=False)[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.

See also

API:Userinfo

New in version 7.0: The force parameter

Parameters

force (bool) – Whether the cache should be discarded.

Return type

bool

is_data_repository()[source]

Return True if its data repository is itself.

Return type

bool

is_image_repository()[source]

Return True if Site object is the image repository.

Return type

bool

is_locked(user=None, force=False)[source]

Return True when given user is locked globally.

New in version 7.0.

Parameters
  • user (Optional[Union[int, str]]) – The user name or user ID. Defaults to the current user.

  • force (bool) – Whether the cache should be discarded.

Return type

bool

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.

Return type

bool

property lang: str

Return the code for the language of this Site.

linktrail()[source]

Build linktrail regex from siteinfo linktrail.

Letters that can follow a wikilink and are regarded as part of this link. This depends on the linktrail setting in LanguageXx.php

New in version 7.3.

Returns

The linktrail regex.

Return type

str

list_to_text(args)[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 (Iterable[str]) – text to be expanded

Return type

str

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] API:Imageinfo

Parameters validation and error handling left to the API call.

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

  • url_width (Optional[int]) – see iiurlwidth in [1]

  • url_height (Optional[int]) – see iiurlheigth in [1]

  • url_param (Optional[str]) – see iiurlparam in [1]

  • page (pywikibot.page._filepage.FilePage) –

Return type

None

loadpageinfo(page, preload=False)[source]

Load page info from api and store in page attributes.

See also

API:Info

Parameters
Return type

None

loadpageprops(page)[source]

Load page props for the given page.

Parameters

page (pywikibot.page._pages.BasePage) –

Return type

None

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
Parameters

prefix (str) –

Return type

bool

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=False, user=None)[source]

Log the user in if not already logged in.

See also

API:Login

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

  • user (Optional[str]) – 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.

Return type

None

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.

See also

API:Logout

Raises

APIError – Logout is not available when OAuth enabled.

Return type

None

property logtypes: Set[str]

Return a set of log types available on current site.

property maxlimit: int

Get the maximum limit of pages to be retrieved.

New in version 7.0.

mediawiki_message(key, lang=None)[source]

Fetch the text for a MediaWiki message.

Parameters
  • key (str) – name of MediaWiki message

  • lang (Optional[str]) – a language code, default is self.lang

Return type

str

mediawiki_messages(keys, lang=None)[source]

Fetch the text of a set of MediaWiki messages.

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

See also

API:Allmessages

Parameters
  • keys (Iterable[str]) – MediaWiki messages to fetch

  • lang (Optional[str]) – a language code, default is self.lang

Return type

OrderedDict[str, str]

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

Merge revisions from one page into another.

See also

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.BasePage) – Source page from which revisions will be merged

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

  • timestamp (Optional[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[str]) – Optional reason for the history merge

Return type

None

messages()[source]

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

Return type

bool

property months_names: List[Tuple[str, str]]

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)

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

Move a Page to a new title.

See also

API:Move

Changed in version 7.2: The movesubpages parameter was added

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

  • newtitle (str) – the new title for the Page

  • summary (str) – edit summary (required!)

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

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

  • movesubpages (bool) – Rename subpages, if applicable.

Returns

Page object with the new title

Return type

pywikibot.page.Page

property mw_version: pywikibot.tools.MediaWikiVersion

Return self.version() as a MediaWikiVersion object.

Cache the result for 24 hours.

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 (bool) – If True return a Namespace object. Otherwise return the namespace name.

Returns

local name or Namespace object

Return type

Union[str, pywikibot.site._namespace.Namespace]

nice_get_address(title)[source]

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

Parameters

title (str) –

Return type

str

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
Raises

ValueError – invalid action parameter

Return type

bool

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.

Raises
Return type

Optional[pywikibot.page._pages.Page]

page_isredirect(page)[source]

Return True if and only if page is a redirect.

Parameters

page (pywikibot.page._pages.BasePage) –

Return type

bool

page_restrictions(page)[source]

Return a dictionary reflecting page protections.

Parameters

page (pywikibot.page._pages.BasePage) –

Return type

Dict[str, Tuple[str, str]]

pagename2codes()[source]

Return list of localized PAGENAMEE tags for the site.

Return type

List[str]

pagenamecodes()[source]

Return list of localized PAGENAME tags for the site.

Return type

List[str]

protect(page, protections, reason, expiry=None, **kwargs)[source]

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

See also

API:Protect

Parameters
  • protections (Dict[str, Optional[str]]) – 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 (str) – Reason for the action

  • expiry (Optional[Union[datetime.datetime, str]]) – 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.

  • page (pywikibot.page.BasePage) –

  • kwargs (Any) –

Return type

None

protection_levels()[source]

Return the protection levels available on this site.

See also

Siteinfo._get_default()

Returns

protection types available

Return type

Set[str]

protection_types()[source]

Return the protection types available on this site.

See also

Siteinfo._get_default()

Returns

protection types available

Return type

Set[str]

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

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

Parameters
  • pages (List[pywikibot.page.BasePage]) – list of Page objects

  • redirects (bool) – Automatically resolve redirects.

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

  • forcelinkupdate (bool) – Update the links tables.

  • forcerecursivelinkupdate (bool) – 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

Return type

bool

redirect()[source]

Return the localized #REDIRECT keyword.

Return type

str

property redirect_regex: Pattern[str]

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 also

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
Keyword Arguments

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

Return type

None

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

pywikibot.Timestamp

simple_request(**kwargs)[source]

Create a request by defining all kwargs as parameters.

Changed in version 7.1: _simple_request becomes a public method

Parameters

kwargs (Any) –

Return type

pywikibot.data.api.Request

property siteinfo: pywikibot.site._siteinfo.Siteinfo

Site information dict.

stash_info(file_key, props=None)[source]

Get the stash info for a given file key.

Parameters
  • file_key (str) –

  • props (Optional[List[str]]) –

Return type

Dict[str, Any]

unblockuser(user, reason=None)[source]

Remove the block for the user.

See also

API:Block

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

  • reason (Optional[str]) – Reason for the unblock.

Return type

Dict[str, Any]

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

Undelete page from the wiki. Requires appropriate privilege level.

See also

API:Undelete

New in version 6.1: renamed from undelete_page

Changed in version 6.1: fileids parameter was added, keyword argument required for revisions.

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

  • reason (str) – Undeletion reason.

  • revisions (Optional[List[str]]) – List of timestamps to restore. If None, restores all revisions.

  • fileids (Optional[List[Union[int, str]]]) – List of fileids to restore.

Return type

None

upload(filepage, **kwargs)[source]

Upload a file to the wiki.

See also

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.

For keyword arguments refer pywikibot.site._upload.Uploader

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

  • kwargs (Any) –

Returns

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

Return type

bool

property userinfo: Dict[str, Any]

Retrieve userinfo from site and store in _userinfo attribute.

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

See also

API:Userinfo

Returns

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)

validate_tokens(types)[source]

Validate if requested tokens are acceptable.

Valid tokens depend on mw version.

Parameters

types (List[str]) –

Return type

List[str]

version()[source]

Return live project version number as a string.

Use pywikibot.site.mw_version to compare MediaWiki versions.

Return type

str

watch(pages, unwatch=False)[source]

Add or remove pages from watchlist.

See also

API:Watch

Parameters
Returns

True if API returned expected response; False otherwise

Raises

KeyError – ‘watch’ isn’t in API response

Return type

bool

Objects representing API interface to MediaWiki site extenstions.

class pywikibot.site._extensions.EchoMixin[source]

Bases: object

APISite mixin for Echo extension.

notifications(**kwargs)[source]

Yield Notification objects from the Echo extension.

Keyword Arguments

format – If specified, notifications will be returned formatted this way. Its value is either ‘model’, ‘special’ or None. Default is ‘special’.

Refer API reference for other keywords.

notifications_mark_read(**kwargs)[source]

Mark selected notifications as read.

Returns

whether the action was successful

Return type

bool

class pywikibot.site._extensions.FlowMixin[source]

Bases: object

APISite mixin for Flow extension.

create_new_topic(page, title, content, content_format)[source]

Create a new topic on a Flow board.

Parameters
  • page (Board) – A Flow board

  • title (str) – The title of the new topic (must be in plaintext)

  • content (str) – The content of the topic’s initial post

  • content_format (str (either 'wikitext' or 'html')) – The content format of the supplied content

Returns

The metadata of the new topic

Return type

dict

delete_post(post, reason)[source]

Delete a Flow post.

Parameters
  • post (Post) – A Flow post

  • reason (str) – The reason to delete the post

Returns

Metadata returned by the API

Return type

dict

delete_topic(page, reason)[source]

Delete a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • reason (str) – The reason to delete the topic

Returns

Metadata returned by the API

Return type

dict

hide_post(post, reason)[source]

Hide a Flow post.

Parameters
  • post (Post) – A Flow post

  • reason (str) – The reason to hide the post

Returns

Metadata returned by the API

Return type

dict

hide_topic(page, reason)[source]

Hide a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • reason (str) – The reason to hide the topic

Returns

Metadata returned by the API

Return type

dict

load_board(page)[source]

Retrieve the data for a Flow board.

Parameters

page (Board) – A Flow board

Returns

A dict representing the board’s metadata.

Return type

dict

load_post_current_revision(page, post_id, content_format)[source]

Retrieve the data for a post to a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • post_id (str) – The UUID of the Post

  • content_format (str) – The content format used for the returned content; must be either ‘wikitext’, ‘html’, or ‘fixed-html’

Returns

A dict representing the post data for the given UUID.

Return type

dict

load_topic(page, content_format)[source]

Retrieve the data for a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • content_format (str) – The content format to request the data in. Must ne either ‘wikitext’, ‘html’, or ‘fixed-html’

Returns

A dict representing the topic’s data.

Return type

dict

load_topiclist(page, content_format='wikitext', limit=100, sortby='newest', toconly=False, offset=None, offset_id=None, reverse=False, include_offset=False)[source]

Retrieve the topiclist of a Flow board.

Parameters
  • page (Board) – A Flow board

  • content_format (str) – The content format to request the data in. must be either ‘wikitext’, ‘html’, or ‘fixed-html’

  • limit (int) – The number of topics to fetch in each request.

  • sortby (str) – Algorithm to sort topics by (‘newest’ or ‘updated’).

  • toconly (bool) – Whether to only include information for the TOC.

  • offset (Timestamp or equivalent str) – The timestamp to start at (when sortby is ‘updated’).

  • offset_id (str (in the form of a UUID)) – The topic UUID to start at (when sortby is ‘newest’).

  • reverse (bool) – Whether to reverse the topic ordering.

  • include_offset (bool) – Whether to include the offset topic.

Returns

A dict representing the board’s topiclist.

Return type

dict

lock_topic(page, lock, reason)[source]

Lock or unlock a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • lock (bool (True corresponds to locking the topic.)) – Whether to lock or unlock the topic

  • reason (str) – The reason to lock or unlock the topic

Returns

Metadata returned by the API

Return type

dict

moderate_post(post, state, reason)[source]

Moderate a Flow post.

Parameters
  • post (Post) – A Flow post

  • state (str) – The new moderation state

  • reason (str) – The reason to moderate the topic

Returns

Metadata returned by the API

Return type

dict

moderate_topic(page, state, reason)[source]

Moderate a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • state (str) – The new moderation state

  • reason (str) – The reason to moderate the topic

Returns

Metadata returned by the API

Return type

dict

reply_to_post(page, reply_to_uuid, content, content_format)[source]

Reply to a post on a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • reply_to_uuid (str) – The UUID of the Post to create a reply to

  • content (str) – The content of the reply

  • content_format (str) – The content format used for the supplied content; must be either ‘wikitext’ or ‘html’

Returns

Metadata returned by the API

Return type

dict

restore_post(post, reason)[source]

Restore a Flow post.

Parameters
  • post (Post) – A Flow post

  • reason (str) – The reason to restore the post

Returns

Metadata returned by the API

Return type

dict

restore_topic(page, reason)[source]

Restore a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • reason (str) – The reason to restore the topic

Returns

Metadata returned by the API

Return type

dict

suppress_post(post, reason)[source]

Suppress a Flow post.

Parameters
  • post (Post) – A Flow post

  • reason (str) – The reason to suppress the post

Returns

Metadata returned by the API

Return type

dict

suppress_topic(page, reason)[source]

Suppress a Flow topic.

Parameters
  • page (Topic) – A Flow topic

  • reason (str) – The reason to suppress the topic

Returns

Metadata returned by the API

Return type

dict

class pywikibot.site._extensions.GeoDataMixin[source]

Bases: object

APISite mixin for GeoData extension.

loadcoordinfo(page)[source]

Load [[mw:Extension:GeoData]] info.

Return type

None

class pywikibot.site._extensions.GlobalUsageMixin[source]

Bases: object

APISite mixin for Global Usage extension.

globalusage(page, total=None)[source]

Iterate global image usage for a given FilePage.

Parameters
  • page (pywikibot.FilePage) – the page to return global image usage for.

  • total – iterate no more than this number of pages in total.

Raises
class pywikibot.site._extensions.LinterMixin[source]

Bases: object

APISite mixin for Linter extension.

linter_pages(lint_categories=None, total=None, namespaces=None, pageids=None, lint_from=None)[source]

Return a generator to pages containing linter errors.

Parameters
  • lint_categories (an iterable that returns values (str), or a pipe-separated string of values.) – categories of lint errors

  • total (int) – if not None, yielding this many items in total

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces

  • pageids (an iterable that returns pageids (str or int), or a comma- or pipe-separated string of pageids (e.g. '945097,1483753, 956608' or '945097|483753|956608')) – only include lint errors from the specified pageids

  • lint_from (str representing digit or integer) – Lint ID to start querying from

Returns

pages with Linter errors.

Return type

Iterable[pywikibot.Page]

class pywikibot.site._extensions.PageImagesMixin[source]

Bases: object

APISite mixin for PageImages extension.

loadpageimage(page)[source]

Load [[mw:Extension:PageImages]] info.

Parameters

page (pywikibot.Page) – The page for which to obtain the image

Raises

APIError – PageImages extension is not installed

Return type

None

class pywikibot.site._extensions.ProofreadPageMixin[source]

Bases: object

APISite mixin for ProofreadPage extension.

property proofread_index_ns

Return Index namespace for the ProofreadPage extension.

property proofread_levels

Return Quality Levels for the ProofreadPage extension.

property proofread_page_ns

Return Page namespace for the ProofreadPage extension.

class pywikibot.site._extensions.TextExtractsMixin[source]

Bases: object

APISite mixin for TextExtracts extension.

New in version 7.1.

extract(page, *, chars=None, sentences=None, intro=True, plaintext=True)[source]

Retrieve an extract of a page.

Parameters
  • page (pywikibot.Page) – The Page object for which the extract is read

  • chars (Optional[int]) – How many characters to return. Actual text returned might be slightly longer.

  • sentences (Optional[int]) – How many sentences to return

  • intro (bool) – Return only content before the first section

  • plaintext (bool) – if True, return extracts as plain text instead of limited HTML

Return type

str

class pywikibot.site._extensions.ThanksFlowMixin[source]

Bases: object

APISite mixin for Thanks and Flow extension.

thank_post(post)[source]

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

Parameters

post (Post) – The post to be thanked for.

Raises

APIError – On thanking oneself or other API errors.

Returns

The API response.

class pywikibot.site._extensions.ThanksMixin[source]

Bases: object

APISite mixin for Thanks extension.

thank_revision(revid, source=None)[source]

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

Parameters
  • revid (int) – Revision ID for the revision to be thanked.

  • source (str) – A source for the thanking operation.

Raises

APIError – On thanking oneself or other API errors.

Returns

The API response.

class pywikibot.site._extensions.UrlShortenerMixin[source]

Bases: object

APISite mixin for UrlShortener extension.

Return a shortened link.

Note that on Wikimedia wikis only metawiki supports this action, and this wiki can process links to all WM domains.

Parameters

url (str) – The link to reduce, with propotol prefix.

Returns

The reduced link, without protocol prefix.

Return type

str

class pywikibot.site._extensions.WikibaseClientMixin[source]

Bases: object

APISite mixin for WikibaseClient extension.

unconnected_pages(total=None)[source]

Yield Page objects from Special:UnconnectedPages.

Parameters

total – number of pages to return

Objects representing API generators to MediaWiki site.

class pywikibot.site._generators.GeneratorsMixin[source]

Bases: object

API generators mixin to MediaWiki site.

allcategories(start='!', prefix='', total=None, reverse=False, content=False)[source]

Iterate categories used (which need not have a Category page).

Iterator yields Category objects. Note that, in practice, links that were found on pages that have been deleted may not have been removed from the database table, so this method can return false positives.

Parameters
  • start (str) – Start at this category title (category need not exist).

  • prefix (str) – Only yield categories starting with this string.

  • reverse (bool) – if True, iterate in reverse Unicode lexigraphic order (default: iterate in forward order)

  • content (bool) – if True, load the current content of each iterated page (default False); note that this means the contents of the category description page, not the pages that are members of the category

alldeletedrevisions(*, namespaces=None, reverse=False, content=False, total=None, **kwargs)[source]

Iterate all deleted revisions.

Parameters
  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – Only iterate pages in these namespaces

  • reverse (bool) – Iterate oldest revisions first (default: newest)

  • content (bool) – If True, retrieve the content of each revision

  • total (Optional[int]) – Number of revisions to retrieve

Keyword Arguments
  • from – Start listing at this title

  • to – Stop listing at this title

  • prefix – Search for all page titles that begin with this value

  • excludeuser – Exclude revisions by this user

  • tag – Only list revisions tagged with this tag

  • user – List revisions by this user

  • start – Iterate revisions starting at this Timestamp

  • end – Iterate revisions ending at this Timestamp

  • prop – Which properties to get. Defaults are ids, timestamp, flags, user, and comment (if you have the right to view).

Return type

Iterable[Dict[str, Any]]

allimages(start='!', prefix='', minsize=None, maxsize=None, reverse=False, sha1=None, sha1base36=None, total=None, content=False)[source]

Iterate all images, ordered by image title.

Yields FilePages, but these pages need not exist on the wiki.

See also

API:Allimages

Parameters
  • start (str) – start at this title (name need not exist)

  • prefix (str) – only iterate titles starting with this substring

  • minsize – only iterate images of at least this many bytes

  • maxsize – only iterate images of no more than this many bytes

  • reverse (bool) – if True, iterate in reverse lexigraphic order

  • sha1 – only iterate image (it is theoretically possible there could be more than one) with this sha1 hash

  • sha1base36 – same as sha1 but in base 36

  • content (bool) – if True, load the current content of each iterated page (default False); note that this means the content of the image description page, not the image itself

Iterate all links to pages (which need not exist) in one namespace.

Note that, in practice, links that were found on pages that have been deleted may not have been removed from the links table, so this method can return false positives.

See also

API:Alllinks

Parameters
  • start (str) – Start at this title (page need not exist).

  • prefix (str) – Only yield pages starting with this string.

  • namespace (int or Namespace) – Iterate pages from this (single) namespace

  • unique (bool) – If True, only iterate each link title once (default: iterate once for each linking page)

  • fromids (bool) – if True, include the pageid of the page containing each link (default: False) as the ‘_fromid’ attribute of the Page; cannot be combined with unique

Raises
  • KeyError – the namespace identifier was not resolved

  • TypeError – the namespace identifier has an inappropriate type such as bool, or an iterable with more than one namespace

allpages(start='!', prefix='', namespace=0, filterredir=None, filterlanglinks=None, minsize=None, maxsize=None, protect_type=None, protect_level=None, reverse=False, total=None, content=False)[source]

Iterate pages in a single namespace.

See also

API:Allpages

Parameters
  • start (str) – Start at this title (page need not exist).

  • prefix (str) – Only yield pages starting with this string.

  • namespace (int or Namespace.) – Iterate pages from this (single) namespace

  • filterredir – if True, only yield redirects; if False (and not None), only yield non-redirects (default: yield both)

  • filterlanglinks – if True, only yield pages with language links; if False (and not None), only yield pages without language links (default: yield both)

  • minsize – if present, only yield pages at least this many bytes in size

  • maxsize – if present, only yield pages at most this many bytes in size

  • protect_type (str) – only yield pages that have a protection of the specified type

  • protect_level – only yield pages that have protection at this level; can only be used if protect_type is specified

  • reverse (bool) – if True, iterate in reverse Unicode lexigraphic order (default: iterate in forward order)

  • content (bool) – if True, load the current content of each iterated page (default False)

Raises
  • KeyError – the namespace identifier was not resolved

  • TypeError – the namespace identifier has an inappropriate type such as bool, or an iterable with more than one namespace

allusers(start='!', prefix='', group=None, total=None)[source]

Iterate registered users, ordered by username.

Iterated values are dicts containing ‘name’, ‘editcount’, ‘registration’, and (sometimes) ‘groups’ keys. ‘groups’ will be present only if the user is a member of at least 1 group, and will be a list of str; all the other values are str and should always be present.

See also

API:Allusers

Parameters
  • start (str) – start at this username (name need not exist)

  • prefix (str) – only iterate usernames starting with this substring

  • group (str) – only iterate users that are members of this group

ancientpages(total=None)[source]

Yield Pages, datestamps from Special:Ancientpages.

Parameters

total – number of pages to return

blocks(starttime=None, endtime=None, reverse=False, blockids=None, users=None, iprange=None, total=None)[source]

Iterate all current blocks, in order of creation.

The iterator yields dicts containing keys corresponding to the block properties.

See also

API:Blocks

Note

logevents only logs user blocks, while this method iterates all blocks including IP ranges.

Warning

iprange parameter cannot be used together with users.

Parameters
  • starttime (pywikibot.Timestamp) – start iterating at this Timestamp

  • endtime (pywikibot.Timestamp) – stop iterating at this Timestamp

  • reverse (bool) – if True, iterate oldest blocks first (default: newest)

  • blockids (str, tuple or list) – only iterate blocks with these id numbers. Numbers must be separated by ‘|’ if given by a str.

  • users (str, tuple or list) – only iterate blocks affecting these usernames or IPs

  • iprange (Optional[str]) – a single IP or an IP range. Ranges broader than IPv4/16 or IPv6/19 are not accepted.

  • total (Optional[int]) – total amount of block entries

botusers(total=None)[source]

Iterate bot users.

Iterated values are dicts containing ‘name’, ‘userid’, ‘editcount’, ‘registration’, and ‘groups’ keys. ‘groups’ will be present only if the user is a member of at least 1 group, and will be a list of str; all the other values are str and should always be present.

broken_redirects(total=None)[source]

Yield Pages with broken redirects from Special:BrokenRedirects.

Parameters

total – number of pages to return

categorymembers(category, *, namespaces=None, sortby=None, reverse=False, starttime=None, endtime=None, total=None, content=False, member_type=None, startprefix=None, endprefix=None)[source]

Iterate members of specified category.

Parameters
  • category – The Category to iterate.

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – If present, only return category members from these namespaces. To yield subcategories or files, use parameter member_type instead.

  • sortby (Optional[str]) – determines the order in which results are generated, valid values are “sortkey” (default, results ordered by category sort key) or “timestamp” (results ordered by time page was added to the category)

  • reverse (bool) – if True, generate results in reverse order (default False)

  • starttime (pywikibot.Timestamp) – if provided, only generate pages added after this time; not valid unless sortby=”timestamp”

  • endtime – if provided, only generate pages added before this time; not valid unless sortby=”timestamp”

  • startprefix (Optional[str]) – if provided, only generate pages >= this title lexically; not valid if sortby=”timestamp”

  • endprefix (Optional[str]) – if provided, only generate pages < this title lexically; not valid if sortby=”timestamp”

  • content (bool) – if True, load the current content of each iterated page (default False)

  • member_type (str or iterable of str; values: page, subcat, file) – member type; if member_type includes ‘page’ and is used in conjunction with sortby=”timestamp”, the API may limit results to only pages in the first 50 namespaces.

  • total (Optional[int]) –

Return type

Iterable[pywikibot.Page]

Raises
  • KeyError – a namespace identifier was not resolved

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

deadendpages(total=None)[source]

Yield Page objects retrieved from Special:Deadendpages.

Parameters

total – number of pages to return

deletedrevs(titles=None, start=None, end=None, reverse=False, content=False, total=None, **kwargs)[source]

Iterate deleted revisions.

Each value returned by the iterator will be a dict containing the ‘title’ and ‘ns’ keys for a particular Page and a ‘revisions’ key whose value is a list of revisions in the same format as recentchanges plus a ‘content’ element with key ‘*’ if requested when ‘content’ parameter is set. For older wikis a ‘token’ key is also given with the content request.

Parameters
  • titles (str (multiple titles delimited with '|') or pywikibot.Page or Iterable[pywikibot.Page] or Iterable[str]) – The page titles to check for deleted revisions

  • reverse (bool) –

  • content (bool) –

Keyword Arguments

revids – Get revisions by their ID

Note

either titles or revids must be set but not both

Parameters
  • start – Iterate revisions starting at this Timestamp

  • end – Iterate revisions ending at this Timestamp

  • reverse (bool) – Iterate oldest revisions first (default: newest)

  • content (bool) – If True, retrieve the content of each revision

  • total – number of revisions to retrieve

Keyword Arguments
  • user – List revisions by this user

  • excludeuser – Exclude revisions by this user

  • tag – Only list revision tagged with this tag

  • prop – Which properties to get. Defaults are ids, user, comment, flags and timestamp

double_redirects(total=None)[source]

Yield Pages with double redirects from Special:DoubleRedirects.

Parameters

total – number of pages to return

exturlusage(url=None, protocol=None, namespaces=None, total=None, content=False)[source]

Iterate Pages that contain links to the given URL.

See also

API:Exturlusage

Parameters
  • url (Optional[str]) – The URL to search for (with or without the protocol prefix); this may include a ‘*’ as a wildcard, only at the start of the hostname

  • namespaces (list of int) – list of namespace numbers to fetch contribs from

  • total (Optional[int]) – Maximum number of pages to retrieve in total

  • protocol (Optional[str]) – Protocol to search for, likely http or https, http by default. Full list shown on Special:LinkSearch wikipage

  • content (bool) –

filearchive(start=None, end=None, reverse=False, total=None, **kwargs)[source]

Iterate archived files.

Yields dict of file archive informations.

See also

API:filearchive

Parameters
  • start – start at this title (name need not exist)

  • end – end at this title (name need not exist)

  • reverse (bool) – if True, iterate in reverse lexigraphic order

  • total – maximum number of pages to retrieve in total

Keyword Arguments
  • prefix – only iterate titles starting with this substring

  • sha1 – only iterate image with this sha1 hash

  • sha1base36 – same as sha1 but in base 36

  • prop – Image information to get. Default is timestamp

imageusage(image, *, namespaces=None, filterredir=None, total=None, content=False)[source]

Iterate Pages that contain links to the given FilePage.

See also

API:Imageusage

Changed in version 7.2: all parameters except image are keyword only.

Parameters
  • image (pywikibot.page._filepage.FilePage) – the image to search for (FilePage need not exist on the wiki)

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – If present, only iterate pages in these namespaces

  • filterredir (Optional[bool]) – if True, only yield redirects; if False (and not None), only yield non-redirects (default: yield both)

  • total (Optional[int]) – iterate no more than this number of pages in total

  • content (bool) – if True, load the current content of each iterated page (default False)

Raises
  • KeyError – a namespace identifier was not resolved

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

load_pages_from_pageids(pageids)[source]

Return a page generator from pageids.

Pages are iterated in the same order than in the underlying pageids.

Pageids are filtered and only one page is returned in case of duplicate pageids.

Parameters

pageids – an iterable that returns pageids (str or int), or a comma- or pipe-separated string of pageids (e.g. ‘945097,1483753, 956608’ or ‘945097|483753|956608’)

loadrevisions(page, *, content=False, section=None, **kwargs)[source]

Retrieve revision information and store it in page object.

By default, retrieves the last (current) revision of the page, unless any of the optional parameters revids, startid, endid, starttime, endtime, rvdir, user, excludeuser, or total are specified. Unless noted below, all parameters not specified default to False.

If rvdir is False or not specified, startid must be greater than endid if both are specified; likewise, starttime must be greater than endtime. If rvdir is True, these relationships are reversed.

See also

API:Revisions

Parameters
  • page (pywikibot.Page) – retrieve revisions of this Page and hold the data.

  • content (bool) – if True, retrieve the wiki-text of each revision; otherwise, only retrieve the revision metadata (default)

  • section (int) – if specified, retrieve only this section of the text (content must be True); section must be given by number (top of the article is section 0), not name

Keyword Arguments
  • revids – retrieve only the specified revision ids (raise Exception if any of revids does not correspond to page)

  • startid – retrieve revisions starting with this revid

  • endid – stop upon retrieving this revid

  • starttime – retrieve revisions starting at this Timestamp

  • endtime – stop upon reaching this Timestamp

  • rvdir – if false, retrieve newest revisions first (default); if true, retrieve oldest first

  • user – retrieve only revisions authored by this user

  • excludeuser – retrieve all revisions not authored by this user

  • total – number of revisions to retrieve

Raises
  • ValueError – invalid startid/endid or starttime/endtime values

  • pywikibot.exceptions.Error – revids belonging to a different page

logevents(logtype=None, user=None, page=None, namespace=None, start=None, end=None, reverse=False, tag=None, total=None)[source]

Iterate all log entries.

See also

API:Logevents

Note

logevents with logtype='block' only logs user blocks whereas site.blocks iterates all blocks including IP ranges.

Parameters
  • logtype (Optional[str]) – only iterate entries of this type (see mediawiki api documentation for available types)

  • user (Optional[str]) – only iterate entries that match this user name

  • page (pywikibot.Page or str) – only iterate entries affecting this page

  • namespace (int or Namespace or an iterable of them) – namespace(s) to retrieve logevents from

  • reverse (bool) –

  • tag (Optional[str]) –

  • total (Optional[int]) –

Note

due to an API limitation, if namespace param contains multiple namespaces, log entries from all namespaces will be fetched from the API and will be filtered later during iteration.

Parameters
  • start (Timestamp or ISO date string) – only iterate entries from and after this Timestamp

  • end (Timestamp or ISO date string) – only iterate entries up to and through this Timestamp

  • reverse (bool) – if True, iterate oldest entries first (default: newest)

  • tag (Optional[str]) – only iterate entries tagged with this tag

  • total (Optional[int]) – maximum number of events to iterate

  • logtype (Optional[str]) –

  • user (Optional[str]) –

Return type

iterable

Raises
  • KeyError – the namespace identifier was not resolved

  • TypeError – the namespace identifier has an inappropriate type such as bool, or an iterable with more than one namespace

lonelypages(total=None)[source]

Yield Pages retrieved from Special:Lonelypages.

Parameters

total – number of pages to return

longpages(total=None)[source]

Yield Pages and lengths from Special:Longpages.

Yields a tuple of Page object, length(int).

Parameters

total – number of pages to return

newpages(user=None, returndict=False, start=None, end=None, reverse=False, bot=False, redirect=False, excludeuser=None, patrolled=None, namespaces=None, total=None)[source]

Yield new articles (as Page objects) from recent changes.

Starts with the newest article and fetches the number of articles specified in the first argument.

The objects yielded are dependent on parameter returndict. When true, it yields a tuple composed of a Page object and a dict of attributes. When false, it yields a tuple composed of the Page object, timestamp (str), length (int), an empty string, username or IP address (str), comment (str).

Parameters
  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces

  • returndict (bool) –

  • reverse (bool) –

  • bot (bool) –

  • redirect (bool) –

Raises
  • KeyError – a namespace identifier was not resolved

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

page_embeddedin(page, *, filter_redirects=None, namespaces=None, total=None, content=False)[source]

Iterate all pages that embedded the given page as a template.

See also

API:Embeddedin

Parameters
  • page – The Page to get inclusions for.

  • filter_redirects – If True, only return redirects that embed the given page. If False, only return non-redirect links. If None, return both (no filtering).

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – If present, only return links from the namespaces in this list.

  • content (bool) – if True, load the current content of each iterated page (default False)

Return type

Iterable[pywikibot.Page]

Raises
  • KeyError – a namespace identifier was not resolved

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

Iterate all external links on page, yielding URL strings.

See also

API:Extlinks

page_redirects(page, *, filter_fragments=None, namespaces=None, total=None, content=False)[source]

Iterale all redirects to the given page.

See also

API:Redirects

New in version 7.0.

Parameters
  • page (pywikibot.Page) – The Page to get redirects for.

  • filter_fragments (Optional[bool]) – If True, only return redirects with fragments. If False, only return redirects without fragments. If None, return both (no filtering).

  • namespaces (Optional[Union[int, str, Namespace, Iterable[Union[int, str, Namespace]]]]) – Only return redirects from the namespaces

  • total (Optional[int]) – maximum number of redirects to retrieve in total

  • content (bool) – load the current content of each redirect

Return type

Iterable[pywikibot.Page]

Iterate all pages that link to the given page.

See also

API:Backlinks

Parameters
  • page – The Page to get links to.

  • follow_redirects (bool) – Also return links to redirects pointing to the given page.

  • filter_redirects – If True, only return redirects to the given page. If False, only return non-redirect links. If None, return both (no filtering).

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – If present, only return links from the namespaces in this list.

  • total – Maximum number of pages to retrieve in total.

  • content (bool) – if True, load the current content of each iterated page (default False)

Return type

Iterable[pywikibot.Page]

Raises
  • KeyError – a namespace identifier was not resolved

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

pagecategories(page, *, total=None, content=False)[source]

Iterate categories to which page belongs.

See also

API:Categories

Parameters

content (bool) – if True, load the current content of each iterated page (default False); note that this means the contents of the category description page, not the pages contained in the category

pageimages(page, *, total=None, content=False)[source]

Iterate images used (not just linked) on the page.

See also

API:Images

Parameters

content (bool) – if True, load the current content of each iterated page (default False); note that this means the content of the image description page, not the image itself

Iterate all interlanguage links on page, yielding Link objects.

Changed in version 6.2:: include_empty_titles parameter was added.

See also

API:Langlinks

Parameters
  • include_obsolete (bool) – if true, yield even Link objects whose site is obsolete

  • include_empty_titles (bool) – if true, yield even Link objects whose title is empty but redirects to a site like [[en:]]

  • total (Optional[int]) –

Iterate internal wikilinks contained (or transcluded) on page.

See also

API:Links

Parameters
  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – Only iterate pages in these namespaces (default: all)

  • follow_redirects (bool) – if True, yields the target of any redirects, rather than the redirect page

  • total (Optional[int]) – iterate no more than this number of pages in total

  • content (bool) – if True, load the current content of each iterated page

Raises
  • KeyError – a namespace identifier was not resolved

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

Return type

Generator[pywikibot.page._pages.Page, None, None]

pagereferences(page, *, follow_redirects=False, filter_redirects=None, with_template_inclusion=True, only_template_inclusion=False, namespaces=None, total=None, content=False)[source]

Convenience method combining pagebacklinks and page_embeddedin.

Parameters
  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – If present, only return links from the namespaces in this list.

  • follow_redirects (bool) –

  • with_template_inclusion (bool) –

  • only_template_inclusion (bool) –

  • content (bool) –

Return type

Iterable[pywikibot.Page]

Raises
  • KeyError – a namespace identifier was not resolved

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

pages_with_property(propname, *, total=None)[source]

Yield Page objects from Special:PagesWithProp.

Parameters
  • propname (str) – must be a valid property.

  • total (Optional[int]) – number of pages to return

Returns

return a generator of Page objects

Return type

iterator

pagetemplates(page, *, namespaces=None, total=None, content=False)[source]

Iterate templates transcluded (not just linked) on the page.

See also

API:Templates

Parameters
  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – Only iterate pages in these namespaces

  • content (bool) – if True, load the current content of each iterated page (default False)

Raises
  • KeyError – a namespace identifier was not resolved

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

patrol(rcid=None, revid=None, revision=None)[source]

Return a generator of patrolled pages.

See also

API:Patrol

Pages to be patrolled are identified by rcid, revid or revision. At least one of the parameters is mandatory. See https://www.mediawiki.org/wiki/API:Patrol.

Parameters
  • rcid (iterable/iterator which returns a number or string which contains only digits; it also supports a string (as above) or int) – an int/string/iterable/iterator providing rcid of pages to be patrolled.

  • revid (iterable/iterator which returns a number or string which contains only digits; it also supports a string (as above) or int.) – an int/string/iterable/iterator providing revid of pages to be patrolled.

  • revision (iterable/iterator which returns a Revision object; it also supports a single Revision.) – an Revision/iterable/iterator providing Revision object of pages to be patrolled.

Return type

iterator of dict with ‘rcid’, ‘ns’ and ‘title’ of the patrolled page.

preloadpages(pagelist, *, groupsize=50, templates=False, langlinks=False, pageprops=False)[source]

Return a generator to a list of preloaded pages.

Pages are iterated in the same order than in the underlying pagelist. In case of duplicates in a groupsize batch, return the first entry.

Parameters
  • pagelist – an iterable that returns Page objects

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

  • templates (bool) – preload pages (typically templates) transcluded in the provided pages

  • langlinks (bool) – preload all language links from the provided pages to other languages

  • pageprops (bool) – preload various properties defined in page content

protectedpages(namespace=0, type='edit', level=False, total=None)[source]

Return protected pages depending on protection level and type.

For protection types which aren’t ‘create’ it uses APISite.allpages, while it uses for ‘create’ the ‘query+protectedtitles’ module.

Parameters
  • namespace (int or Namespace or str) – The searched namespace.

  • type (str) – The protection type to search for (default ‘edit’).

  • level (Union[str, bool]) – The protection level (like ‘autoconfirmed’). If False it shows all protection levels.

Returns

The pages which are protected.

Return type

Iterable[pywikibot.Page]

querypage(special_page, total=True)[source]

Yield Page objects retrieved from Special:{special_page}.

See also

API:Querypage

Generic function for all special pages supported by the site MW API.

Parameters
  • special_page – Special page to query

  • total – number of pages to return

Raises

AssertionError – special_page is not supported in SpecialPages.

randompages(total=None, namespaces=None, redirects=False, content=False)[source]

Iterate a number of random pages.

Pages are listed in a fixed sequence, only the starting point is random.

Parameters
  • total – the maximum number of pages to iterate

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces.

  • redirects (Optional[bool]) – if True, include only redirect pages in results, False does not include redirects and None (MW 1.26+) include both types. (default: False)

  • content (bool) – if True, load the current content of each iterated page (default False)

Raises
  • KeyError – a namespace identifier was not resolved

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

  • AssertError – unsupported redirects parameter

recentchanges(*, start=None, end=None, reverse=False, namespaces=None, changetype=None, minor=None, bot=None, anon=None, redirect=None, patrolled=None, top_only=False, total=None, user=None, excludeuser=None, tag=None)[source]

Iterate recent changes.

Parameters
  • start (pywikibot.Timestamp) – Timestamp to start listing from

  • end (pywikibot.Timestamp) – Timestamp to end listing at

  • reverse (bool) – if True, start with oldest changes (default: newest)

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces

  • changetype (Optional[str]) – only iterate changes of this type (“edit” for edits to existing pages, “new” for new pages, “log” for log entries)

  • minor (Optional[bool]) – if True, only list minor edits; if False, only list non-minor edits; if None, list all

  • bot (Optional[bool]) – if True, only list bot edits; if False, only list non-bot edits; if None, list all

  • anon (Optional[bool]) – if True, only list anon edits; if False, only list non-anon edits; if None, list all

  • redirect (Optional[bool]) – if True, only list edits to redirect pages; if False, only list edits to non-redirect pages; if None, list all

  • patrolled (Optional[bool]) – if True, only list patrolled edits; if False, only list non-patrolled edits; if None, list all

  • top_only (bool) – if True, only list changes that are the latest revision (default False)

  • user (Optional[Union[str, List[str]]]) – if not None, only list edits by this user or users

  • excludeuser (Optional[Union[str, List[str]]]) – if not None, exclude edits by this user or users

  • tag (Optional[str]) – a recent changes tag

  • total (Optional[int]) –

Raises
  • KeyError – a namespace identifier was not resolved

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

redirectpages(total=None)[source]

Yield redirect pages from Special:ListRedirects.

Parameters

total – number of pages to return

search(searchstring, *, namespaces=None, where=None, total=None, content=False)[source]

Iterate Pages that contain the searchstring.

Note that this may include non-existing Pages if the wiki’s database table contains outdated entries.

Changed in version 7.0: Default of where parameter has been changed from ‘text’ to None. The behaviour depends on the installed search engine which is ‘text’ on CirrusSearch’. raises APIError instead of Error if searchstring is not set or what parameter is wrong.

See also

API:Search

Parameters
  • searchstring (str) – the text to search for

  • where (Optional[str]) – Where to search; value must be “text”, “title”, “nearmatch” or None (many wikis do not support all search types)

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – search only in these namespaces (defaults to all)

  • content (bool) – if True, load the current content of each iterated page (default False)

  • total (Optional[int]) –

Raises
  • KeyError – a namespace identifier was not resolved

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

  • APIError – The “gsrsearch” parameter must be set: searchstring parameter is not set

  • APIError – Unrecognized value for parameter “gsrwhat”: wrong where parameter is given

shortpages(total=None)[source]

Yield Pages and lengths from Special:Shortpages.

Yields a tuple of Page object, length(int).

Parameters

total – number of pages to return

uncategorizedcategories(total=None)[source]

Yield Categories from Special:Uncategorizedcategories.

Parameters

total – number of pages to return

uncategorizedfiles(total=None)

Yield FilePages from Special:Uncategorizedimages.

Parameters

total – number of pages to return

uncategorizedimages(total=None)[source]

Yield FilePages from Special:Uncategorizedimages.

Parameters

total – number of pages to return

uncategorizedpages(total=None)[source]

Yield Pages from Special:Uncategorizedpages.

Parameters

total – number of pages to return

uncategorizedtemplates(total=None)[source]

Yield Pages from Special:Uncategorizedtemplates.

Parameters

total – number of pages to return

unusedcategories(total=None)[source]

Yield Category objects from Special:Unusedcategories.

Parameters

total – number of pages to return

unusedfiles(total=None)[source]

Yield FilePage objects from Special:Unusedimages.

Parameters

total – number of pages to return

unwatchedpages(total=None)[source]

Yield Pages from Special:Unwatchedpages (requires Admin privileges).

Parameters

total – number of pages to return

usercontribs(user=None, userprefix=None, start=None, end=None, reverse=False, namespaces=None, minor=None, total=None, top_only=False)[source]

Iterate contributions by a particular user.

Iterated values are in the same format as recentchanges.

See also

API:Usercontribs

Parameters
  • user – Iterate contributions by this user (name or IP)

  • userprefix – Iterate contributions by all users whose names or IPs start with this substring

  • start – Iterate contributions starting at this Timestamp

  • end – Iterate contributions ending at this Timestamp

  • reverse (bool) – Iterate oldest contributions first (default: newest)

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces

  • minor – if True, iterate only minor edits; if False and not None, iterate only non-minor edits (default: iterate both)

  • total (Optional[int]) – limit result to this number of pages

  • top_only (bool) – if True, iterate only edits which are the latest revision (default: False)

Raises
  • pywikibot.exceptions.Error – either user or userprefix must be non-empty

  • KeyError – a namespace identifier was not resolved

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

users(usernames)[source]

Iterate info about a list of users by name or IP.

See also

API:Users

Parameters

usernames (list, or other iterable, of str) – a list of user names

wantedcategories(total=None)[source]

Yield Pages from Special:Wantedcategories.

Parameters

total – number of pages to return

wantedfiles(total=None)[source]

Yield Pages from Special:Wantedfiles.

Parameters

total – number of pages to return

wantedpages(total=None)[source]

Yield Pages from Special:Wantedpages.

Parameters

total – number of pages to return

wantedtemplates(total=None)[source]

Yield Pages from Special:Wantedtemplates.

Parameters

total – number of pages to return

watched_pages(force=False, total=None)[source]

Return watchlist.

See also

API:Watchlistraw

Parameters
  • force (bool) – Reload watchlist

  • total (int) – if not None, limit the generator to yielding this many items in total

Returns

list of pages in watchlist

Return type

list of pywikibot.Page objects

watchlist_revs(start=None, end=None, reverse=False, namespaces=None, minor=None, bot=None, anon=None, total=None)[source]

Iterate revisions to pages on the bot user’s watchlist.

Iterated values will be in same format as recentchanges.

See also

API:Watchlist

Parameters
  • start – Iterate revisions starting at this Timestamp

  • end – Iterate revisions ending at this Timestamp

  • reverse (bool) – Iterate oldest revisions first (default: newest)

  • namespaces (iterable of str or Namespace key, or a single instance of those types. May be a '|' separated list of namespace identifiers.) – only iterate pages in these namespaces

  • minor – if True, only list minor edits; if False (and not None), only list non-minor edits

  • bot – if True, only list bot edits; if False (and not None), only list non-bot edits

  • anon – if True, only list anon edits; if False (and not None), only list non-anon edits

Raises
  • KeyError – a namespace identifier was not resolved

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

withoutinterwiki(total=None)[source]

Yield Pages without language links from Special:Withoutinterwiki.

Parameters

total – number of pages to return

DataSite Package

Objects representing API interface to Wikibase site.

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

Bases: pywikibot.site._apisite.APISite

Wikibase data capable site.

Return type

None

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

Return type

None

add_form(lexeme, form, *, bot=True, baserevid=None)[source]

Add a form.

Parameters
Keyword Arguments
  • bot – Whether to mark the edit as a bot edit

  • baserevid – Base revision id override, used to detect conflicts.

Return type

dict

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) – An optional snaktype (‘value’, ‘novalue’ or ‘somevalue’). 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, **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

editQualifier(claim, qualifier, new=False, bot=True, summary=None)[source]

Create/Edit a qualifier.

Changed in version 7.0: deprecated baserevid parameter was removed

Parameters
  • claim (pywikibot.Claim) – A Claim object to add the qualifier to

  • qualifier (pywikibot.Claim) – A Claim object to be used as a qualifier

  • new (bool) – Whether to create a new one if the “qualifier” already exists

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

  • summary (Optional[str]) – Edit summary

editSource(claim, source, new=False, bot=True, summary=None)[source]

Create/Edit a source.

Changed in version 7.0: deprecated baserevid parameter was removed

Parameters
  • claim (pywikibot.Claim) – A Claim object to add the source to

  • source (pywikibot.Claim) – A Claim object to be used as a source

  • new (bool) – Whether to create a new one if the “source” already exists

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

  • summary (Optional[str]) – Edit summary

edit_form_elements(form, data, *, bot=True, baserevid=None)[source]

Edit lexeme form elements.

Parameters
Keyword Arguments
  • bot – Whether to mark the edit as a bot edit

  • baserevid – Base revision id override, used to detect conflicts.

Returns

New form 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)[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

mergeLexemes(from_lexeme, to_lexeme, summary=None, *, bot=True)[source]

Merge two lexemes together.

Parameters
Keyword Arguments

bot – 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

removeClaims(claims, bot=True, summary=None)[source]

Remove claims.

Changed in version 7.0: deprecated baserevid parameter was removed

Parameters
  • claims (List[pywikibot.Claim]) – Claims to be removed

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

  • summary (str) – Edit summary

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

Remove sources.

Changed in version 7.0: deprecated baserevid parameter was removed

Parameters
  • claim (pywikibot.Claim) – A Claim object to remove the sources from

  • sources (list) – A list of Claim objects that are sources

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

  • summary (Optional[str]) – Edit summary

remove_form(form, *, bot=True, baserevid=None)[source]

Remove a form.

Parameters
Keyword Arguments
  • bot – Whether to mark the edit as a bot edit

  • baserevid – Base revision id override, used to detect conflicts.

Return type

dict

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

Remove qualifiers.

Changed in version 7.0: deprecated baserevid parameter was removed

Parameters
  • claim (pywikibot.Claim) – A Claim object to remove the qualifier from

  • qualifiers (List[pywikibot.Claim]) – Claim objects currently used as a qualifiers

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

  • summary (Optional[str]) – Edit summary

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, language, total=None, **kwargs)[source]

Search for pages or properties that contain the given text.

Parameters
  • search (str) – Text to find.

  • language (str) – Language to search in.

  • total (Optional[int]) – 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

Obsolete Sites Package

Objects representing obsolete MediaWiki sites.

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

Bases: pywikibot.site._apisite.APISite

Site closed to read-only mode.

Return type

None

is_uploaddisabled()[source]

Return True if upload is disabled on site.

Return type

bool

newpages(**kwargs)[source]

An error instead of pointless API call.

Return type

None

page_restrictions(page)[source]

Return a dictionary reflecting page protections.

Parameters

page (pywikibot.page._pages.Page) –

Return type

Dict[str, Tuple[str, str]]

recentchanges(**kwargs)[source]

An error instead of pointless API call.

Return type

None

class pywikibot.site._obsoletesites.RemovedSite(code, 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)

Return type

None

Siteinfo Package

Objects representing site info data contents.

class pywikibot.site._siteinfo.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.

Return type

None

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["\\\']: (.+?)\\.?$')
clear()[source]

Remove all items from Siteinfo.

Return type

None

get(key, get_default=True, cache=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 (str) – The name of the siteinfo property.

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

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

  • expiry (Union[datetime.datetime, float, bool]) – 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

Raises

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

See

_get_siteinfo

Return type

Any

get_requested_time(key)[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 (str) – 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_cached(key)[source]

Return whether the value is cached.

New in version 7.1.

Parameters

key (str) –

Return type

bool

is_recognised(key)[source]

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

Parameters

key (str) –

Return type

Optional[bool]

Namespace Package

Objects representing Namespaces of MediaWiki site.

class pywikibot.site._namespace.BuiltinNamespace(value)[source]

Bases: enum.IntEnum

Builtin namespace enum.

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
property canonical: str

Canonical form of MediaWiki built-in namespace.

New in version 7.1.

class pywikibot.site._namespace.Namespace(id, canonical_name=None, custom_name=None, aliases=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 (Optional[str]) – Canonical name

  • custom_name (Optional[str]) – Name defined in server LocalSettings.php

  • aliases (Optional[List[str]]) – Aliases

Return type

None

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.

Parameters

case (str) –

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._namespace.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.

Return type

None

lookup_name(name)[source]

Find the Namespace for a name also checking aliases.

Parameters

name (str) – Name of the namespace.

Return type

Optional[pywikibot.site._namespace.Namespace]

lookup_normalized_name(name)[source]

Find the Namespace for a name also checking aliases.

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

Parameters

name (str) – Name of the namespace.

Return type

Optional[pywikibot.site._namespace.Namespace]

resolve(identifiers)[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

Return type

List[pywikibot.site._namespace.Namespace]

TokenWallet Package

Objects representing api tokens.

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

Bases: object

Container for tokens.

Return type

None

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.

Return type

None

Uploader Package

Objects representing API upload to MediaWiki site.

class pywikibot.site._upload.Uploader(site, filepage, *, source_filename=None, source_url=None, comment=None, text=None, watch=False, chunk_size=0, asynchronous=False, ignore_warnings=False, report_success=None)[source]

Bases: object

Uploader class to upload a file to the wiki.

New in version 7.1.

Parameters
  • site (pywikibot.site.APISite) – The current site to work on

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

  • source_filename (Optional[str]) – path to the file to be uploaded

  • source_url (Optional[str]) – URL of the file to be uploaded

  • comment (Optional[str]) – 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 (Optional[str]) – Initial page text; if this is not set, then filepage.text will be used, or comment.

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

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

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

  • 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.

  • report_success (Optional[bool]) – 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.

Return type

None

upload()[source]

Check for required parameters to upload and run the job.

Returns

Whether the upload was successful.

Return type

bool