pywikibot — Base Classes and Functions

The initialization file for the Pywikibot framework.

class pywikibot.Bot(site=None, **kwargs)

Bases: BaseBot

Generic bot subclass for multiple sites.

If possible the MultipleSitesBot or SingleSiteBot classes should be used instead which specifically handle multiple or single sites.

Create a Bot instance and initialize cached sites.

Parameters:

• site (Optional[BaseSite]) –

• kwargs (Any) –

init_page(item)

Update site before calling treat.

Parameters:

item (Any) –

Return type:

BasePage

run()

Check if it automatically updates the site before run.

Return type:

None

property site: Optional[BaseSite]

Get the current site.

class pywikibot.Category(source, title='', sort_key=None)

Bases: Page

A page in the Category: namespace.

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

Parameters:

title (str) –

articles(recurse=False, total=None, content=False, namespaces=None, sortby=None, reverse=False, starttime=None, endtime=None, startprefix=None, endprefix=None)

Yield all articles in the current category.

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

Parameters:

• recurse (int) – 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 (Optional[int]) – iterate no more than this number of pages in total (at all levels)

• namespaces (Optional[Union[int, List[int]]]) – only yield pages in the specified namespaces

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

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

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

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

• endtime (Timestamp) – 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”

Return type:

Iterable[Page]

aslink(sort_key=None)

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.

Return type:

str

property categoryinfo: dict

Return a dict containing information about the category.

The dict contains values for:

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

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)

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

Return type:

Iterable[Page]

Parameters:

• recurse (bool) –

• total (Optional[int]) –

