`pywikibot` — Base Classes and Functions#

The initialization file for the Pywikibot framework.

Imports from bot module

The following classes and functions are inported from bot module but can also be used as pywikibot members:

Imports from i18n module

The following function is inported from i18n module but can also be used as pywikibot members:

pywikibot.translate()

Imports from logging module

The following functions are inported from logging module but can also be used as pywikibot members:

Imports from page module

The following classes and function are inported from page module but can also be used as pywikibot members:

Imports from time module

The following class is inported from time module but can also be used as pywikibot members:

pywikibot.Timestamp

class pywikibot.Bot(site=None, **kwargs)[source]#

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 (BaseSite | None)
kwargs (Any)

init_page(item)[source]#

Update site before calling treat.

Parameters:: item (Any)
Return type:: BasePage

run()[source]#

Check if it automatically updates the site before run.

Return type:: None

property site: BaseSite | None#: Get the current site.

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

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, **kwargs)[source]#

Yield all articles in the current category.

Yields all pages in the category that are not subcategories. Duplicates are filtered. To enable duplicates use members() with member_type=['page', 'file'] instead.

Usage:

>>> site = pywikibot.Site('wikipedia:test')
>>> cat = pywikibot.Category(site, 'Pywikibot')
>>> list(cat.articles())
[Page('Pywikibot nobots test')]
>>> for p in cat.articles(recurse=1, namespaces=2, total=3):
...     print(p.depth)
...
2
3
4

Warning

Categories may have infinite recursions of subcategories. If recurse option is given as True or an int value and this value is less than sys.getrecursionlimit(), an RecursionError may be raised. Be careful if passing this generator to a collection in such case.

Changed in version 8.0: all parameters are keyword arguments only.

Parameters:

recurse (int | 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 (int | None) – iterate no more than this number of pages in total (at all levels)
kwargs (Any) – Additional parameters. Refer to APISite.categorymembers() for complete list (member_type excluded).

Return type:

Generator[Page, None, None]

aslink(sort_key=None)[source]#

Return a link to place a page in this Category.

Warning

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

Usage:

>>> site = pywikibot.Site('wikipedia:test')
>>> cat = pywikibot.Category(site, 'Foo')
>>> cat.aslink()
'[[Category:Foo]]'
>>> cat = pywikibot.Category(site, 'Foo', sort_key='bar')
>>> cat.aslink()
'[[Category:Foo|bar]]'
>>> cat.aslink('baz')
'[[Category:Foo|baz]]'

Parameters:: sort_key (str | None) – 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[str, Any]#

Return a dict containing information about the category.

The dict contains values for numbers of pages, subcategories, files, and total contents.

See also

APISite.categoryinfo()

isEmptyCategory()[source]#

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

Return type:: bool

isHiddenCategory()[source]#

Return True if the category is hidden.

Return type:: bool

members(*, recurse=False, total=None, **kwargs)[source]#

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

Usage:

>>> site = pywikibot.Site('wikipedia:test')
>>> cat = pywikibot.Category(site, 'Pywikibot')
>>> list(cat.members(member_type='subcat'))
[Category('Category:Subpage testing')]
>>> list(cat.members(member_type=['page', 'file']))
[Page('Pywikibot nobots test')]

Calling this method with member_type='subcat' is equal to calling subcategories(). Calling this method with member_type=['page', 'file'] is equal to calling articles() except that the later will filter duplicates.

See also

APISite.categorymembers()

Warning

Changed in version 8.0: all parameters are keyword arguments only. Additional parameters are supported.

Parameters:

recurse (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 (int | None) – iterate no more than this number of pages in total (at all levels)
kwargs (Any) – Additional parameters. Refer to APISite.categorymembers() for complete list.

Return type:

Generator[Page, None, None]

newest_pages(total=None)[source]#

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 | None) – 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, **kwargs)[source]#

Yield all subcategories of the current category.

Usage:

>>> site = pywikibot.Site('wikipedia:en')
>>> cat = pywikibot.Category(site, 'Contents')
>>> next(cat.subcategories())
Category('Category:Wikipedia administration')
>>> len(list(cat.subcategories(recurse=2, total=50)))
50

Subcategories of the same level of each subtree are yielded first before the next subcategories level are yielded. For example having this category tree:

A
+-- B
|   +-- E
|   |   +-- H
|   +-- F
|   +-- G
+-- C
|   +-- I
|   |   +-- E
|   |       +-- H
|   +-- J
|       +-- K
|       +-- L
|           +-- G
+-- D

Subcategories are yields in the following order: B, C, D, E, F, G, H, I, J, E, H, K, L, G

See also

categoryinfo

Warning

Changed in version 8.0: all parameters are keyword arguments only. Additional parameters are supported. The order of subcategories are yielded was changed. The old order was B, E, H, F, G, C, I, E, H, J, K, L, G, D

Parameters:

recurse (int | 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.)
kwargs (Any) – Additional parameters. Refer to APISite.categorymembers() for complete list (member_type excluded).

Return type:

