pywikibot package#

The initialization file for the Pywikibot framework.

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

  • 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: Optional[BaseSite]#

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, content=False, namespaces=None, sortby=None, reverse=False, starttime=None, endtime=None, startprefix=None, endprefix=None)[source]#

Yield all articles in the current category.

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

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

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

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

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

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

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

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

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

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

Return type:

Iterable[Page]

Return a link to place a page in this Category.

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

Parameters:

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

Return type:

str

property categoryinfo: dict#

Return a dict containing information about the category.

The dict contains values for:

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

isEmptyCategory()[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, namespaces=None, total=None, content=False)[source]#

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

Return type:

Iterable[Page]

Parameters:
  • recurse (bool) –

  • total (Optional[int]) –

  • content (bool) –

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 (Optional[int]) – The total number of pages queried.

Returns:

A page generator of all pages in a category ordered by the creation date. From newest to oldest.

Note

It currently only returns Page instances and not a subclass of it if possible. This might change so don’t expect to only get Page instances.

Return type:

Generator[Page, None, None]

subcategories(recurse=False, total=None, content=False)[source]#

Iterate all subcategories of the current category.

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

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

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

class pywikibot.Claim(site, pid, snak=None, hash=None, is_reference=False, is_qualifier=False, rank='normal', **kwargs)[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 the claim is on

  • pid – property id, with “P” prefix

  • snak – snak identifier for claim

  • hash – hash identifier for references

  • is_reference (bool) – whether specified claim is a reference

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

  • rank (str) – rank for claim

SNAK_TYPES = ('value', 'somevalue', 'novalue')#
TARGET_CONVERTER = {'commonsMedia': <function Claim.<lambda>>, 'geo-shape': <bound method _WbDataPage.fromWikibase of <class 'pywikibot.WbGeoShape'>>, 'globe-coordinate': <bound method Coordinate.fromWikibase of <class 'pywikibot.Coordinate'>>, 'monolingualtext': <function Claim.<lambda>>, 'quantity': <bound method WbQuantity.fromWikibase of <class 'pywikibot.WbQuantity'>>, 'tabular-data': <bound method _WbDataPage.fromWikibase of <class 'pywikibot.WbTabularData'>>, 'time': <bound method WbTime.fromWikibase of <class 'pywikibot.WbTime'>>, 'wikibase-form': <function Claim.<lambda>>, 'wikibase-item': <function Claim.<lambda>>, 'wikibase-lexeme': <function Claim.<lambda>>, 'wikibase-property': <function Claim.<lambda>>, 'wikibase-sense': <function Claim.<lambda>>}#
addQualifier(qualifier, **kwargs)[source]#

Add the given qualifier.

Parameters:

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

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 pywikibot.Claim) – the claims to add

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.

Parameters:

data (dict) – JSON containing claim data

Return type:

pywikibot.page.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#

Return item 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 returned 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 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 pywikibot.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

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.

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 (Optional[float]) – Altitude

  • precision (Optional[float]) – precision

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

  • typ (str) – The type of coordinate point

  • name (str) – The name

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

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

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

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

property entity: str#

Return the entity uri of the globe.

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

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

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

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

Return type:

Coordinate