• content (bool) –

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 (Optional[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[Page, None, None]

subcategories(recurse=False, total=None, content=False)

Iterate all subcategories of the current category.

Parameters:

• recurse (int) – 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 (Optional[int]) – iterate no more than this number of subcategories in total (at all levels)

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

class pywikibot.Claim(site, pid, snak=None, hash=None, is_reference=False, is_qualifier=False, rank='normal', **kwargs)

Bases: Property

A Claim on a Wikibase entity.

Claims are standard claims as well as references and qualifiers.

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 (bool) – whether specified claim is a reference

• is_qualifier (bool) – whether specified claim is a qualifier

• rank (str) – rank for claim

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-form': <function Claim.<lambda>>, 'wikibase-item': <function Claim.<lambda>>, 'wikibase-lexeme': <function Claim.<lambda>>, 'wikibase-property': <function Claim.<lambda>>, 'wikibase-sense': <function Claim.<lambda>>}

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 (Claim) – the claim to add

Return type:

None

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?

Return type:

None

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

Set the target value in the data repository.

Parameters:

• value (object) – The new target value.

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

Return type:

None

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

Return type:

None

removeQualifiers(qualifiers, **kwargs)

Remove the qualifiers.

Parameters:

qualifiers (list Claim) – the qualifiers to remove

Return type:

None

removeSource(source, **kwargs)

Remove the source. Call removeSources().

Parameters:

source (Claim) – the source to remove

Return type:

None

removeSources(sources, **kwargs)

Remove the sources.

Parameters:

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

Return type:

None

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

Check if two claims are same.

Parameters:

• ignore_rank (bool) –

• ignore_quals (bool) –

• ignore_refs (bool) –

Return type:

bool

setRank(rank)

Set the rank of the Claim.

Return type:

None

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:

• WikibaseEntity 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.Coordinate(lat, lon, alt=None, precision=None, globe=None, typ='', name='', dim=None, site=None, globe_item=None, primary=False)

Bases: WbRepresentation

Class for handling and storing Coordinates.

Represent a geo coordinate.

Parameters:

• lat (float) – Latitude

• lon (float) – Longitude

• alt (Optional[float]) – Altitude

• precision (Optional[float]) – precision

• globe (Optional[str]) – Which globe the point is on

• typ (str) – The type of coordinate point

• name (str) – The name

• dim (Optional[int]) – Dimension (in meters)

• site (Optional[DataSite]) – The Wikibase site

• globe_item (Optional[Union[str, ItemPage]]) – The Wikibase item for the globe, or the entity URI of this Wikibase item. Takes precedence over ‘globe’ if present.

• primary (bool) – True for a primary set of coordinates

property entity: str

Return the entity uri of the globe.

classmethod fromWikibase(data, site=None)

Constructor to create an object from Wikibase’s JSON output.

Parameters:

• data (Dict[str, Any]) – Wikibase JSON

• site (Optional[DataSite]) – The Wikibase site

Return type:

Coordinate

get_globe_item(repo=None, lazy_load=False)

Return the ItemPage corresponding to the globe.

Note that the globe need not be in the same data repository as the Coordinate itself.

A successful lookup is stored as an internal value to avoid the need for repeated lookups.

Parameters:

• repo (Optional[DataSite]) – the Wikibase site for the globe, if different from that provided with the Coordinate.

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

Returns:

pywikibot.ItemPage

Return type:

ItemPage

property precision: Optional[float]

Return the precision of the geo coordinate.

The precision is calculated if the Coordinate does not have a precision, and self._dim is set.

When no precision and no self._dim exists, None is returned.

The biggest error (in degrees) will be given by the longitudinal error; the same error in meters becomes larger (in degrees) further up north. We can thus ignore the latitudinal error.

The longitudinal can be derived as follows:

In small angle approximation (and thus in radians):

M{Δλ ≈ Δpos / r_φ}, where r_φ is the radius of earth at the given latitude. Δλ is the error in longitude.

M{r_φ = r cos φ}, where r is the radius of earth, φ the latitude

Therefore:

precision = math.degrees(
    self._dim/(radius*math.cos(math.radians(self.lat))))

precisionToDim()

Convert precision from Wikibase to GeoData’s dim and return the latter.

dim is calculated if the Coordinate doesn’t have a dimension, and precision is set. When neither dim nor precision are set, ValueError is thrown.

Carrying on from the earlier derivation of precision, since precision = math.degrees(dim/(radius*math.cos(math.radians(self.lat)))) we get:

dim = math.radians(
    precision)*radius*math.cos(math.radians(self.lat))

But this is not valid, since it returns a float value for dim which is an integer. We must round it off to the nearest integer.

Therefore:

dim = int(round(math.radians(
    precision)*radius*math.cos(math.radians(self.lat))))

Return type:

Optional[int]

toWikibase()

Export the data to a JSON object for the Wikibase API.

FIXME: Should this be in the DataSite object?

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

class pywikibot.CurrentPageBot(**kwargs)

Bases: BaseBot

A bot which automatically sets ‘current_page’ on each treat().

This class should be always used together with either the MultipleSitesBot or SingleSiteBot class as there is no site management in this class.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

ignore_save_related_errors = True

ignore_server_errors = False

put_current(new_text, ignore_save_related_errors=None, ignore_server_errors=None, **kwargs)

Call Bot.userPut but use the current page.

It compares the new_text to the current page text.

Parameters:

• new_text (str) – The new text

• ignore_save_related_errors (Optional[bool]) – Ignore save related errors and automatically print a message. If None uses this instances default.

• ignore_server_errors (Optional[bool]) – Ignore server errors and automatically print a message. If None uses this instances default.

• kwargs (Any) – Additional parameters directly given to Bot.userPut.

Returns:

whether the page was saved successfully

Return type:

bool

treat(page)

Set page to current page and treat that page.

Parameters:

page (BasePage) –

Return type:

None

treat_page()

Process one page (Abstract method).

Return type:

None

class pywikibot.FilePage(source, title='')

Bases: Page

A subclass of Page representing a file description page.

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

Parameters:

title (str) –

data_item()

Convenience function to get the associated Wikibase item of the file.

If WikibaseMediaInfo extension is available (e.g. on Commons), the method returns the associated mediainfo entity. Otherwise, it falls back to behavior of BasePage.data_item.

New in version 6.5.

Return type:

pywikibot.page.WikibaseEntity

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.

Raises:

IOError – if filename cannot be written for any reason.

file_is_shared()

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

Changed in version 7.0: return False if file does not exist on shared image repository instead raising NoPageError.

Return type:

bool

property file_is_used: bool

Check whether the file is used at this site.

New in version 7.1.

getFileVersionHistoryTable()

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

Return type:

str

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.

Return type:

str

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

See also

using_pages()

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

  NOTE: If report_success is True or None it’ll raise an UploadError exception if the static boolean is False.

• chunk_size – The chunk size in bytesfor 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.

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

Returns:

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

Return type:

bool

usingPages(**kwargs)

Yield Pages on which the file is displayed.

Deprecated since version 7.4.0: Use using_pages() instead.

using_pages(**kwargs)

Yield Pages on which the file is displayed.

For parameters refer APISite.imageusage()

Usage example:

>>> site = pywikibot.Site('wikipedia:test')
>>> file = pywikibot.FilePage(site, 'Pywikibot MW gear icon.svg')
>>> used = list(file.using_pages(total=10))
>>> len(used)
1
>>> used[0].title()
'Pywikibot'

See also

globalusage()

Changed in version 7.2: all parameters from APISite.imageusage() are available.

Changed in version 7.4: renamed from usingPages().

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

Bases: 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.

Parameters:

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

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

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

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 NoPageError if either page or corresponding ItemPage does not exist.

Return type:

pywikibot.page.ItemPage

Raises:

• pywikibot.exceptions.NoPageError – 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 (str) – Entity uri for the Wikibase item.

• lazy_load (bool) – Do not raise NoPageError 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.NoPageError – 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

• IsRedirectPageError – instance is a redirect page and get_redirect is not True

Returns:

actual data which entity holds

Return type:

Dict[str, Any]

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

Parameters:

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

• force (bool) – override caching

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

Raises:

• IsRedirectPageError – instance is a redirect page

• NoPageError – site is not in sitelinks

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

Return type:

None

removeSitelink(site, **kwargs)

Remove a sitelink.

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

Return type:

None

removeSitelinks(sites, **kwargs)

Remove sitelinks.

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

Return type:

None

setSitelink(sitelink, **kwargs)

Set sitelinks. Calls setSitelinks().

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

Refer WikibasePage.editEntity() for asynchronous and callback usage.

Parameters:

sitelink (Union[BasePage, BaseLink, Dict[str, str]]) –

Return type:

None

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 key for ‘site’ and a value for ‘title’.

Refer editEntity() for asynchronous and callback usage.

Parameters:

sitelinks (List[Union[BasePage, BaseLink, Dict[str, str]]]) –

Return type:

None

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.

• create (bool) –

• keep_section (bool) –

• save (bool) –

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 NoPageError 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.LexemeForm(repo, id_=None)

Bases: LexemeSubEntity

Wikibase lexeme form.

DATA_ATTRIBUTES = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'representations': <class 'pywikibot.page._collections.LanguageDict'>}

edit_elements(data, **kwargs)

Update form elements.

Parameters:

data (dict) – Data to be saved

Return type:

None

entity_type = 'form'

get(force=False)

Fetch all form data, and cache it.

Parameters:

force (bool) – override caching

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

title_pattern = 'L[1-9]\\d*-F[1-9]\\d*'

toJSON(diffto=None)

Create dict suitable for the MediaWiki API.

Parameters:

diffto (Optional[dict]) –

Return type:

dict

class pywikibot.LexemePage(site, title=None)

Bases: WikibasePage

Wikibase entity of type ‘lexeme’.

Basic usage sample:

>>> import pywikibot
>>> repo = pywikibot.Site('wikidata')
>>> L2 = pywikibot.LexemePage(repo, 'L2')  # create a Lexeme page
>>> list(L2.claims.keys())  # access the claims
['P5831', 'P5402']
>>> len(L2.forms)  # access the forms
2
>>> F1 = L2.forms[0]  # access the first form
>>> list(F1.claims.keys())  # access its claims
['P898']
>>> len(L2.senses)  # access the senses
1
>>> S1 = L2.senses[0]  # access the first sense
>>> list(S1.claims.keys())  # and its claims
['P5137', 'P5972', 'P2888']

Parameters:

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

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

DATA_ATTRIBUTES = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'forms': <class 'pywikibot.page._wikibase.LexemeFormCollection'>, 'lemmas': <class 'pywikibot.page._collections.LanguageDict'>, 'senses': <class 'pywikibot.page._wikibase.LexemeSenseCollection'>}

