pywikibot.page package

Objects representing various types of MediaWiki, including Wikibase, pages.

This module also includes objects:

• Property: a type of semantic data.

• Claim: an instance of a semantic assertion.

• Revision: a single change to a wiki page.

• FileInfo: a structure holding imageinfo of latest rev. of FilePage

• Link: an internal or interwiki link in wikitext.

class pywikibot.page.BaseLink(title: str, namespace=None, site=None)

Bases: pywikibot.tools.ComparableMixin

A MediaWiki link (local or interwiki).

Has the following attributes:

• title: The title of the page linked to (str); does not include namespace or section

• namespace: The Namespace object of the page linked to

• site: The Site object for the wiki linked to

__hash__()

A stable identifier to be used as a key in hash-tables.

__init__(title: str, namespace=None, site=None)

Initializer.

Parameters

• title – the title of the page linked to (str); does not include namespace or section

• namespace (int, pywikibot.Namespace or str) – the namespace of the page linked to. Can be provided as either an int, a Namespace instance or a str, defaults to the MAIN namespace.

• site (pywikibot.Site or str) – the Site object for the wiki linked to. Can be provided as either a Site instance or a db key, defaults to pywikibot.Site().

__module__ = 'pywikibot.page'

__repr__()

Return a more complete string representation.

__str__() → str

Return a str string representation.

astext(onsite=None)

Return a text representation of the link.

Parameters

onsite – if specified, present as a (possibly interwiki) link from the given site; otherwise, present as an internal link on the site.

canonical_title()

Return full page title, including localized namespace.

classmethod fromPage(page)

Create a BaseLink to a Page.

Parameters

page (pywikibot.page.Page) – target pywikibot.page.Page

Return type

pywikibot.page.BaseLink

lookup_namespace()

Look up the namespace given the provided namespace id or name.

Return type

pywikibot.Namespace

property namespace

Return the namespace of the link.

Return type

pywikibot.Namespace

ns_title(onsite=None)

Return full page title, including namespace.

Parameters

onsite – site object if specified, present title using onsite local namespace, otherwise use self canonical namespace.

Raises

pywikibot.Error – no corresponding namespace is found in onsite

property site

Return the site of the link.

Return type

pywikibot.Site

class pywikibot.page.BasePage(source, title='', ns=0)

Bases: pywikibot.tools.ComparableMixin

BasePage: Base object for a MediaWiki page.

This object only implements internally methods that do not require reading from or writing to the wiki. All other methods are delegated to the Site object.

Will be subclassed by Page, WikibasePage, and FlowPage.

__hash__()

A stable identifier to be used as a key in hash-tables.

This relies on the fact that the string representation of an instance cannot change after the construction.

__init__(source, title='', ns=0)

Instantiate a Page object.

Three calling formats are supported:

• If the first argument is a Page, create a copy of that object. This can be used to convert an existing Page into a subclass object, such as Category or FilePage. (If the title is also given as the second argument, creates a copy with that title; this is used when pages are moved.)

• If the first argument is a Site, create a Page on that Site using the second argument as the title (may include a section), and the third as the namespace number. The namespace number is mandatory, even if the title includes the namespace prefix. This is the preferred syntax when using an already-normalized title obtained from api.php or a database dump. WARNING: may produce invalid objects if page title isn’t in normal form!

• If the first argument is a BaseLink, create a Page from that link. This is the preferred syntax when using a title scraped from wikitext, URLs, or another non-normalized source.

Parameters

• source (pywikibot.page.BaseLink (or subclass), pywikibot.page.Page (or subclass), or pywikibot.page.Site) – the source of the page

• title (str) – normalized title of the page; required if source is a Site, ignored otherwise

• ns (int) – namespace number; required if source is a Site, ignored otherwise

__module__ = 'pywikibot.page'

__repr__()

Return a more complete string representation.

__str__()

Return a string representation.

applicable_protections() → set

Return the protection types allowed for that page.

If the page doesn’t exist it only returns “create”. Otherwise it returns all protection types provided by the site, except “create”. It also removes “upload” if that page is not in the File namespace.

It is possible, that it returns an empty set, but only if original protection types were removed.

Returns

set of str

autoFormat()

Return date.getAutoFormat dictName and value, if any.

Value can be a year, date, etc., and dictName is ‘YearBC’, ‘Year_December’, or another dictionary name. Please note that two entries may have exactly the same autoFormat, but be in two different namespaces, as some sites have categories with the same names. Regular titles return (None, None).

backlinks(follow_redirects=True, filter_redirects=None, namespaces=None, total=None, content=False, followRedirects='[deprecated name of follow_redirects]', step=NotImplemented, filterRedirects='[deprecated name of filter_redirects]')

Return an iterator for pages that link to this page.

Parameters

• follow_redirects – if True, also iterate pages that link to a redirect pointing to the page.

• filter_redirects – if True, only iterate redirects; if False, omit redirects; if None, do not filter

• namespaces – only iterate pages in these namespaces

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

• content – if True, retrieve the content of the current version of each referring page (default False)

botMayEdit()

Determine whether the active bot is allowed to edit the page.

This will be True if the page doesn’t contain {{bots}} or {{nobots}} or any other template from edit_restricted_templates list in x_family.py file, or it contains them and the active bot is allowed to edit this page. (This method is only useful on those sites that recognize the bot-exclusion protocol; on other sites, it will always return True.)

The framework enforces this restriction by default. It is possible to override this by setting ignore_bot_templates=True in user-config.py, or using page.put(force=True).

Return type

bool

categories(with_sort_key=False, total=None, content=False, get_redirect=NotImplemented, withSortKey='[deprecated name of with_sort_key]', step=NotImplemented, nofollow_redirects=NotImplemented)

Iterate categories that the article is in.

Parameters

• with_sort_key – if True, include the sort key in each Category.

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

• content – if True, retrieve the content of the current version of each category description page (default False)

Returns

a generator that yields Category objects.

Return type

generator

change_category(old_cat, new_cat, summary=None, sort_key=None, in_place=True, include=[], sortKey='[deprecated name of sort_key]', newCat='[deprecated name of new_cat]', comment='[deprecated name of summary]', inPlace='[deprecated name of in_place]', oldCat='[deprecated name of old_cat]')

Remove page from oldCat and add it to newCat.

Parameters

• old_cat (pywikibot.page.Category) – category to be removed

• new_cat (pywikibot.page.Category or None) – category to be added, if any

• summary – string to use as an edit summary

• sort_key – sortKey to use for the added category. Unused if newCat is None, or if inPlace=True If sortKey=True, the sortKey used for oldCat will be used.

• in_place – if True, change categories in place rather than rearranging them.

• include (list) – list of tags not to be disabled by default in relevant textlib functions, where CategoryLinks can be searched.

Returns

True if page was saved changed, otherwise False.

Return type

bool

clear_cache()

Clear the cached attributes of the page.

property content_model

Return the content model for this page.

If it cannot be reliably determined via the API, None is returned.

contributors(total=None, starttime=None, endtime=None, step=NotImplemented)

Compile contributors of this page with edit counts.

Parameters

• total – iterate no more than this number of revisions in total

• starttime – retrieve revisions starting at this Timestamp

• endtime – retrieve revisions ending at this Timestamp

Returns

number of edits for each username

Return type

collections.Counter

coordinates(primary_only=False)

Return a list of Coordinate objects for points on the page.

Uses the MediaWiki extension GeoData.

Parameters

primary_only – Only return the coordinate indicated to be primary

Returns

A list of Coordinate objects or a single Coordinate if primary_only is True

Return type

list of Coordinate or Coordinate or None

create_short_link(permalink=False, with_protocol=True)

Return a shortened link that points to that page.

If shared_urlshortner_wiki is defined in family config, it’ll use that site to create the link instead of the current wiki.

Parameters

• permalink (bool) – If true, the link will point to the actual revision of the page.

• with_protocol (bool) – If true, and if it’s not already included, the link will have http(s) protocol prepended. On Wikimedia wikis the protocol is already present.

Returns

The reduced link.

Return type

str

data_item()

Convenience function to get the Wikibase item of a page.

Return type

pywikibot.page.ItemPage

property data_repository

Return the Site object for the data repository.

defaultsort(force=False)

Extract value of the {{DEFAULTSORT:}} magic word from the page.

Parameters

force – force updating from the live site

Return type

str or None

delete(reason=None, prompt=True, mark=False, quit=False, throttle=NotImplemented)

Delete the page from the wiki. Requires administrator status.

Parameters