Generator[Page, None, None]

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

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 where the property of the claim is defined. Note that this does not have to correspond to the repository where the claim has been stored.
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._wbtypes.WbGeoShape'>>, 'globe-coordinate': <bound method Coordinate.fromWikibase of <class 'pywikibot._wbtypes.Coordinate'>>, 'monolingualtext': <function Claim.<lambda>>, 'quantity': <bound method WbQuantity.fromWikibase of <class 'pywikibot._wbtypes.WbQuantity'>>, 'tabular-data': <bound method WbDataPage.fromWikibase of <class 'pywikibot._wbtypes.WbTabularData'>>, 'time': <bound method WbTime.fromWikibase of <class 'pywikibot._wbtypes.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)[source]#

Add the given qualifier.

Parameters:: qualifier (pywikibot.page.Claim) – the qualifier to add
Return type:: None

addSource(claim, **kwargs)[source]#

Add the claim as a source.

Parameters:: claim (Claim) – the claim to add
Return type:: None

addSources(claims, **kwargs)[source]#

Add the claims as one source.

Parameters:: claims (list of Claim) – the claims to add
Return type:: None

changeRank(rank, **kwargs)[source]#: Change the rank of the Claim and save.

changeSnakType(value=None, **kwargs)[source]#

Save the new snak value.

TODO: Is this function really needed?

Return type:: None

changeTarget(value=None, snaktype='value', **kwargs)[source]#

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()[source]#

Create an independent copy of this object.

Return type:: pywikibot.page.Claim

classmethod fromJSON(site, data)[source]#

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

Changed in version 9.4: print a warning if the Claim.type is not given and missing in the wikibase.

Parameters:: data (dict[str, Any]) – JSON containing claim data
Return type:: Claim

getRank()[source]#: Return the rank of the Claim.

getSnakType()[source]#

Return the type of snak.

Returns:: str (‘value’, ‘somevalue’ or ‘novalue’)
Return type:: str

getSources()[source]#

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

Return type:: list

getTarget()[source]#

Return the target value of this Claim.

None is returned if no target is set

Returns:: object

has_qualifier(qualifier_id, target)[source]#

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: WikibaseEntity | None#: Return entity this claim is attached to.

classmethod qualifierFromJSON(site, data)[source]#

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)[source]#

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

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

Return type:: dict

removeQualifier(qualifier, **kwargs)[source]#

Remove the qualifier. Call removeQualifiers().

Parameters:: qualifier (pywikibot.page.Claim) – the qualifier to remove
Return type:: None

removeQualifiers(qualifiers, **kwargs)[source]#

Remove the qualifiers.

Parameters:: qualifiers (list of Claim) – the qualifiers to remove
Return type:: None

removeSource(source, **kwargs)[source]#

Remove the source. Call removeSources().

Parameters:: source (Claim) – the source to remove
Return type:: None

removeSources(sources, **kwargs)[source]#

Remove the sources.

Parameters:: sources (list of Claim) – the sources to remove
Return type:: None

same_as(other, ignore_rank=True, ignore_quals=False, ignore_refs=True)[source]#

Check if two claims are same.

Parameters:

ignore_rank (bool)
ignore_quals (bool)
ignore_refs (bool)

Return type:

bool

setRank(rank)[source]#

Set the rank of the Claim.

Return type:: None

setSnakType(value)[source]#

Set the type of snak.

Parameters:: value (str ('value', 'somevalue', or 'novalue')) – Type of snak
Return type:: None

setTarget(value)[source]#

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.
Return type:: None

target_equals(value)[source]#

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()[source]#

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)[source]#

Bases: WbRepresentation

Class for handling and storing Coordinates.

Represent a geo coordinate.

Parameters:

lat (float) – Latitude
lon (float) – Longitude
alt (float | None) – Altitude
precision (float | None) – precision
globe (str | None) – Which globe the point is on
typ (str) – The type of coordinate point
name (str) – The name
dim (int | None) – Dimension (in meters)
site (DataSite | None) – The Wikibase site
globe_item (ItemPageStrNoneType) – 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)[source]#

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

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

Coordinate

get_globe_item(repo=None, lazy_load=False)[source]#

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 (DataSite | None) – 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: float | None#

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()[source]#

Convert precision from Wikibase to GeoData’s dim.

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:: int | None

toWikibase()[source]#

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)[source]#

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)[source]#

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 (bool | None) – Ignore save related errors and automatically print a message. If None uses this instances default.
ignore_server_errors (bool | None) – 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)[source]#

Set page to current page and treat that page.

Parameters:: page (BasePage)
Return type:: None

treat_page()[source]#

Process one page (Abstract method).

Return type:: None

class pywikibot.FilePage(source, title='', *, ignore_extension=False)[source]#

Bases: Page

A subclass of Page representing a file description page.

Supports the same interface as Page except ns; some added methods.

Changed in version 8.4: Check for valid extensions.

Changed in version 9.3: Added the optional ignore_extension parameter.

Changed in version 9.6: Show a warning if ignore_extension was set and the extension is invalid.

See also

Site.file_extensions

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
ignore_extension (bool) – prevent extension check

Raises:

ValueError – Either the title is not in the file namespace or does not have a valid extension and ignore_extension was not set.

data_item()[source]#

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 the behavior of BasePage.data_item().