add_form(form, **kwargs)

Add a form to the lexeme.

Parameters:

form (Form) – The form to add

Keyword Arguments:

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

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

• callback – a callable object that will be called after the claim has been added. It must take two arguments: (1) a LexemePage 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.

Return type:

None

entity_type = 'lexeme'

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

Fetch all lexeme data, and cache it.

Parameters:

• force (bool) – override caching

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

Raises:

NotImplementedError – a value in args or kwargs

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

get_data_for_new_entity()

Return data required for creation of a new lexeme.

isRedirectPage()

Return True if lexeme is redirect, False if not or not existing.

mergeInto(lexeme, **kwargs)

Merge the lexeme into another lexeme.

Parameters:

lexeme (LexemePage) – The lexeme to merge into

remove_form(form, **kwargs)

Remove a form from the lexeme.

Parameters:

form (LexemeForm) – The form to remove

Return type:

None

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

toJSON(diffto=None)

Create JSON suitable for Wikibase API.

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

Parameters:

diffto (Optional[dict]) – JSON containing entity data

Return type:

dict

class pywikibot.LexemeSense(repo, id_=None)

Bases: LexemeSubEntity

Wikibase lexeme sense.

DATA_ATTRIBUTES = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'glosses': <class 'pywikibot.page._collections.LanguageDict'>}

entity_type = 'sense'

title_pattern = 'L[1-9]\\d*-S[1-9]\\d*'

class pywikibot.Link(text, source=None, default_namespace=0)

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

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.

property anchor: str

Return the anchor of the link.

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

Return the section of the link.

property site

Return the site of the link.

Return type:

pywikibot.Site

property title: str

Return the title of the link.

class pywikibot.MediaInfo(repo, id_=None)

Bases: WikibaseEntity

Interface for MediaInfo entities on Commons.

New in version 6.5.

Parameters:

• repo (DataSite) – Entity repository.

• id (str or None, -1 and None mean non-existing) – Entity identifier.

DATA_ATTRIBUTES = {'labels': <class 'pywikibot.page._collections.LanguageDict'>}

property file: FilePage

Get the file associated with the mediainfo.

get(force=False)

Fetch all MediaInfo entity data and cache it.

Parameters:

force (bool) – override caching

Raises:

NoWikibaseEntityError – if this entity doesn’t exist

Returns:

actual data which entity holds

Return type:

dict

getID(numeric=False)

Get the entity identifier.

Parameters:

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

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

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

Bases: BasePage, WikiBlameMixin

Page: A MediaWiki page.

Instantiate a Page object.

Parameters:

title (str) –

get_best_claim(prop)

Return the first best Claim for this page.

Return the first ‘preferred’ ranked Claim specified by Wikibase property or the first ‘normal’ one otherwise.

New in version 3.0.

Parameters:

prop (str) – property id, “P###”

Returns:

Claim object given by Wikibase property number for this page object.

Return type:

Claim or None

Raises:

UnknownExtensionError – site has no Wikibase extension

property raw_extracted_templates

Extract templates and parameters.