• reason – The edit summary for the deletion, or rationale for deletion if requesting. If None, ask for it.

• prompt – If true, prompt user for confirmation before deleting.

• mark – If true, and user does not have sysop rights, place a speedy-deletion request on the page instead. If false, non-sysops will be asked before marking pages for deletion.

• quit – show also the quit option, when asking for confirmation.

property depth

Return the depth/subpage level of the page.

editTime()

Return timestamp of last revision to page.

Return type

pywikibot.Timestamp

embeddedin(filter_redirects=None, namespaces=None, total=None, content=False, step=NotImplemented)

Return an iterator for pages that embed this page as a template.

Parameters

• filter_redirects – if True, only iterate redirects; if False, omit redirects; if None, do not filter

• namespaces – only iterate pages in these namespaces

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

• content – if True, retrieve the content of the current version of each embedding page (default False)

exists()

Return True if page exists on the wiki, even if it’s a redirect.

If the title includes a section, return False if this section isn’t found.

Return type

bool

expand_text(force=False, includecomments=False, refresh='[deprecated name of force]')

Return the page text with all templates and parser words expanded.

Parameters

• force – force updating from the live site

• includecomments – Also strip comments if includecomments parameter is not True.

extlinks(total=None, step=NotImplemented)

Iterate all external URLs (not interwiki links) from this page.

Parameters

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

Returns

a generator that yields str objects containing URLs.

Return type

generator

full_url()

Return the full URL.

get(force=False, get_redirect=False, expandtemplates=NotImplemented, throttle=NotImplemented, change_edit_time=NotImplemented)

Return the wiki-text of the page.

This will retrieve the page from the server if it has not been retrieved yet, or if force is True. This can raise the following exceptions that should be caught by the calling code:

Raises

• pywikibot.exceptions.NoPage – The page does not exist

• pywikibot.exceptions.IsRedirectPage – The page is a redirect. The argument of the exception is the title of the page it redirects to.

• pywikibot.exceptions.SectionError – The section does not exist on a page with a # link

Parameters

• force – reload all page attributes, including errors.

• get_redirect – return the redirect text, do not follow the redirect, do not raise an exception.

Return type

str

getCategoryRedirectTarget()

If this is a category redirect, return the target category title.

Return type

pywikibot.page.Category

getCreator()

Get the first revision of the page.

DEPRECATED: Use Page.oldest_revision.

Returns

tuple of username and timestamp in isoformat

Return type

tuple[str]

getDeletedRevision(timestamp, content=False, retrieveText='[deprecated name of content]')

Return a particular deleted revision by timestamp.

Returns

a list of [date, editor, comment, text, restoration marker]. text will be None, unless content is True (or has been retrieved earlier). If timestamp is not found, returns empty list.

Return type

list

getLatestEditors(total=1, limit='[deprecated name of total]')

Get a list of revision information of the last total edits.

DEPRECATED: Use Page.revisions.

Parameters

total – iterate no more than this number of revisions in total

Returns

list of dict, each dict containing the username and Timestamp

getMovedTarget()

Return a Page object for the target this Page was moved to.

DEPRECATED: Use Page.moved_target().

If this page was not moved, it will raise a NoPage exception. This method also works if the source was already deleted.

Return type

pywikibot.page.Page

Raises

pywikibot.exceptions.NoPage – this page was not moved

getOldVersion(oldid, force=False, get_redirect=False, throttle=NotImplemented, change_edit_time=NotImplemented)

Return text of an old revision of this page; same options as get().

Parameters

oldid – The revid of the revision desired.

Return type

str

getRedirectTarget()

Return a Page object for the target this Page redirects to.

If this page is not a redirect page, will raise an IsNotRedirectPage exception. This method also can raise a NoPage exception.

Return type

pywikibot.Page

getReferences(follow_redirects=True, with_template_inclusion=True, only_template_inclusion=False, filter_redirects=False, namespaces=None, total=None, content=False, withTemplateInclusion='[deprecated name of with_template_inclusion]', step=NotImplemented, redirectsOnly='[deprecated name of filter_redirects]', onlyTemplateInclusion='[deprecated name of only_template_inclusion]')

Return an iterator all pages that refer to or embed the page.

If you need a full list of referring pages, use pages = list(s.getReferences())

Parameters

• follow_redirects – if True, also iterate pages that link to a redirect pointing to the page.

• with_template_inclusion – if True, also iterate pages where self is used as a template.

• only_template_inclusion – if True, only iterate pages where self is used as a template.

• filter_redirects – if True, only iterate redirects to self.

• namespaces – only iterate pages in these namespaces

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

• content – if True, retrieve the content of the current version of each referring page (default False)

Return type

typing.Iterable[pywikibot.Page]

getVersionHistoryTable(reverse=False, total=None, step=NotImplemented, reverseOrder='[deprecated name of reverse]', forceReload=NotImplemented)

Return the version history as a wiki table.

has_permission(action='edit')

Determine whether the page can be modified.

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

Parameters

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

Return type

bool

Raises

ValueError – invalid action parameter

property image_repository

Return the Site object for the image repository.

imagelinks(total=None, content=False, followRedirects=NotImplemented, step=NotImplemented, loose=NotImplemented)

Iterate FilePage objects for images displayed on this Page.

Parameters

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

• content – if True, retrieve the content of the current version of each image description page (default False)

Returns

a generator that yields FilePage objects.

interwiki(expand=True)

Iterate interwiki links in the page text, excluding language links.

Parameters

expand (bool) – if True (default), include interwiki links found in templates transcluded onto this page; if False, only iterate interwiki links found in this page’s own wikitext

Returns

a generator that yields Link objects

Return type

generator

isAutoTitle()

Return True if title of this Page is in the autoFormat dict.

isCategoryRedirect()

Return True if this is a category redirect page, False otherwise.

Return type

bool

isDisambig()

Return True if this is a disambiguation page, False otherwise.

By default, it uses the the Disambiguator extension’s result. The identification relies on the presence of the __DISAMBIG__ magic word which may also be transcluded.

If the Disambiguator extension isn’t activated for the given site, the identification relies on the presence of specific templates. First load a list of template names from the Family file; if the value in the Family file is None or no entry was made, look for the list on [[MediaWiki:Disambiguationspage]]. If this page does not exist, take the MediaWiki message. ‘Template:Disambig’ is always assumed to be default, and will be appended regardless of its existence.

Return type

bool

isIpEdit()

Return True if last editor was unregistered.

Return type

bool

isRedirectPage()

Return True if this is a redirect, False if not or not existing.

isStaticRedirect(force=False)

Determine whether the page is a static redirect.

A static redirect must be a valid redirect, and contain the magic word __STATICREDIRECT__.

Parameters

force (bool) – Bypass local caching

Return type

bool

isTalkPage()

Return True if this page is in any talk namespace.

is_categorypage()

Return True if the page is a Category, False otherwise.

is_filepage()

Return True if this is an file description page, False otherwise.

is_flow_page()

Whether a page is a Flow page.

Return type

bool

iterlanglinks(total=None, include_obsolete=False, step=NotImplemented)

Iterate all inter-language links on this page.

Parameters

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

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

Returns

a generator that yields Link objects.

Return type

generator

itertemplates(total=None, content=False, step=NotImplemented)

Iterate Page objects for templates used on this Page.

Template parameters are ignored. This method only returns embedded templates, not template pages that happen to be referenced through a normal link.

Parameters

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

• content – if True, retrieve the content of the current version of each template (default False)

• content – bool

langlinks(include_obsolete=False)

Return a list of all inter-language Links on this page.

Parameters

include_obsolete (bool) – if true, return even Link objects whose site is obsolete

Returns

list of Link objects.

Return type

list

lastNonBotUser()

Return name or IP address of last human/non-bot user to edit page.

Determine the most recent human editor out of the last revisions. If it was not able to retrieve a human user, returns None.

If the edit was done by a bot which is no longer flagged as ‘bot’, i.e. which is not returned by Site.botusers(), it will be returned as a non-bot edit.

Return type

str

property latest_revision

Return the current revision for this page.

property latest_revision_id

Return the current revision id for this page.

linkedPages(namespaces=None, total=None, content=False, step=NotImplemented)

Iterate Pages that this Page links to.

Only returns pages from “normal” internal links. Image and category links are omitted unless prefixed with “:”. Embedded templates are omitted (but links within them are returned). All interwiki and external links are omitted.

Parameters

• namespaces – only iterate links in these namespaces

• namespaces – int, or list of ints

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