Added in version 6.5.

Return type:: pywikibot.page.WikibaseEntity

download(filename=None, chunk_size=102400, revision=None, *, url_width=None, url_height=None, url_param=None)[source]#

Download to filename file of FilePage.

Usage examples:

Download an image:

>>> site = pywikibot.Site('wikipedia:test')
>>> file = pywikibot.FilePage(site, 'Pywikibot MW gear icon.svg')
>>> file.download()
True

Pywikibot_MW_gear_icon.svg was downloaded.

Download a thumbnail:

>>> file.download(url_param='120px')
True

The suffix has changed and Pywikibot_MW_gear_icon.png was downloaded.

Added in version 8.2: url_width, url_height and url_param parameters.

Changed in version 8.2: filename argument may be also a path-like object or an iterable of path segments.

Note

filename suffix is adjusted if target url’s suffix is different which may be the case if a thumbnail is loaded.

Warning

If a file already exists, it will be overridden without further notes.

See also

API:Imageinfo for new parameters

Parameters:

filename (str | PathLike | Iterable[str] | None) – filename where to save file. If None, self.title(as_filename=True, with_ns=False) will be used. If an Iterable is specified the items will be used as path segments. To specify the user directory path you have to use either ~ or ~user as first path segment e.g. ~/foo or ('~', 'foo') as filename. If only the user directory specifier is given, the title is used as filename like for None. If the suffix is missing or different from url (which can happen if a url_width, url_height or url_param argument is given), the file suffix is adjusted.
chunk_size (int) – the size of each chunk to be received and written to file.
revision (FileInfo | None) – file revision to download. If None latest_file_info will be used; otherwise provided revision will be used.
url_width (int | None) – download thumbnail with given width
url_height (int | None) – download thumbnail with given height
url_param (str | None) – download thumbnail with given param

Returns:

True if download is successful, False otherwise.

Raises:

IOError – if filename cannot be written for any reason.

Return type:

bool

file_is_shared()[source]#

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.

Added in version 7.1.

getFileVersionHistoryTable()[source]#

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

Return type:: str

getImagePageHtml()[source]#

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()[source]#

Return the file’s version history.

Returns:: dictionary with: key: timestamp of the entry value: instance of FileInfo()
Return type:: dict

get_file_info(ts)[source]#

Retrieve and store information of a specific Image rev. of FilePage.

This function will load also metadata. It is also used as a helper in FileInfo to load metadata lazily.

Added in version 8.6.

Parameters:: ts – timestamp of the Image rev. to retrieve
Returns:: instance of FileInfo()
Return type:: dict

get_file_url(url_width=None, url_height=None, url_param=None)[source]#

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

Fetch the information if not available.

Once retrieved, file information will also be accessible as latest_file_info attributes, named as in API:Imageinfo. If url_width, url_height or url_param is given, additional properties thumbwidth, thumbheight, thumburl and responsiveUrls are provided.

Note

Parameters validation and error handling left to the API call.

See also

Parameters:

url_width (int | None) – get info for a thumbnail with given width
url_height (int | None) – get info for a thumbnail with given height
url_param (str | None) – get info for a thumbnail with given param

Returns:

latest file url or thumburl

Return type:

str

globalusage(total=None)[source]#

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)[source]#

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

using_pages(**kwargs)[source]#

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)
2
>>> 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)[source]#

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: dict[str, Any] = {'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)[source]#

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)[source]#

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)[source]#

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)[source]#

Get the entity identifier.

Parameters:

numeric (bool) – Strip the first letter and return an int
force (bool) – Force an update of new data

getRedirectTarget(*, ignore_section=True)[source]#

Return the redirect target for this page.

Added in version 9.3: ignore_section parameter

See also

page.BasePage.getRedirectTarget()

Parameters:

ignore_section (bool) – do not include section to the target even the link has one

Raises:

CircularRedirectError – page is a circular redirect
InterwikiRedirectPageError – the redirect target is on another site
Error – target page has wrong content model
IsNotRedirectPageError – page is not a redirect
RuntimeError – no redirects found
SectionError – the section is not found on target page and ignore_section is not set

getSitelink(site, force=False)[source]#

Return the title for the specific site.

If the item doesn’t have a link to that site, raise NoSiteLinkError.

Changed in version 8.1: raises NoSiteLinkError instead of NoPageError.

Parameters:

site (pywikibot.Site or database name) – Site to find the linked page of.
force (bool) – override caching

Raises:

IsRedirectPageError – instance is a redirect page
NoSiteLinkError – site is not in sitelinks

Return type:

str

isRedirectPage()[source]#: Return True if item is a redirect, False if not or not existing.

iterlinks(family=None)[source]#

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)[source]#

Merge the item into another item.

Parameters:: item (pywikibot.page.ItemPage) – The item to merge into
Return type:: None

removeSitelink(site, **kwargs)[source]#

Remove a sitelink.

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

Parameters:: site (LANGUAGE_IDENTIFIER)
Return type:: None

removeSitelinks(sites, **kwargs)[source]#

Remove sitelinks.

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

Parameters:: sites (list[LANGUAGE_IDENTIFIER])
Return type:: None