This method is using textlib.extract_templates_and_params(). Disabled parts and whitespace are stripped, except for whitespace in anonymous positional arguments.

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 (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()

Return templates used on this Page.

The templates are extracted by raw_extracted_templates(), 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.PropertyPage(source, title=None, datatype=None)

Bases: WikibasePage, Property

A Wikibase entity in the property namespace.

Should be created as:

PropertyPage(DataSite, 'P21')

or:

PropertyPage(DataSite, datatype='url')

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.

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

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:

Claim

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

pywikibot.Site(code=None, fam=None, user=None, *, interface=None, url=None)

A factory method to obtain a Site object.

Site objects are cached and reused by this method.

By default rely on config settings. These defaults may all be overridden using the method parameters.

Creating the default site using config.mylang and config.family:

site = pywikibot.Site()

Override default site code:

site = pywikibot.Site('fr')

Override default family:

site = pywikibot.Site(fam='wikisource')

Setting a specific site:

site = pywikibot.Site('fr', 'wikisource')

which is equal to:

site = pywikibot.Site('wikisource:fr')

Note

An already created site is cached an a new variable points to the same object if interface, family, code and user are equal:

>>> import pywikibot
>>> site_1 = pywikibot.Site('wikisource:fr')
>>> site_2 = pywikibot.Site('fr', 'wikisource')
>>> site_1 is site_2
True
>>> site_1
APISite("fr", "wikisource")

APISite is the default interface. Refer pywikibot.site for other interface types.

Warning

Never create a site object via interface class directly. Always use this factory method.

Changed in version 7.3: Short creation if site code is equal to family name like Site('commons'), Site('meta') or Site('wikidata').

Parameters:

• code (Optional[str]) – language code (override config.mylang) code may also be a sitename like ‘wikipedia:test’

• fam (Optional[Union[str, Family]]) – family name or object (override config.family)

• user (Optional[str]) – bot user name to use on this site (override config.usernames)

• interface (Union[None, str, BaseSite]) – site class or name of class in pywikibot.site (override config.site_interface)

• url (Optional[str]) – Instead of code and fam, does try to get a Site based on the URL. Still requires that the family supporting that URL exists.

Raises:

• ValueError – URL and pair of code and family given

• ValueError – Invalid interface name

• ValueError – Missing Site code

• ValueError – Missing Site family

Return type:

BaseSite

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

Bases: BaseLink

A single sitelink in a Wikibase item.

Extends BaseLink by the following attribute:

• badges: Any badges associated with the sitelink

New in version 3.0.

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 ([ItemPage]) – list of badges

property badges

Return a list of all badges associated with the link.

Return type:

[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.Timestamp

Bases: datetime

Class for handling MediaWiki timestamps.

This inherits from datetime.datetime, so it can use all of the methods and operations of a datetime object. To ensure that the results of any operation are also a Timestamp object, be sure to use only Timestamp objects (and datetime.timedeltas) in any operation.

Use Timestamp.fromISOformat() and Timestamp.fromtimestampformat() to create Timestamp objects from MediaWiki string formats. As these constructors are typically used to create objects using data passed provided by site and page methods, some of which return a Timestamp when previously they returned a MediaWiki string representation, these methods also accept a Timestamp object, in which case they return a clone.

Alternatively, Timestamp.set_timestamp() can create Timestamp objects from Timestamp, datetime.datetime object, or strings compliant with ISO8601, MW, or POSIX formats.

Use Site.server_time() for the current time; this is more reliable than using Timestamp.utcnow().

Changed in version 7.5: moved to time module

ISO8601Format = '%Y-%m-%dT%H:%M:%SZ'

clone()

Clone this instance.

Return type:

Timestamp

classmethod fromISOformat(ts, sep='T')

Convert an ISO 8601 timestamp to a Timestamp object.

Parameters:

• ts (Union[str, Timestamp]) – ISO 8601 timestamp or a Timestamp object already

• sep (str) – one-character separator, placed between the date and time

Returns:

Timestamp object

Return type:

Timestamp

classmethod fromtimestampformat(ts)

Convert a MediaWiki internal timestamp to a Timestamp object.

Parameters:

ts (Union[str, Timestamp]) –

Return type:

Timestamp

isoformat(sep='T')

Convert object to an ISO 8601 timestamp accepted by MediaWiki.

datetime.datetime.isoformat does not postfix the ISO formatted date with a ‘Z’ unless a timezone is included, which causes MediaWiki ~1.19 and earlier to fail.

Parameters:

sep (str) –

Return type:

str

mediawikiTSFormat = '%Y%m%d%H%M%S'

posix_timestamp()

Convert object to a POSIX timestamp.

See Note in datetime.timestamp().

Return type:

float

posix_timestamp_format()

Convert object to a POSIX timestamp format.

Return type:

str

classmethod set_timestamp(ts)

Set Timestamp from input object.

ts is converted to a datetime naive object representing UTC time. String shall be compliant with: - Mediwiki timestamp format: YYYYMMDDHHMMSS - ISO8601 format: YYYY-MM-DD[T ]HH:MM:SS[Z|±HH[MM[SS[.ffffff]]]] - POSIX format: seconds from Unix epoch S{1,13}[.ffffff]]

Parameters:

ts (Union[str, datetime]) – Timestamp, datetime.datetime or str

Returns:

Timestamp object

Raises:

ValueError – conversion failed

Return type:

Timestamp

totimestampformat()

Convert object to a MediaWiki internal timestamp.

Return type:

str

class pywikibot.User(source, title='')

Bases: Page

A class that represents a Wiki user.

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

Initializer for a User object.

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

Parameters:

title (str) –

block(*args, **kwargs)

Block user.

Refer APISite.blockuser method for parameters.

Returns:

None

contributions(total=500, **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

deleted_contributions(*, total=500, **kwargs)

Yield tuples describing this user’s deleted edits.

New in version 5.5.

Parameters:

total (int) – Limit results 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

Return type:

Iterable[Tuple[Page, Revision]]

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: Optional[Tuple[Page, int, Timestamp, str]]

Return first user contribution.

Returns:

first user contribution entry

Returns:

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

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:

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:

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.

Deprecated since version 7.0: use is_blocked() instead

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

is_blocked(force=False)

Determine whether the user is currently blocked.

Changed in version 7.0: renamed from isBlocked() method, can also detect range blocks.

Parameters:

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

Return type:

bool

is_locked(force=False)

Determine whether the user is currently locked globally.

New in version 7.0.

Parameters:

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

Return type:

bool

property is_thankable: bool

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 T57401#2216861 and T120753#1863894.

property last_edit: Optional[Tuple[Page, int, Timestamp, str]]

Return last user contribution.

Returns:

last user contribution entry

Returns:

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

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

registration(force=False)

Fetch registration date for this user.

Parameters:

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

Return type:

Optional[Timestamp]

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

Return type:

None

uploadedImages(total=10)

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

The username.

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

class pywikibot.WbGeoShape(page, site=None)

Bases: _WbDataPage

A Wikibase geo-shape representation.

Create a new _WbDataPage object.

Parameters:

• page (Page) – page containing the data

• site (Optional[DataSite]) – The Wikibase site

class pywikibot.WbMonolingualText(text, language)

Bases: WbRepresentation

A Wikibase monolingual text representation.

Create a new WbMonolingualText object.

Parameters:

• text (str) – text string

• language (str) – language code of the string

classmethod fromWikibase(data, site=None)

Create a WbMonolingualText from the JSON data given by Wikibase API.

Parameters:

• data (Dict[str, Any]) – Wikibase JSON

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbMonolingualText

toWikibase()

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

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

class pywikibot.WbQuantity(amount, unit=None, error=None, site=None)

Bases: WbRepresentation

A Wikibase quantity representation.

Create a new WbQuantity object.

Parameters:

• amount (Optional[Union[int, float, str, Decimal]]) – number representing this quantity

• unit (Optional[Union[str, ItemPage]]) – the Wikibase item for the unit or the entity URI of this Wikibase item.

• error (Union[int, float, str, Decimal, None, Tuple[Optional[Union[int, float, str, Decimal]], Optional[Union[int, float, str, Decimal]]]]) – the uncertainty of the amount (e.g. ±1)

• site (Optional[DataSite]) – The Wikibase site

classmethod fromWikibase(data, site=None)

Create a WbQuantity from the JSON data given by the Wikibase API.

Parameters:

• data (Dict[str, Any]) – Wikibase JSON

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbQuantity

get_unit_item(repo=None, lazy_load=False)

Return the ItemPage corresponding to the unit.

Note that the unit need not be in the same data repository as the WbQuantity itself.

A successful lookup is stored as an internal value to avoid the need for repeated lookups.

Parameters:

• repo (Optional[DataSite]) – the Wikibase site for the unit, if different from that provided with the WbQuantity.

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

Returns:

pywikibot.ItemPage

Return type:

ItemPage

toWikibase()

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

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

property unit: str

Return _unit’s entity uri or ‘1’ if _unit is None.

class pywikibot.WbTabularData(page, site=None)

Bases: _WbDataPage

A Wikibase tabular-data representation.

Create a new _WbDataPage object.

Parameters:

• page (Page) – page containing the data

• site (Optional[DataSite]) – The Wikibase site

class pywikibot.WbTime(year=None, month=None, day=None, hour=None, minute=None, second=None, precision=None, before=0, after=0, timezone=0, calendarmodel=None, site=None)

Bases: WbRepresentation

A Wikibase time representation.

Create a new WbTime object.

The precision can be set by the Wikibase int value (0-14) or by a human readable string, e.g., ‘hour’. If no precision is given, it is set according to the given time units.

Timezone information is given in three different ways depending on the time:

• Times after the implementation of UTC (1972): as an offset from UTC in minutes;

• Times before the implementation of UTC: the offset of the time zone from universal time;

• Before the implementation of time zones: The longitude of the place of the event, in the range −180° to 180°, multiplied by 4 to convert to minutes.

Parameters:

• year (Optional[int]) – The year as a signed integer of between 1 and 16 digits.

• month (Optional[int]) – Month

• day (Optional[int]) – Day

• hour (Optional[int]) – Hour

• minute (Optional[int]) – Minute

• second (Optional[int]) – Second

• precision (Optional[Union[int, str]]) – The unit of the precision of the time.

• before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.

• after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.

• timezone (int) – Timezone information in minutes.

• calendarmodel (Optional[str]) – URI identifying the calendar model

• site (Optional[DataSite]) – The Wikibase site

FORMATSTR = '{0:+012d}-{1:02d}-{2:02d}T{3:02d}:{4:02d}:{5:02d}Z'

PRECISION = {'10000': 5, '100000': 4, '1000000': 3, '10000000': 2, '100000000': 1, '1000000000': 0, 'century': 7, 'day': 11, 'decade': 8, 'hour': 12, 'millenia': 6, 'minute': 13, 'month': 10, 'second': 14, 'year': 9}

classmethod fromTimestamp(timestamp, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)

Create a new WbTime object from a pywikibot.Timestamp.

Parameters:

• timestamp (Timestamp) – Timestamp

• precision (Union[int, str]) – The unit of the precision of the time.

• before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.

• after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.

• timezone (int) – Timezone information in minutes.

• calendarmodel (Optional[str]) – URI identifying the calendar model

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbTime

classmethod fromTimestr(datetimestr, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)

Create a new WbTime object from a UTC date/time string.

The timestamp differs from ISO 8601 in that:

• The year is always signed and having between 1 and 16 digits;

• The month, day and time are zero if they are unknown;

• The Z is discarded since time zone is determined from the timezone param.

Parameters:

• datetimestr (str) – Timestamp in a format resembling ISO 8601, e.g. +2013-01-01T00:00:00Z

• precision (Union[int, str]) – The unit of the precision of the time.

• before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.

• after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.

• timezone (int) – Timezone information in minutes.

• calendarmodel (Optional[str]) – URI identifying the calendar model

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbTime

classmethod fromWikibase(data, site=None)

Create a WbTime from the JSON data given by the Wikibase API.

Parameters:

• data (Dict[str, Any]) – Wikibase JSON

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbTime

toTimestamp()

Convert the data to a pywikibot.Timestamp.

Raises:

ValueError – instance value cannot be represented using Timestamp

Return type:

Timestamp

toTimestr(force_iso=False)

Convert the data to a UTC date/time string.

See fromTimestr() for differences between output with and without force_iso.

Parameters:

force_iso (bool) – whether the output should be forced to ISO 8601

Returns:

Timestamp in a format resembling ISO 8601

Return type:

str

toWikibase()

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

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

class pywikibot.WbUnknown(json)

Bases: WbRepresentation

A Wikibase representation for unknown data type.

This will prevent the bot from breaking completely when a new type is introduced.

This data type is just a json container

New in version 3.0.

Create a new WbUnknown object.

Parameters:

json (Dict[str, Any]) – Wikibase JSON

classmethod fromWikibase(data, site=None)

Create a WbUnknown from the JSON data given by the Wikibase API.

Parameters:

• data (Dict[str, Any]) – Wikibase JSON

• site (Optional[DataSite]) – The Wikibase site

Return type:

WbUnknown

toWikibase()

Return the JSON object for the Wikibase API.

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

class pywikibot.WikidataBot(**kwargs)

Bases: Bot, ExistingPageBot

Generic Wikidata Bot to be subclassed.

Source claims (P143) can be created for specific sites

Variables:

• use_from_page – If True (default) it will apply ItemPage.fromPage for every item. If False it assumes that the pages are actually already ItemPage (page in treat_page_and_item will be None). If None it’ll use ItemPage.fromPage when the page is not in the site’s item namespace.

• treat_missing_item – Whether pages without items should be treated. Note that this is checked after create_missing_item.

• create_missing_item – If True, new items will be created if the current page doesn’t have one. Subclasses should override this in the initializer with a bool value or using self.opt attribute.

Parameters:

kwargs (Any) –

Initializer of the WikidataBot.

cacheSources()

Fetch the sources from the list on Wikidata.

It is stored internally and reused by getSource()

Return type:

None

create_item_for_page(page, data=None, summary=None, **kwargs)

Create an ItemPage with the provided page as the sitelink.

Parameters:

• page (BasePage) – the page for which the item will be created

• data (Optional[Dict[str, Any]]) – additional data to be included in the new item (optional). Note that data created from the page have higher priority.

• summary (Optional[str]) – optional edit summary to replace the default one

• kwargs (Any) –

Returns:

pywikibot.ItemPage or None

Return type:

Optional[ItemPage]

getSource(site)

Create a Claim usable as a source for Wikibase statements.

Parameters:

site (BaseSite) – site that is the source of assertions.

Returns:

pywikibot.Claim or None

Return type:

Optional[pywikibot.page.Claim]

get_property_by_name(property_name)

Find given property and return its ID.

Method first uses site.search() and if the property isn’t found, then asks user to provide the property ID.

Parameters:

property_name (str) – property to find

Return type:

str

treat_missing_item = False

treat_page()

Treat a page.

Return type:

None

treat_page_and_item(page, item)

Treat page together with its item (if it exists).

Must be implemented in subclasses.

Parameters:

• page (BasePage) –

• item (ItemPage) –

Return type:

None

use_from_page = True

user_add_claim(item, claim, source=None, bot=True, **kwargs)

Add a claim to an item, with user confirmation as required.

Parameters:

• item (pywikibot.page.ItemPage) – page to be edited

• claim (pywikibot.page.Claim) – claim to be saved

• source (Optional[BaseSite]) – site where the claim comes from

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

• kwargs (Any) –

Keyword Arguments:

• ignore_server_errors – if True, server errors will be reported and ignored (default: False)

• ignore_save_related_errors – if True, errors related to page save will be reported and ignored (default: False)

Returns:

whether the item was saved successfully

Return type:

bool

Note

calling this method sets the current_page property to the item which changes the site property

Note

calling this method with the ‘source’ argument modifies the provided claim object in place

user_add_claim_unless_exists(item, claim, exists_arg='', source=None, logger_callback=<function deprecated_args.<locals>.decorator.<locals>.wrapper>, **kwargs)

Decorator of user_add_claim.

Before adding a new claim, it checks if we can add it, using provided filters.

See also

documentation of claimit.py

Parameters:

• exists_arg (Container) – pattern for merging existing claims with new ones

• logger_callback (Callable[str, Any]) – function logging the output of the method

• item (pywikibot.page.ItemPage) –

• claim (pywikibot.page.Claim) –

• source (Optional[BaseSite]) –

• kwargs (Any) –

Returns:

whether the claim could be added

Return type:

bool

Note

calling this method may change the current_page property to the item which will also change the site property

Note

calling this method with the ‘source’ argument modifies the provided claim object in place

user_edit_entity(entity, data=None, ignore_save_related_errors=None, ignore_server_errors=None, **kwargs)

Edit entity with data provided, with user confirmation as required.

Parameters:

• entity (WikibasePage) – page to be edited

• data (Optional[Dict[str, str]]) – data to be saved, or None if the diff should be created automatically

• ignore_save_related_errors (Optional[bool]) – Ignore save related errors and automatically print a message. If None uses this instances default.

• ignore_server_errors (Optional[bool]) – Ignore server errors and automatically print a message. If None uses this instances default.

• kwargs (Any) –

Keyword Arguments:

• summary – revision comment, passed to ItemPage.editEntity

• show_diff – show changes between oldtext and newtext (default: True)

Returns:

whether the item was saved successfully

Return type:

bool

pywikibot.async_manager(block=True)

Daemon; take requests from the queue and execute them in background.

Return type:

None

pywikibot.async_request(request, *args, **kwargs)

Put a request on the queue, and start the daemon if necessary.

Parameters:

• request (Callable) –

• args (Any) –

• kwargs (Any) –

Return type:

None

pywikibot.calledModuleName()

Return the name of the module calling this function.

This is required because the -help option loads the module’s docstring and because the module name will be used for the filename of the log.

Return type:

str

pywikibot.critical(msg, text='[deprecated name of msg]', *args, **kwargs)

Output a critical record to the user with level CRITICAL.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text`was renamed to `msg; only keyword arguments are allowed except for msg.

See also

Logger.critical()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.debug(msg, text='[deprecated name of msg]', *args, **kwargs)

Output a debug record to the log file with level DEBUG.

The arguments are interpreted as for logoutput().

Changed in version 7.2: layer parameter is optional; text`was renamed to `msg; only keyword arguments are allowed except for msg.

See also

Logger.debug()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.error(msg, text='[deprecated name of msg]', *args, **kwargs)

Output an error message to the user with level ERROR.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text`was renamed to `msg; only keyword arguments are allowed except for msg.

See also

Logger.error()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.exception(msg=None, tb='[deprecated name of exc_info]', *args, exc_info=True, **kwargs)

Output an error traceback to the user with level ERROR.

Use directly after an ‘except’ statement:

...
except Exception:
    pywikibot.exception()
...

or alternatively:

...
except Exception as e:
    pywikibot.exception(e)
...

With exc_info=False this function works like error() except that the msg parameter may be omitted. This function should only be called from an Exception handler. msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: only keyword arguments are allowed except for msg; exc_info keyword is to be used instead of tb.

Changed in version 7.3: exc_info is True by default

See also

Logger.exception()

The arguments are interpreted as for output().

Parameters:

• msg (Any) –

• args (Any) –

• exc_info (bool) –

• kwargs (Any) –

pywikibot.handle_args(args=None, do_help=True)

Handle global command line arguments and return the rest as a list.

Takes the command line arguments as strings, processes all global parameters such as -lang or -log, initialises the logging layer, which emits startup information into log at level ‘verbose’. This function makes sure that global arguments are applied first, regardless of the order in which the arguments were given. args may be passed as an argument, thereby overriding sys.argv.

>>> local_args = pywikibot.handle_args()  # sys.argv is used
>>> local_args  
[]
>>> local_args = pywikibot.handle_args(['-simulate', '-myoption'])
>>> local_args  # global optons are handled, show the remaining
['-myoption']
>>> for arg in local_args: pass  # do whatever is wanted with local_args

Changed in version 5.2: -site global option was added

Changed in version 7.1: -cosmetic_changes and -cc may be set directly instead of toggling the value. Refer tools.strtobool() for valid values.

Changed in version 7.7: -config global option was added.

Parameters:

• args (Optional[Iterable[str]]) – Command line arguments. If None, pywikibot.argvu is used which is a copy of sys.argv

• do_help (bool) – Handle parameter ‘-help’ to show help and invoke sys.exit

Returns:

list of arguments not recognised globally

Return type:

List[str]

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

Replace HTML entities with equivalent unicode.

Parameters:

• ignore – HTML entities to ignore

• ignore – list of int

• text (str) –

Return type:

str

pywikibot.info(msg='', text='[deprecated name of msg]', *args, **kwargs)

Output a message to the user with level INFO.

msg will be sent to stderr via pywikibot.userinterfaces. It may be omitted and a newline is printed in that case. The arguments are interpreted as for logoutput().

New in version 7.2: was renamed from output().

See also

Logger.info()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.input(question, password=False, default='', force=False)

Ask the user a question, return the user’s answer.

Parameters:

• question (str) – a string that will be shown to the user. Don’t add a space after the question mark/colon, this method will do this for you.

• password (bool) – if True, hides the user’s input (for password entry).

• default (Optional[str]) – The default answer if none was entered. None to require an answer.

• force (bool) – Automatically use the default

Return type:

str

pywikibot.input_choice(question, answers, default=None, return_shortcut=True, automatic_quit=True, force=False)

Ask the user the question and return one of the valid answers.

Parameters:

• question (str) – The question asked without trailing spaces.

• answers (Union[Iterable[Union[Tuple[str, str], Option]], Option]) – The valid answers each containing a full length answer and a shortcut. Each value must be unique.

• default (Optional[str]) – The result if no answer was entered. It must not be in the valid answers and can be disabled by setting it to None. If it should be linked with the valid answers it must be its shortcut.

• return_shortcut (bool) – Whether the shortcut or the index of the answer is returned.

• automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) and throw a QuitKeyboardInterrupt if selected.

• force (bool) – Automatically use the default

Returns:

The selected answer shortcut or index. Is -1 if the default is selected, it does not return the shortcut and the default is not a valid shortcut.

Return type:

Any

pywikibot.input_yn(question, default=None, automatic_quit=True, force=False)

Ask the user a yes/no question and return the answer as a bool.

Parameters:

• question (str) – The question asked without trailing spaces.

• default (Optional[Union[bool, str]]) – The result if no answer was entered. It must be a bool or ‘y’ or ‘n’ and can be disabled by setting it to None.

• automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) and throw a QuitKeyboardInterrupt if selected.