• content (bool) – if True, retrieve the content of the current version of each linked page (default False)

Returns

a generator that yields Page objects.

Return type

generator

loadDeletedRevisions(total=None, step=NotImplemented)

Retrieve deleted revisions for this Page.

Stores all revisions’ timestamps, dates, editors and comments in self._deletedRevs attribute.

Returns

iterator of timestamps (which can be used to retrieve revisions later on).

Return type

generator

markDeletedRevision(timestamp, undelete=True)

Mark the revision identified by timestamp for undeletion.

Parameters

undelete (bool) – if False, mark the revision to remain deleted.

merge_history(dest, timestamp=None, reason=None)

Merge revisions from this page into another page.

See APISite.merge_history for details.

Parameters

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

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

• reason (str) – Optional reason for the history merge

move(newtitle, reason=None, movetalk=True, noredirect=False, throttle=NotImplemented, deleteAndMove='[deprecated name of noredirect]', movetalkpage='[deprecated name of movetalk]')

Move this page to a new title.

Parameters

• newtitle – The new page title.

• reason – The edit summary for the move.

• movetalk – If true, move this page’s talk page (if it exists)

• noredirect – if move succeeds, delete the old page (usually requires sysop privileges, depending on wiki settings)

moved_target()

Return a Page object for the target this Page was moved to.

If this page was not moved, it will raise a NoMoveTarget exception. This method also works if the source was already deleted.

Return type

pywikibot.page.Page

Raises

pywikibot.exceptions.NoMoveTarget – this page was not moved

namespace()

Return the namespace of the page.

Returns

namespace of the page

Return type

pywikibot.Namespace

property oldest_revision

Return the first revision of this page.

Return type

Revision

page_image()

Return the most appropriate image on the page.

Uses the MediaWiki extension PageImages.

Returns

A FilePage object

Return type

pywikibot.page.FilePage

property pageid

Return pageid of the page.

Returns

pageid or 0 if page does not exist

Return type

int

permalink(oldid=None, percent_encoded=True, with_protocol=False)

Return the permalink URL of an old revision of this page.

Parameters

• oldid – The revid of the revision desired.

• percent_encoded – if false, the link will be provided without title uncoded.

• with_protocol – if true, http or https prefixes will be included before the double slash.

Return type

str

preloadText()

The text returned by EditFormPreloadText.

See API module “info”.

Application: on Wikisource wikis, text can be preloaded even if a page does not exist, if an Index page is present.

Return type

str

previousRevision()

Return the revision id for the previous revision.

DEPRECATED: Use latest_revision.parent_id instead.

Return type

int

Raises

AssertionError – Use on MediaWiki prior to v1.16.

properties(force=False)

Return the properties of the page.

Parameters

force – force updating from the live site

Return type

dict

protect(edit=False, move=False, create=None, upload=None, unprotect=False, reason=None, prompt=None, protections=None, throttle=NotImplemented, **kwargs)

Protect or unprotect a wiki page. Requires administrator status.

Valid protection levels (in MediaWiki 1.12) are ‘’ (equivalent to ‘none’), ‘autoconfirmed’, and ‘sysop’. If None is given, however, that protection will be skipped.

Parameters

• protections (dict) – A dict mapping type of protection to protection level of that type.

• reason (basestring) – Reason for the action

• prompt (bool) – Whether to ask user for confirmation (deprecated). Defaults to protections is None

protection()

Return a dictionary reflecting page protections.

Return type

dict

purge(**kwargs)

Purge the server’s cache for this page.

Keyword Arguments

• redirects – Automatically resolve redirects.

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

• forcelinkupdate – Update the links tables.

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

Return type

bool

put(newtext, summary=None, watch=None, minor=True, botflag=None, force=False, asynchronous=False, callback=None, watchArticle='[deprecated name of watch]', comment='[deprecated name of summary]', minorEdit='[deprecated name of minor]', async='[deprecated name of asynchronous]', **kwargs)

Save the page with the contents of the first argument as the text.

This method is maintained primarily for backwards-compatibility. For new code, using Page.save() is preferred. See save() method docs for all parameters not listed here.

Parameters

newtext (str) – The complete text of the revised page.

revision_count(contributors=None)

Determine number of edits from a set of contributors.

Parameters

contributors (iterable of str) – contributor usernames

Returns

number of edits for all provided usernames

Return type

int

revisions(reverse=False, total=None, content=False, starttime=None, endtime=None, getText='[deprecated name of content]', step=NotImplemented, rollback=NotImplemented, reverseOrder='[deprecated name of reverse]')

Generator which loads the version history as Revision instances.

save(summary=None, watch=None, minor=True, botflag=None, force=False, asynchronous=False, callback=None, apply_cosmetic_changes=None, quiet=False, comment='[deprecated name of summary]', sysop=NotImplemented, async='[deprecated name of asynchronous]', **kwargs)

Save the current contents of page’s text to the wiki.

Parameters

• summary (str) – The edit summary for the modification (optional, but most wikis strongly encourage its use)

• watch (str, bool (deprecated) or None) –

  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 If None (default), follow bot account’s default settings

  For backward compatibility watch parameter may also be boolean: if True, add or if False, remove this Page to/from bot user’s watchlist.

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

• botflag – if True, mark this edit as made by a bot (default: True if user has bot status, False if not)

• force (bool) – if True, ignore botMayEdit() setting

• asynchronous – if True, launch a separate thread to save asynchronously

• callback – a callable object that will be called after the page put operation. This object must take two arguments: (1) a Page object, and (2) an exception instance, which will be None if the page was saved successfully. The callback is intended for use by bots that need to keep track of which saves were successful.

• apply_cosmetic_changes (bool or None) – Overwrites the cosmetic_changes configuration value to this value unless it’s None.

• quiet (bool) – enable/disable successful save operation message; defaults to False. In asynchronous mode, if True, it is up to the calling bot to manage the output e.g. via callback.

section()

Return the name of the section this Page refers to.

The section is the part of the title following a ‘#’ character, if any. If no section is present, return None.

Return type

str or None

property site

Return the Site object for the wiki on which this Page resides.

Return type

pywikibot.Site

templates(content=False, get_redirect=NotImplemented)

Return a list of Page objects for templates used on this Page.

Template parameters are ignored. This method only returns embedded templates, not template pages that happen to be referenced through a normal link.

Parameters

• content – if True, retrieve the content of the current version of each template (default False)

• content – bool

property text

Return the current (edited) wikitext, loading it if necessary.

Returns

text of the page

Return type

str

title(asUrl='[deprecated name of as_url]', withSection='[deprecated name of with_section]', asLink='[deprecated name of as_link]', withNamespace='[deprecated name of with_ns]', forceInterwiki='[deprecated name of force_interwiki]', savetitle='[deprecated name of as_url]', allowInterwiki='[deprecated name of allow_interwiki]', *, underscore=False, with_ns=True, with_section=True, as_url=False, as_link=False, allow_interwiki=True, force_interwiki=False, textlink=False, as_filename=False, insite=None, without_brackets=False)

Return the title of this Page, as a string.

Parameters

• underscore – (not used with as_link) if true, replace all ‘ ‘ characters with ‘_’

• with_ns – if false, omit the namespace prefix. If this option is false and used together with as_link return a labeled link like [[link|label]]

• with_section – if false, omit the section

• as_url – (not used with as_link) if true, quote title as if in an URL

• as_link – if true, return the title in the form of a wikilink

• allow_interwiki – (only used if as_link is true) if true, format the link as an interwiki link if necessary

• force_interwiki – (only used if as_link is true) if true, always format the link as an interwiki link

• textlink – (only used if as_link is true) if true, place a ‘:’ before Category: and Image: links

• as_filename – (not used with as_link) if true, replace any characters that are unsafe in filenames

• insite – (only used if as_link is true) a site object where the title is to be shown. default is the current family/lang given by -family and -lang option i.e. config.family and config.mylang

• without_brackets – (cannot be used with as_link) if true, remove the last pair of brackets(usually removes disambiguation brackets).

Return type

str

toggleTalkPage()

Return other member of the article-talk page pair for this Page.

If self is a talk page, returns the associated content page; otherwise, returns the associated talk page. The returned page need not actually exist on the wiki.

Returns

Page or None if self is a special page.

Return type

typing.Optional[pywikibot.Page]

touch(callback=None, botflag=False, **kwargs)

Make a touch edit for this page.

See save() method docs for all parameters. The following parameters will be overridden by this method: - summary, watch, minor, force, asynchronous

Parameter botflag is False by default.