setSitelink(sitelink, **kwargs)[source]#

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 (SITELINK_TYPE)
Return type:: None

setSitelinks(sitelinks, **kwargs)[source]#

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[SITELINK_TYPE])
Return type:: None

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, botflag='[deprecated name of bot]', **kwargs)[source]#

Make the item redirect to another item.

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

Changed in version 9.3: botflag keyword parameter was renamed to bot.

Parameters:

target_page (ItemPage | str) – 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)[source]#

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)[source]#

Bases: LexemeSubEntity

Wikibase lexeme form.

DATA_ATTRIBUTES: dict[str, Any] = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'representations': <class 'pywikibot.page._collections.LanguageDict'>}#

edit_elements(data, **kwargs)[source]#

Update form elements.

Parameters:: data (dict) – Data to be saved
Return type:: None

entity_type = 'form'#

get(force=False)[source]#

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)[source]#

Create dict suitable for the MediaWiki API.

Parameters:: diffto (dict | None)
Return type:: dict

class pywikibot.LexemePage(site, title=None)[source]#

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)  # access the claims
['P5402', 'P5831', 'P12690', 'P12448', 'P31', 'P5275', 'P12510', ...]
>>> len(L2.forms)  # access the forms
3
>>> F1 = L2.forms[0]  # access the first form
>>> list(F1.claims)  # access its claims
['P898']
>>> len(L2.senses)  # access the senses
2
>>> S1 = L2.senses[0]  # access the first sense
>>> list(S1.claims)  # 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: dict[str, Any] = {'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)[source]#

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)[source]#

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()[source]#

Return data required for creation of a new lexeme.

Return type:: NoReturn

isRedirectPage()[source]#: Return True if lexeme is redirect, False if not or not existing.

mergeInto(lexeme, **kwargs)[source]#

Merge the lexeme into another lexeme.

Parameters:: lexeme (LexemePage) – The lexeme to merge into
Return type:: None

remove_form(form, **kwargs)[source]#

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)[source]#

Create JSON suitable for Wikibase API.

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

Parameters:: diffto (dict | None) – JSON containing entity data
Return type:: dict

class pywikibot.LexemeSense(repo, id_=None)[source]#

Bases: LexemeSubEntity

Wikibase lexeme sense.

DATA_ATTRIBUTES: dict[str, Any] = {'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)[source]#

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)[source]#

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)[source]#

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)[source]#

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)[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 (Site) – Link from site source

Return type:

pywikibot.page.Link

property namespace#

Return the namespace of the link.

Return type:: pywikibot.Namespace

parse()[source]#

Parse wikitext of the link.

Called internally when accessing attributes.

Return type:: None

parse_site()[source]#

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)[source]#

Bases: WikibaseEntity

Interface for MediaInfo entities on Commons.

Added in version 6.5.

Parameters:

repo (DataSite) – Entity repository.
id (str or None, -1 and None mean non-existing) – Entity identifier.
id_ (str | None)

DATA_ATTRIBUTES: dict[str, Any] = {'labels': <class 'pywikibot.page._collections.LanguageDict'>, 'statements': <class 'pywikibot.page._collections.ClaimCollection'>}#

addClaim(claim, bot=True, **kwargs)[source]#

Add a claim to the MediaInfo.

Added in version 8.5.

Parameters:

claim (pywikibot.page.Claim) – The claim to add
bot (bool) – Whether to flag as bot (if possible)

Return type:

None

editLabels(labels, **kwargs)[source]#

Edit MediaInfo labels (eg. captions).

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.

Usage:

>>> repo = pywikibot.Site('commons','commons')
>>> page = pywikibot.FilePage(repo, 'File:Sandbox-Test.svg')
>>> item = page.data_item()
>>> item.editLabels({'en': 'Test file.'})

Added in version 8.5.

Parameters:: labels (LANGUAGE_TYPE)
Return type:: None

entity_type = 'mediainfo'#

property file: FilePage#: Get the file associated with the mediainfo.

get(force=False)[source]#

Fetch all MediaInfo entity data and cache it.

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

Changed in version 9.0: Added pageid, ns, title, lastrevid, modified, id values to _content attribute when it is loaded.

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)[source]#

Get the entity identifier.

See also

title()

Parameters:: numeric (bool) – Strip the first letter and return an int
Raises:: NoWikibaseEntityError – if this entity is associated with a non-existing file
Return type:: str | int

removeClaims(claims, **kwargs)[source]#

Remove the claims from the MediaInfo.

Added in version 8.5.

Parameters:: claims (list or Claim) – list of claims to be removed
Return type:: None

title()[source]#

Return ID as title of the MediaInfo.

Added in version 9.4.

See also

getID()

Raises:: NoWikibaseEntityError – if this entity is associated with a non-existing file
Returns:: the entity identifier
Return type:: str

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

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

Bases: BasePage, WikiBlameMixin

Page: A MediaWiki page.

Instantiate a Page object.

Parameters:: title (str)

get_best_claim(prop)[source]#

Return the first best Claim for this page.

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

Added 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, botflag='[deprecated name of bot]', **kwargs)[source]#

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