• force (bool) – Automatically use the default

Returns:

Return True if the user selected yes and False if the user selected no. If the default is not None it’ll return True if default is True or ‘y’ and False if default is False or ‘n’.

Return type:

bool

pywikibot.log(msg, text='[deprecated name of msg]', *args, **kwargs)

Output a record to the log file with level VERBOSE.

The arguments are interpreted as for logoutput().

Changed in version 7.2: text`was renamed to `msg; only keyword arguments are allowed except for msg.

See also

Logger.log()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.output(msg='', text='[deprecated name of msg]', *args, **kwargs)

Output a message to the user with level INFO.

msg will be sent to stderr via pywikibot.userinterfaces. It may be omitted and a newline is printed in that case. The arguments are interpreted as for logoutput().

New in version 7.2: was renamed from output().

See also

Logger.info()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.showDiff(oldtext, newtext, context=0)

Output a string showing the differences between oldtext and newtext.

The differences are highlighted (only on compatible systems) to show which changes were made.

Parameters:

• oldtext (str) –

• newtext (str) –

• context (int) –

Return type:

None

pywikibot.show_help(module_name=None, show_global=False)

Show help for the Bot.

Changed in version 4.0: Renamed from showHelp() to show_help().

Parameters:

• module_name (Optional[str]) –