get_globe_item(repo=None, lazy_load=False)[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 (Optional[DataSite]) – the Wikibase site for the globe, if different from that provided with the Coordinate.

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

Returns:

pywikibot.ItemPage

Return type:

ItemPage

property precision: Optional[float]#

Return the precision of the geo coordinate.

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

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

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

The longitudinal can be derived as follows:

In small angle approximation (and thus in radians):

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

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

Therefore:

precision = math.degrees(
    self._dim/(radius*math.cos(math.radians(self.lat))))
precisionToDim()[source]#

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

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

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

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

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

Therefore:

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

Optional[int]

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

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

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

Returns:

whether the page was saved successfully

Return type:

bool

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

Bases: Page

A subclass of Page representing a file description page.

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

Parameters:

title (str) –

data_item()[source]#

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

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

New in version 6.5.

Return type:

pywikibot.page.WikibaseEntity

download(filename=None, chunk_size=102400, revision=None)[source]#

Download to filename file of FilePage.

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

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

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

Returns:

True if download is successful, False otherwise.

Raises:

IOError – if filename cannot be written for any reason.

file_is_shared()[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.

New 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_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, thumburl information will also be accessible as latest_file_info attributes, named as in [1]: - url, thumburl, thumbwidth and thumbheight

Parameters correspond to iiprops in: [1] API:Imageinfo

Parameters validation and error handling left to the API call.

Parameters:
  • url_width – see iiurlwidth in [1]

  • url_height – see iiurlheigth in [1]

  • url_param – see iiurlparam in [1]

Returns:

latest file url or thumburl

Return type:

str

globalusage(total=None)[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 thet list. If the result is False it’ll not continue uploading the file and otherwise disable any warning and reattempt to upload the file.

    Note

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

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

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

Returns:

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

Return type:

bool

usingPages(**kwargs)[source]#

Yield Pages on which the file is displayed.

Deprecated since version 7.4.0: Use using_pages() instead.

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)
1
>>> used[0].title()
'Pywikibot'

See also

globalusage()

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

Changed in version 7.4: renamed from usingPages().

class pywikibot.ItemPage(site, title=None, ns=None)[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 = {'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

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

Return the redirect target for this page.

Return the title for the specific site.

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

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

  • force (bool) – override caching

Return type:

str

isRedirectPage()[source]#

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

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

Remove a sitelink.

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

Return type:

None

Remove sitelinks.

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

Return type:

None

Set sitelinks. Calls setSitelinks().

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

Return type:

None

Set sitelinks.

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

Return type:

None

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, **kwargs)[source]#

Make the item redirect to another item.

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

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

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

  • create (bool) –

  • keep_section (bool) –

  • save (bool) –

title(**kwargs)[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 = {'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 (Optional[dict]) –

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.keys())  # access the claims
['P5831', 'P5402']
>>> len(L2.forms)  # access the forms
2
>>> F1 = L2.forms[0]  # access the first form
>>> list(F1.claims.keys())  # access its claims
['P898']
>>> len(L2.senses)  # access the senses
1
>>> S1 = L2.senses[0]  # access the first sense
>>> list(S1.claims.keys())  # and its claims
['P5137', 'P5972', 'P2888']
Parameters:
  • site (pywikibot.site.DataSite) – data repository

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

DATA_ATTRIBUTES = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'forms': <class 'pywikibot.page._wikibase.LexemeFormCollection'>, 'lemmas': <class 'pywikibot.page._collections.LanguageDict'>, 'senses': <class 'pywikibot.page._wikibase.LexemeSenseCollection'>}#
add_form(form, **kwargs)[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.

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

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 (Optional[dict]) – JSON containing entity data

Return type:

dict

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

Bases: LexemeSubEntity

Wikibase lexeme sense.

DATA_ATTRIBUTES = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'glosses': <class 'pywikibot.page._collections.LanguageDict'>}#
entity_type = 'sense'#
title_pattern = 'L[1-9]\\d*-S[1-9]\\d*'#

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 – Link from site source

  • source – Site

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.

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.

New in version 6.5.

Parameters:
  • repo (DataSite) – Entity repository.

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

DATA_ATTRIBUTES = {'labels': <class 'pywikibot.page._collections.LanguageDict'>}#
property file: FilePage#

Get the file associated with the mediainfo.

get(force=False)[source]#

Fetch all MediaInfo entity data and cache it.

Parameters:

force (bool) – override caching

Raises:

NoWikibaseEntityError – if this entity doesn’t exist

Returns:

actual data which entity holds

Return type:

dict

getID(numeric=False)[source]#

Get the entity identifier.

Parameters:

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

title_pattern = 'M[1-9]\\d*'#
class pywikibot.Page(source, title='', ns=0)[source]#

Bases: BasePage

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.

New in version 3.0.

Parameters:

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

Returns:

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

Return type:

Claim or None

Raises:

UnknownExtensionError – site has no Wikibase extension

property raw_extracted_templates#

Extract templates and parameters.

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

Return type:

list of (str, OrderedDict)

set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, **kwargs)[source]#

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

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

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

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

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

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

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

templatesWithParams()[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 of (pywikibot.page.Page, list)

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 = {'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:

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

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

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

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

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

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

Raises:
  • ValueError – URL and pair of code and family given

  • ValueError – Invalid interface name

  • ValueError – Missing Site code

  • ValueError – Missing Site family

Return type:

BaseSite

Bases: BaseLink

A single sitelink in a Wikibase item.

Extends BaseLink by the following attribute:

  • badges: Any badges associated with the sitelink

New in version 3.0.

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

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

  • badges ([ItemPage]) – list of badges

property badges#

Return a list of all badges associated with the link.

Return type:

[ItemPage]

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

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

Parameters:
  • data (dict) – JSON containing SiteLink data

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

Return type:

pywikibot.page.SiteLink

toJSON()[source]#

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

Returns:

Wikibase JSON

Return type:

dict

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.timedeltas) in any operation.

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

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

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

Changed in version 7.5: moved to time module

ISO8601Format = '%Y-%m-%dT%H:%M:%SZ'#
clone()[source]#

Clone this instance.

Return type:

Timestamp

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

Convert an ISO 8601 timestamp to a Timestamp object.

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

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

Returns:

Timestamp object

Return type:

Timestamp

classmethod fromtimestampformat(ts)[source]#

Convert a MediaWiki internal timestamp to a Timestamp object.

Parameters:

ts (Union[str, Timestamp]) –

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

Convert object to a POSIX timestamp.

See Note in datetime.timestamp().

Return type:

float

posix_timestamp_format()[source]#

Convert object to a POSIX timestamp format.

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

Parameters:

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

Returns:

Timestamp object

Raises:

ValueError – conversion failed

Return type:

Timestamp

totimestampformat()[source]#

Convert object to a MediaWiki internal timestamp.

Return type:

str

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.

Returns:

None

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

Yield tuples describing this user edits.

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

Parameters:

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

Keyword Arguments:
  • start – Iterate contributions starting at this Timestamp

  • end – Iterate contributions ending at this Timestamp

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

  • namespaces – only iterate pages in these namespaces

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

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

Returns:

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

Return type:

tuple

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

Yield tuples describing this user’s deleted edits.

New in version 5.5.

Parameters:

total (int) – Limit results to this number of pages

Keyword Arguments:
  • start – Iterate contributions starting at this Timestamp

  • end – Iterate contributions ending at this Timestamp

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

  • namespaces – Only iterate pages in these namespaces

Return type:

Iterable[Tuple[Page, Revision]]

editCount(force=False)[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: Optional[Tuple[Page, int, Timestamp, str]]#

Return first user contribution.

Returns:

first user contribution entry

Returns:

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

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

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.

Return type:

bool

isBlocked(force=False)[source]#

Determine whether the user is currently blocked.

Deprecated since version 7.0: use is_blocked() instead

Parameters:

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

Return type:

bool

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

Parameters:

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

Return type:

bool

is_blocked(force=False)[source]#

Determine whether the user is currently blocked.

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

Parameters:

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

Return type:

bool

is_locked(force=False)[source]#

Determine whether the user is currently locked globally.

New in version 7.0.

Parameters:

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

Return type:

bool

property is_thankable: bool#

Determine if the user has thanks notifications enabled.

Note

This doesn’t accurately determine if thanks is enabled for user. Privacy of thanks preferences is under discussion, please see T57401#2216861 and T120753#1863894.

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

Return last user contribution.

Returns:

last user contribution entry

Returns:

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

property last_event#

Return last user activity.

Returns:

last user log entry

Return type:

LogEntry or None

logevents(**kwargs)[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:

Optional[Timestamp]

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

operation successful indicator

Return type:

bool

unblock(reason=None)[source]#

Remove the block for the user.

Parameters:

reason (Optional[str]) – 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 (Optional[DataSite]) – 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 (Optional[DataSite]) – 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 (Optional[Union[int, float, str, Decimal]]) – number representing this quantity

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

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

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

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

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

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

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

Return type:

WbQuantity

get_unit_item(repo=None, lazy_load=False)[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 (Optional[DataSite]) – the Wikibase site for the unit, if different from that provided with the WbQuantity.

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

Returns:

pywikibot.ItemPage

Return type:

ItemPage

toWikibase()[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 (Optional[DataSite]) – The Wikibase site

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

Bases: WbRepresentation

A Wikibase time representation.

Create a new WbTime object.

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

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

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

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

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

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

  • month (Optional[int]) – Month

  • day (Optional[int]) – Day

  • hour (Optional[int]) – Hour

  • minute (Optional[int]) – Minute

  • second (Optional[int]) – Second

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

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

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

  • timezone (int) – Timezone information in minutes.

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

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

FORMATSTR = '{0:+012d}-{1:02d}-{2:02d}T{3:02d}:{4:02d}:{5:02d}Z'#
PRECISION = {'10000': 5, '100000': 4, '1000000': 3, '10000000': 2, '100000000': 1, '1000000000': 0, 'century': 7, 'day': 11, 'decade': 8, 'hour': 12, 'millenia': 6, 'minute': 13, 'month': 10, 'second': 14, 'year': 9}#
classmethod fromTimestamp(timestamp, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)[source]#

Create a new WbTime object from a pywikibot.Timestamp.

Parameters:
  • timestamp (Timestamp) – Timestamp

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

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

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

  • timezone (int) – Timezone information in minutes.

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

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

Return type:

WbTime

classmethod fromTimestr(datetimestr, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)[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 (Union[int, str]) – The unit of the precision of the time.

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

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

  • timezone (int) – Timezone information in minutes.

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

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

Return type:

WbTime

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

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

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

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

Return type:

WbTime

toTimestamp()[source]#

Convert the data to a pywikibot.Timestamp.

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 fromTimestr() for differences between output with and without force_iso.

Parameters:

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

Returns:

Timestamp in a format resembling ISO 8601

Return type:

str

toWikibase()[source]#

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

Returns:

Wikibase JSON

Return type:

Dict[str, Any]

class pywikibot.WbUnknown(json)[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

New in version 3.0.

Create a new WbUnknown object.

Parameters:

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

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 (Optional[DataSite]) – The Wikibase site

Return type:

WbUnknown

toWikibase()[source]#

Return the JSON object for the Wikibase API.

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 (Optional[Dict[str, Any]]) – additional data to be included in the new item (optional). Note that data created from the page have higher priority.

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

  • kwargs (Any) –

Returns:

pywikibot.ItemPage or None

Return type:

Optional[ItemPage]

getSource(site)[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:

Optional[pywikibot.page.Claim]

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:
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 (Optional[BaseSite]) – site where the claim comes from

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

  • kwargs (Any) –

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

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

Returns:

whether the item was saved successfully

Return type:

bool

Note

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

Note

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

user_add_claim_unless_exists(item, claim, exists_arg='', source=None, logger_callback=<function deprecated_args.<locals>.decorator.<locals>.wrapper>, **kwargs)[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 (Optional[BaseSite]) –

  • kwargs (Any) –

Returns:

whether the claim could be added

Return type:

bool

Note

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

Note

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

user_edit_entity(entity, data=None, ignore_save_related_errors=None, ignore_server_errors=None, **kwargs)[source]#

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

Parameters:
  • entity (WikibasePage) – page to be edited

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

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

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

  • kwargs (Any) –

Keyword Arguments:
  • summary – revision comment, passed to ItemPage.editEntity

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

Returns:

whether the item was saved successfully

Return type:

bool

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

Return type:

str

pywikibot.critical(msg, text='[deprecated name of 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.

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

pywikibot.debug(msg, text='[deprecated name of 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.

See also

Logger.debug()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

pywikibot.error(msg, text='[deprecated name of 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.

See also

Logger.error()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

pywikibot.exception(msg=None, tb='[deprecated name of exc_info]', *args, exc_info=True, **kwargs)[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.

Changed in version 7.3: exc_info is True by default

The arguments are interpreted as for output().

Parameters:
  • msg (Any) –

  • args (Any) –

  • exc_info (bool) –

  • kwargs (Any) –

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

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

Parameters:
  • args (Optional[Iterable[str]]) – Command line arguments

  • 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 – HTML entities to ignore

  • ignore – list of int

  • text (str) –

Return type:

str

pywikibot.info(msg='', text='[deprecated name of 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().

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

See also

Logger.info()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

pywikibot.input(question, password=False, default='', force=False)[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 (Optional[str]) – The default answer if none was entered. None to require an answer.

  • force (bool) – Automatically use the default

Return type:

str

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

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

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

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

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

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

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

  • force (bool) – Automatically use the default

Returns:

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

Return type:

Any

pywikibot.input_yn(question, default=None, automatic_quit=True, force=False)[source]#

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

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

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

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

  • force (bool) – Automatically use the default

Returns:

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

Return type:

bool

pywikibot.log(msg, text='[deprecated name of msg]', *args, **kwargs)[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.

See also

Logger.log()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

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

Output a message to the user with level INFO.

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

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

See also

Logger.info()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

pywikibot.showDiff(oldtext, newtext, context=0)[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().

Parameters:
  • module_name (Optional[str]) –

  • show_global (bool) –

Return type:

None

pywikibot.stdout(msg='', text='[deprecated name of 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.

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

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

For PLURAL support have a look at the twtranslate method.

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

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

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

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

Returns:

the localized string

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

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

Return type:

Optional[str]

pywikibot.url2unicode(title, encodings='utf-8')[source]#

Convert URL-encoded text to unicode using several encoding.

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

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

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

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

Raises:

UnicodeError – Could not convert using any encoding.

Return type:

str

pywikibot.warning(msg, text='[deprecated name of msg]', *args, **kwargs)[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.

See also

Logger.warning()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

Pywikibot Subpackages#

Submodules#

backports module#

This module contains backports to support older Python versions.

backports.pairwise(iterable)[source]#

Return successive overlapping pairs taken from the input iterable.

New in version 7.6.

backports.removeprefix(string, prefix)[source]#

Remove prefix from a string or return a copy otherwise.

New in version 5.4.

Parameters:
  • string (str) –

  • prefix (str) –

Return type:

str

backports.removesuffix(string, suffix)[source]#

Remove prefix from a string or return a copy otherwise.

New in version 5.4.

Parameters:
  • string (str) –

  • suffix (str) –

Return type:

str

bot module#

User-interface related functions for building bots.

This module supports several different bot classes which could be used in conjunction. Each bot should subclass at least one of these four classes:

  • BaseBot: Basic bot class in case where the site is handled differently, like working on multiple sites in parallel. No site attribute is provided. Instead site of the current page should be used. This class should normally not be used directly.

  • SingleSiteBot: Bot class which should only be run on a single site. They usually store site specific content and thus can’t be easily run when the generator returns a page on another site. It has a property site which can also be changed. If the generator returns a page of a different site it’ll skip that page.

  • MultipleSitesBot: An alias of BaseBot. Should not be used if any other bot class is used.

  • ConfigParserBot: Bot class which supports reading options from a scripts.ini configuration file. That file consists of sections, led by a [section] header and followed by option: value or option=value entries. The section is the script name without .py suffix. All options identified must be predefined in available_options dictionary.

  • Bot: The previous base class which should be avoided. This class is mainly used for bots which work with Wikibase or together with an image repository.

Additionally there is the CurrentPageBot class which automatically sets the current page to the page treated. It is recommended to use this class and to use treat_page instead of treat and put_current instead of userPut. It by default subclasses the BaseBot class.

With CurrentPageBot it’s possible to subclass one of the following classes to filter the pages which are ultimately handled by treat_page:

It is possible to combine filters by subclassing multiple of them. They are new-style classes so when a class is first subclassing ExistingPageBot and then FollowRedirectPageBot it will also work on pages which do not exist when a redirect pointed to that. If the order is inversed it’ll first follow them and then check whether they exist.

Additionally there is the AutomaticTWSummaryBot which subclasses CurrentPageBot and automatically defines the summary when put_current is used.

bot.critical(msg, text='[deprecated name of 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.

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

bot.debug(msg, text='[deprecated name of 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.

See also

Logger.debug()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

bot.error(msg, text='[deprecated name of 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.

See also

Logger.error()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

bot.exception(msg=None, tb='[deprecated name of exc_info]', *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.

Changed in version 7.3: exc_info is True by default

The arguments are interpreted as for output().

Parameters:
  • msg (Any) –

  • args (Any) –

  • exc_info (bool) –

  • kwargs (Any) –

bot.log(msg, text='[deprecated name of 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.

See also

Logger.log()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

bot.warning(msg, text='[deprecated name of 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.

See also

Logger.warning()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

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

Output a message to the user with level INFO.

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

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

See also

Logger.info()

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

bot.stdout(msg='', text='[deprecated name of 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.

Parameters:
  • msg (Any) –

  • args (Any) –

  • kwargs (Any) –

class bot.LoggingFormatter(fmt=None, datefmt=None, style='%')[source]#

Bases: Formatter

Format LogRecords for output to file.

Initialize the formatter with specified format strings.

Initialize the formatter either with the specified format string, or a default as described above. Allow for specialized date formatting with the optional datefmt argument. If datefmt is omitted, you get an ISO8601-like (or RFC 3339-like) format.

Use a style parameter of ‘%’, ‘{’ or ‘$’ to specify that you want to use one of %-formatting, str.format() ({}) formatting or string.Template formatting in your format string.

Changed in version 3.2: Added the style parameter.

format(record)[source]#

Strip trailing newlines before outputting text to file.

bot.set_interface(module_name)[source]#

Configures any bots to use the given interface module.

Search for user interface module in the pywikibot.userinterfaces subdirectory and initialize UI. Calls init_handlers() to re-initialize if we were already initialized with another UI.

New in version 6.4.

Parameters:

module_name (str) –

Return type:

None

bot.init_handlers()[source]#

Initialize the handlers and formatters for the logging system.

This relies on the global variable ui which is a UI object.

See also

pywikibot.userinterfaces

Calls writelogheader() after handlers are initialized. This function must be called before using any input/output methods; and must be called again if ui handler is changed. Use set_interface() to set the new interface which initializes it.

Note

this function is called by any user input and output function, so it should normally not need to be called explicitly.

All user output is routed through the logging module. Each type of output is handled by an appropriate handler object. This structure is used to permit eventual development of other user interfaces (GUIs) without modifying the core bot code.

The following output levels are defined:

  • DEBUG: only for file logging; debugging messages.

  • STDOUT: output that must be sent to sys.stdout (for bots that may have their output redirected to a file or other destination).

  • VERBOSE: optional progress information for display to user.

  • INFO: normal (non-optional) progress information for display to user.

  • INPUT: prompts requiring user response.

  • WARN: user warning messages.

  • ERROR: user error messages.

  • CRITICAL: fatal error messages.

See also

Accordingly, do not use print statements in bot code; instead, use pywikibot.output() function and other functions from pywikibot.logging module.

Changed in version 6.2: Different logfiles are used if multiple processes of the same script are running.

Return type:

None

bot.writelogheader()[source]#

Save additional version, system and status info to the log file in use.

This may help the user to track errors or report bugs.

Return type:

None

bot.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 (Optional[str]) – The default answer if none was entered. None to require an answer.

  • force (bool) – Automatically use the default

Return type:

str

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

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

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

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

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

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

  • force (bool) – Automatically use the default

Returns:

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

Return type:

Any

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

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

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

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

  • force (bool) – Automatically use the default

Returns:

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

Return type:

bool

bot.input_list_choice(question, answers, default=None, force=False)[source]#

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

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

  • answers (Union[Iterable[Union[Tuple[str, str], Option]], Option]) – The valid answers each containing a full length answer.

  • default (Optional[Union[int, str]]) – The result if no answer was entered. It must not be in the valid answers and can be disabled by setting it to None.

  • force (bool) – Automatically use the default

Returns:

The selected answer.

Return type:

str

bot.ui = <pywikibot.userinterfaces.terminal_interface_unix.UnixUI object>#

Holds a user interface object defined in pywikibot.userinterfaces subpackage.

class bot.Option(stop=True)[source]#

Bases: ABC

A basic option for input_choice.

The following methods need to be implemented:

  • format(default=None)

  • result(value)

  • test(value)

The methods test and handled are in such a relationship that when handled returns itself that test must return True for that value. So if test returns False handled may not return itself but it may return not None.

Also result only returns a sensible value when test returns True for the same value.

Parameters:

stop (bool) –

static formatted(text, options, default=None)[source]#

Create a text with the options formatted into it.

This static method is used by pywikibot.input_choice(). It calls format for all options to combine the question for pywikibot.input().

Parameters:
  • text (str) – Text into which options are to be formatted

  • options (Iterable[Option]) – Option instances to be formatted

  • default (Optional[str]) – filler for any option’s ‘default’ placeholder

Returns:

Text with the options formatted into it

Return type:

str

property stop: bool#

Return whether this option stops asking.

handled(value)[source]#

Return the Option object that applies to the given value.

If this Option object doesn’t know which applies it returns None.

Parameters:

value (str) –

Return type:

Optional[Option]

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str) –

Return type:

bool

abstract result(value)[source]#

Return the actual value which is associated by the given one.

New in version 6.2: result() is an abstract method and must be defined in subclasses

Parameters:

value (str) –

Return type:

Any

class bot.StandardOption(option, shortcut, **kwargs)[source]#

Bases: Option

An option with a description and shortcut and returning the shortcut.

Parameters:
  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any) –

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

result(value)[source]#

Return the lowercased shortcut.

Parameters:

value (str) –

Return type:

Any

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str) –

Return type:

bool

class bot.NestedOption(option, shortcut, description, options)[source]#

Bases: OutputOption, StandardOption

An option containing other options.

It will return True in test if this option applies but False if a sub option applies while handle returns the sub option.

Parameters:
  • option (str) –

  • shortcut (str) –

  • description (str) –

  • options (Iterable[Option]) –

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

handled(value)[source]#

Return itself if it applies or the applying sub option.

Parameters:

value (str) –

Return type:

Optional[Option]

property out: str#

Output of suboptions.

class bot.IntegerOption(minimum=1, maximum=None, prefix='', **kwargs)[source]#

Bases: Option

An option allowing a range of integers.

Parameters:
  • minimum (int) –

  • maximum (Optional[int]) –

  • prefix (str) –

  • kwargs (Any) –

test(value)[source]#

Return whether the value is an int and in the specified range.

Parameters:

value (str) –

Return type:

bool

property minimum: int#

Return the lower bound of the range of allowed values.

property maximum: Optional[int]#

Return the upper bound of the range of allowed values.

format(default=None)[source]#

Return a formatted string showing the range.

Parameters:

default (Optional[str]) –

Return type:

str

parse(value)[source]#

Return integer from value with prefix removed.

Parameters:

value (str) –

Return type:

int

result(value)[source]#

Return a tuple with the prefix and value converted into an int.

Parameters:

value (str) –

Return type:

Any

class bot.ContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: OutputOption, StandardOption

An option to show more and more context.

Parameters:
  • option (str) –

  • shortcut (str) –

  • text (str) –

  • context (int) –

  • delta (int) –

  • start (int) –

  • end (int) –

result(value)[source]#

Add the delta to the context.

Parameters:

value (str) –

Return type:

Any

property out: str#

Output section of the text.

output_range(start, end)[source]#

DEPRECATED. Output a section from the text.

Parameters:
  • start (int) –

  • end (int) –

Return type:

None

class bot.ListOption(sequence, prefix='', **kwargs)[source]#

Bases: IntegerOption

An option to select something from a list.

Parameters:
  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

format(default=None)[source]#

Return a string showing the range.

Parameters:

default (Optional[str]) –

Return type:

str

property maximum: int#

Return the maximum value.

result(value)[source]#

Return a tuple with the prefix and selected value.

Parameters:

value (str) –

Return type:

Any

class bot.ShowingListOption(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ListOption, OutputOption

An option to show a list and select an item.

New in version 3.0.

Parameters:
  • pre (Optional[str]) – Additional comment printed before the list.

  • post (Optional[str]) – Additional comment printed after the list.

  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

before_question = True#

Place output before or after the question

property stop: bool#

Return whether this option stops asking.

property out: str#

Output text of the enumerated list.

class bot.MultipleChoiceList(sequence, prefix='', **kwargs)[source]#

Bases: ListOption

An option to select multiple items from a list.

Parameters:
  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

test(value)[source]#

Return whether the values are int and in the specified range.

Parameters:

value (str) –

Return type:

bool

result(value)[source]#

Return a tuple with the prefix and selected values as a list.

Parameters:

value (str) –

Return type:

Any

class bot.ShowingMultipleChoiceList(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ShowingListOption, MultipleChoiceList

An option to show a list and select multiple items.

Parameters:
  • pre (Optional[str]) – Additional comment printed before the list.

  • post (Optional[str]) – Additional comment printed after the list.

  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

class bot.OutputProxyOption(option, shortcut, output, **kwargs)[source]#

Bases: OutputOption, StandardOption

An option which calls out property of the given output class.

Create a new option for the given sequence.

Parameters:
  • option (str) –

  • shortcut (str) –

  • output (OutputOption) –

  • kwargs (Any) –

property out: str#

Return the contents.

class bot.HighlightContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: ContextOption

Show the original region highlighted.

Parameters:
  • option (str) –

  • shortcut (str) –

  • text (str) –

  • context (int) –

  • delta (int) –

  • start (int) –

  • end (int) –

color = 'lightred'#
property out: str#

Highlighted output section of the text.

output_range(start, end)[source]#

Show normal context with a highlighted center region.

Deprecated since version 6.2: use out instead.

Parameters:
  • start (int) –

  • end (int) –

Return type:

None

exception bot.ChoiceException(option, shortcut, **kwargs)[source]#

Bases: StandardOption, Exception

A choice for input_choice which result in this exception.

Parameters:
  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any) –

Return type:

None

result(value)[source]#

Return itself to raise the exception.

Parameters:

value (Any) –

Return type:

Any

exception bot.UnhandledAnswer[source]#

Bases: Exception

The given answer didn’t suffice.

class bot.Choice(option, shortcut, replacer)[source]#

Bases: StandardOption

A simple choice consisting of an option, shortcut and handler.

Parameters:
  • option (str) –

  • shortcut (str) –

  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

property replacer: Optional[InteractiveReplace]#

The replacer.

abstract handle()[source]#

Handle this choice. Must be implemented.

Return type:

Any

The current link will be handled by this choice.

Return type:

bool

class bot.StaticChoice(option, shortcut, result)[source]#

Bases: Choice

A static choice which just returns the given value.

Create instance with replacer set to None.

Parameters:
  • option (str) –

  • shortcut (str) –

  • result (Any) –

handle()[source]#

Return the predefined value.

Return type:

Any

class bot.LinkChoice(option, shortcut, replacer, replace_section, replace_label)[source]#

Bases: Choice

A choice returning a mix of the link new and current link.

Parameters:
  • option (str) –

  • shortcut (str) –

  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

  • replace_section (bool) –

  • replace_label (bool) –

handle()[source]#

Handle by either applying the new section or label.

Return type:

Any

class bot.AlwaysChoice(replacer, option='always', shortcut='a')[source]#

Bases: Choice

Add an option to always apply the default.

Parameters:
  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

  • option (str) –

  • shortcut (str) –

handle()[source]#

Handle the custom shortcut.

Return type:

Any

Directly return answer whether it’s applying it always.

Return type:

bool

property answer: Any#

Get the actual default answer instructing the replacement.

exception bot.QuitKeyboardInterrupt[source]#

Bases: ChoiceException, KeyboardInterrupt

The user has cancelled processing at a prompt.

Constructor using the ‘quit’ (‘q’) in input_choice.

Return type:

None

class bot.InteractiveReplace(old_link, new_link, default=None, automatic_quit=True)[source]#

Bases: object

A callback class for textlib’s replace_links.

It shows various options which can be switched on and off: * allow_skip_link = True (skip the current link) * allow_unlink = True (unlink) * allow_replace = False (just replace target, keep section and label) * allow_replace_section = False (replace target and section, keep label) * allow_replace_label = False (replace target and label, keep section) * allow_replace_all = False (replace target, section and label) (The boolean values are the default values)

It has also a context attribute which must be a non-negative integer. If it is greater 0 it shows that many characters before and after the link in question. The context_delta attribute can be defined too and adds an option to increase context by the given amount each time the option is selected.

Additional choices can be defined using the ‘additional_choices’ and will be amended to the choices defined by this class. This list is mutable and the Choice instance returned and created by this class are too.

Parameters:
  • old_link (Union[pywikibot.page.Link, pywikibot.page.Page]) – The old link which is searched. The label and section are ignored.

  • new_link (Union[pywikibot.page.Link, pywikibot.page.Page, bool]) – The new link with which it should be replaced. Depending on the replacement mode it’ll use this link’s label and section. If False it’ll unlink all and the attributes beginning with allow_replace are ignored.

  • default (Optional[str]) – The default answer as the shortcut

  • automatic_quit (bool) – Add an option to quit and raise a QuitKeyboardException.

handle_answer(choice)[source]#

Return the result for replace_links.

Parameters:

choice (str) –

Return type:

Any

property choices: Tuple[StandardOption, ...]#

Return the tuple of choices.

Handle the currently given replacement.

Return type:

Any

Get the current link when it’s handling one currently.

property current_text: str#

Get the current text when it’s handling one currently.

property current_groups: Mapping[str, str]#

Get the current groups when it’s handling one currently.

property current_range: Tuple[int, int]#

Get the current range when it’s handling one currently.

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

Return type:

str

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

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

Parameters:
  • args (Optional[Iterable[str]]) – Command line arguments

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

Returns:

list of arguments not recognised globally

Return type:

List[str]

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

Parameters:
  • module_name (Optional[str]) –

  • show_global (bool) –

Return type:

None

bot.suggest_help(missing_parameters=None, missing_generator=False, unknown_parameters=None, exception=None, missing_action=False, additional_text='', missing_dependencies=None)[source]#

Output error message to use -help with additional text before it.

Parameters:
  • missing_parameters (Optional[Sequence[str]]) – A list of parameters which are missing.

  • missing_generator (bool) – Whether a generator is missing.

  • unknown_parameters (Optional[Sequence[str]]) – A list of parameters which are unknown.

  • exception (Optional[Exception]) – An exception thrown.

  • missing_action (bool) – Add an entry that no action was defined.

  • additional_text (str) – Additional text added to the end.

  • missing_dependencies (Optional[Sequence[str]]) – A list of dependencies which cannot be imported.

Returns:

True if an error message was printed, False otherwise

Return type:

bool

bot.writeToCommandLogFile()[source]#

Save name of the called module along with all params to logs/commands.log.

This can be used by user later to track errors or report bugs.

Return type:

None

bot.open_webbrowser(page)[source]#

Open the web browser displaying the page and wait for input.

Parameters:

page (BasePage) –

Return type:

None

class bot.OptionHandler(**kwargs)[source]#

Bases: object

Class to get and set options.

How to use options of OptionHandler and its BaseBot subclasses: First define an available_options class attribute for your own option handler to define all available options:

>>> default_options = {'foo': 'bar', 'bar': 42, 'baz': False}
>>> class MyHandler(OptionHandler): available_options = default_options

Or you may update the predefined setting in the class initializer. BaseBot predefines a ‘always’ options and sets it to False:

self.available_options.update(always=True, another_option=’Yes’)

Now you can instantiate an OptionHandler or BaseBot class passing options other than default values:

>>> bot = MyHandler(baz=True)

You can access bot options either as keyword item or attribute:

>>> bot.opt.foo
'bar'
>>> bot.opt['bar']
42
>>> bot.opt.baz  # default was overridden
True

You can set the options in the same way:

>>> bot.opt.bar = 4711
>>> bot.opt['baz'] = None
>>>

Or you can use the option as a dict:

>>> 'Option opt.{foo} is {bar}'.format_map(bot.opt)
'Option opt.bar is 4711'

Warning

You must not access bot options as an attribute if the keyword is a dict method.

Only accept options defined in available_options.

Parameters:

kwargs (Any) – bot options

available_options = {}#

Handler configuration attribute. Only the keys of the dict can be passed as __init__ options. The values are the default values. Overwrite this in subclasses!

set_options(**options)[source]#

Set the instance options.

Parameters:

options (Any) –

Return type:

None

class bot.BaseBot(**kwargs)[source]#

Bases: OptionHandler

Generic Bot to be subclassed.

Only accepts generator and options defined in available_options.

This class provides a run() method for basic processing of a generator one page at a time.

If the subclass places a page generator in self.generator, Bot will process each page in the generator, invoking the method treat() which must then be implemented by subclasses.

Each item processed by treat() must be a page.BasePage type. Use init_page() to upcast the type. To enable other types, set BaseBot.treat_page_type to an appropriate type; your bot should derive from BaseBot in that case and handle site properties.

If the subclass does not set a generator, or does not override treat() or run(), NotImplementedError is raised.

For bot options handling refer OptionHandler class above.

Changed in version 7.0: A counter instance variable is provided.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

use_disambigs = None#

Attribute to determine whether to use disambiguation pages. Set it to True to use disambigs only, set it to False to skip disambigs. If None both are processed.

New in version 7.2.

use_redirects = None#

Attribute to determine whether to use redirect pages. Set it to True to use redirects only, set it to False to skip redirects. If None both are processed. For example to create a RedirectBot you may define:

class MyRedirectBot(ExistingPageBot):

    '''Bot who only works on existing redirects.'''

    use_redirects = True

New in version 7.2.

available_options = {'always': False}#

Handler configuration attribute. Only the keys of the dict can be passed as __init__ options. The values are the default values. Overwrite this in subclasses!

update_options = {}#

update_options can be used to update available_options; do not use it if the bot class is to be derived but use self.available_options.update(<dict>) initializer in such case.

New in version 6.4.

generator#

instance variable to hold the generator processed by run() method

counter#

Instance variable which holds counters. The default counters are ‘read’, ‘write’ and ‘skip’. You can use your own counters like:

self.counter['delete'] += 1

New in version 7.0.

Changed in version 7.3: Your additional counters are also printed during exit()

generator_completed#

Instance attribute which is True if the generator is completed.

To check for an empty generator you may use:

if self.generator_completed and not self.counter['read']:
    print('generator was emtpty')

Note

An empty generator remains False.

New in version 3.0.

Changed in version 7.4: renamed to generator_completed to become a public attribute.

treat_page_type#

instance variable to hold the default page type

property current_page: BasePage#

Return the current working page as a property.

user_confirm(question)[source]#

Obtain user response if bot option ‘always’ not enabled.

Parameters:

question (str) –

Return type:

bool

userPut(page, oldtext, newtext, **kwargs)[source]#

Save a new revision of a page, with user confirmation as required.

Print differences, ask user for confirmation, and puts the page if needed.

Option used:

  • ‘always’

Keyword Arguments:
  • asynchronous – passed to page.save

  • summary – passed to page.save

  • show_diff – show changes between oldtext and newtext (enabled)

  • ignore_save_related_errors – report and ignore (disabled)

  • ignore_server_errors – report and ignore (disabled)

Returns:

whether the page was saved successfully

Parameters:
  • page (BasePage) –

  • oldtext (str) –

  • newtext (str) –

  • kwargs (Any) –

Return type:

bool

_save_page(page, func, *args, **kwargs)[source]#

Helper function to handle page save-related option error handling.

Note

Do no use it directly. Use userPut() instead.

Parameters:
  • page (BasePage) – currently edited page

  • func (Callable[[...], Any]) – the function to call

  • args (Any) – passed to the function

  • kwargs (Any) – passed to the function

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

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

Returns:

whether the page was saved successfully

Return type:

bool

quit()[source]#

Cleanup and quit processing.

Return type:

None

exit()[source]#

Cleanup and exit processing.

Invoked when run() is finished. Waits for pending threads, prints counter statistics and informs whether the script terminated gracefully or was halted by exception.

Note

Do not overwrite it by subclasses; teardown() should be used instead.

Changed in version 7.3: Statistics are printed for all entries in counter

Return type:

None

init_page(item)[source]#

Initialize a generator item before treating.

Ensure that the result of init_page is always a pywikibot.Page object or any other type given by the treat_page_type even when the generator returns something else.

Also used to set the arrange the current site. This is called before skip_page() and treat().

Parameters:

item (Any) – any item from generator

Returns:

return the page object to be processed further

Return type:

BasePage

skip_page(page)[source]#

Return whether treat should be skipped for the page.

New in version 3.0.

Changed in version 7.2: use use_redirects to handle redirects, use use_disambigs to handle disambigs

Parameters:

page (BasePage) – Page object to be processed

Return type:

bool

treat(page)[source]#

Process one page (abstract method).

Parameters:

page (Any) – Object to be processed, usually a page.BasePage. For other page types the treat_page_type must be set.

Return type:

None

setup()[source]#

Some initial setup before run() operation starts.

This can be used for reading huge parts from life wiki or file operation which is more than just initialize the instance. Invoked by run() before running through generator loop.

New in version 3.0.

Return type:

None

teardown()[source]#

Some cleanups after run() operation. Invoked by exit().

New in version 3.0.

Return type:

None

run()[source]#

Process all pages in generator.

Raises:

AssertionError – “page” is not a pywikibot.page.BasePage object

Return type:

None

class bot.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 (Optional[BaseSite]) –

  • kwargs (Any) –

property site: Optional[BaseSite]#

Get the current site.

run()[source]#

Check if it automatically updates the site before run.

Return type:

None

init_page(item)[source]#

Update site before calling treat.

Parameters:

item (Any) –

Return type:

BasePage

class bot.ConfigParserBot(**kwargs)[source]#

Bases: BaseBot

A bot class that can read options from scripts.ini file.

All options must be predefined in available_options dictionary. The type of these options is responsible for the correct interpretation of the options type given by the .ini file. They can be interpreted as bool, int, float or str (default). The settings file may be like:

[add_text]
# edit summary for the bot.
summary = Bot: Aggiungo template Categorizzare

[commonscat] ; commonscat options
always: true

The option values are interpreted in this order:

  1. available_options default setting

  2. script.ini options settings

  3. command line arguments

New in version 3.0.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

INI = 'scripts.ini'#
set_options(**kwargs)[source]#

Read settings from scripts.ini file.

Parameters:

kwargs (Any) –

Return type:

None

class bot.SingleSiteBot(site=True, **kwargs)[source]#

Bases: BaseBot

A bot only working on one site and ignoring the others.

If no site is given from the start it’ll use the first page’s site. Any page after the site has been defined and is not on the defined site will be ignored.

Create a SingleSiteBot instance.

Parameters:
  • site (Optional[Union[BaseSite, bool]]) – If True it’ll be set to the configured site using pywikibot.Site.

  • kwargs (Any) –

property site: BaseSite#

Site that the bot is using.

init_page(item)[source]#

Set site if not defined.

Parameters:

item (Any) –

Return type:

BasePage

skip_page(page)[source]#

Skip page if it is not on the defined site.

Parameters:

page (BasePage) –

Return type:

bool

class bot.MultipleSitesBot(**kwargs)[source]#

Bases: BaseBot

A bot class working on multiple sites.

The bot should accommodate for that case and not store site specific information on only one site.

Changed in version 6.2: Site attribute has been dropped.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

class bot.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_server_errors = False#
treat_page()[source]#

Process one page (Abstract method).

Return type:

None

treat(page)[source]#

Set page to current page and treat that page.

Parameters:

page (BasePage) –

Return type:

None

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

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

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

Returns:

whether the page was saved successfully

Return type:

bool

class bot.AutomaticTWSummaryBot(**kwargs)[source]#

Bases: CurrentPageBot

A class which automatically defines summary for put_current.

The class must defined a summary_key string which contains the i18n key for i18n.twtranslate. It can also override the summary_parameters property to specify any parameters for the translated message.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

summary_key = None#

Must be defined in subclasses.

property summary_parameters: Dict[str, str]#

A dictionary of all parameters for i18n.

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

Defining a summary if not already defined and then call original.

Parameters:
  • args (Any) –

  • kwargs (Any) –

Return type:

None

class bot.ExistingPageBot(**kwargs)[source]#

Bases: CurrentPageBot

A CurrentPageBot class which only treats existing pages.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

skip_page(page)[source]#

Treat page if it exists and handle NoPageError.

Warning

If subclassed, call super().skip_page() first to ensure that non existent pages are filtered before other calls are made

Parameters:

page (BasePage) –

Return type:

bool

class bot.FollowRedirectPageBot(**kwargs)[source]#

Bases: CurrentPageBot

A CurrentPageBot class which follows the redirect.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

treat(page)[source]#

Treat target if page is redirect and the page otherwise.

Parameters:

page (BasePage) –

Return type:

None

class bot.CreatingPageBot(**kwargs)[source]#

Bases: CurrentPageBot

A CurrentPageBot class which only treats nonexistent pages.

Parameters:

kwargs (Any) – bot options

Keyword Arguments:

generator – a generator processed by run() method

skip_page(page)[source]#

Treat page if doesn’t exist.

Parameters:

page (BasePage) –

Return type:

bool

class bot.RedirectPageBot(*args, **kwargs)[source]#

Bases: CurrentPageBot

A RedirectPageBot class which only treats redirects.

Deprecated since version 7.2: use BaseBot attribute use_redirects  = True instead

Deprecate RedirectPageBot.

skip_page(page)[source]#

Treat only redirect pages and handle IsNotRedirectPageError.

Parameters:

page (BasePage) –

Return type:

bool

class bot.NoRedirectPageBot(*args, **kwargs)[source]#

Bases: CurrentPageBot

A NoRedirectPageBot class which only treats non-redirects.

Deprecated since version 7.2: use BaseBot attribute use_redirects  = False instead

Deprecate NoRedirectPageBot.

skip_page(page)[source]#

Treat only non-redirect pages and handle IsRedirectPageError.

Parameters:

page (BasePage) –

Return type:

bool

class bot.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.

use_from_page = True#
treat_missing_item = False#
cacheSources()[source]#

Fetch the sources from the list on Wikidata.

It is stored internally and reused by getSource()

Return type:

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

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 (Optional[Dict[str, str]]) – data to be saved, or None if the diff should be created automatically

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

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

  • kwargs (Any) –

Keyword Arguments:
  • summary – revision comment, passed to ItemPage.editEntity

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

Returns:

whether the item was saved successfully

Return type:

bool

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 (Optional[BaseSite]) – site where the claim comes from

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

  • kwargs (Any) –

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

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

Returns:

whether the item was saved successfully

Return type:

bool

Note

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

Note

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

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:

Optional[pywikibot.page.Claim]

user_add_claim_unless_exists(item, claim, exists_arg='', source=None, logger_callback=<function deprecated_args.<locals>.decorator.<locals>.wrapper>, **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 (Optional[BaseSite]) –

  • kwargs (Any) –

Returns:

whether the claim could be added

Return type:

bool

Note

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

Note

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

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 (Optional[Dict[str, Any]]) – additional data to be included in the new item (optional). Note that data created from the page have higher priority.

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

  • kwargs (Any) –

Returns:

pywikibot.ItemPage or None

Return type:

Optional[ItemPage]

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

None

bot_choice module#

Options and Choices for pywikibot.input_choice().

class bot_choice.AlwaysChoice(replacer, option='always', shortcut='a')[source]#

Bases: Choice

Add an option to always apply the default.

Parameters:
  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

  • option (str) –

  • shortcut (str) –

property answer: Any#

Get the actual default answer instructing the replacement.

handle()[source]#

Handle the custom shortcut.

Return type:

Any

Directly return answer whether it’s applying it always.

Return type:

bool

class bot_choice.Choice(option, shortcut, replacer)[source]#

Bases: StandardOption

A simple choice consisting of an option, shortcut and handler.

Parameters:
  • option (str) –

  • shortcut (str) –

  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

abstract handle()[source]#

Handle this choice. Must be implemented.

Return type:

Any

The current link will be handled by this choice.

Return type:

bool

property replacer: Optional[InteractiveReplace]#

The replacer.

exception bot_choice.ChoiceException(option, shortcut, **kwargs)[source]#

Bases: StandardOption, Exception

A choice for input_choice which result in this exception.

Parameters:
  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any) –

Return type:

None

result(value)[source]#

Return itself to raise the exception.

Parameters:

value (Any) –

Return type:

Any

class bot_choice.ContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: OutputOption, StandardOption

An option to show more and more context.

Parameters:
  • option (str) –

  • shortcut (str) –

  • text (str) –

  • context (int) –

  • delta (int) –

  • start (int) –

  • end (int) –

property out: str#

Output section of the text.

output_range(start, end)[source]#

DEPRECATED. Output a section from the text.

Parameters:
  • start (int) –

  • end (int) –

Return type:

None

result(value)[source]#

Add the delta to the context.

Parameters:

value (str) –

Return type:

Any

class bot_choice.HighlightContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: ContextOption

Show the original region highlighted.

Parameters:
  • option (str) –

  • shortcut (str) –

  • text (str) –

  • context (int) –

  • delta (int) –

  • start (int) –

  • end (int) –

color = 'lightred'#
property out: str#

Highlighted output section of the text.

output_range(start, end)[source]#

Show normal context with a highlighted center region.

Deprecated since version 6.2: use out instead.

Parameters:
  • start (int) –

  • end (int) –

Return type:

None

class bot_choice.IntegerOption(minimum=1, maximum=None, prefix='', **kwargs)[source]#

Bases: Option

An option allowing a range of integers.

Parameters:
  • minimum (int) –

  • maximum (Optional[int]) –

  • prefix (str) –

  • kwargs (Any) –

format(default=None)[source]#

Return a formatted string showing the range.

Parameters:

default (Optional[str]) –

Return type:

str

property maximum: Optional[int]#

Return the upper bound of the range of allowed values.

property minimum: int#

Return the lower bound of the range of allowed values.

parse(value)[source]#

Return integer from value with prefix removed.

Parameters:

value (str) –

Return type:

int

result(value)[source]#

Return a tuple with the prefix and value converted into an int.

Parameters:

value (str) –

Return type:

Any

test(value)[source]#

Return whether the value is an int and in the specified range.

Parameters:

value (str) –

Return type:

bool

class bot_choice.LinkChoice(option, shortcut, replacer, replace_section, replace_label)[source]#

Bases: Choice

A choice returning a mix of the link new and current link.

Parameters:
  • option (str) –

  • shortcut (str) –

  • replacer (Optional[pywikibot.bot.InteractiveReplace]) –

  • replace_section (bool) –

  • replace_label (bool) –

handle()[source]#

Handle by either applying the new section or label.

Return type:

Any

class bot_choice.ListOption(sequence, prefix='', **kwargs)[source]#

Bases: IntegerOption

An option to select something from a list.

Parameters:
  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

format(default=None)[source]#

Return a string showing the range.

Parameters:

default (Optional[str]) –

Return type:

str

property maximum: int#

Return the maximum value.

result(value)[source]#

Return a tuple with the prefix and selected value.

Parameters:

value (str) –

Return type:

Any

class bot_choice.MultipleChoiceList(sequence, prefix='', **kwargs)[source]#

Bases: ListOption

An option to select multiple items from a list.

Parameters:
  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

result(value)[source]#

Return a tuple with the prefix and selected values as a list.

Parameters:

value (str) –

Return type:

Any

test(value)[source]#

Return whether the values are int and in the specified range.

Parameters:

value (str) –

Return type:

bool

class bot_choice.NestedOption(option, shortcut, description, options)[source]#

Bases: OutputOption, StandardOption

An option containing other options.

It will return True in test if this option applies but False if a sub option applies while handle returns the sub option.

Parameters:
  • option (str) –

  • shortcut (str) –

  • description (str) –

  • options (Iterable[Option]) –

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

handled(value)[source]#

Return itself if it applies or the applying sub option.

Parameters:

value (str) –

Return type:

Optional[Option]

property out: str#

Output of suboptions.

class bot_choice.Option(stop=True)[source]#

Bases: ABC

A basic option for input_choice.

The following methods need to be implemented:

  • format(default=None)

  • result(value)

  • test(value)

The methods test and handled are in such a relationship that when handled returns itself that test must return True for that value. So if test returns False handled may not return itself but it may return not None.

Also result only returns a sensible value when test returns True for the same value.

Parameters:

stop (bool) –

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

static formatted(text, options, default=None)[source]#

Create a text with the options formatted into it.

This static method is used by pywikibot.input_choice(). It calls format for all options to combine the question for pywikibot.input().

Parameters:
  • text (str) – Text into which options are to be formatted

  • options (Iterable[Option]) – Option instances to be formatted

  • default (Optional[str]) – filler for any option’s ‘default’ placeholder

Returns:

Text with the options formatted into it

Return type:

str

handled(value)[source]#

Return the Option object that applies to the given value.

If this Option object doesn’t know which applies it returns None.

Parameters:

value (str) –

Return type:

Optional[Option]

abstract result(value)[source]#

Return the actual value which is associated by the given one.

New in version 6.2: result() is an abstract method and must be defined in subclasses

Parameters:

value (str) –

Return type:

Any

property stop: bool#

Return whether this option stops asking.

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str) –

Return type:

bool

class bot_choice.OutputOption(stop=True)[source]#

Bases: Option

An option that never stops and can output on each question.

pywikibot.input_choice() uses before_question attribute to decide whether to output before or after the question.

Note

OutputOption must have an out property which returns a string for userinterface output() method.

Parameters:

stop (bool) –

before_question = False#

Place output before or after the question

property out: str#

String to be used when selected before or after the question.

Note

This method is used by ui.input_choice instead of deprecated output().

New in version 6.2.

output()[source]#

Output string.

Deprecated since version 6.5: This method was replaced by out property and is no no longer used by the userinterfaces system.

Return type:

None

result(value)[source]#

Just return None.

Parameters:

value (str) –

Return type:

Any

property stop: bool#

Never stop asking.

class bot_choice.OutputProxyOption(option, shortcut, output, **kwargs)[source]#

Bases: OutputOption, StandardOption

An option which calls out property of the given output class.

Create a new option for the given sequence.

Parameters:
  • option (str) –

  • shortcut (str) –

  • output (OutputOption) –

  • kwargs (Any) –

property out: str#

Return the contents.

exception bot_choice.QuitKeyboardInterrupt[source]#

Bases: ChoiceException, KeyboardInterrupt

The user has cancelled processing at a prompt.

Constructor using the ‘quit’ (‘q’) in input_choice.

Return type:

None

class bot_choice.ShowingListOption(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ListOption, OutputOption

An option to show a list and select an item.

New in version 3.0.

Parameters:
  • pre (Optional[str]) – Additional comment printed before the list.

  • post (Optional[str]) – Additional comment printed after the list.

  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

before_question = True#

Place output before or after the question

property out: str#

Output text of the enumerated list.

property stop: bool#

Return whether this option stops asking.

class bot_choice.ShowingMultipleChoiceList(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ShowingListOption, MultipleChoiceList

An option to show a list and select multiple items.

Parameters:
  • pre (Optional[str]) – Additional comment printed before the list.

  • post (Optional[str]) – Additional comment printed after the list.

  • sequence (Sequence[str]) –

  • prefix (str) –

  • kwargs (Any) –

class bot_choice.StandardOption(option, shortcut, **kwargs)[source]#

Bases: Option

An option with a description and shortcut and returning the shortcut.

Parameters:
  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any) –

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (Optional[str]) –

Return type:

str

result(value)[source]#

Return the lowercased shortcut.

Parameters:

value (str) –

Return type:

Any

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str) –

Return type:

bool

class bot_choice.StaticChoice(option, shortcut, result)[source]#

Bases: Choice

A static choice which just returns the given value.

Create instance with replacer set to None.

Parameters:
  • option (str) –

  • shortcut (str) –

  • result (Any) –

handle()[source]#

Return the predefined value.

Return type:

Any

exception bot_choice.UnhandledAnswer[source]#

Bases: Exception

The given answer didn’t suffice.

config module#

API reference#

Module to define and load pywikibot configuration default and user preferences.

User preferences are loaded from a python file called user-config.py, which may be located in directory specified by the environment variable PYWIKIBOT_DIR, or the same directory as pwb.py, or in a directory within the users home. See get_base_dir for more information.

If user-config.py cannot be found in any of those locations, this module will fail to load unless the environment variable PYWIKIBOT_NO_USER_CONFIG is set to a value other than '0'. i.e. PYWIKIBOT_NO_USER_CONFIG=1 will allow config to load without a user-config.py. However, warnings will be shown if user-config.py was not loaded. To prevent these warnings, set PYWIKIBOT_NO_USER_CONFIG=2. If Pywikibot is installed as a site-package the behaviour is like PYWIKIBOT_NO_USER_CONFIG=2 is set.

Functions made available to user-config:

  • user_home_path

Sets module global base_dir and provides utility methods to build paths relative to base_dir:

  • makepath

  • datafilepath

  • shortpath

config.datafilepath(*filename, create=True)[source]#

Return an absolute path to a data file in a standard location.

Argument(s) are zero or more directory names, optionally followed by a data file name. The return path is offset to config.base_dir. Any directories in the path that do not already exist are created if create is True, otherwise the filesystem keeps unchanged.

Parameters:
  • filename (str) – path in the filesystem

  • create (bool) – create the directory if it is True. Otherwise don’t change the filesystem. Default is True.

Return type:

str

config.get_base_dir(test_directory=None)[source]#

Return the directory in which user-specific information is stored.

This is determined in the following order:
  1. If the script was called with a -dir: argument, use the directory provided in this argument.

  2. If the user has a PYWIKIBOT_DIR environment variable, use the value of it.

  3. If user-config is present in current directory, use the current directory.

  4. If user-config is present in pwb.py directory, use that directory

  5. Use (and if necessary create) a 'pywikibot' folder under 'Application Data' or 'AppDataRoaming' (Windows) or '.pywikibot' directory (Unix and similar) under the user’s home directory.

Set PYWIKIBOT_NO_USER_CONFIG=1 to disable loading user-config.py or install Pywikibot as a site-package.

Parameters:

test_directory (Optional[str]) – Assume that a user config file exists in this directory. Used to test whether placing a user config file in this directory will cause it to be selected as the base directory.

Return type:

str

config.makepath(path, create=True)[source]#

Return a normalized absolute version of the path argument.

If the given path already exists in the filesystem or create is False the filesystem is not modified. Otherwise if create is True makepath creates directories along the given path using the dirname() of the path. You may append a ‘/’ to the path if you want it to be a directory path.

from holger@trillke.net 2002/03/18

Parameters:
  • path (str) – path in the filesystem

  • create (bool) – create the directory if it is True. Otherwise do not change the filesystem. Default is True.

Return type:

str

config.register_families_folder(folder_path, not_exists_ok=False)[source]#

Register all family class files contained in a directory.

New in version 7.0: The not_exists_ok parameter

Parameters:
  • folder_path (str) – The path of a folder containing family files. The families may also be inside a zip archive structure.

  • not_exists_ok (bool) – When true, ignore FileNotFoundError

Raises:
  • FileNotFoundError – Family folder does not exist

  • NotADirectoryError – folder_path is not a directory

Return type:

None

config.register_family_file(family_name, file_path)[source]#

Deprecated; use family_files[family_name] = file_path instead.

Register a single family class file.

Parameter file_path may be a path or an url. family.AutoFamily function is used when the url is given.

Parameters:
  • family_name (str) –

  • file_path (str) –

Return type:

None

config.shortpath(path)[source]#

Return a file path relative to config.base_dir.

Parameters:

path (str) –

Return type:

str

config.user_home_path(path)[source]#

Return a file path to a file in the user home.

Parameters:

path (str) –

Return type:

str

Option setting#

Account Settings#

# ############# ACCOUNT SETTINGS ##############

# The family of sites we are working on. pywikibot will import
# families/xxx_family.py so if you want to change this variable,
# you need to write such a file if one does not exist.
family = 'wikipedia'
# The language code of the site we're working on.
mylang = 'language'
# If family and mylang are not modified from the above, the default is changed
# to test:test, which is test.wikipedia.org, at the end of this module.

# The dictionary usernames should contain a username for each site where you
# have a bot account. Please set your usernames by adding such lines to your
# user-config.py:
#
# usernames['wikipedia']['de'] = 'myGermanUsername'
# usernames['wiktionary']['en'] = 'myEnglishUsername'
#
# If you have a unique username for all languages of a family,
# you can use '*'
# usernames['wikibooks']['*'] = 'mySingleUsername'
# You may use '*' for family name in a similar manner.
#
usernames = collections.defaultdict(dict)  # type: Dict[str, Dict[str, str]]
disambiguation_comment = collections.defaultdict(dict)  # type: _DabComDict

# User agent format.
# For the meaning and more help in customization see:
# https://www.mediawiki.org/wiki/Manual:Pywikibot/User-agent
user_agent_format = ('{script_product} ({script_comments}) {pwb} ({revision}) '
                     '{http_backend} {python}')

# User agent description
# This is a free-form string that can be user to describe specific bot/tool,
# provide contact information, etc.
user_agent_description = None
# Fake user agent.
# Some external websites reject bot-like user agents. It is possible to use
# fake user agents in requests to these websites.
# It is recommended to default this to False and use on an as-needed basis.
#
# Default behaviours in modules that can utilize fake UAs.
# True for enabling fake UA, False for disabling / using pywikibot's own UA,
# str to specify custom UA.
fake_user_agent_default = {'reflinks': False, 'weblinkchecker': False}
# Website domains excepted to the default behaviour.
# True for enabling, False for disabling, str to hardcode a UA.
# Example: {'problematic.site.example': True,
#           'prefers.specific.ua.example': 'snakeoil/4.2'}
fake_user_agent_exceptions = {}  # type: Dict[str, Union[bool, str]]

# The default interface for communicating with the site
# currently the only defined interface is 'APISite', so don't change this!
site_interface = 'APISite'
# number of days to cache namespaces, api configuration, etc.
API_config_expiry = 30

# The maximum number of bytes which uses a GET request, if not positive
# it'll always use POST requests
maximum_GET_length = 255
# Some networks modify GET requests when they are not encrypted, to avoid
# bug reports related to that disable those. If we are confident that bug
# related to this are really because of the network this could be changed.
enable_GET_without_SSL = False

# Solve captchas in the webbrowser. Setting this to False will result in the
# exception CaptchaError being thrown if a captcha is encountered.
solve_captcha = True

# Some sites will require password authentication to access the HTML pages at
# the site. If you have any such site, add lines to your user-config.py of
# the following form:
#
# authenticate['en.wikipedia.org'] = ('John','XXXXX')
# authenticate['*.wikipedia.org'] = ('John','XXXXX')
#
# where John is your login name, and XXXXX your password.
# Note:
# 1. This is only for sites that use authentication in the form that gives
#    you a popup for name and password when you try to access any data, NOT
#    for, for example, wiki usernames
# 2. You must use the hostname of the site, not its family/language pair.
#    Pywikibot supports wildcard (*) in the prefix of hostname and select the
#    best match authentication. So you can specify authentication not only for
#    one site
#
# Pywikibot also support OAuth 1.0a via mwoauth
# https://pypi.org/project/mwoauth
#
# You can add OAuth tokens to your user-config.py of the following form:
#
# authenticate['en.wikipedia.org'] = ('consumer_key','consumer_secret',
#                                     'access_key', 'access_secret')
# authenticate['*.wikipedia.org'] = ('consumer_key','consumer_secret',
#                                    'access_key', 'access_secret')
#
# Note: the target wiki site must install OAuth extension
authenticate = {}  # type: Dict[str, Tuple[str, ...]]

# By default you are asked for a password on the terminal.
# A password file may be used, e.g. password_file = '.passwd'
# The path to the password file is relative to that of the user_config file.
# The password file should consist of lines containing Python tuples of any
# of the following formats:
# (code, family, username, password)
# (family, username, password)
# (username, password)
# It's also possible (and safer) for bot users to use BotPasswords to limit
# the permissions given to a bot. When using BotPasswords, each instance gets
# keys. This combination can only access the API, not the normal web interface.
# See https://www.mediawiki.org/wiki/Manual:Pywikibot/BotPasswords to know how
# use them. In this case, the password file should contain a BotPassword object
# in the following format:
# (username, BotPassword(botname, botpassword))
password_file = None

# edit summary to use if not supplied by bot script
# WARNING: this should NEVER be used in practice, ALWAYS supply a more
#          relevant summary for bot edits
default_edit_summary = 'Pywikibot ' + pwb_version

# What permissions to use to set private files to it
# such as password file.
#
# stat.S_IRWXU 0o700 mask for owner permissions
# stat.S_IRUSR 0o400 read permission for owner
# stat.S_IWUSR 0o200 write permission for owner
# stat.S_IXUSR 0o100 execute permission for owner
# stat.S_IRWXG 0o070 mask for group permissions
# stat.S_IRGRP 0o040 read permission for group
# stat.S_IWGRP 0o020 write permission for group
# stat.S_IXGRP 0o010 execute permission for group
# stat.S_IRWXO 0o007 mask for others permissions
# stat.S_IROTH 0o004 read permission for others
# stat.S_IWOTH 0o002 write permission for others
# stat.S_IXOTH 0o001 execute permission for others
private_files_permission = stat.S_IRUSR | stat.S_IWUSR

# Allow user to stop warnings about file security
# by setting this to true.
ignore_file_security_warnings = False

# Custom headers to send on all requests.
# This is mainly intended to support setting the
# X-Wikimedia-Debug header, which is sometimes
# needed to debug issues with Wikimedia sites:
# https://wikitech.wikimedia.org/wiki/Debugging_in_production
#
# Note that these headers will be sent with all requests,
# not just MediaWiki API calls.
extra_headers = {}  # type: Mapping[str, str]

# Set to True to override the {{bots}} exclusion protocol (at your own risk!)
ignore_bot_templates = False

User Interface Settings#

# ############# USER INTERFACE SETTINGS ##############

# The encoding that's used in the user's console, i.e. how strings are encoded
# when they are read by raw_input(). On Windows systems' DOS box, this should
# be 'cp850' ('cp437' for older versions). Linux users might try 'iso-8859-1'
# or 'utf-8'.
# This default code should work fine, so you don't have to think about it.
# When using pywikibot inside a daemonized twisted application, we get
# "StdioOnnaStick instance has no attribute 'encoding'"; assign None instead.
# TODO: consider getting rid of this config variable.
console_encoding = getattr(sys.stdout, 'encoding', None)

# The encoding the user would like to see text transliterated to. This can be
# set to a charset (e.g. 'ascii', 'iso-8859-1' or 'cp850'), and we will output
# only characters that exist in that charset. However, the characters will be
# output using console_encoding.
# If this is not defined on Windows, we emit a Warning explaining the user
# to either switch to a Unicode-able font and use
#    transliteration_target = None
# or to keep using raster fonts and set
#    transliteration_target = console_encoding
# After emitting the warning, this last option will be set.

transliteration_target = None

# The encoding in which textfiles are stored, which contain lists of page
# titles. The most used is 'utf-8'; 'utf-8-sig' recognizes BOM.
# For a complete list please see:
# https://docs.python.org/3/library/codecs.html#standard-encodings
textfile_encoding = 'utf-8'

# currently terminal and buffer are the only supported userinterfaces
userinterface = 'terminal'

# this can be used to pass variables to the UI init function
# useful for e.g.
# userinterface_init_kwargs = {'default_stream': 'stdout'}
userinterface_init_kwargs = {}  # type: Dict[str, str]

# i18n setting for user interface language
# default is obtained from locale.getlocale
userinterface_lang = None

# Should we transliterate characters that do not exist in the console
# character set?
# True: whenever possible
# False: never - always replace them by question marks
# Currently only works if interface 'terminal' is set.
transliterate = True

# The pwb.py wrapper calls the script given as parameter in this way
# python pwb.py <name_of_script> <options>
# If there is a misspelling in <name_of_script> the most similar script
# scripts are displayed or if only one is found, it will be started.
# There are some configuration values to change the behavior
#
# pwb_close_matches: the maximum number of simular scripts to be found
pwb_close_matches = 10  # must be greater than 0
# pwb_cut_off: similarity of scripts to be found
pwb_cut_off = 0.7  # must be a float in the range [0, 1]
# pwb_autostart_waittime: wait time until the most similar script starts
pwb_autostart_waittime = 5.0

# Should the system bell ring if the bot expects user input?
ring_bell = False

# Colorization can be used to markup important text parts of the output.
# On Linux/Unix terminals, ANSI escape codes are used for this. On Windows,
# it is done by a DLL call via ctypes.
# Set this to False if you're using Linux and your tty doesn't support
# ANSI colors.
try:
    # Don't print colorized when the output is, for example, piped to a file.
    colorized_output = sys.stdout.isatty()
except AttributeError:
    # When using pywikibot inside a daemonized twisted application,
    # we get "StdioOnnaStick instance has no attribute 'isatty'"
    colorized_output = False

# An indication of the size of your screen, or rather the size of the screen
# to be shown, for flickrripper
tkhorsize = 1600
tkvertsize = 1000

External Editor Settings#

# ############# EXTERNAL EDITOR SETTINGS ##############
# The command for the editor you want to use. If set to None, a simple Tkinter
# editor will be used.
editor = os.environ.get('EDITOR')

# Warning: DO NOT use an editor which doesn't support Unicode to edit pages!
# You will BREAK non-ASCII symbols!
editor_encoding = 'utf-8'

# The temporary file name extension can be set in order to use syntax
# highlighting in your text editor.
editor_filename_extension = 'wiki'

Logfile Settings#

# ############# LOGFILE SETTINGS ##############

# Defines for which scripts a logfile should be enabled. Logfiles will be
# saved in the 'logs' subdirectory.
#
# Example:
#     log = ['redirect', 'replace', 'weblinkchecker']
# It is also possible to enable logging for all scripts, using this line:
#     log = ['*']
# To disable all logging, use this:
#     log = []
# Per default, no logging is enabled.
# This setting can be overridden by the -log or -nolog command-line arguments.
log = []  # type: List[str]
# filename defaults to modulename-bot.log
logfilename = None  # type: Optional[str]
# maximal size of a logfile in kilobytes. If the size reached that limit the
# logfile will be renamed (if logfilecount is not 0) and the old file is filled
# again. logfilesize must be an integer value
logfilesize = 1024
# Number of rotating logfiles are created. The older files get the higher
# number. If logfilecount is 0, no logfile will be archived but the current
# logfile will be overwritten if the file size reached the logfilesize above.
# If logfilecount is -1 there are no rotating logfiles but the files where
# renamed if the logfile is full. The newest file gets the highest number until
# some logfiles where deleted.
logfilecount = 5
# set to 1 (or higher) to generate "informative" messages to terminal
verbose_output = 0
# set to True to fetch the pywiki version online
log_pywiki_repo_version = False
# if True, include a lot of debugging info in logfile
# (overrides log setting above)
debug_log = []  # type: List[str]

External Script Path Settings#

# ############# EXTERNAL SCRIPT PATH SETTINGS ##############
# Set your own script path to lookup for your script files.
#
# Your private script path is relative to your base directory.
# Subfolders must be delimited by '.'. every folder must contain
# an (empty) __init__.py file.
#
# The search order is
# 1. user_script_paths in the given order
# 2. scripts/userscripts
# 3. scripts
# 4. scripts/maintenance
# 5. pywikibot/scripts
#
# 2. - 4. are available in directory mode only
#
# sample:
# user_script_paths = ['scripts.myscripts']
user_script_paths = []  # type: List[str]

External Families Settings#

# ############# EXTERNAL FAMILIES SETTINGS ##############
# Set your own family path to lookup for your family files.
#
# Your private family path may be either an absolute or a relative path.
# You may have multiple paths defined in user_families_paths list.
#
# You may also define various family files stored directly in
# family_files dict. Use the family name as dict key and the path or an
# url as value.
#
# samples:
# family_files['mywiki'] = 'https://de.wikipedia.org'
# user_families_paths = ['data/families']
user_families_paths = []  # type: List[str]

Interwiki Settings#

# ############# INTERWIKI SETTINGS ##############

# Should interwiki.py report warnings for missing links between foreign
# languages?
interwiki_backlink = True

# Should interwiki.py display every new link it discovers?
interwiki_shownew = True

# Should interwiki.py output a graph PNG file on conflicts?
# You need pydot for this:
# https://pypi.org/project/pydot/
interwiki_graph = False

# Specifies that the robot should process that amount of subjects at a time,
# only starting to load new pages in the original language when the total
# falls below that number. Default is to process (at least) 100 subjects at
# once.
interwiki_min_subjects = 100

# If interwiki graphs are enabled, which format(s) should be used?
# Supported formats include png, jpg, ps, and svg. See:
# http://www.graphviz.org/doc/info/output.html
# If you want to also dump the dot files, you can use this in your
# user-config.py:
# interwiki_graph_formats = ['dot', 'png']
# If you need a PNG image with an HTML image map, use this:
# interwiki_graph_formats = ['png', 'cmap']
# If you only need SVG images, use:
# interwiki_graph_formats = ['svg']
interwiki_graph_formats = ['png']

# You can post the contents of your autonomous_problems.dat to the wiki,
# e.g. to https://de.wikipedia.org/wiki/Wikipedia:Interwiki-Konflikte .
# This allows others to assist you in resolving interwiki problems.
# To help these people, you can upload the interwiki graphs to your
# webspace somewhere. Set the base URL here, e.g.:
# 'https://www.example.org/~yourname/interwiki-graphs/'
interwiki_graph_url = None

# Save file with local articles without interwikis.
without_interwiki = False

Solve Disambiguations Settings#

# ############# SOLVE_DISAMBIGUATION SETTINGS ############
#
# Set disambiguation_comment[FAMILY][LANG] to a non-empty string to override
# the default edit comment for the solve_disambiguation bot.
#
# Use %s to represent the name of the disambiguation page being treated.
# Example:
#
# disambiguation_comment['wikipedia']['en'] = \
#    'Robot-assisted disambiguation ([[WP:DPL|you can help!]]): %s'

# Sorting order for alternatives. Set to True to ignore case for sorting order.
sort_ignore_case = False

Settings to Avoid Server Overload#

# ############# SETTINGS TO AVOID SERVER OVERLOAD ##############

# Slow down the robot such that it never requests a second page within
# 'minthrottle' seconds. This can be lengthened if the server is slow,
# but never more than 'maxthrottle' seconds. However - if you are running
# more than one bot in parallel the times are lengthened.
#
# 'maxlag' is used to control the rate of server access (see below).
# Set minthrottle to non-zero to use a throttle on read access.
minthrottle = 0
maxthrottle = 60

# Slow down the robot such that it never makes a second page edit within
# 'put_throttle' seconds.
put_throttle = 10  # type: Union[int, float]

# Sometimes you want to know when a delay is inserted. If a delay is larger
# than 'noisysleep' seconds, it is logged on the screen.
noisysleep = 3.0

# Defer bot edits during periods of database server lag. For details, see
# https://www.mediawiki.org/wiki/Manual:Maxlag_parameter
# You can set this variable to a number of seconds, or to None (or 0) to
# disable this behavior. Higher values are more aggressive in seeking
# access to the wiki.
# Non-Wikimedia wikis may or may not support this feature; for families
# that do not use it, it is recommended to set minthrottle (above) to
# at least 1 second.
maxlag = 5

# Maximum of pages which can be retrieved at one time from wiki server.
# -1 indicates limit by api restriction
step = -1

# Maximum number of times to retry an API request before quitting.
max_retries = 15
# Minimum time to wait before resubmitting a failed API request.
retry_wait = 5
# Maximum time to wait before resubmitting a failed API request.
retry_max = 120

Database Settings#

# ############# DATABASE SETTINGS ##############
# Setting to connect the database or replica of the database of the wiki.
# db_name_format can be used to manipulate the dbName of site.
#
# Example for a pywikibot running on Wikimedia Cloud (Toolforge):
# db_hostname_format = '{0}.analytics.db.svc.wikimedia.cloud'
# db_name_format = '{0}_p'
# db_connect_file = user_home_path('replica.my.cnf')
db_hostname_format = 'localhost'
db_username = ''
db_password = ''
db_name_format = '{0}'
db_connect_file = user_home_path('.my.cnf')
# local port for mysql server
# ssh -L 4711:enwiki.analytics.db.svc.eqiad.wmflabs:3306 \
#     user@login.toolforge.org
db_port = 3306

Http Settings#

# ############# HTTP SETTINGS ##############
# Default socket timeout in seconds.
# DO NOT set to None to disable timeouts. Otherwise this may freeze your
# script.
# You may assign either a tuple of two int or float values for connection and
# read timeout, or a single value for both in a tuple.
socket_timeout = (6.05, 45)


Cosmetic Changes Settings#

# ############# COSMETIC CHANGES SETTINGS ##############
# The bot can make some additional changes to each page it edits, e.g. fix
# whitespace or positioning of category links.

# This is an experimental feature; handle with care and consider re-checking
# each bot edit if enabling this!
cosmetic_changes = False

# If cosmetic changes are switched on, and you also have several accounts at
# projects where you're not familiar with the local conventions, you probably
# only want the bot to do cosmetic changes on your "home" wiki which you
# specified in config.mylang and config.family.
# If you want the bot to also do cosmetic changes when editing a page on a
# foreign wiki, set cosmetic_changes_mylang_only to False, but be careful!
cosmetic_changes_mylang_only = True

# The dictionary cosmetic_changes_enable should contain a tuple of languages
# for each site where you wish to enable in addition to your own langlanguage
# (if cosmetic_changes_mylang_only is set)
# Please set your dictionary by adding such lines to your user-config.py:
# cosmetic_changes_enable['wikipedia'] = ('de', 'en', 'fr')
cosmetic_changes_enable = {}  # type: Dict[str, Tuple[str, ...]]

# The dictionary cosmetic_changes_disable should contain a tuple of languages
# for each site where you wish to disable cosmetic changes. You may use it with
# cosmetic_changes_mylang_only is False, but you can also disable your own
# language. This also overrides the settings in the cosmetic_changes_enable
# dictionary. Please set your dict by adding such lines to your user-config.py:
# cosmetic_changes_disable['wikipedia'] = ('de', 'en', 'fr')
cosmetic_changes_disable = {}  # type: Dict[str, Tuple[str, ...]]

# cosmetic_changes_deny_script is a list of scripts for which cosmetic changes
# are disabled. You may add additional scripts by appending script names in
# your user-config.py ("+=" operator is strictly recommended):
# cosmetic_changes_deny_script += ['your_script_name_1', 'your_script_name_2']
# Appending the script name also works:
# cosmetic_changes_deny_script.append('your_script_name')
cosmetic_changes_deny_script = ['category_redirect', 'cosmetic_changes',
                                'newitem', 'touch']

Replication Bot Settings#

# ############# REPLICATION BOT SETTINGS ################
# You can add replicate_replace to your user-config.py.
#
# Use has the following format:
#
# replicate_replace = {
#            'wikipedia:li': {'Hoofdpagina': 'Veurblaad'}
# }
#
# to replace all occurrences of 'Hoofdpagina' with 'Veurblaad' when writing to
# liwiki. Note that this does not take the origin wiki into account.
replicate_replace = {}  # type: Dict[str, Dict[str, str]]

Further Settings#

# ############# FURTHER SETTINGS ##############

# Simulate settings

# Defines what additional actions the bots are NOT allowed to do (e.g. 'edit')
# on the wiki server. Allows simulation runs of bots to be carried out without
# changing any page on the server side. Use this setting to add more actions
# in user-config.py for wikis with extra write actions.
actions_to_block = []  # type: List[str]

# Set simulate to True or use -simulate option to block all actions given
# above.
simulate = False  # type: Union[bool, str]

# How many pages should be put to a queue in asynchronous mode.
# If maxsize is <= 0, the queue size is infinite.
# Increasing this value will increase memory space but could speed up
# processing. As higher this value this effect will decrease.
max_queue_size = 64

# Pickle protocol version to use for storing dumps.
# This config variable is not used for loading dumps.
# Version 0 is a more or less human-readable protocol
# Version 2 is common to both Python 2 and 3, and should
# be used when dumps are accessed by both versions.
# Version 3 is only available for Python 3
# Version 4 is only available for Python 3.4+
# Version 5 was added with Python 3.8
pickle_protocol = 2

cosmetic_changes module#

This module can do slight modifications to tidy a wiki page’s source code.

The changes are not supposed to change the look of the rendered wiki page.

If you wish to run this as an stand-alone script, use:

scripts/cosmetic_changes.py

For regular use, it is recommended to put this line into your user-config.py:

cosmetic_changes = True

You may enable cosmetic changes for additional languages by adding the dictionary cosmetic_changes_enable to your user-config.py. It should contain a tuple of languages for each site where you wish to enable in addition to your own langlanguage if cosmetic_changes_mylang_only is True (see below). Please set your dictionary by adding such lines to your user-config.py:

cosmetic_changes_enable['wikipedia'] = ('de', 'en', 'fr')

There is another config variable: You can set:

cosmetic_changes_mylang_only = False

if you’re running a bot on multiple sites and want to do cosmetic changes on all of them, but be careful if you do.

You may disable cosmetic changes by adding the all unwanted languages to the dictionary cosmetic_changes_disable in your user-config.py. It should contain a tuple of languages for each site where you wish to disable cosmetic changes. You may use it with cosmetic_changes_mylang_only is False, but you can also disable your own language. This also overrides the settings in the dictionary cosmetic_changes_enable. Please set this dictionary by adding such lines to your user-config.py:

cosmetic_changes_disable['wikipedia'] = ('de', 'en', 'fr')

You may disable cosmetic changes for a given script by appending the all unwanted scripts to the list cosmetic_changes_deny_script in your user-config.py. By default it contains cosmetic_changes.py itself and touch.py. This overrides all other enabling settings for cosmetic changes. Please modify the given list by adding such lines to your user-config.py:

cosmetic_changes_deny_script.append('your_script_name_1')

or by adding a list to the given one:

cosmetic_changes_deny_script += ['your_script_name_1',
                                 'your_script_name_2']
class cosmetic_changes.CANCEL(value)[source]#

Bases: IntEnum

Cancel level to ignore exceptions.

If an error occurred and either skips the page or the method or a single match. ALL raises the exception.

New in version 6.3.

ALL = 0#
MATCH = 3#
METHOD = 2#
PAGE = 1#
class cosmetic_changes.CosmeticChangesToolkit(page, *, show_diff=False, ignore=CANCEL.ALL)[source]#

Bases: object

Cosmetic changes toolkit.

Changed in version 7.0: from_page() method was removed

Changed in version 5.2: instantiate the CosmeticChangesToolkit from a page object; only allow keyword arguments except for page parameter; namespace and pageTitle parameters are deprecated

Changed in version 7.0: namespace and pageTitle parameters were removed

Parameters:
  • page (pywikibot.page.BasePage) – the Page object containing the text to be modified

  • show_diff (bool) – show difference after replacements

  • ignore (IntEnum) – ignores if an error occurred and either skips the page or only that method. It can be set one of the CANCEL constants

change(text)[source]#

Execute all clean up methods and catch errors if activated.

Parameters:

text (str) –

Return type:

Union[bool, str]

Tidy up wikilinks found in a string.

This function will: * Replace underscores with spaces

  • Move leading and trailing spaces out of the wikilink and into the surrounding text

  • Convert URL-encoded characters into Unicode-encoded characters

  • Move trailing characters out of the link and make the link without using a pipe, if possible

  • Capitalize the article title of the link, if appropriate

Parameters:

text (str) – string to perform the clean-up on

Returns:

text with tidied wikilinks

Return type:

str

cleanUpSectionHeaders(text)[source]#

Add a space between the equal signs and the section title.

Example:

==Section title==

becomes:

== Section title ==

Note

This space is recommended in the syntax help on the English and German Wikipedias. It is not wanted on Lojban and English Wiktionaries (T168399, T169064) and it might be that it is not wanted on other wikis. If there are any complaints, please file a bug report.

Parameters:

text (str) –

Return type:

str

commonsfiledesc(text)[source]#

Clean up file descriptions on Wikimedia Commons.

It works according to [1] and works only on pages in the file namespace on Wikimedia Commons.

[1]: https://commons.wikimedia.org/wiki/Commons:Tools/pywiki_file_description_cleanup

Parameters:

text (str) –

Return type:

str

fixArabicLetters(text)[source]#

Fix Arabic and Persian letters.

Parameters:

text (str) –

Return type:

str

fixHtml(text)[source]#

Relace html markups with wikitext markups.

Parameters:

text (str) –

Return type:

str

fixReferences(text)[source]#

Fix references tags.

Parameters:

text (str) –

Return type:

str

fixSelfInterwiki(text)[source]#

Interwiki links to the site itself are displayed like local links.

Remove their language code prefix.

Parameters:

text (str) –

Return type:

str

fixStyle(text)[source]#

Convert prettytable to wikitable class.

Parameters:

text (str) –

Return type:

str

fixSyntaxSave(text)[source]#

Convert weblinks to wikilink, fix link syntax.

Parameters:

text (str) –

Return type:

str

fixTypo(text)[source]#

Fix units.

Parameters:

text (str) –

Return type:

str

fix_ISBN(text)[source]#

Hyphenate ISBN numbers.

Parameters:

text (str) –

Return type:

str

putSpacesInLists(text)[source]#

Add a space between the * or # and the text.

Note

This space is recommended in the syntax help on the English, German and French Wikipedias. It might be that it is not wanted on other wikis. If there are any complaints, please file a bug report.

Parameters:

text (str) –

Return type:

str

removeEmptySections(text)[source]#

Cleanup empty sections.

Parameters:

text (str) –

Return type:

str

removeNonBreakingSpaceBeforePercent(text)[source]#

Remove a non-breaking space between number and percent sign.

Newer MediaWiki versions automatically place a non-breaking space in front of a percent sign, so it is no longer required to place it manually.

Parameters:

text (str) –

Return type:

str

removeUselessSpaces(text)[source]#

Cleanup multiple or trailing spaces.

Parameters:

text (str) –

Return type:

str

replaceDeprecatedTemplates(text)[source]#

Replace deprecated templates.

Parameters:

text (str) –

Return type:

str

resolveHtmlEntities(text)[source]#

Replace HTML entities with string.

Parameters:

text (str) –

Return type:

str

safe_execute(method, text)[source]#

Execute the method and catch exceptions if enabled.

Parameters:
  • method (Callable[[str], str]) –

  • text (str) –

Return type:

str

standardizePageFooter(text)[source]#

Standardize page footer.

Makes sure that interwiki links and categories are put into the correct position and into the right order. This combines the old instances of standardizeInterwiki and standardizeCategories.

The page footer consists of the following parts in that sequence: 1. categories 2. additional information depending on the local site policy 3. interwiki

Parameters:

text (str) –

Return type:

str

translateAndCapitalizeNamespaces(text)[source]#

Use localized namespace names.

Changed in version 7.4: No longer expect a specific namespace alias for File:

Parameters:

text (str) –

Return type:

str

translateMagicWords(text)[source]#

Use localized magic words.

Parameters:

text (str) –

Return type:

str

daemonize module#

Module to daemonize the current process on Unix.

daemonize.daemonize(close_fd=True, chdir=True, redirect_std=None)[source]#

Daemonize the current process.

Only works on POSIX compatible operating systems. The process will fork to the background and return control to terminal.

Parameters:
  • close_fd (bool) – Close the standard streams and replace them by /dev/null

  • chdir (bool) – Change the current working directory to /

  • redirect_std (Optional[str]) – Filename to redirect stdout and stdin to

Return type:

None

date module#

Date data and manipulation module.

class date.MonthFormat(index, format_key)[source]#

Bases: MutableMapping

A Mapping which creates months formats.

Initializer of MonthFormat mapping.

Parameters:
  • index (int) – month number

  • format_key (str) – formats key like Day_January or Year_December

day_formats = {'af': ('%d {}', True), 'ang': ('%d {}', True), 'ar': ('%d {}', True), 'arz': ('%d {}', True), 'bg': ('%d {}', False), 'bn': ('{} %%B', None), 'ceb': ('{} %d', True), 'csb': ('%d {}a', False), 'cv': ('{}, %d', True), 'cy': ('%d {}', True), 'de': ('%d. {}', True), 'en': ('{} %d', True), 'eo': ('%d-a de {}', False), 'es': ('%d de {}', False), 'eu': ('{}aren %d', True), 'fi': ('%d. {}ta', False), 'fur': ('%d di {}', True), 'fy': ('%d {}', False), 'gl': ('%d de {}', False), 'gsw': ('%d. {}', True), 'he': ('%d ב{}', None), 'hu': ('{} %d.', True), 'ia': ('%d de {}', False), 'id': ('%d {}', True), 'ie': ('%d {}', False), 'io': ('%d di {}', False), 'it': ('%d {}', False), 'jv': ('%d {}', True), 'ka': ('%d {}', None), 'lb': ('%d. {}', True), 'mhr': ('%d {}', False), 'ml': ('{} %d', None), 'ms': ('%d {}', True), 'nap': ("%d 'e {}", False), 'nds': ('%d. {}', True), 'pt': ('%d de {}', True), 'ro': ('%d {}', False), 'scn': ('%d di {}', False), 'sco': ('%d {}', True), 'su': ('%d {}', True), 'sv': ('%d {}', False), 'ta': ('{} %d', None), 'te': ('{} %d', None), 'th': ('%d {}', None), 'tl': ('{} %d', None), 'tr': ('%d {}', True), 'tt': ('%d. {}', True), 'vec': ('%d de {}', False), 'vo': ('{} %d', False)}#
year_formats = {'cs': ('{} %d', None), 'eo': ('{} de %d', None), 'es': ('{} de %d', True), 'it': ('Attualità/Anno %d - {}', True), 'ka': ('{}, %d', None), 'sk': ('{} %d', None), 'th': ('{} พ.ศ. %%T', None), 'tl': ('{} %d', None)}#
class date.MonthNames[source]#

Bases: Mapping

A Mapping which reads month names from MediaWiki messages.

months = {'br': <function MonthNames.<lambda>>, 'en': <function MonthNames.<lambda>>, 'ja': <function MonthNames.<lambda>>, 'ko': <function MonthNames.<lambda>>, 'wa': <function MonthNames.<lambda>>, 'zh': <function MonthNames.<lambda>>}#
date.addFmt1(lang, isMnthOfYear, patterns)[source]#

Add 12 month formats for a specific type (‘January’, ‘Feb.’).

The function must accept one parameter for the ->int or ->string conversions, just like everywhere else in the formats map. The patterns parameter is a list of 12 elements to be used for each month.

Parameters:
  • lang (str) – language code

  • isMnthOfYear (bool) –

  • patterns (Sequence[Optional[str]]) –

Return type:

None

date.alwaysTrue(x)[source]#

Return True, always.

Used for multiple value selection function to accept all other values.

Parameters:

x (Any) – not used

Returns:

True

Return type:

bool

date.apply_month_delta(date, month_delta=1, add_overlap=False)[source]#

Add or subtract months from the date.

By default if the new month has less days then the day of the date it chooses the last day in the new month. For example a date in the March 31st added by one month will result in April 30th.

When the overlap is enabled, and there is overlap, then the new_date will be one month off and get_month_delta will report a number one higher.

It does only work on calendars with 12 months per year, and where the months are numbered consecutively beginning by 1.

Parameters:
  • date (date) – The starting date

  • month_delta (int) – The amount of months added or subtracted.

  • add_overlap (bool) – Add any missing days to the date, increasing the month once more.

Returns:

The end date

Return type:

date

date.decSinglVal(v)[source]#

Return first item in list v.

Parameters:

v (Sequence[Any]) –

Return type:

Any

date.dh(value, pattern, encf, decf, filter=None)[source]#
date.dh(value, pattern, encf, decf, filter=None)

Function to help with year parsing.

Usually it will be used as a lambda call in a map:

lambda v: dh(v, 'pattern string', encf, decf)
Parameters:
  • encf (Callable[[int], Union[int, Sequence[int]]]) –

    Converts from an integer parameter to another integer or a tuple of integers. Depending on the pattern, each integer will be converted to a proper string representation, and will be passed as a format argument to the pattern:

    pattern % encf(value)
    

    This function is a complement of decf.

  • decf (Callable[[Sequence[int]], int]) – Converts a tuple/list of non-negative integers found in the original value string into a normalized value. The normalized value can be passed right back into dh() to produce the original string. This function is a complement of encf. dh() interprets %d as a decimal and %s as a roman numeral number.

  • value (int) –

  • pattern (str) –

  • filter (Optional[Callable[[int], bool]]) –

Return type:

str

date.dh_centuryAD(value, pattern)[source]#

Helper for decoding an AD century.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_centuryBC(value, pattern)[source]#

Helper for decoding an BC century.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_constVal(value, ind, match)[source]#
date.dh_constVal(value, ind, match)

Helper function to match a single value to a constant.

formats[‘CurrEvents’][‘en’](ind) => ‘Current Events’ formats[‘CurrEvents’][‘en’](‘Current Events’) => ind

Parameters:
  • value (int) –

  • ind (int) –

  • match (str) –

Return type:

str

date.dh_dayOfMnth(value, pattern)[source]#

Helper for decoding a single integer value.

The single integer should be <=31, no conversion, no rounding (used in days of month).

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_decAD(value, pattern)[source]#

Helper for decoding a single integer value.

It should be no conversion, round to decimals (used in decades)

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_decBC(value, pattern)[source]#

Helper for decoding a single integer value.

It should be no conversion, round to decimals (used in decades)

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_millenniumAD(value, pattern)[source]#

Helper for decoding an AD millennium.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_millenniumBC(value, pattern)[source]#

Helper for decoding an BC millennium.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_mnthOfYear(value, pattern)[source]#

Helper for decoding a single integer value.

The value should be >=1000, no conversion, no rounding (used in month of the year)

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_noConv(value, pattern, limit)[source]#

Helper for decoding an integer value, no conversion, no rounding.

Parameters:
  • value (int) –

  • pattern (str) –

  • limit (Callable[[int], bool]) –

Return type:

str

date.dh_number(value, pattern)[source]#

Helper for decoding a number.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_simpleYearAD(value)[source]#

Helper for decoding a single integer value.

This value should be representing a year with no extra symbols.

Parameters:

value (int) –

Return type:

str

date.dh_singVal(value, match)[source]#
date.dh_singVal(value, match)

Helper function to match a single value to a constant.

Parameters:
  • value (int) –

  • match (str) –

Return type:

str

date.dh_yearAD(value, pattern)[source]#

Helper for decoding a year value.

The value should have no conversion, no rounding, limits to 3000.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.dh_yearBC(value, pattern)[source]#

Helper for decoding a year value.

The value should have no conversion, no rounding, limits to 3000.

Parameters:
  • value (int) –

  • pattern (str) –

Return type:

str

date.encDec0(i)[source]#

Round to the nearest decade, decade starts with a ‘0’-ending year.

Parameters:

i (int) –

Return type:

int

date.encDec1(i)[source]#

Round to the nearest decade, decade starts with a ‘1’-ending year.

Parameters:

i (int) –

Return type:

int

date.escapePattern2(pattern)[source]#

Convert a string pattern into a regex expression and cache.

Allows matching of any _digitDecoders inside the string. Returns a compiled regex object and a list of digit decoders.

Parameters:

pattern (str) –

Return type:

Tuple[Pattern[str], str, List[Union[Tuple[str, Callable[[int], str], Callable[[str], int]], Tuple[str, Callable[[int], str], Callable[[str], int], int]]]]

date.formatYear(lang, year)[source]#

Return year name in a language.

Parameters:
  • lang (str) –

  • year (int) –

Return type:

str

date.format_date(month, day, lang=None, year=2000)[source]#

Format a date localized to given lang.

Parameters:
  • month (int) – month in range of 1..12

  • day (int) – day of month in range of 1..31

  • lang (Optional[Union[str, BaseSite]]) – a site object or language key. Defaults to current site.

  • year (int) – year for which the date is to be formatted. always 29 will be given For February except the year is given. Default is leap year 2000.

Returns:

localized date like “January 11”

Raises:
  • ValueError – Wrong day value; must be 1-28/29/30/31

  • IllegalMonthError – bad month number; must be 1-12

Return type:

str

date.getAutoFormat(lang, title, ignoreFirstLetterCase=True)[source]#

Return first matching formatted date value.

Parameters:
  • lang (str) – language code

  • title (str) – value to format

  • ignoreFirstLetterCase (bool) –

Returns:

dictName (‘YearBC’, ‘December’, …) and value (a year, date, …)

Return type:

Tuple[Optional[str], Optional[str]]

date.get_month_delta(date1, date2)[source]#

Return the difference between two dates in months.

It does only work on calendars with 12 months per year, and where the months are consecutive and non-negative numbers.

Parameters:
  • date1 (date) –

  • date2 (date) –

Return type:

int

date.intToLocalDigitsStr(value, digitsToLocalDict)[source]#

Encode an integer value into a textual form.

Parameters:
  • value (int) –

  • digitsToLocalDict (Mapping[int, str]) –

Return type:

str

date.intToRomanNum(i)[source]#

Convert integer to roman numeral.

Parameters:

i (int) –

Return type:

str

date.localDigitsStrToInt(value, digitsToLocalDict, localToDigitsDict)[source]#

Convert digits to integer.

Parameters:
  • value (str) –

  • digitsToLocalDict (Mapping[int, str]) –

  • localToDigitsDict (Mapping[int, str]) –

Return type:

int

date.makeMonthList(pattern)[source]#

Return a list of 12 elements based on the number of the month.

Parameters:

pattern (str) –

Return type:

List[str]

date.makeMonthNamedList(lang, pattern, makeUpperCase=None)[source]#

Create a list of 12 elements based on the name of the month.

The language-dependent month name is used as a formatting argument to the pattern. The pattern must be have one %s that will be replaced by the localized month name. Use %%d for any other parameters that should be preserved.

Parameters:
  • lang (str) –

  • pattern (str) –

  • makeUpperCase (Optional[bool]) –

Return type:

List[str]

date.monthName(lang, ind)[source]#

Return the month name for a language.

Parameters:
  • lang (str) –

  • ind (int) –

Return type:

str

date.multi(value, tuplst)[source]#
date.multi(value, tuplst)

Run multiple pattern checks for the same entry.

For example: 1st century, 2nd century, etc.

The tuplst is a list of tuples. Each tuple must contain two functions: first to encode/decode a single value (e.g. simpleInt), second is a predicate function with an integer parameter that returns true or false. When the 2nd function evaluates to true, the 1st function is used.

Parameters:
  • value (int) –

  • tuplst (List[Tuple[Callable[[Union[int, str]], Any], Callable[[Union[int, str]], bool]]]) –

Return type:

Any

date.romanNumToInt(v)[source]#

Convert roman numeral to integer.

Parameters:

v (str) –

Return type:

int

date.slh(value, lst)[source]#
date.slh(value, lst)

Helper function for simple list value matching.

!!!!! The index starts at 1, so 1st element has index 1, not 0 !!!!!

Usually it will be used as a lambda call in a map:

lambda v: slh(v, ['January','February',...])

Usage scenarios:

formats['MonthName']['en'](1) => 'January'
formats['MonthName']['en']('January') => 1
formats['MonthName']['en']('anything else') => raise ValueError
Parameters:
  • value (int) –

  • lst (Sequence[str]) –

Return type:

str

diff module#

Diff module.

class diff.Hunk(a, b, grouped_opcode)[source]#

Bases: object

One change hunk between a and b.

Note

parts of this code are taken from by difflib.get_grouped_opcodes().

Parameters:
  • a (Union[str, Sequence[str]]) – sequence of lines

  • b (Union[str, Sequence[str]]) – sequence of lines

  • grouped_opcode (Sequence[Tuple[str, int, int, int, int]]) – list of 5-tuples describing how to turn a into b. It has the same format as returned by difflib.get_opcodes().

APPR = 1#
NOT_APPR = -1#
PENDING = 0#
apply()[source]#

Turn a into b for this hunk.

Return type:

Sequence[str]

color_line(line, line_ref=None)[source]#

Color line characters.

If line_ref is None, the whole line is colored. If line_ref[i] is not blank, line[i] is colored. Color depends if line starts with +/-.

line_ref: string.

Parameters:
  • line (str) –

  • line_ref (Optional[str]) –

Return type:

str

create_diff()[source]#

Generator of diff text for this hunk, without formatting.

Check each line ends with line feed to prevent behaviour like Python issue 2142

Return type:

Iterable[str]

format_diff()[source]#

Color diff lines.

Return type:

Iterable[str]

get_header()[source]#

Provide header of unified diff.

Return type:

str

static get_header_text(a_rng, b_rng, affix='@@')[source]#

Provide header for any ranges.

Parameters:
  • a_rng (Tuple[int, int]) –

  • b_rng (Tuple[int, int]) –

  • affix (str) –

Return type:

str

class diff.PatchManager(text_a, text_b, context=0, by_letter=False, replace_invisible=False)[source]#

Bases: object

Apply patches to text_a to obtain a new text.

If all hunks are approved, text_b will be obtained.

Parameters:
  • text_a (str) – base text

  • text_b (str) – target text

  • context (int) – number of lines which are context

  • by_letter (bool) – if text_a and text_b are single lines, comparison can be done letter by letter.

  • replace_invisible (bool) – Replace invisible characters like U+200e with the charnumber in brackets (e.g. <200e>).

apply()[source]#

Apply changes. If there are undecided changes, ask to review.

Return type:

List[str]

get_blocks()[source]#

Return list with blocks of indexes.

Format of each block:

[-1, (i1, i2), (-1, -1)] -> block a[i1:i2] does not change from
    a to b then is there is no corresponding hunk.
[hunk index, (i1, i2), (j1, j2)] -> block a[i1:i2] becomes b[j1:j2]
Return type:

List[Tuple[int, Tuple[int, int], Tuple[int, int]]]

print_hunks()[source]#

Print the headers and diff texts of all hunks to the output.

Return type:

None

review_hunks()[source]#

Review hunks.

Return type:

None

diff.cherry_pick(oldtext, newtext, n=0, by_letter=False)[source]#

Propose a list of changes for approval.

Text with approved changes will be returned. n: int, line of context as defined in difflib.get_grouped_opcodes(). by_letter: if text_a and text_b are single lines, comparison can be done

Parameters:
  • oldtext (str) –

  • newtext (str) –

  • n (int) –

  • by_letter (bool) –

Return type:

str

diff.html_comparator(compare_string)[source]#

List of added and deleted contexts from ‘action=compare’ html string.

This function is useful when combineds with site.py’s “compare” method. Site.compare() returns HTML that is useful for displaying on a page. Here we use BeautifulSoup to get the un-HTML-ify the context of changes. Finally we present the added and deleted contexts. :param compare_string: HTML string from MediaWiki API :return: deleted and added list of contexts

Parameters:

compare_string (str) –

Return type:

Dict[str, List[str]]

echo module#

Classes and functions for working with the Echo extension.

class echo.Notification(site)[source]#

Bases: object

A notification issued by the Echo extension.

Initialize an empty Notification object.

Parameters:

site (pywikibot.site.BaseSite) –

classmethod fromJSON(site, data)[source]#

Construct a Notification object from our API’s JSON data.

Parameters:
  • site (BaseSite) –

  • data (Dict[str, Any]) –

Return type:

Notification

mark_as_read()[source]#

Mark the notification as read.

Return type:

bool

editor module#

Text editor class for your favourite editor.

class editor.TextEditor[source]#

Bases: object

Text editor.

edit(text, jumpIndex=None, highlight=None)[source]#

Call the editor and thus allows the user to change the text.

Halts the thread’s operation until the editor is closed.

Parameters:
  • text (str) – the text to be edited

  • jumpIndex (Optional[int]) – position at which to put the caret

  • highlight (Optional[str]) – each occurrence of this substring will be highlighted

Returns:

the modified text, or None if the user didn’t save the text file in his text editor

Return type:

Optional[str]

exceptions module#

Pywikibot Exceptions and warning classes.

This module contains all exception and warning classes used throughout the framework:

Exception
 +-- Error
      +-- APIError
      |    +-- APIMWError
      |    +-- UploadError
      +-- AutoblockUserError
      +-- CaptchaError
      +-- InvalidTitleError
      +-- NoUsernameError
      +-- PageInUseError
      +-- PageRelatedError
      |    +-- CircularRedirectError
      |    +-- InterwikiRedirectPageError
      |    +-- IsNotRedirectPageError
      |    +-- IsRedirectPageError
      |    +-- NoMoveTargetError
      |    +-- NoPageError
      |    +-- NotEmailableError
      |    +-- PageLoadRelatedError
      |    |    +-- InconsistentTitleError
      |    |    +-- InvalidPageError
      |    +-- PageSaveRelatedError
      |    |    +-- EditConflictError
      |    |    |    +-- ArticleExistsConflictError
      |    |    |    +-- PageCreatedConflictError
      |    |    |    +-- PageDeletedConflictError
      |    |    +-- LockedPageError
      |    |    |    +-- LockedNoPageError
      |    |    |    +-- CascadeLockedPageError
      |    |    +-- NoCreateError
      |    |    +-- OtherPageSaveError
      |    |    +-- SpamblacklistError
      |    |    +-- TitleblacklistError
      |    |    +-- AbuseFilterDisallowedError
      |    +-- UnsupportedPageError
      +-- SectionError
      +-- ServerError
      |    +-- FatalServerError
      |    +-- Server414Error
      |    +-- Server504Error
      +-- SiteDefinitionError
      |    +-- UnknownFamilyError
      |    +-- UnknownSiteError
      +-- TimeoutError
      |    +-- MaxlagTimeoutError
      +-- TranslationError
      +-- UserRightsError
      |    +-- HiddenKeyError (KeyError)
      +-- UnknownExtensionError (NotImplementedError)
      +-- VersionParseError
      +-- WikiBaseError
           +-- CoordinateGlobeUnknownError (NotImplementedError)
           +-- EntityTypeUnknownError
           +-- NoWikibaseEntityError

UserWarning
 +-- ArgumentDeprecationWarning (FutureWarning)
 +-- FamilyMaintenanceWarning

RuntimeWarning
 +-- NotImplementedWarning

Error: Base class, all exceptions should the subclass of this class.

  • NoUsernameError: Username is not in user-config.py, or it is invalid.

  • AutoblockUserError: requested action on a virtual autoblock user not valid

  • TranslationError: no language translation found

  • UserRightsError: insufficient rights for requested action

  • InvalidTitleError: Invalid page title

  • CaptchaError: Captcha is asked and config.solve_captcha == False

  • i18n.TranslationError: i18n/l10n message not available

  • PageInUseError: Page cannot be reserved due to a lock

  • UnknownExtensionError: Extension is not defined for this site

  • VersionParseError: failed to parse version information

  • SectionError: The section specified by # does not exist

APIError: wiki API returned an error

  • APIMWError: MediaWiki internal exception

  • UploadError: upload failed

SiteDefinitionError: Site loading problem

  • UnknownSiteError: Site does not exist in Family

  • UnknownFamilyError: Family is not registered

PageRelatedError: any exception which is caused by an operation on a Page.

  • NoPageError: Page does not exist

  • UnsupportedPageError: Page is not supported due to a namespace restriction

  • IsRedirectPageError: Page is a redirect page

  • IsNotRedirectPageError: Page is not a redirect page

  • CircularRedirectError: Page is a circular redirect

  • InterwikiRedirectPageError: Page is a redirect to another site

  • InvalidPageError: Page is invalid e.g. without history

  • NotEmailableError: The target user has disabled email

  • NoMoveTargetError: An expected move target page does not exist

PageLoadRelatedError: any exception which happens while loading a Page.
  • InconsistentTitleError: Page receives a title inconsistent with query

PageSaveRelatedError: page exceptions within the save operation on a Page

  • AbuseFilterDisallowedError: AbuseFilter disallowed

  • SpamblacklistError: MediaWiki spam filter detected a blacklisted URL

  • TitleblacklistError: MediaWiki detected a blacklisted page title

  • OtherPageSaveError: misc. other save related exception.

  • LockedPageError: Page is locked
    • LockedNoPageError: Title is locked against creation

    • CascadeLockedPageError: Page is locked due to cascading protection

  • EditConflictError: Edit conflict while uploading the page
    • PageDeletedConflictError: Page was deleted since being retrieved

    • PageCreatedConflictError: Page was created by another user

    • ArticleExistsConflictError: Page article already exists

  • NoCreateError: parameter nocreate not allow page creation

ServerError: a problem with the server.

  • FatalServerError: A fatal/non-recoverable server error

  • Server414Error: Server timed out with HTTP 414 code

  • Server504Error: Server timed out with HTTP 504 code

WikiBaseError: any issue specific to Wikibase.

  • NoWikibaseEntityError: entity doesn’t exist

  • CoordinateGlobeUnknownError: globe is not implemented yet.

  • EntityTypeUnknownError: entity type is not available on the site.

TimeoutError: request failed with a timeout

  • MaxlagTimeoutError: request failed with a maxlag timeout

DeprecationWarning: old functionality replaced by new functionality

PendingDeprecationWarning: problematic code which has not yet been fully deprecated, possibly because a replacement is not available

RuntimeWarning: problems developers should have fixed, and users need to be aware of its status.

  • NotImplementedWarning: functionality not implemented

UserWarning: warnings targeted at users

  • config._ConfigurationDeprecationWarning: user configuration file problems

  • login._PasswordFileWarning: password file problems

  • ArgumentDeprecationWarning: command line argument problems

  • FamilyMaintenanceWarning: missing information in family definition

Changed in version 6.0: exceptions were renamed and are ending with “Error”.

Changed in version 7.0: All Pywikibot Error exceptions must be imported from pywikibot.exceptions. Deprecated exceptions identifiers were removed.

exception exceptions.APIError(code, info, **kwargs)[source]#

Bases: Error

The wiki site returned an error message.

Save error dict returned by MW API.

Parameters:
  • code (str) –

  • info (str) –

  • kwargs (Any) –

Return type:

None

exception exceptions.APIMWError(mediawiki_exception_class_name, info, **kwargs)[source]#

Bases: APIError

The API site returned an error about a MediaWiki internal exception.

Save error dict returned by MW API.

Parameters:
  • mediawiki_exception_class_name (str) –

  • info (str) –

  • kwargs (Any) –

Return type:

None

exception exceptions.AbuseFilterDisallowedError(page, info)[source]#

Bases: PageSaveRelatedError

Page save failed because the AbuseFilter disallowed it.

Parameters:
  • page (pywikibot.page.BasePage) –

  • info (str) –

Return type:

None

message = 'Edit to page {title} disallowed by the AbuseFilter.\n{info}'#
exception exceptions.ArgumentDeprecationWarning[source]#

Bases: UserWarning, FutureWarning

Command line argument that is no longer supported.

exception exceptions.ArticleExistsConflictError(page, message=None)[source]#

Bases: EditConflictError

Page already exists.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Destination article {} already exists and is not a redirect to the source article'#
exception exceptions.AutoblockUserError(arg)[source]#

Bases: Error

Requested action on a virtual autoblock user not valid.

The class AutoblockUserError is an exception that is raised whenever an action is requested on a virtual autoblock user that’s not available for him (i.e. roughly everything except unblock).

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.CaptchaError(arg)[source]#

Bases: Error

Captcha is asked and config.solve_captcha == False.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.CascadeLockedPageError(page, message=None)[source]#

Bases: LockedPageError

Page is locked due to cascading protection.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is locked due to cascading protection.'#
exception exceptions.CircularRedirectError(page, message=None)[source]#

Bases: PageRelatedError

Page is a circular redirect.

Exception argument is the redirect target; this may be the same title as this page or a different title (in which case the target page directly or indirectly redirects back to this one)

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is a circular redirect.'#
exception exceptions.CoordinateGlobeUnknownError(arg)[source]#

Bases: WikiBaseError, NotImplementedError

This globe is not implemented yet in either WikiBase or pywikibot.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.EditConflictError(page, message=None)[source]#

Bases: PageSaveRelatedError

There has been an edit conflict while uploading the page.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} could not be saved due to an edit conflict'#
exception exceptions.EntityTypeUnknownError(arg)[source]#

Bases: WikiBaseError

The requested entity type is not recognised on this site.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.Error(arg)[source]#

Bases: Exception

Pywikibot error.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.FamilyMaintenanceWarning[source]#

Bases: UserWarning

Family class is missing definitions.

exception exceptions.FatalServerError(arg)[source]#

Bases: ServerError

A fatal server error will not be corrected by resending the request.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.HiddenKeyError(arg)[source]#

Bases: UserRightsError, KeyError

Insufficient user rights to view the hidden key.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.InconsistentTitleError(page, actual)[source]#

Bases: PageLoadRelatedError

Page receives a title inconsistent with query.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • actual (str) – title obtained by query

Return type:

None

exception exceptions.InterwikiRedirectPageError(page, target_page)[source]#

Bases: PageRelatedError

Page is a redirect to another site.

This is considered invalid in Pywikibot. See bug T75184.

Parameters:
  • target_page (pywikibot.page.BasePage) – Target page of the redirect.

  • page (pywikibot.page.BasePage) –

Return type:

None

message = 'Page redirects to a page on another Site.\nPage: {page}\nTarget page: {target_page} on {target_site}.'#
exception exceptions.InvalidPageError(page, message=None)[source]#

Bases: PageLoadRelatedError

Missing page history.

New in version 6.2.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is invalid.'#
exception exceptions.InvalidTitleError(arg)[source]#

Bases: Error

Invalid page title.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.IsNotRedirectPageError(page, message=None)[source]#

Bases: PageRelatedError

Page is not a redirect page.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is not a redirect page.'#
exception exceptions.IsRedirectPageError(page, message=None)[source]#

Bases: PageRelatedError

Page is a redirect page.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is a redirect page.'#
exception exceptions.LockedNoPageError(page, message=None)[source]#

Bases: LockedPageError

Title is locked against creation.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} does not exist and is locked preventing creation.'#
exception exceptions.LockedPageError(page, message=None)[source]#

Bases: PageSaveRelatedError

Page is locked.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is locked.'#
exception exceptions.MaxlagTimeoutError(arg)[source]#

Bases: TimeoutError

Request failed with a maxlag timeout error.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.NoCreateError(page, message=None)[source]#

Bases: PageSaveRelatedError

Parameter nocreate doesn’t allow page creation.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} could not be created due to parameter nocreate'#
exception exceptions.NoMoveTargetError(page, message=None)[source]#

Bases: PageRelatedError

Expected move target page not found.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Move target page of {} not found.'#
exception exceptions.NoPageError(page, message=None)[source]#

Bases: PageRelatedError

Page does not exist.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = "Page {} doesn't exist."#
exception exceptions.NoUsernameError(arg)[source]#

Bases: Error

Username is not in user-config.py.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.NoWikibaseEntityError(entity)[source]#

Bases: WikiBaseError

This entity doesn’t exist.

Parameters:

entity (pywikibot.page.WikibaseEntity) – Wikibase entity

Return type:

None

exception exceptions.NotEmailableError(page, message=None)[source]#

Bases: PageRelatedError

This user is not emailable.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = '{} is not emailable.'#
exception exceptions.NotImplementedWarning[source]#

Bases: _NotImplementedWarning

Feature that is no longer implemented.

exception exceptions.OtherPageSaveError(page, reason)[source]#

Bases: PageSaveRelatedError

Saving the page has failed due to uncatchable error.

Parameters:
  • reason (Union[str, Exception]) – Details of the problem

  • page (pywikibot.page.BasePage) –

Return type:

None

property args: str#

Expose args.

message = 'Edit to page {title} failed:\n{reason}'#
exception exceptions.PageCreatedConflictError(page, message=None)[source]#

Bases: EditConflictError

Page was created by another user.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} has been created since last retrieved.'#
exception exceptions.PageDeletedConflictError(page, message=None)[source]#

Bases: EditConflictError

Page was deleted since being retrieved.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} has been deleted since last retrieved.'#
exception exceptions.PageInUseError(arg)[source]#

Bases: Error

Page cannot be reserved for writing due to existing lock.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.PageLoadRelatedError(page, message=None)[source]#

Bases: PageRelatedError

Loading the contents of a Page object has failed.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} was not loaded.'#
exception exceptions.PageRelatedError(page, message=None)[source]#

Bases: Error

Abstract Exception, used when the exception concerns a particular Page.

This class should be used when the Exception concerns a particular Page, and when a generic message can be written once for all.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = ''#
exception exceptions.PageSaveRelatedError(page, message=None)[source]#

Bases: PageRelatedError

Saving the page has failed.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} was not saved.'#
exception exceptions.SectionError(arg)[source]#

Bases: Error

The section specified by # does not exist.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.Server414Error(arg)[source]#

Bases: ServerError

Server returned with HTTP 414 code.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.Server504Error(arg)[source]#

Bases: ServerError

Server timed out with HTTP 504 code.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.ServerError(arg)[source]#

Bases: Error

Got unexpected server response.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.SiteDefinitionError(arg)[source]#

Bases: Error

Site does not exist.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.SpamblacklistError(page, url)[source]#

Bases: PageSaveRelatedError

Page save failed because MediaWiki detected a blacklisted spam URL.

Parameters:
  • page (pywikibot.page.BasePage) –

  • url (str) –

Return type:

None

message = 'Edit to page {title} rejected by spam filter due to content:\n{url}'#
exception exceptions.TimeoutError(arg)[source]#

Bases: Error

Request failed with a timeout error.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.TitleblacklistError(page, message=None)[source]#

Bases: PageSaveRelatedError

Page save failed because MediaWiki detected a blacklisted page title.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is title-blacklisted.'#
exception exceptions.TranslationError(arg)[source]#

Bases: Error, ImportError

Raised when no correct translation could be found.

Inherits from ImportError, as this exception is now used where previously an ImportError would have been raised, and may have been caught by scripts as such.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.UnknownExtensionError(arg)[source]#

Bases: Error, NotImplementedError

Extension is not defined.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.UnknownFamilyError(arg)[source]#

Bases: SiteDefinitionError

Family is not registered.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.UnknownSiteError(arg)[source]#

Bases: SiteDefinitionError

Site does not exist in Family.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.UnsupportedPageError(page, message=None)[source]#

Bases: PageRelatedError

Unsupported page due to namespace restriction.

Parameters:
  • page (pywikibot.page.BasePage) – Page that caused the exception

  • message (Optional[str]) –

Return type:

None

message = 'Page {} is not supported due to namespace restriction.'#
exception exceptions.UploadError(code, message, file_key=None, offset=0)[source]#

Bases: APIError

Upload failed with a warning message (passed as the argument).

Create a new UploadError instance.

Parameters:
  • file_key (Optional[str]) – The file_key of the uploaded file to reuse it later. If no key is known or it is an incomplete file it may be None.

  • offset (Union[int, bool]) – The starting offset for a chunked upload. Is False when there is no offset.

  • code (str) –

  • message (str) –

Return type:

None

property message: str#

Return warning message.

exception exceptions.UserRightsError(arg)[source]#

Bases: Error

Insufficient user rights to perform an action.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.VersionParseError(arg)[source]#

Bases: Error

Failed to parse version information.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

exception exceptions.WikiBaseError(arg)[source]#

Bases: Error

Wikibase related error.

Parameters:

arg (Union[Exception, str]) –

Return type:

None

family module#

Objects representing MediaWiki families.

family.AutoFamily(name, url)[source]#

Family that automatically loads the site configuration.

Parameters:
  • name (str) – Name for the family

  • url (str) – API endpoint URL of the wiki

Returns:

Generated family class

Return type:

SingleSiteFamily

class family.Family[source]#

Bases: object

Parent singleton class for all wiki families.

Allocator.

alphabetic = ['ace', 'kbd', 'ady', 'af', 'ak', 'als', 'alt', 'am', 'smn', 'ang', 'ab', 'ar', 'an', 'arc', 'roa-rup', 'frp', 'as', 'ast', 'atj', 'awa', 'gn', 'av', 'ay', 'az', 'ban', 'bm', 'bn', 'bjn', 'zh-min-nan', 'nan', 'map-bms', 'ba', 'be', 'be-tarask', 'mnw', 'bh', 'bcl', 'bi', 'bg', 'bar', 'blk', 'bo', 'bs', 'br', 'bxr', 'ca', 'cv', 'ceb', 'cs', 'ch', 'cbk-zam', 'ny', 'sn', 'tum', 'cho', 'co', 'cy', 'dag', 'da', 'dk', 'ary', 'pdc', 'de', 'dv', 'nv', 'dsb', 'dty', 'dz', 'mh', 'et', 'el', 'eml', 'en', 'myv', 'es', 'eo', 'ext', 'eu', 'ee', 'fa', 'hif', 'fo', 'fr', 'fy', 'ff', 'fur', 'ga', 'gv', 'gag', 'gd', 'gl', 'gan', 'ki', 'glk', 'guw', 'gu', 'gor', 'got', 'hak', 'xal', 'ko', 'ha', 'haw', 'hy', 'hi', 'ho', 'hsb', 'hr', 'hyw', 'io', 'ig', 'ilo', 'inh', 'bpy', 'id', 'ia', 'ie', 'iu', 'ik', 'os', 'xh', 'zu', 'is', 'it', 'he', 'jv', 'kbp', 'kl', 'kn', 'kr', 'pam', 'krc', 'ka', 'ks', 'csb', 'kk', 'kw', 'rw', 'rn', 'sw', 'kv', 'kg', 'gom', 'avk', 'ht', 'gcr', 'ku', 'kj', 'ky', 'mrj', 'lld', 'lad', 'lbe', 'lo', 'ltg', 'la', 'lv', 'lb', 'lez', 'lfn', 'lt', 'lij', 'li', 'ln', 'olo', 'jbo', 'lg', 'lmo', 'lrc', 'mad', 'hu', 'mai', 'mk', 'mg', 'ml', 'mt', 'mi', 'mr', 'xmf', 'arz', 'mzn', 'mni', 'ms', 'min', 'cdo', 'mwl', 'mdf', 'mo', 'mn', 'mus', 'my', 'nah', 'na', 'fj', 'nl', 'nds-nl', 'cr', 'ne', 'new', 'nia', 'ja', 'nqo', 'nap', 'ce', 'frr', 'pih', 'no', 'nb', 'nn', 'nrm', 'nov', 'ii', 'oc', 'mhr', 'or', 'om', 'ng', 'hz', 'uz', 'pa', 'pi', 'pfl', 'pag', 'ami', 'pnb', 'pap', 'ps', 'jam', 'koi', 'km', 'pcd', 'pms', 'pwn', 'tpi', 'nds', 'pl', 'pnt', 'pt', 'aa', 'kaa', 'crh', 'ty', 'ksh', 'ro', 'rmy', 'rm', 'qu', 'rue', 'ru', 'sah', 'szy', 'se', 'sm', 'sa', 'sg', 'sat', 'skr', 'sc', 'sco', 'trv', 'stq', 'st', 'nso', 'tn', 'sq', 'scn', 'si', 'simple', 'sd', 'ss', 'sk', 'sl', 'cu', 'szl', 'so', 'ckb', 'srn', 'sr', 'sh', 'su', 'fi', 'sv', 'shi', 'tl', 'shn', 'ta', 'kab', 'roa-tara', 'tt', 'tay', 'te', 'tet', 'th', 'ti', 'tg', 'to', 'chr', 'chy', 've', 'tcy', 'tr', 'azb', 'tk', 'tw', 'kcg', 'tyv', 'din', 'udm', 'bug', 'uk', 'ur', 'ug', 'za', 'vec', 'vep', 'vi', 'vo', 'fiu-vro', 'wa', 'zh-classical', 'vls', 'war', 'wo', 'wuu', 'ts', 'yi', 'yo', 'zh-yue', 'diq', 'zea', 'bat-smg', 'zh', 'zh-tw', 'zh-cn']#
alphabetic_revised = ['ace', 'ady', 'kbd', 'af', 'ak', 'als', 'alt', 'kcg', 'am', 'smn', 'ang', 'ab', 'ar', 'an', 'arc', 'roa-rup', 'frp', 'as', 'ast', 'atj', 'awa', 'gn', 'av', 'ay', 'az', 'bjn', 'id', 'ms', 'ban', 'bm', 'bn', 'zh-min-nan', 'nan', 'map-bms', 'jv', 'su', 'ba', 'min', 'be', 'be-tarask', 'mnw', 'mad', 'bh', 'bcl', 'bi', 'bar', 'blk', 'bo', 'bs', 'br', 'bug', 'bg', 'bxr', 'ca', 'ceb', 'cv', 'cs', 'ch', 'cbk-zam', 'ny', 'sn', 'tum', 'cho', 'co', 'cy', 'dag', 'da', 'dk', 'ary', 'pdc', 'de', 'dv', 'nv', 'dsb', 'na', 'dty', 'dz', 'mh', 'et', 'el', 'eml', 'en', 'myv', 'es', 'eo', 'ext', 'eu', 'ee', 'fa', 'hif', 'fo', 'fr', 'fy', 'ff', 'fur', 'ga', 'gv', 'sm', 'gag', 'gd', 'gl', 'gan', 'ki', 'glk', 'guw', 'gu', 'got', 'hak', 'xal', 'ko', 'ha', 'haw', 'hy', 'hi', 'ho', 'hsb', 'hr', 'hyw', 'io', 'ig', 'ilo', 'inh', 'bpy', 'ia', 'ie', 'iu', 'ik', 'os', 'xh', 'zu', 'is', 'it', 'he', 'kl', 'kn', 'kr', 'pam', 'ka', 'ks', 'csb', 'kk', 'kw', 'rw', 'ky', 'rn', 'mrj', 'sw', 'kv', 'kg', 'gom', 'avk', 'gor', 'ht', 'gcr', 'ku', 'shn', 'kj', 'lld', 'lad', 'lbe', 'lez', 'lfn', 'lo', 'la', 'ltg', 'lv', 'to', 'lb', 'lt', 'lij', 'li', 'ln', 'nia', 'olo', 'jbo', 'lg', 'lmo', 'lrc', 'hu', 'mai', 'mk', 'mg', 'ml', 'krc', 'mt', 'mi', 'mr', 'xmf', 'arz', 'mzn', 'mni', 'cdo', 'mwl', 'koi', 'mdf', 'mo', 'mn', 'mus', 'my', 'nah', 'fj', 'nl', 'nds-nl', 'cr', 'ne', 'new', 'ja', 'nqo', 'nap', 'ce', 'frr', 'pih', 'no', 'nb', 'nn', 'nrm', 'nov', 'ii', 'oc', 'mhr', 'or', 'om', 'ng', 'hz', 'uz', 'pa', 'pi', 'pfl', 'pag', 'ami', 'pnb', 'pap', 'ps', 'jam', 'km', 'pcd', 'pms', 'pwn', 'nds', 'pl', 'pnt', 'pt', 'aa', 'kaa', 'crh', 'ty', 'ksh', 'ro', 'rmy', 'rm', 'qu', 'ru', 'rue', 'sah', 'szy', 'se', 'sa', 'sg', 'sat', 'skr', 'sc', 'sco', 'trv', 'stq', 'st', 'nso', 'tn', 'sq', 'scn', 'si', 'simple', 'sd', 'ss', 'sk', 'sl', 'cu', 'szl', 'so', 'ckb', 'srn', 'sr', 'sh', 'fi', 'sv', 'shi', 'tl', 'ta', 'kab', 'kbp', 'roa-tara', 'tt', 'tay', 'te', 'tet', 'th', 'vi', 'ti', 'tg', 'tpi', 'chr', 'chy', 've', 'tcy', 'tr', 'azb', 'tk', 'tw', 'tyv', 'din', 'udm', 'uk', 'ur', 'ug', 'za', 'vec', 'vep', 'vo', 'fiu-vro', 'wa', 'zh-classical', 'vls', 'war', 'wo', 'wuu', 'ts', 'yi', 'yo', 'zh-yue', 'diq', 'zea', 'bat-smg', 'zh', 'zh-tw', 'zh-cn']#
apipath(code)[source]#

Return path to api.php.

Return type:

str

archived_page_templates = {}#
base_url(code, uri, protocol=None)[source]#

Prefix uri with port and hostname.

Parameters:
  • code (str) – The site code

  • uri (str) – The absolute path after the hostname

  • protocol – The protocol which is used. If None it’ll determine the protocol from the code.

Returns:

The full URL ending with uri

Return type:

str

categories_last = []#
category_attop = []#
category_on_one_line = []#
category_redirect_templates = {'_default': []}#
category_redirects(code, fallback='_default')[source]#

Return list of category redirect templates.

Parameters:

fallback (str) –

category_text_separator = '\n\n'#
codes = {}#
cross_allowed = []#
cross_projects = []#
cross_projects_cookies = ['centralauth_Session', 'centralauth_Token', 'centralauth_User']#
crossnamespace = {}#
dbName(code)[source]#

Return the name of the MySQL database.

Return type:

str

disambcatname = {}#
disambig(code, fallback='_default')[source]#

Return list of disambiguation templates.

Parameters:

fallback (str) –

disambiguationTemplates = {'_default': []}#
domains = {}#
edit_restricted_templates = {}#
encoding(code)[source]#

Return the encoding for a specific language wiki.

Return type:

str

encodings(code)[source]#

Return list of historical encodings for a specific language wiki.

eventstreams_host(code)[source]#

Hostname for EventStreams.

New in version 3.0.

eventstreams_path(code)[source]#

Return path for EventStreams.

New in version 3.0.

from_url(url)[source]#

Return whether this family matches the given url.

It is first checking if a domain of this family is in the domain of the URL. If that is the case it’s checking all codes and verifies that a path generated via APISite.articlepath and Family.path matches the path of the URL together with the hostname for that code.

It is using Family.domains to first check if a domain applies and then iterates over Family.codes to actually determine which code applies.

Parameters:

url (str) – the URL which may contain a $1. If it’s missing it is assumed to be at the end.

Returns:

The language code of the url. None if that url is not from this family.

Raises:

RuntimeError – When there are multiple languages in this family which would work with the given URL.

Return type:

Optional[str]

fyinterwiki = ['aa', 'ab', 'ace', 'ady', 'af', 'ay', 'ak', 'als', 'alt', 'am', 'ami', 'an', 'ang', 'ar', 'arc', 'ary', 'arz', 'as', 'ast', 'atj', 'av', 'avk', 'awa', 'az', 'azb', 'ba', 'ban', 'bar', 'bat-smg', 'bcl', 'be', 'be-tarask', 'bg', 'bh', 'bi', 'bjn', 'blk', 'bm', 'bn', 'bo', 'bpy', 'br', 'bs', 'bug', 'bxr', 'ca', 'cbk-zam', 'cdo', 'ce', 'ceb', 'ch', 'chy', 'cho', 'chr', 'cy', 'ckb', 'co', 'cr', 'crh', 'cs', 'csb', 'cu', 'cv', 'da', 'dag', 'de', 'din', 'diq', 'dk', 'dsb', 'dty', 'dv', 'dz', 'ee', 'el', 'eml', 'en', 'eo', 'es', 'et', 'eu', 'ext', 'fa', 'ff', 'fi', 'fy', 'fiu-vro', 'fj', 'fo', 'fr', 'frp', 'frr', 'fur', 'ga', 'gag', 'gan', 'gcr', 'gd', 'gl', 'glk', 'gn', 'gom', 'gor', 'got', 'gu', 'guw', 'gv', 'ha', 'hak', 'haw', 'he', 'hi', 'hy', 'hif', 'hyw', 'ho', 'hr', 'hsb', 'ht', 'hu', 'hz', 'ia', 'id', 'ie', 'ig', 'ii', 'yi', 'ik', 'ilo', 'inh', 'io', 'yo', 'is', 'it', 'iu', 'ja', 'jam', 'jbo', 'jv', 'ka', 'kaa', 'kab', 'kbd', 'kbp', 'kcg', 'kg', 'ki', 'ky', 'kj', 'kk', 'kl', 'km', 'kn', 'ko', 'koi', 'kr', 'krc', 'ks', 'ksh', 'ku', 'kv', 'kw', 'la', 'lad', 'lb', 'lbe', 'lez', 'lfn', 'lg', 'li', 'lij', 'lld', 'lmo', 'ln', 'lo', 'lrc', 'lt', 'ltg', 'lv', 'mad', 'mai', 'map-bms', 'mdf', 'mg', 'mh', 'mhr', 'mi', 'my', 'min', 'myv', 'mk', 'ml', 'mn', 'mni', 'mnw', 'mo', 'mr', 'mrj', 'ms', 'mt', 'mus', 'mwl', 'mzn', 'na', 'nah', 'nan', 'nap', 'nds', 'nds-nl', 'ne', 'new', 'ng', 'ny', 'nia', 'nl',