Changed in version 9.3: botflag keyword parameter was renamed to bot.

Parameters:

target_page (Page | str) – 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()[source]#

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[tuple[Page, list[str]]]

class pywikibot.PropertyPage(source, title=None, datatype=None)[source]#

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: dict[str, Any] = {'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)[source]#

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)[source]#

Get the identifier of this property.

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

get_data_for_new_entity()[source]#: Return data required for creation of new property.

newClaim(*args, **kwargs)[source]#

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)[source]#

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').

Changed in version 10.0: url does not have to contain an api, requests or script path any longer.

Parameters:

code (str | None) – language code (override config.mylang) code may also be a sitename like ‘wikipedia:test’
fam (str | Family | None) – family name or object (override config.family)
user (str | None) – bot user name to use on this site (override config.usernames)
interface (str | BaseSite | None) – site class or name of class in pywikibot.site (override config.site_interface)
url (str | None) – 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)[source]#

Bases: BaseLink

A single sitelink in a Wikibase item.

Extends BaseLink by the following attribute:

badges: Any badges associated with the sitelink

Added 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)[source]#

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

Parameters:

data (dict[str, Any]) – JSON containing SiteLink data
site (pywikibot.site.DataSite) – The Wikibase site

Return type:

SiteLink

toJSON()[source]#

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

Returns:: Wikibase JSON
Return type:: dict[str, str | list[str]]

class pywikibot.Timestamp[source]#

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.timedelta) 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, MediaWiki, or POSIX formats.

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

Changed in version 7.5: moved to time module

ISO8601Format#

classproperty ISO8601 format string class property for compatibility purpose.

Return type:: str

clone()[source]#

Clone this instance.

Deprecated since version 8.0: Use replace() method instead.

Return type:: Timestamp

classmethod fromISOformat(ts, sep='T')[source]#

Convert an ISO 8601 timestamp to a Timestamp object.

Parameters:

ts (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, strict=False)[source]#

Convert a MediaWiki internal timestamp to a Timestamp object.

Changed in version 3.0: create a Timestamp if only year, month and day are given.

Changed in version 8.0: the strict parameter was added which discards missing element tolerance.

Example

>>> Timestamp.fromtimestampformat('20220705082234')
Timestamp(2022, 7, 5, 8, 22, 34)
>>> Timestamp.fromtimestampformat('20220927')
Timestamp(2022, 9, 27, 0, 0)
>>> Timestamp.fromtimestampformat('20221109', strict=True)
Traceback (most recent call last):
...
ValueError: time data '20221109' does not match MW format.

param ts:: the timestamp to be converted
param strict:: If true, do not ignore missing timestamp elements for hours, minutes or seconds
return:: return the Timestamp object from given ts.
raises ValueError:: The timestamp is invalid, e.g. missing or invalid timestamp component.

Parameters:

ts (str | Timestamp)
strict (bool)

Return type:

Timestamp

isoformat(sep='T')[source]#

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

classmethod nowutc(*, with_tz=True)[source]#

Return the current UTC date and time.

If with_tz is True it returns an aware Timestamp object with UTC timezone by calling now(datetime.UTC). As such this is just a short way to get it.

Otherwise the UTC timestamp is returned as a naive Timestamp object with timezone of None. This is equal to the Timestamp.utcnow().

Warning

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware Timestamps or datetimes to represent times in UTC. As such, it is not recommended to set with_tz to False.

Caution

You cannot compare, add or subtract offset-naive and offset- aware Timestamps/datetimes (i.e. missing or having timezone). A TypeError will be raised in such cases.

Added in version 9.0.

See also

Parameters:: with_tz (bool) – Whether to include UTC timezone or not
Return type:: Timestamp

posix_timestamp()[source]#

Convert object to a POSIX timestamp.

See Note in datetime.timestamp().

Added in version 7.5.

Return type:: float

posix_timestamp_format()[source]#

Convert object to a POSIX timestamp format.

Added in version 7.5.

Return type:: str

classmethod set_timestamp(ts)[source]#

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

Added in version 7.5.

Changed in version 8.0: raises TypeError instead of ValueError.

Parameters:: ts (str | datetime | Timestamp) – Timestamp, datetime.datetime or str
Returns:: Timestamp object
Raises:: TypeError – conversion failed
Return type:: Timestamp

totimestampformat()[source]#

Convert object to a MediaWiki internal timestamp.

Return type:: str

classmethod utcnow()[source]#

Return the current UTC date and time, with tzinfo None.

This is like Timestamp.now(), but returns the current UTC date and time, as a naive Timestamp object. An aware current UTC datetime can be obtained by calling Timestamp.nowutc().

Note

This method is deprecated since Python 3.12 but held here for backward compatibility because utcnow is widely used inside the framework to compare MediaWiki timestamps which are UTC-based. Neither datetime.fromisoformat() implementations of Python < 3.11 nor Timestamp specific fromISOformat() supports timezone.

Warning

Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware Timestamps or datetimes to represent times in UTC. As such, the recommended way to create an object representing the current time in UTC is by calling Timestamp.nowutc().

Hint

This method might be deprecated later.

Added in version 9.0.

See also