minor and botflag parameters are set to False which prevents hiding the edit when it becomes a real edit due to a bug.

undelete(reason=None, comment='[deprecated name of reason]', throttle=NotImplemented)

Undelete revisions based on the markers set by previous calls.

If no calls have been made since loadDeletedRevisions(), everything will be restored.

Simplest case:

Page(...).undelete('This will restore all revisions')

More complex:

pg = Page(...)
revs = pg.loadDeletedRevisions()
for rev in revs:
    if ... #decide whether to undelete a revision
        pg.markDeletedRevision(rev) #mark for undeletion
pg.undelete('This will restore only selected revisions.')

Parameters

reason (basestring) – Reason for the action.

userName()

Return name or IP address of last user to edit page.

Return type

str

version()

Return MediaWiki version number of the page site.

This is needed to use @need_version() decorator for methods of Page objects.

watch(unwatch=False)

Add or remove this page to/from bot account’s watchlist.

Parameters

unwatch (bool) – True to unwatch, False (default) to watch.

Returns

True if successful, False otherwise.

Return type

bool

class pywikibot.page.Category(source, title='', sort_key=None, sortKey='[deprecated name of sort_key]', insite=NotImplemented)

Bases: pywikibot.page.Page

A page in the Category: namespace.

__init__(source, title='', sort_key=None, sortKey='[deprecated name of sort_key]', insite=NotImplemented)

Initializer.

All parameters are the same as for Page() Initializer.

__module__ = 'pywikibot.page'

articles(recurse=False, total=None, content=False, namespaces=None, sortby=None, reverse=False, starttime=None, endtime=None, startsort=None, endsort=None, startprefix=None, endprefix=None, step=NotImplemented, startFrom='[deprecated name of startprefix]')

Yield all articles in the current category.

By default, yields all pages in the category that are not subcategories!

Parameters

• recurse (int or bool) – if not False or 0, also iterate articles in subcategories. If an int, limit recursion to this number of levels. (Example: recurse=1 will iterate articles in first-level subcats, but no deeper.)

• total – iterate no more than this number of pages in total (at all levels)

• namespaces (int or list of ints) – only yield pages in the specified namespaces

• content – if True, retrieve the content of the current version of each page (default False)

• sortby (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). This applies recursively.

• reverse – 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 (pywikibot.Timestamp) – if provided, only generate pages added before this time; not valid unless sortby=”timestamp”

• startsort (str) – if provided, only generate pages that have a sortkey >= startsort; not valid if sortby=”timestamp” (Deprecated in MW 1.24)

• endsort (str) – if provided, only generate pages that have a sortkey <= endsort; not valid if sortby=”timestamp” (Deprecated in MW 1.24)

• startprefix (str) – if provided, only generate pages >= this title lexically; not valid if sortby=”timestamp”; overrides “startsort” (requires MW 1.18+)

• endprefix (str) – if provided, only generate pages < this title lexically; not valid if sortby=”timestamp”; overrides “endsort” (requires MW 1.18+)

Return type

typing.Iterable[pywikibot.Page]

aslink(sort_key=None, textlink=NotImplemented, noInterwiki=NotImplemented, forceInterwiki=NotImplemented, sortKey='[deprecated name of sort_key]')

Return a link to place a page in this Category.

Use this only to generate a “true” category link, not for interwikis or text links to category pages.

Parameters

sort_key ((optional) str) – The sort key for the article to be placed in this Category; if omitted, default sort key is used.

property categoryinfo

Return a dict containing information about the category.

The dict contains values for:

Numbers of pages, subcategories, files, and total contents.

Return type

dict

isEmptyCategory()

Return True if category has no members (including subcategories).

Return type

bool

isHiddenCategory()

Return True if the category is hidden.

Return type

bool

members(recurse=False, namespaces=None, total=None, content=False, step=NotImplemented)

Yield all category contents (subcats, pages, and files).

Return type

typing.Iterable[pywikibot.Page]

newest_pages(total=None)

Return pages in a category ordered by the creation date.

If two or more pages are created at the same time, the pages are returned in the order they were added to the category. The most recently added page is returned first.

It only allows to return the pages ordered from newest to oldest, as it is impossible to determine the oldest page in a category without checking all pages. But it is possible to check the category in order with the newly added first and it yields all pages which were created after the currently checked page was added (and thus there is no page created after any of the cached but added before the currently checked).

Parameters

total (int) – The total number of pages queried.

Returns

A page generator of all pages in a category ordered by the creation date. From newest to oldest. Note: It currently only returns Page instances and not a subclass of it if possible. This might change so don’t expect to only get Page instances.

Return type

generator

subcategories(recurse=False, total=None, content=False, step=NotImplemented, cacheResults=NotImplemented, startFrom=NotImplemented)

Iterate all subcategories of the current category.

Parameters

• recurse (int or bool) – if not False or 0, also iterate subcategories of subcategories. If an int, limit recursion to this number of levels. (Example: recurse=1 will iterate direct subcats and first-level sub-sub-cats, but no deeper.)

• total – iterate no more than this number of subcategories in total (at all levels)

• content – if True, retrieve the content of the current version of each category description page (default False)

class pywikibot.page.Claim(site, pid, snak=None, hash=None, is_reference=False, is_qualifier=False, rank='normal', isReference='[deprecated name of is_reference]', isQualifier='[deprecated name of is_qualifier]', **kwargs)

Bases: pywikibot.page.Property

A Claim on a Wikibase entity.

Claims are standard claims as well as references and qualifiers.

SNAK_TYPES = ('value', 'somevalue', 'novalue')

TARGET_CONVERTER = {'commonsMedia': <function Claim.<lambda>>, 'geo-shape': <bound method _WbDataPage.fromWikibase of <class 'pywikibot.WbGeoShape'>>, 'globe-coordinate': <bound method Coordinate.fromWikibase of <class 'pywikibot.Coordinate'>>, 'monolingualtext': <function Claim.<lambda>>, 'quantity': <bound method WbQuantity.fromWikibase of <class 'pywikibot.WbQuantity'>>, 'tabular-data': <bound method _WbDataPage.fromWikibase of <class 'pywikibot.WbTabularData'>>, 'time': <bound method WbTime.fromWikibase of <class 'pywikibot.WbTime'>>, 'wikibase-item': <function Claim.<lambda>>, 'wikibase-property': <function Claim.<lambda>>}

__eq__(other)

Return self==value.

__hash__ = None

__init__(site, pid, snak=None, hash=None, is_reference=False, is_qualifier=False, rank='normal', isReference='[deprecated name of is_reference]', isQualifier='[deprecated name of is_qualifier]', **kwargs)

Initializer.

Defined by the “snak” value, supplemented by site + pid

Parameters

• site (pywikibot.site.DataSite) – repository the claim is on

• pid – property id, with “P” prefix

• snak – snak identifier for claim

• hash – hash identifier for references

• is_reference – whether specified claim is a reference

• is_qualifier – whether specified claim is a qualifier

• rank – rank for claim

__module__ = 'pywikibot.page'

__ne__(other)

Return self!=value.

__repr__()

Return the representation string.

addQualifier(qualifier, **kwargs)

Add the given qualifier.

Parameters

qualifier (pywikibot.page.Claim) – the qualifier to add

addSource(claim, **kwargs)

Add the claim as a source.

Parameters

claim (pywikibot.Claim) – the claim to add

addSources(claims, **kwargs)

Add the claims as one source.

Parameters

claims (list of pywikibot.Claim) – the claims to add

changeRank(rank, **kwargs)

Change the rank of the Claim and save.

changeSnakType(value=None, **kwargs)

Save the new snak value.

TODO: Is this function really needed?

changeTarget(value=None, snaktype='value', **kwargs)

Set the target value in the data repository.

Parameters

• value (object) – The new target value.

• snaktype (str ('value', 'somevalue', or 'novalue')) – The new snak type.

copy()

Create an independent copy of this object.

Return type

pywikibot.page.Claim

classmethod fromJSON(site, data)

Create a claim object from JSON returned in the API call.

Parameters

data (dict) – JSON containing claim data

Return type

pywikibot.page.Claim

getRank()

Return the rank of the Claim.

getSnakType()

Return the type of snak.

Returns

str (‘value’, ‘somevalue’ or ‘novalue’)

Return type

str

getSources()

Return a list of sources, each being a list of Claims.

Return type

list

getTarget()

Return the target value of this Claim.

None is returned if no target is set

Returns

object

has_qualifier(qualifier_id, target)

Check whether Claim contains specified qualifier.