• show_global (bool) –

Return type:

None

pywikibot.sleep(secs)

Suspend execution of the current thread for the given number of seconds.

Drop this process from the throttle log if wait time is greater than 30 seconds.

Parameters:

secs (int) –

Return type:

None

pywikibot.stdout(msg='', text='[deprecated name of msg]', *args, **kwargs)

Output script results to the user with level STDOUT.

msg will be sent to standard output (stdout) via pywikibot.userinterfaces, so that it can be piped to another process. All other functions will send to stderr. msg may be omitted and a newline is printed in that case.

The arguments are interpreted as for logoutput().

Changed in version 7.2: text`was renamed to `msg; msg parameter may be omitted; only keyword arguments are allowed except for msg.

See also

• Logger.log()

• https://en.wikipedia.org/wiki/Pipeline_%28Unix%29

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –

pywikibot.stopme()

Drop this process from the throttle log, after pending threads finish.

Can be called manually if desired. Does not clean async_manager. This should be run when a bot does not interact with the Wiki, or when it has stopped doing so. After a bot has run stopme() it will not slow down other bots any more.

Return type:

None

pywikibot.translate(code, xdict, parameters=None, fallback=False)

Return the most appropriate localization from a localization dict.

Given a site code and a dictionary, returns the dictionary’s value for key ‘code’ if this key exists; otherwise tries to return a value for an alternative code that is most applicable to use on the wiki in language ‘code’ except fallback is False.