datetime.utcnow()

Return type:: Timestamp

class pywikibot.User(source, title='')[source]#

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)[source]#

Block user.

Refer APISite.blockuser method for parameters.

Return type:: None

contributions(total=500, **kwargs)[source]#

Yield tuples describing this user edits.

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

Example:

>>> site = pywikibot.Site('wikipedia:test')
>>> user = pywikibot.User(site, 'pywikibot-test')
>>> contrib = next(user.contributions(reverse=True))
>>> len(contrib)
4
>>> contrib[0].title()
'User:John Vandenberg/appendtext test'
>>> contrib[1]
504588
>>> str(contrib[2])
'2022-03-04T17:36:02Z'
>>> contrib[3]
''

See also

Site.usercontribs()

Parameters:

total (int | None) – 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:

Generator[tuple[Page, int, Timestamp, str | None], None, None]

deleted_contributions(*, total=500, **kwargs)[source]#

Yield tuples describing this user’s deleted edits.

Added in version 5.5.

Parameters:

total (int | None) – 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:

Generator[tuple[Page, Revision], None, None]

editCount(force=False)[source]#

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: tuple[Page, int, Timestamp, str | None] | None#

Return first user contribution.

Returns:: first user contribution entry
Returns:: tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment

gender(force=False)[source]#

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='')[source]#

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='')[source]#

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)[source]#

Return a properties about the user.

Changed in version 9.0: detect range blocks

Parameters:: force (bool) – if True, forces reloading the data from API
Return type:: dict

groups(force=False)[source]#

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()[source]#

Determine if the user is editing as an IP address.

See also

Return type:: bool

isEmailable(force=False)[source]#

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)[source]#

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.

See also

isAnonymous()

Parameters:: force (bool) – if True, forces reloading the data from API
Return type:: bool

is_CIDR()[source]#

Determine if the input refers to a range of IP addresses.

Added in version 9.0.

See also

Return type:: bool

is_blocked(force=False)[source]#

Determine whether the user is currently blocked.

Changed in version 7.0: renamed from isBlocked() method

Changed in version 9.0: can also detect range blocks.

Parameters:: force (bool) – if True, forces reloading the data from API
Return type:: bool

is_locked(force=False)[source]#

Determine whether the user is currently locked globally.

Added 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: tuple[Page, int, Timestamp, str | None] | None#

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)[source]#

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)[source]#

Fetch registration date for this user.

Parameters:: force (bool) – if True, forces reloading the data from API
Return type:: Timestamp | None

renamed_target()[source]#

Return a User object for the target this user was renamed to.

If this user was not renamed, it will raise a NoRenameTargetError.

Usage:

>>> site = pywikibot.Site('wikipedia:de')
>>> user = pywikibot.User(site, 'Foo')
>>> user.isRegistered()
False
>>> target = user.renamed_target()
>>> target.isRegistered()
True
>>> target.title(with_ns=False)
'Foo~dewiki'
>>> target.renamed_target()
Traceback (most recent call last):
...
pywikibot.exceptions.NoRenameTargetError: Rename target user ...

See also

BasePage.moved_target()
BasePage.getRedirectTarget()

Added in version 9.4.

Raises:: NoRenameTargetError – user was not renamed
Return type:: User

rights(force=False)[source]#

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)[source]#

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)[source]#

Remove the block for the user.

Parameters:: reason (str | None) – Reason for the unblock.
Return type:: None

uploadedImages(total=10)[source]#

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)[source]#

Bases: WbDataPage

A Wikibase geo-shape representation.

Create a new WbDataPage object.

Parameters:

page (Page) – page containing the data
site (DataSite | None) – The Wikibase site

class pywikibot.WbMonolingualText(text, language)[source]#

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)[source]#

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

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

WbMonolingualText

toWikibase()[source]#

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)[source]#

Bases: WbRepresentation

A Wikibase quantity representation.

Create a new WbQuantity object.

Parameters:

amount (ToDecimalType) – number representing this quantity
unit (ItemPageStrNoneType) – the Wikibase item for the unit or the entity URI of this Wikibase item.
error (ToDecimalType | tuple[ToDecimalType, ToDecimalType]) – the uncertainty of the amount (e.g. ±1)
site (DataSite | None) – The Wikibase site

classmethod fromWikibase(data, site=None)[source]#

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

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

WbQuantity

get_unit_item(repo=None, lazy_load=False)[source]#

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 (DataSite | None) – 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()[source]#

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)[source]#

Bases: WbDataPage

A Wikibase tabular-data representation.

Create a new WbDataPage object.

Parameters:

page (Page) – page containing the data
site (DataSite | None) – 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)[source]#

Bases: WbRepresentation

A Wikibase time representation.

Make a WbTime object from the current time:

current_ts = pywikibot.Timestamp.now()
wbtime = pywikibot.WbTime.fromTimestamp(current_ts)

For converting python datetime objects to WbTime objects, see pywikibot.Timestamp and fromTimestamp().

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.

Note

Comparison information: When using the greater than or equal to operator, or the less than or equal to operator, two different time objects with the same UTC time after factoring in timezones are considered equal. However, the equality operator will return false if the timezone is different.