Parameters

• qualifier_id (str) – id of the qualifier

• target – qualifier target to check presence of

Returns

true if the qualifier was found, false otherwise

Return type

bool

property on_item

Return item this claim is attached to.

classmethod qualifierFromJSON(site, data)

Create a Claim for a qualifier from JSON.

Qualifier objects are represented a bit differently like references, but I’m not sure if this even requires it’s own function.

Return type

pywikibot.page.Claim

classmethod referenceFromJSON(site, data)

Create a dict of claims from reference JSON returned in the API call.

Reference objects are represented a bit differently, and require some more handling.

Return type

dict

removeQualifier(qualifier, **kwargs)

Remove the qualifier. Call removeQualifiers().

Parameters

qualifier (pywikibot.page.Claim) – the qualifier to remove

removeQualifiers(qualifiers, **kwargs)

Remove the qualifiers.

Parameters

qualifiers (list Claim) – the qualifiers to remove

removeSource(source, **kwargs)

Remove the source. Call removeSources().

Parameters

source (pywikibot.Claim) – the source to remove

removeSources(sources, **kwargs)

Remove the sources.

Parameters

sources (list of pywikibot.Claim) – the sources to remove

same_as(other, ignore_rank=True, ignore_quals=False, ignore_refs=True)

Check if two claims are same.

setRank(rank)

Set the rank of the Claim.

setSnakType(value)

Set the type of snak.

Parameters

value (str ('value', 'somevalue', or 'novalue')) – Type of snak

setTarget(value)

Set the target value in the local object.

Parameters

value (object) – The new target value.

Raises

ValueError – if value is not of the type required for the Claim type.

target_equals(value)

Check whether the Claim’s target is equal to specified value.

The function checks for:

• WikibasePage ID equality

• WbTime year equality

• Coordinate equality, regarding precision

• WbMonolingualText text equality

• direct equality

Parameters

value – the value to compare with

Returns

true if the Claim’s target is equal to the value provided, false otherwise

Return type

bool

toJSON()

Create dict suitable for the MediaWiki API.

Return type

dict

class pywikibot.page.FileInfo(file_revision)

Bases: pywikibot.tools.DotReadableDict

A structure holding imageinfo of latest rev. of FilePage.

All keys of API imageinfo dictionary are mapped to FileInfo attributes. Attributes can be retrieved both as self[‘key’] or self.key.

Following attributes will be returned:

• timestamp, user, comment, url, size, sha1, mime, metadata

• archivename (not for latest revision)

See Site.loadimageinfo() for details.

Note: timestamp will be casted to pywikibot.Timestamp.

__eq__(other)

Test if two File_info objects are equal.

__hash__ = None

__init__(file_revision)

Initiate the class using the dict from APISite.loadimageinfo.

__module__ = 'pywikibot.page'

class pywikibot.page.FilePage(source, title='', insite=NotImplemented)

Bases: pywikibot.page.Page

A subclass of Page representing a file description page.

Supports the same interface as Page, with some added methods.

__init__(source, title='', insite=NotImplemented)

Initializer.

__module__ = 'pywikibot.page'

download(filename=None, chunk_size=102400, revision=None)

Download to filename file of FilePage.

Parameters

• filename (None or str) – filename where to save file: None: self.title(as_filename=True, with_ns=False) will be used str: provided filename will be used.

• chunk_size (int) – the size of each chunk to be received and written to file.

• revision (None or FileInfo) – file revision to download: None: self.latest_file_info will be used FileInfo: provided revision will be used.

Returns

True if download is successful, False otherwise.

Raise

IOError if filename cannot be written for any reason.

fileIsOnCommons()

DEPRECATED. Check if the image is stored on Wikimedia Commons.

Return type

bool

fileIsShared()

DEPRECATED. Check if the image is stored on Wikimedia Commons.

Return type

bool

file_is_shared()

Check if the file is stored on any known shared repository.

Return type

bool

getFileVersionHistoryTable()

Return the version history in the form of a wiki table.

getImagePageHtml()

Download the file page, and return the HTML, as a string.

Caches the HTML code, so that if you run this method twice on the same FilePage object, the page will only be downloaded once.

get_file_history()

Return the file’s version history.

Returns

dictionary with: key: timestamp of the entry value: instance of FileInfo()

Return type

dict

get_file_url(url_width=None, url_height=None, url_param=None)

Return the url or the thumburl of the file described on this page.

Fetch the information if not available.

Once retrieved, thumburl information will also be accessible as latest_file_info attributes, named as in [1]: - url, thumburl, thumbwidth and thumbheight

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

Parameters validation and error handling left to the API call.

Parameters

• url_width – see iiurlwidth in [1]

• url_height – see iiurlheigth in [1]

• url_param – see iiurlparam in [1]

Returns

latest file url or thumburl

Return type

str

globalusage(total=None)

Iterate all global usage for this page.

Parameters

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

Returns

a generator that yields Pages also on sites different from self.site.

Return type

generator

property latest_file_info

Retrieve and store information of latest Image rev. of FilePage.

At the same time, the whole history of Image is fetched and cached in self._file_revisions

Returns

instance of FileInfo()

property oldest_file_info

Retrieve and store information of oldest Image rev. of FilePage.

At the same time, the whole history of Image is fetched and cached in self._file_revisions

Returns

instance of FileInfo()

upload(source, **kwargs)

Upload this file to the wiki.

keyword arguments are from site.upload() method.

Parameters

source (str) – Path or URL to the file to be uploaded.

Keyword Arguments

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

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

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

• ignore_warnings – It may be a static boolean, a callable returning a boolean or an iterable. The callable gets a list of UploadWarning instances and the iterable should contain the warning codes for which an equivalent callable would return True if all UploadWarning 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 UploadWarning exception if the static boolean is False.

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

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

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

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

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

Returns

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

Return type

bool

usingPages(total=None, content=False, step=NotImplemented)

Yield Pages on which the file is displayed.

Parameters

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

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

class pywikibot.page.ItemPage(site, title=None, ns=None)

Bases: pywikibot.page.WikibasePage

Wikibase entity of type ‘item’.

A Wikibase item may be defined by either a ‘Q’ id (qid), or by a site & title.

If an item is defined by site & title, once an item’s qid has been looked up, the item is then defined by the qid.

DATA_ATTRIBUTES = {'aliases': <class 'pywikibot.page.AliasesDict'>, 'claims': <class 'pywikibot.page.ClaimCollection'>, 'descriptions': <class 'pywikibot.page.LanguageDict'>, 'labels': <class 'pywikibot.page.LanguageDict'>, 'sitelinks': <class 'pywikibot.page.SiteLinkCollection'>}

__init__(site, title=None, ns=None)

Initializer.

Parameters

• site (pywikibot.site.DataSite) – data repository

• title (str) – identifier of item, “Q###”, -1 or None for an empty item.

__module__ = 'pywikibot.page'

concept_url(**kw)

entity_type = 'item'

classmethod fromPage(page, lazy_load=False)

Get the ItemPage for a Page that links to it.

Parameters

• page (pywikibot.page.Page) – Page to look for corresponding data item

• lazy_load (bool) – Do not raise NoPage if either page or corresponding ItemPage does not exist.

Return type

pywikibot.page.ItemPage

Raises

• pywikibot.exceptions.NoPage – There is no corresponding ItemPage for the page

• pywikibot.exceptions.WikiBaseError – The site of the page has no data repository.

classmethod from_entity_uri(site, uri, lazy_load=False)

Get the ItemPage from its entity uri.

Parameters

• site (pywikibot.site.DataSite) – The Wikibase site for the item.

• uri (basestring) – Entity uri for the Wikibase item.

• lazy_load (bool) – Do not raise NoPage if ItemPage does not exist.

Return type

pywikibot.page.ItemPage

Raises

• TypeError – Site is not a valid DataSite.

• ValueError – Site does not match the base of the provided uri.

• pywikibot.exceptions.NoPage – Uri points to non-existent item.

get(force=False, get_redirect=False, *args, **kwargs)

Fetch all item data, and cache it.

Parameters

• force (bool) – override caching

• get_redirect (bool) – return the item content, do not follow the redirect, do not raise an exception.

Raises

NotImplementedError – a value in args or kwargs

Returns

actual data which entity holds

Return type

dict

Note

dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content

getID(numeric=False, force=False)

Get the entity identifier.

Parameters

• numeric (bool) – Strip the first letter and return an int

• force (bool) – Force an update of new data

getRedirectTarget()

Return the redirect target for this page.