The code itself is always checked first, then these codes that have been defined to be alternatives, and finally English.

If fallback is False and the code is not found in the

For PLURAL support have a look at the twtranslate method.

Parameters:

• code (Union[str, BaseSite]) – The site code as string or Site object. If xdict is an extended dictionary the Site object should be used in favour of the code string. Otherwise localizations from a wrong family might be used.

• xdict (Union[str, Mapping[str, str]]) – dictionary with language codes as keys or extended dictionary with family names as keys containing code dictionaries or a single string. May contain PLURAL tags as described in twtranslate

• parameters (Optional[Mapping[str, int]]) – For passing (plural) parameters

• fallback (Union[bool, Iterable[str]]) – Try an alternate language code. If it’s iterable it’ll also try those entries and choose the first match.

Returns:

the localized string

Raises:

• IndexError – If the language supports and requires more plurals than defined for the given PLURAL pattern.

• KeyError – No fallback key found if fallback is not False

Return type:

Optional[str]

pywikibot.url2unicode(title, encodings='utf-8')

Convert URL-encoded text to unicode using several encoding.

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

Deprecated since version 6.2: Use tools.chars.url2string() instead.

Parameters:

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

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

Raises:

UnicodeError – Could not convert using any encoding.

Return type:

str

pywikibot.warning(msg, text='[deprecated name of msg]', *args, **kwargs)

Output a warning message to the user with level WARNING.

msg will be sent to stderr via pywikibot.userinterfaces. The arguments are interpreted as for logoutput().

Changed in version 7.2: text`was renamed to `msg; only keyword arguments are allowed except for msg.

See also

Logger.warning()

Parameters:

• msg (Any) –

• args (Any) –

• kwargs (Any) –