Deprecated since version 10.0: precision value ‘millenia’ is deprecated; ‘millennium’ must be used instead.

Parameters:

year (int | None) – The year as a signed integer of between 1 and 16 digits.
month (int | None) – Month of the timestamp, if it exists.
day (int | None) – Day of the timestamp, if it exists.
hour (int | None) – Hour of the timestamp, if it exists.
minute (int | None) – Minute of the timestamp, if it exists.
second (int | None) – Second of the timestamp, if it exists.
precision (int | str | None) – The unit of the precision of the time. Must be either an int in range 0 - 14 or one of ‘1000000000’, ‘100000000’, ‘10000000’, ‘1000000’, ‘100000’, ‘10000’, ‘millennium’, ‘century’, ‘decade’, ‘year’, month’, ‘day’, ‘hour’, ‘minute’ or ‘second’.
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 (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.

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

PRECISION = <pywikibot._wbtypes._Precision object>#

equal_instant(other)[source]#

Checks if the two times represent the same instant in time.

This is different from the equality operator, which will return false for two times that are the same number of UTC seconds, but with different timezone information.

For example, a time with at 10:00 UTC-5 would return false if checked with == with a time at 15:00 UTC, but would return true with this method.

Added in version 9.0.

Parameters:: other (WbTime)
Return type:: bool

classmethod fromTimestamp(timestamp, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None, copy_timezone=False)[source]#

Create a new WbTime object from a pywikibot.Timestamp.

Changed in version 8.0: Added copy_timezone parameter.

Parameters:

timestamp (Timestamp) – Timestamp
precision (int | str) – The unit of the precision of the time. Defaults to 14 (second).
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 (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.
copy_timezone (bool) – Whether to copy the timezone from the timestamp if it has timezone information. Defaults to False to maintain backwards compatibility. If a timezone is given, timezone information is discarded.

Return type:

WbTime

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

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 (int | str) – The unit of the precision of the time. Defaults to 14 (second).
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 (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.

Return type:

WbTime

classmethod fromWikibase(data, site=None)[source]#

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

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py.

Return type:

WbTime

normalize()[source]#

Normalizes the WbTime object to account for precision.

Normalization is needed because WbTime objects can have hidden values that affect naive comparisons, such as an object set to a precision of YEAR but containing a month and day value.

This function returns a new normalized object and does not do any modification in place.

Normalization will delete timezone information if the precision is less than or equal to DAY.

Note: Normalized WbTime objects can only be compared to other normalized WbTime objects of the same precision. Normalization might make a WbTime object that was less than another WbTime object before normalization, greater than it after normalization, or vice versa.

Return type:: WbTime

toTimestamp(timezone_aware=False)[source]#

Convert the data to a pywikibot.Timestamp.

Changed in version 8.0.1: timezone_aware parameter was added.

Parameters:: timezone_aware (bool) – Whether the timezone should be passed to the Timestamp object.
Raises:: ValueError – instance value cannot be represented using Timestamp
Return type:: Timestamp

toTimestr(force_iso=False)[source]#

Convert the data to a UTC date/time string.

See also

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

Changed in version 8.0: normalize parameter was added.

Changed in version 8.2: normalize parameter was removed due to T340495 and T57755

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()[source]#

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

Changed in version 8.0: normalize parameter was added.

Changed in version 8.2: normalize parameter was removed due to T340495 and T57755

Returns:: Wikibase JSON
Return type:: dict[str, Any]

class pywikibot.WbUnknown(json, warning='')[source]#

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

Added in version 3.0.

Changed in version 9.4: warning parameter was added

Create a new WbUnknown object.

Parameters:

json (dict[str, Any]) – Wikibase JSON
warning (str) – a warning message which is shown once if toWikibase() is called

classmethod fromWikibase(data, site=None)[source]#

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

Parameters:

data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site

Return type:

WbUnknown

toWikibase()[source]#

Return the JSON object for the Wikibase API.

Changed in version 9.4: a waning message given by the warning attribute is shown once.

Returns:: Wikibase JSON
Return type:: dict[str, Any]

class pywikibot.WikidataBot(**kwargs)[source]#

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()[source]#

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)[source]#

Create an ItemPage with the provided page as the sitelink.

Parameters:

page (BasePage) – the page for which the item will be created
data (dict[str, Any] | None) – additional data to be included in the new item (optional). Note that data created from the page have higher priority.
summary (str | None) – optional edit summary to replace the default one
kwargs (Any)

Returns:

pywikibot.ItemPage or None

Return type:

ItemPage | None

getSource(site)[source]#

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:: pywikibot.page.Claim | None

get_property_by_name(property_name)[source]#

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()[source]#

Treat a page.

Return type:: None

treat_page_and_item(page, item)[source]#

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)[source]#

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 (BaseSite | None) – 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 log>, **kwargs)[source]#

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 (BaseSite | None)
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)[source]#

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

Parameters:

entity (WikibasePage) – page to be edited
data (dict[str, str] | None) – data to be saved, or None if the diff should be created automatically
ignore_save_related_errors (bool | None) – Ignore save related errors and automatically print a message. If None uses this instances default.
ignore_server_errors (bool | None) – 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)[source]#

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