getSitelink(site, force=False)

Return the title for the specific site.

If the item doesn’t have that language, raise NoPage.

Parameters

• site (pywikibot.Site or database name) – Site to find the linked page of.

• force – override caching

Return type

str

isRedirectPage()

Return True if item is a redirect, False if not or not existing.

iterlinks(family=None)

Iterate through all the sitelinks.

Parameters

family (str|pywikibot.family.Family) – string/Family object which represents what family of links to iterate

Returns

iterator of pywikibot.Page objects

Return type

iterator

mergeInto(item, **kwargs)

Merge the item into another item.

Parameters

item (pywikibot.page.ItemPage) – The item to merge into

removeSitelink(site, **kwargs)

Remove a sitelink.

A site can either be a Site object, or it can be a dbName.

removeSitelinks(sites, **kwargs)

Remove sitelinks.

Sites should be a list, with values either being Site objects, or dbNames.

setSitelink(sitelink, **kwargs)

Set sitelinks. Calls setSitelinks().

A sitelink can be a Page object, a BaseLink object or a {‘site’:dbname,’title’:title} dictionary.

setSitelinks(sitelinks, **kwargs)

Set sitelinks.

Sitelinks should be a list. Each item in the list can either be a Page object, a BaseLink object, or a dict with a value for ‘site’ and ‘title’.

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, **kwargs)

Make the item redirect to another item.

You need to define an extra argument to make this work, like save=True

Parameters

• target_page (pywikibot.page.ItemPage or string) – target of the redirect, this argument is required.

• force (bool) – if true, it sets the redirect target even the page is not redirect.

title(**kwargs)

Return ID as title of the ItemPage.

If the ItemPage was lazy-loaded via ItemPage.fromPage, this method will fetch the wikibase item ID for the page, potentially raising NoPage with the page on the linked wiki if it does not exist, or does not have a corresponding wikibase item ID.

This method also refreshes the title if the id property was set. i.e. item.id = ‘Q60’

All optional keyword parameters are passed to the superclass.

title_pattern = 'Q[1-9]\\d*'

class pywikibot.page.Link(text, source=None, default_namespace=0, defaultNamespace='[deprecated name of default_namespace]')

Bases: pywikibot.page.BaseLink

A MediaWiki wikitext link (local or interwiki).

Constructs a Link object based on a wikitext link and a source site.

Extends BaseLink by the following attributes:

• section: The section of the page linked to (str or None); this contains any text following a ‘#’ character in the title

• anchor: The anchor text (str or None); this contains any text following a ‘|’ character inside the link

__init__(text, source=None, default_namespace=0, defaultNamespace='[deprecated name of default_namespace]')

Initializer.

Parameters

• text (str) – the link text (everything appearing between [[ and ]] on a wiki page)

• source (Site or BasePage) – the Site on which the link was found (not necessarily the site to which the link refers)

• default_namespace (int) – a namespace to use if the link does not contain one (defaults to 0)

Raises

UnicodeError – text could not be converted to unicode.

__module__ = 'pywikibot.page'

property anchor

Return the anchor of the link.

Return type

str

astext(onsite=None)

Return a text representation of the link.

Parameters

onsite – if specified, present as a (possibly interwiki) link from the given site; otherwise, present as an internal link on the source site.

classmethod create_separated(link, source, default_namespace=0, section=None, label=None)

Create a new instance but overwrite section or label.

The returned Link instance is already parsed.

Parameters

• link (str) – The original link text.

• source (Site) – The source of the link.

• default_namespace (int) – The namespace this link uses when no namespace is defined in the link text.

• section (None or str) – The new section replacing the one in link. If None (default) it doesn’t replace it.

• label – The new label replacing the one in link. If None (default) it doesn’t replace it.

classmethod fromPage(page, source=None)

Create a Link to a Page.

Parameters

• page (pywikibot.page.Page) – target Page

• source – Link from site source

• source – Site

Return type

pywikibot.page.Link

illegal_titles_pattern = re.compile('[\\x00-\\x1f\\x23\\x3c\\x3e\\x5b\\x5d\\x7b\\x7c\\x7d\\x7f]|%[0-9A-Fa-f]{2}|&[A-Za-z0-9\x80-ÿ]+;|&#[0-9]+;|&#x[0-9A-Fa-f]+;')

classmethod langlinkUnsafe(lang, title, source)

Create a “lang:title” Link linked from source.

Assumes that the lang & title come clean, no checks are made.

Parameters

• lang (str) – target site code (language)

• title (str) – target Page

• source – Link from site source

• source – Site

Return type

pywikibot.page.Link

property namespace

Return the namespace of the link.

Return type

pywikibot.Namespace

parse()

Parse wikitext of the link.

Called internally when accessing attributes.

parse_site()

Parse only enough text to determine which site the link points to.

This method does not parse anything after the first “:”; links with multiple interwiki prefixes (such as “wikt:fr:Parlais”) need to be re-parsed on the first linked wiki to get the actual site.

Returns

The family name and site code for the linked site. If the site is not supported by the configured families it returns None instead of a str.

Return type

tuple

property section

Return the section of the link.

Return type

str

property site

Return the site of the link.

Return type

pywikibot.Site

property title

Return the title of the link.

Return type

str

class pywikibot.page.Page(source, title='', ns=0, insite=NotImplemented, defaultNamespace='[deprecated name of ns]')

Bases: pywikibot.page.BasePage

Page: A MediaWiki page.

__init__(source, title='', ns=0, insite=NotImplemented, defaultNamespace='[deprecated name of ns]')

Instantiate a Page object.

__module__ = 'pywikibot.page'

property raw_extracted_templates

Extract templates using textlib.extract_templates_and_params.

Disabled parts and whitespace are stripped, except for whitespace in anonymous positional arguments.

This value is cached.

Return type

list of (str, OrderedDict)

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, **kwargs)

Change the page’s text to point to the redirect page.

Parameters

• target_page (pywikibot.Page or string) – target of the redirect, this argument is required.

• create (bool) – if true, it creates the redirect even if the page doesn’t exist.

• force (bool) – if true, it set the redirect target even the page doesn’t exist or it’s not redirect.

• keep_section (bool) – if the old redirect links to a section and the new one doesn’t it uses the old redirect’s section.

• save (bool) – if true, it saves the page immediately.

• kwargs – Arguments which are used for saving the page directly afterwards, like ‘summary’ for edit summary.

templatesWithParams(get_redirect=NotImplemented)

Return templates used on this Page.

The templates are extracted by textlib.extract_templates_and_params, with positional arguments placed first in order, and each named argument appearing as ‘name=value’.

All parameter keys and values for each template are stripped of whitespace.

Returns

a list of tuples with one tuple for each template invocation in the page, with the template Page as the first entry and a list of parameters as the second entry.

Return type

list of (pywikibot.page.Page, list)

class pywikibot.page.Property(site, id, datatype=None)

Bases: object

A Wikibase property.

While every Wikibase property has a Page on the data repository, this object is for when the property is used as part of another concept where the property is not _the_ Page of the property.

For example, a claim on an ItemPage has many property attributes, and so it subclasses this Property class, but a claim does not have Page like behaviour and semantics.

__init__(site, id, datatype=None)

Initializer.

Parameters

• site (pywikibot.site.DataSite) – data repository

• id (basestring) – id of the property

• datatype (basestring) – datatype of the property; if not given, it will be queried via the API

__module__ = 'pywikibot.page'

getID(numeric=False)

Get the identifier of this property.

Parameters

numeric (bool) – Strip the first letter and return an int

property type

Return the type of this property.

Return type

str

types = {'commonsMedia': <class 'pywikibot.page.FilePage'>, 'external-id': <class 'str'>, 'geo-shape': <class 'pywikibot.WbGeoShape'>, 'globe-coordinate': <class 'pywikibot.Coordinate'>, 'math': <class 'str'>, 'monolingualtext': <class 'pywikibot.WbMonolingualText'>, 'quantity': <class 'pywikibot.WbQuantity'>, 'string': <class 'str'>, 'tabular-data': <class 'pywikibot.WbTabularData'>, 'time': <class 'pywikibot.WbTime'>, 'url': <class 'str'>, 'wikibase-item': <class 'pywikibot.page.ItemPage'>, 'wikibase-property': <class 'pywikibot.page.PropertyPage'>}

value_types = {'commonsMedia': 'string', 'external-id': 'string', 'geo-shape': 'string', 'globe-coordinate': 'globecoordinate', 'math': 'string', 'tabular-data': 'string', 'url': 'string', 'wikibase-item': 'wikibase-entityid', 'wikibase-property': 'wikibase-entityid'}