Parameters:: block – If true, block page_put_queue if necessary until a request is available to process. Otherwise process a request if one is immediately available, else leave the function.
Return type:: None

pywikibot.async_request(request, *args, **kwargs)[source]#

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

Parameters:

request (Callable)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.calledModuleName()[source]#

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.

Changed in version 10.0: Detect unittest and pytest run and return the test module.

Return type:: str

pywikibot.critical(msg, *args, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.critical()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.debug(msg, *args, **kwargs)[source]#

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.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.debug()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.error(msg, *args, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.error()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.exception(msg=None, *args, exc_info=True, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 7.3: exc_info is True by default

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.exception()

The arguments are interpreted as for output().

Parameters:

msg (Any)
args (Any)
exc_info (bool)
kwargs (Any)

Return type:

None

pywikibot.handle_args(args=None, do_help=True)[source]#

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 options are handled, show the remaining
['-myoption']
>>> for arg in local_args: pass  # do whatever is wanted with local_args

Caution

Global options might be introduced without warning period. It is up to developers to verify that global options do not interfere with local script options of private scripts.

Tip

Avoid using this method in your private scripts and use the pwb wrapper instead. In directory mode:

python pwb.py <global options> <name_of_script> <local options>

With installed site package:

pwb <global options> <name_of_script> <local options>

Note

the pwb wrapper can be used even if the handle_args method is used within the script.

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.

Changed in version 8.0: Short site value can be given if site code is equal to family like -site:meta.

Changed in version 8.1: -nolog option also discards command.log.

Parameters:

args (Iterable[str] | None) – 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)[source]#

Replace HTML entities with equivalent unicode.

Parameters:

ignore (list[int] | None) – HTML entities to ignore
text (str)

Return type:

str

pywikibot.info(msg='', *args, **kwargs)[source]#

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(). args can be uses as formatting arguments for all logging functions of this module. But this works for old %-formatting only:

>>> info('Hello %s', 'World')
Hello World
>>> info('Pywikibot %(version)d', {'version': 10})
Pywikibot 10

Added in version 7.2: was renamed from output(). Positional arguments for decoder and newline are deprecated; keyword arguments should be used. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.info()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.input(question, password=False, default='', force=False)[source]#

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 (str | None) – 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)[source]#

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

See also

Parameters:

question (str) – The question asked without trailing spaces.
answers (AnswerType) – The valid answers each containing a full length answer and a shortcut. Each value must be unique.
default (str | None) – 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 bot.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)[source]#

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

Example:

>>> input_yn('Do you like Pywikibot?', 'y', False, force=True)
...
Do you like Pywikibot? ([Y]es, [n]o)
True
>>> input_yn('More examples?', False, automatic_quit=False, force=True)
...
Some more examples? ([y]es, [N]o)
False

See also

input_choice()

Parameters:

question (str) – The question asked without trailing spaces.
default (bool | str | None) – The result if no answer was entered. It must be a bool or 'y', 'n', 0 or 1 and can be disabled by setting it to None.
automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) and throw a bot.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, *args, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.log()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.output(msg='', *args, **kwargs)#

Output a message to the user with level INFO.

>>> info('Hello %s', 'World')
Hello World
>>> info('Pywikibot %(version)d', {'version': 10})
Pywikibot 10

Added in version 7.2: was renamed from output(). Positional arguments for decoder and newline are deprecated; keyword arguments should be used. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.info()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.page_put_queue: Queue = <queue.Queue object>#: Queue to hold pending requests

pywikibot.showDiff(oldtext, newtext, context=0)[source]#

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)[source]#

Show help for the Bot.

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

Changed in version 8.0: Do not show version changes.

Parameters:

module_name (str | None)
show_global (bool)

Return type:

None

pywikibot.sleep(secs)[source]#

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 by calling stopme().

Parameters:: secs (int)
Return type:: None

pywikibot.stdout(msg='', *args, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot.stopme()[source]#

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

Can be called manually if desired but usually it is not necessary. 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 instances any more.

stopme() is called with sleep() function during long delays and with bot.BaseBot.exit() to wait for pending write threads.

Return type:: None

pywikibot.translate(code, xdict, parameters=None, fallback=False)[source]#

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 xdict, None is returned.

For PLURAL support have a look at the twtranslate() function.

Changed in version 2.0: parameter other than a mapping (or None) is deprecated.

Changed in version 6.2: ValueError is raised if parameter is not a mapping.

Changed in version 10.2: TypeError instead of ValueError is raised if parameter is not a mapping.

Parameters:

code (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 (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 (Mapping[str, int] | None) – For passing (plural) parameters
fallback (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
TypeError – parameter is not a mapping

Return type:

str | None

pywikibot.warning(msg, *args, **kwargs)[source]#

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. Keyword parameter layer was added.

Changed in version 10.0: args parameter can now given as formatting arguments directly to the logger.

See also

Logger.warning()

Parameters:

msg (Any)
args (Any)
kwargs (Any)

Return type:

None

pywikibot — Base Classes and Functions#

`pywikibot` — Base Classes and Functions#