class pywikibot.page.PropertyPage(source, title=None, datatype=None)

Bases: pywikibot.page.WikibasePage, pywikibot.page.Property

A Wikibase entity in the property namespace.

Should be created as:

PropertyPage(DataSite, 'P21')

or:

PropertyPage(DataSite, datatype='url')

DATA_ATTRIBUTES = {'aliases': <class 'pywikibot.page.AliasesDict'>, 'claims': <class 'pywikibot.page.ClaimCollection'>, 'descriptions': <class 'pywikibot.page.LanguageDict'>, 'labels': <class 'pywikibot.page.LanguageDict'>}

__init__(source, title=None, datatype=None)

Initializer.

Parameters

• source (pywikibot.site.DataSite) – data repository property is on

• title (str) – identifier of property, like “P##”, “-1” or None for an empty property.

• datatype (str) – Datatype for a new property.

__module__ = 'pywikibot.page'

entity_type = 'property'

get(force=False, *args, **kwargs)

Fetch the property entity, and cache it.

Parameters

force (bool) – override caching

Raises

NotImplementedError – a value in args or kwargs

Returns

actual data which entity holds

Return type

dict

Note

dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content

getID(numeric=False)

Get the identifier of this property.

Parameters

numeric (bool) – Strip the first letter and return an int

get_data_for_new_entity()

Return data required for creation of new property.

newClaim(*args, **kwargs)

Helper function to create a new claim object for this property.

Return type

pywikibot.page.Claim

title_pattern = 'P[1-9]\\d*'

class pywikibot.page.Revision(revid, timestamp, user, anon=False, comment='', text=None, minor=False, rollbacktoken=None, parentid=None, contentmodel=None, sha1=None, slots=None)

Bases: pywikibot.tools.DotReadableDict

A structure holding information about a single revision of a Page.

class FullHistEntry(revid, timestamp, user, text, rollbacktoken)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__module__ = 'pywikibot.page'

static __new__(_cls, revid, timestamp, user, text, rollbacktoken)

Create new instance of FullHistEntry(revid, timestamp, user, text, rollbacktoken)

__repr__()

Return a nicely formatted representation string

__slots__ = ()

property revid

Alias for field number 0

property rollbacktoken

Alias for field number 4

property text

Alias for field number 3

property timestamp

Alias for field number 1

property user

Alias for field number 2

class HistEntry(revid, timestamp, user, comment)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__module__ = 'pywikibot.page'

static __new__(_cls, revid, timestamp, user, comment)

Create new instance of HistEntry(revid, timestamp, user, comment)

__repr__()

Return a nicely formatted representation string

__slots__ = ()

property comment

Alias for field number 3

property revid

Alias for field number 0

property timestamp

Alias for field number 1

property user

Alias for field number 2

__init__(revid, timestamp, user, anon=False, comment='', text=None, minor=False, rollbacktoken=None, parentid=None, contentmodel=None, sha1=None, slots=None)

Initializer.

All parameters correspond to object attributes (e.g., revid parameter is stored as self.revid)

Parameters

• revid (int) – Revision id number

• text (str, or None if text not yet retrieved) – Revision wikitext.

• timestamp (pywikibot.Timestamp) – Revision time stamp

• user (str) – user who edited this revision

• anon (bool) – user is unregistered

• comment (str) – edit comment text

• minor (bool) – edit flagged as minor

• rollbacktoken (str) – rollback token

• parentid (int) – id of parent Revision (v1.16+)

• contentmodel (str) – content model label (v1.21+)

• sha1 (str) – sha1 of revision text (v1.19+)

• slots (dict) – revision slots (v1.32+)

__module__ = 'pywikibot.page'

property content_model

Return content model of the revision.

This is meant for compatibility with older MW version which didn’t support revisions with slots. For newer MW versions, this returns the content model of the main slot.

Returns

content model

Return type

str

Raises

AssertionError – content model not supplied to the constructor which always occurs for MediaWiki versions lower than 1.21.

property parent_id

Return id of parent/previous revision.

Returns 0 if there is no previous revision

Returns

id of parent/previous revision

Return type

int

Raises

AssertionError – parent id not supplied to the constructor

property sha1

Return and cache SHA1 checksum of the text.

Returns

if the SHA1 checksum is cached it’ll be returned which is the case when it was requested from the API. Otherwise it’ll use the revision’s text to calculate the checksum (encoding it using UTF8 first). That calculated checksum will be cached too and returned on future calls. If the text is None (not queried) it will just return None and does not cache anything.

Return type

str or None

property text

Return text of this revision.

This is meant for compatibility with older MW version which didn’t support revisions with slots. For newer MW versions, this returns the contents of the main slot.

Returns

text of the revision

Return type

str or None if text not yet retrieved

class pywikibot.page.SiteLink(title, site=None, badges=None)

Bases: pywikibot.page.BaseLink

A single sitelink in a Wikibase item.

Extends BaseLink by the following attribute:

• badges: Any badges associated with the sitelink

__init__(title, site=None, badges=None)

Initializer.

Parameters

• title (str) – the title of the linked page including namespace

• site (pywikibot.Site or str) – the Site object for the wiki linked to. Can be provided as either a Site instance or a db key, defaults to pywikibot.Site().

• badges ([pywikibot.ItemPage]) – list of badges

__module__ = 'pywikibot.page'

property badges

Return a list of all badges associated with the link.

Return type

[pywikibot.ItemPage]

classmethod fromJSON(data, site=None)

Create a SiteLink object from JSON returned in the API call.

Parameters

• data (dict) – JSON containing SiteLink data

• site (pywikibot.site.DataSite) – The Wikibase site

Return type

pywikibot.page.SiteLink

toJSON()

Convert the SiteLink to a JSON object for the Wikibase API.

Returns

Wikibase JSON

Return type

dict

class pywikibot.page.SiteLinkCollection(repo, data=None)

Bases: collections.abc.MutableMapping

A structure holding SiteLinks for a Wikibase item.

__abstractmethods__ = frozenset({})

__contains__(key)

__delitem__(key)

__getitem__(key)

Get the SiteLink with the given key.

Parameters

key (pywikibot.Site or str) – site key as Site instance or db key

Return type

pywikibot.page.SiteLink

__init__(repo, data=None)

Initializer.

Parameters

repo (pywikibot.site.DataSite) – the Wikibase site on which badges are defined

__iter__()

__len__()

__module__ = 'pywikibot.page'

__setitem__(key, val)

Set the SiteLink for a given key.

Parameters

• key (pywikibot.Site or str) – site key as Site instance or db key

• val (dict or str) – page name as a string or JSON containing SiteLink data

Return type

pywikibot.page.SiteLink

classmethod fromJSON(data, repo)

Construct a new SiteLinkCollection from JSON.

static getdbName(site)

Helper function to obtain a dbName for a Site.

Parameters

site (pywikibot.site.BaseSite or str) – The site to look up.

classmethod normalizeData(data)

Helper function to expand data into the Wikibase API structure.

Parameters

data (list or dict) – Data to normalize

Returns

The dict with normalized data

Return type

dict

toJSON(diffto=None)

Create JSON suitable for Wikibase API.

When diffto is provided, JSON representing differences to the provided data is created.

Parameters

diffto (dict) – JSON containing entity data

Return type

dict

pywikibot.page.UnicodeToAsciiHtml(s)

Convert unicode to a str using HTML entities.

class pywikibot.page.User(source, title='', name='[deprecated name of title]', site='[deprecated name of source]')

Bases: pywikibot.page.Page

A class that represents a Wiki user.

This class also represents the Wiki page User:<username>

__init__(source, title='', name='[deprecated name of title]', site='[deprecated name of source]')

Initializer for a User object.

All parameters are the same as for Page() Initializer.

__module__ = 'pywikibot.page'

block(*args, **kwargs)

Block user.

Refer APISite.blockuser method for parameters.

Returns

None

contributions(total=500, namespace='[deprecated name of namespaces]', limit='[deprecated name of total]', **kwargs)

Yield tuples describing this user edits.

Each tuple is composed of a pywikibot.Page object, the revision id (int), the edit timestamp (as a pywikibot.Timestamp object), and the comment (str). Pages returned are not guaranteed to be unique.

Parameters

total (int) – limit result to this number of pages

Keyword Arguments

• start – Iterate contributions starting at this Timestamp

• end – Iterate contributions ending at this Timestamp

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

• namespaces – only iterate pages in these namespaces

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

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

Returns

tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment

Return type

tuple

editCount(force=False)

Return edit count for a registered user.

Always returns 0 for ‘anonymous’ users.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

int

property first_edit

Return first user contribution.

Returns

first user contribution entry

Returns

tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment

Return type

tuple or None

gender(force=False)

Return the gender of the user.

Parameters

force (bool) – if True, forces reloading the data from API

Returns

return ‘male’, ‘female’, or ‘unknown’

Return type

str

getUserPage(subpage='')

Return a Page object relative to this user’s main page.

Parameters

subpage (str) – subpage part to be appended to the main page title (optional)

Returns

Page object of user page or user subpage

Return type

pywikibot.Page

getUserTalkPage(subpage='')

Return a Page object relative to this user’s main talk page.

Parameters

subpage (str) – subpage part to be appended to the main talk page title (optional)

Returns

Page object of user talk page or user talk subpage

Return type

pywikibot.Page

getprops(force=False)

Return a properties about the user.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

dict

groups(force=False)

Return a list of groups to which this user belongs.

The list of groups may be empty.

Parameters

force (bool) – if True, forces reloading the data from API

Returns

groups property

Return type

list

isAnonymous()

Determine if the user is editing as an IP address.

Return type

bool

isBlocked(force=False)

Determine whether the user is currently blocked.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

bool

isEmailable(force=False)

Determine whether emails may be send to this user through MediaWiki.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

bool

isRegistered(force=False)

Determine if the user is registered on the site.

It is possible to have a page named User:xyz and not have a corresponding user with username xyz.

The page does not need to exist for this method to return True.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

bool

property is_thankable

Determine if the user has thanks notifications enabled.

NOTE: This doesn’t accurately determine if thanks is enabled for user.

Privacy of thanks preferences is under discussion, please see https://phabricator.wikimedia.org/T57401#2216861, and https://phabricator.wikimedia.org/T120753#1863894

Return type

bool

property last_edit

Return last user contribution.

Returns

last user contribution entry

Returns

tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment

Return type

tuple or None

property last_event

Return last user activity.

Returns

last user log entry

Return type

LogEntry or None

logevents(**kwargs)

Yield user activities.

Keyword Arguments

• logtype – only iterate entries of this type (see mediawiki api documentation for available types)

• page – only iterate entries affecting this page

• namespace – namespace to retrieve logevents from

• start – only iterate entries from and after this Timestamp

• end – only iterate entries up to and through this Timestamp

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

• tag – only iterate entries tagged with this tag

• total – maximum number of events to iterate

Return type

iterable

name()

The username.

DEPRECATED: use username instead.

Return type

str

registration(force=False)

Fetch registration date for this user.

Parameters

force (bool) – if True, forces reloading the data from API

Return type

pywikibot.Timestamp or None

rights(force=False)

Return user rights.

Parameters

force (bool) – if True, forces reloading the data from API

Returns

return user rights

Return type

list

send_email(subject, text, ccme=False)

Send an email to this user via MediaWiki’s email interface.

Parameters

• subject (str) – the subject header of the mail

• text (str) – mail body

• ccme (bool) – if True, sends a copy of this email to the bot

Raises

• NotEmailableError – the user of this User is not emailable

• UserRightsError – logged in user does not have ‘sendemail’ right

Returns

operation successful indicator

Return type

bool

unblock(reason=None)

Remove the block for the user.

Parameters

reason (basestring) – Reason for the unblock.

uploadedImages(total=10, number='[deprecated name of total]')

Yield tuples describing files uploaded by this user.

Each tuple is composed of a pywikibot.Page, the timestamp (str in ISO8601 format), comment (str) and a bool for pageid > 0. Pages returned are not guaranteed to be unique.

Parameters

total (int) – limit result to this number of pages

property username

The username.

Convenience method that returns the title of the page with namespace prefix omitted, which is the username.

Return type

str

class pywikibot.page.WikibasePage(site, title='', **kwargs)

Bases: pywikibot.page.BasePage, pywikibot.page.WikibaseEntity

Mixin base class for Wikibase entities which are also pages (eg. items).

There should be no need to instantiate this directly.

__delattr__(attr)

Attribute deleter. Deprecates lastrevid.

__getattribute__(name)

Low-level attribute getter. Deprecates lastrevid.

__init__(site, title='', **kwargs)

Initializer.

If title is provided, either ns or entity_type must also be provided, and will be checked against the title parsed using the Page initialisation logic.

Parameters

• site (pywikibot.site.DataSite) – Wikibase data site

• title (str) – normalized title of the page

Keyword Arguments

• ns – namespace

• entity_type – Wikibase entity type

Raises

• TypeError – incorrect use of parameters

• ValueError – incorrect namespace

• pywikibot.Error – title parsing problems

• NotImplementedError – the entity type is not supported

__module__ = 'pywikibot.page'

__setattr__(attr, value)

Attribute setter. Deprecates lastrevid.

addClaim(claim, bot=True, **kwargs)

Add a claim to the entity.

Parameters

• claim (pywikibot.page.Claim) – The claim to add

• bot (bool) – Whether to flag as bot (if possible)

Keyword Arguments

• asynchronous – if True, launch a separate thread to add claim asynchronously

• callback – a callable object that will be called after the claim has been added. It must take two arguments: (1) a WikibasePage object, and (2) an exception instance, which will be None if the entity was saved successfully. This is intended for use by bots that need to keep track of which saves were successful.

botMayEdit()

Return whether bots may edit this page.

Because there is currently no system to mark a page that it shouldn’t be edited by bots on Wikibase pages it always returns True. The content of the page is not text but a dict, the original way (to search for a template) doesn’t apply.

Returns

True

Return type

bool

editAliases(aliases, **kwargs)

Edit entity aliases.

Aliases should be a dict, with the key as a language or a site object. The value should be a list of strings.

editDescriptions(descriptions, **kwargs)

Edit entity descriptions.

Descriptions should be a dict, with the key as a language or a site object. The value should be the string to set it to. You can set it to ‘’ to remove the description.

editEntity(data=None, **kwargs)

Edit an entity using Wikibase wbeditentity API.

This function is wrapped around by:

• editLabels

• editDescriptions

• editAliases

• ItemPage.setSitelinks

Parameters

data (dict, or None to save the current content of the entity.) – Data to be saved

Keyword Arguments

• asynchronous – if True, launch a separate thread to edit asynchronously

• callback – a callable object that will be called after the entity has been updated. It must take two arguments: (1) a WikibasePage object, and (2) an exception instance, which will be None if the page was saved successfully. This is intended for use by bots that need to keep track of which saves were successful.

editLabels(labels, **kwargs)

Edit entity labels.

Labels should be a dict, with the key as a language or a site object. The value should be the string to set it to. You can set it to ‘’ to remove the label.

exists()

Determine if an entity exists in the data repository.

Return type

bool

get(force=False, *args, **kwargs)

Fetch all page data, and cache it.

Parameters

force (bool) – override caching

Raises

NotImplementedError – a value in args or kwargs

Returns

actual data which entity holds

Return type

dict

Note

dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content

property latest_revision_id

Get the revision identifier for the most recent revision of the entity.

Return type

int

namespace()

Return the number of the namespace of the entity.

Returns

Namespace id

Return type

int

removeClaims(claims, **kwargs)

Remove the claims from the entity.

Parameters

claims (list or pywikibot.Claim) – list of claims to be removed

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, **kwargs)

Set target of a redirect for a Wikibase page.

Has not been implemented in the Wikibase API yet, except for ItemPage.

pywikibot.page.html2unicode(text, ignore=None, exceptions=None)

Replace HTML entities with equivalent unicode.

Parameters

• ignore – HTML entities to ignore

• ignore – list of int

Return type

str

pywikibot.page.unicode2html(x, encoding)

Convert unicode string to requested HTML encoding.

Attempt to encode the string into the desired format; if that doesn’t work, encode the unicode into HTML &#; entities. If it does work, return it unchanged.

Parameters

• x (str) – String to update

• encoding (str) – Encoding to use

Return type

str

pywikibot.page.url2unicode(title, encodings='utf-8', site2=NotImplemented, site='[deprecated name of encodings]')

Convert URL-encoded text to unicode using several encoding.

Uses the first encoding that doesn’t cause an error.

Parameters

• title (str) – URL-encoded character data to convert

• encodings (str, list or Site) – Encodings to attempt to use during conversion.

Return type

str

Raises

UnicodeError – Could not convert using any encoding.