pywikibot
— Base Classes and Functions#
The initialization file for the Pywikibot framework.
Imports from bot
module
The following classes and functions are inported from bot
module
but can also be used as pywikibot
members:
Imports from i18n
module
The following function is inported from i18n
module but can also be
used as pywikibot
members:
Imports from logging
module
The following functions are inported from logging
module but can
also be used as pywikibot
members:
Imports from page
module
The following classes and function are inported from page
module
but can also be used as pywikibot
members:
Imports from time
module
The following class is inported from time
module
but can also be used as pywikibot
members:
- class pywikibot.Bot(site=None, **kwargs)[source]#
Bases:
BaseBot
Generic bot subclass for multiple sites.
If possible the MultipleSitesBot or SingleSiteBot classes should be used instead which specifically handle multiple or single sites.
Create a Bot instance and initialize cached sites.
- Parameters:
site (BaseSite | None)
kwargs (Any)
- class pywikibot.Category(source, title='', sort_key=None)[source]#
Bases:
Page
A page in the Category: namespace.
All parameters are the same as for Page() Initializer.
- Parameters:
title (str)
- articles(*, recurse=False, total=None, **kwargs)[source]#
Yield all articles in the current category.
Yields all pages in the category that are not subcategories. Duplicates are filtered. To enable duplicates use
members()
withmember_type=['page', 'file']
instead.Usage:
>>> site = pywikibot.Site('wikipedia:test') >>> cat = pywikibot.Category(site, 'Pywikibot') >>> list(cat.articles()) [Page('Pywikibot nobots test')] >>> for p in cat.articles(recurse=1, namespaces=2, total=3): ... print(p.depth) ... 2 3 4
Warning
Categories may have infinite recursions of subcategories. If
recurse
option is given asTrue
or anint
value and this value is less thansys.getrecursionlimit()
, anRecursionError
may be raised. Be careful if passing this generator to a collection in such case.Changed in version 8.0: all parameters are keyword arguments only.
- Parameters:
recurse (int | bool) – if not False or 0, also iterate articles in subcategories. If an int, limit recursion to this number of levels. (Example:
recurse=1
will iterate articles in first-level subcats, but no deeper.)total (int | None) – iterate no more than this number of pages in total (at all levels)
kwargs (Any) – Additional parameters. Refer to
APISite.categorymembers()
for complete list (member_type excluded).
- Return type:
Generator[Page, None, None]
- aslink(sort_key=None)[source]#
Return a link to place a page in this Category.
Warning
Use this only to generate a “true” category link, not for interwikis or text links to category pages.
Usage:
>>> site = pywikibot.Site('wikipedia:test') >>> cat = pywikibot.Category(site, 'Foo') >>> cat.aslink() '[[Category:Foo]]' >>> cat = pywikibot.Category(site, 'Foo', sort_key='bar') >>> cat.aslink() '[[Category:Foo|bar]]' >>> cat.aslink('baz') '[[Category:Foo|baz]]'
- Parameters:
sort_key (str | None) – The sort key for the article to be placed in this Category; if omitted, default sort key is used.
- Return type:
str
- property categoryinfo: dict[str, Any]#
Return a dict containing information about the category.
The dict contains values for numbers of pages, subcategories, files, and total contents.
See also
- isEmptyCategory()[source]#
Return True if category has no members (including subcategories).
- Return type:
bool
- members(*, recurse=False, total=None, **kwargs)[source]#
Yield all category contents (subcats, pages, and files).
Usage:
>>> site = pywikibot.Site('wikipedia:test') >>> cat = pywikibot.Category(site, 'Pywikibot') >>> list(cat.members(member_type='subcat')) [Category('Category:Subpage testing')] >>> list(cat.members(member_type=['page', 'file'])) [Page('Pywikibot nobots test')]
Calling this method with
member_type='subcat'
is equal to callingsubcategories()
. Calling this method withmember_type=['page', 'file']
is equal to callingarticles()
except that the later will filter duplicates.See also
Warning
Categories may have infinite recursions of subcategories. If
recurse
option is given asTrue
or anint
value and this value is less thansys.getrecursionlimit()
, anRecursionError
may be raised. Be careful if passing this generator to a collection in such case.Changed in version 8.0: all parameters are keyword arguments only. Additional parameters are supported.
- Parameters:
recurse (bool) – if not False or 0, also iterate articles in subcategories. If an int, limit recursion to this number of levels. (Example:
recurse=1
will iterate articles in first-level subcats, but no deeper.)total (int | None) – iterate no more than this number of pages in total (at all levels)
kwargs (Any) – Additional parameters. Refer to
APISite.categorymembers()
for complete list.
- Return type:
Generator[Page, None, None]
- newest_pages(total=None)[source]#
Return pages in a category ordered by the creation date.
If two or more pages are created at the same time, the pages are returned in the order they were added to the category. The most recently added page is returned first.
It only allows to return the pages ordered from newest to oldest, as it is impossible to determine the oldest page in a category without checking all pages. But it is possible to check the category in order with the newly added first and it yields all pages which were created after the currently checked page was added (and thus there is no page created after any of the cached but added before the currently checked).
- Parameters:
total (int | None) – The total number of pages queried.
- Returns:
A page generator of all pages in a category ordered by the creation date. From newest to oldest.
Note
It currently only returns Page instances and not a subclass of it if possible. This might change so don’t expect to only get Page instances.
- Return type:
Generator[Page, None, None]
- subcategories(*, recurse=False, **kwargs)[source]#
Yield all subcategories of the current category.
Usage:
>>> site = pywikibot.Site('wikipedia:en') >>> cat = pywikibot.Category(site, 'Contents') >>> next(cat.subcategories()) Category('Category:Wikipedia administration') >>> len(list(cat.subcategories(recurse=2, total=50))) 50
Subcategories of the same level of each subtree are yielded first before the next subcategories level are yielded. For example having this category tree:
A +-- B | +-- E | | +-- H | +-- F | +-- G +-- C | +-- I | | +-- E | | +-- H | +-- J | +-- K | +-- L | +-- G +-- D
Subcategories are yields in the following order: B, C, D, E, F, G, H, I, J, E, H, K, L, G
See also
Warning
Categories may have infinite recursions of subcategories. If
recurse
option is given asTrue
or anint
value and this value is less thansys.getrecursionlimit()
, anRecursionError
may be raised. Be careful if passing this generator to a collection in such case.Changed in version 8.0: all parameters are keyword arguments only. Additional parameters are supported. The order of subcategories are yielded was changed. The old order was B, E, H, F, G, C, I, E, H, J, K, L, G, D
- Parameters:
recurse (int | bool) – if not False or 0, also iterate articles in subcategories. If an int, limit recursion to this number of levels. (Example:
recurse=1
will iterate articles in first-level subcats, but no deeper.)kwargs (Any) – Additional parameters. Refer to
APISite.categorymembers()
for complete list (member_type excluded).
- Return type:
Generator[Page, None, None]
- class pywikibot.Claim(site, pid, snak=None, hash=None, is_reference=False, is_qualifier=False, rank='normal', **kwargs)[source]#
Bases:
Property
A Claim on a Wikibase entity.
Claims are standard claims as well as references and qualifiers.
Defined by the “snak” value, supplemented by site + pid
- Parameters:
site (pywikibot.site.DataSite) – Repository where the property of the claim is defined. Note that this does not have to correspond to the repository where the claim has been stored.
pid – property id, with “P” prefix
snak – snak identifier for claim
hash – hash identifier for references
is_reference (bool) – whether specified claim is a reference
is_qualifier (bool) – whether specified claim is a qualifier
rank (str) – rank for claim
- SNAK_TYPES = ('value', 'somevalue', 'novalue')#
- TARGET_CONVERTER = {'commonsMedia': <function Claim.<lambda>>, 'geo-shape': <bound method WbDataPage.fromWikibase of <class 'pywikibot._wbtypes.WbGeoShape'>>, 'globe-coordinate': <bound method Coordinate.fromWikibase of <class 'pywikibot._wbtypes.Coordinate'>>, 'monolingualtext': <function Claim.<lambda>>, 'quantity': <bound method WbQuantity.fromWikibase of <class 'pywikibot._wbtypes.WbQuantity'>>, 'tabular-data': <bound method WbDataPage.fromWikibase of <class 'pywikibot._wbtypes.WbTabularData'>>, 'time': <bound method WbTime.fromWikibase of <class 'pywikibot._wbtypes.WbTime'>>, 'wikibase-form': <function Claim.<lambda>>, 'wikibase-item': <function Claim.<lambda>>, 'wikibase-lexeme': <function Claim.<lambda>>, 'wikibase-property': <function Claim.<lambda>>, 'wikibase-sense': <function Claim.<lambda>>}#
- addQualifier(qualifier, **kwargs)[source]#
Add the given qualifier.
- Parameters:
qualifier (pywikibot.page.Claim) – the qualifier to add
- addSource(claim, **kwargs)[source]#
Add the claim as a source.
- Parameters:
claim (Claim) – the claim to add
- Return type:
None
- addSources(claims, **kwargs)[source]#
Add the claims as one source.
- Parameters:
claims (list of Claim) – the claims to add
- 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
- classmethod fromJSON(site, data)[source]#
Create a claim object from JSON returned in the API call.
Changed in version 9.4: print a warning if the Claim.type is not given and missing in the wikibase.
- Parameters:
data (dict[str, Any]) – JSON containing claim data
- Return type:
- getSnakType()[source]#
Return the type of snak.
- Returns:
str (‘value’, ‘somevalue’ or ‘novalue’)
- Return type:
str
- getTarget()[source]#
Return the target value of this Claim.
None is returned if no target is set
- Returns:
object
- has_qualifier(qualifier_id, target)[source]#
Check whether Claim contains specified qualifier.
- Parameters:
qualifier_id (str) – id of the qualifier
target – qualifier target to check presence of
- Returns:
true if the qualifier was found, false otherwise
- Return type:
bool
- property on_item: WikibaseEntity | None#
Return entity this claim is attached to.
- classmethod qualifierFromJSON(site, data)[source]#
Create a Claim for a qualifier from JSON.
Qualifier objects are represented a bit differently like references, but I’m not sure if this even requires it’s own function.
- Return type:
pywikibot.page.Claim
- classmethod referenceFromJSON(site, data)[source]#
Create a dict of claims from reference JSON 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 of Claim) – the qualifiers to remove
- Return type:
None
- removeSource(source, **kwargs)[source]#
Remove the source. Call removeSources().
- Parameters:
source (Claim) – the source to remove
- Return type:
None
- removeSources(sources, **kwargs)[source]#
Remove the sources.
- Parameters:
sources (list of Claim) – the sources to remove
- Return type:
None
- same_as(other, ignore_rank=True, ignore_quals=False, ignore_refs=True)[source]#
Check if two claims are same.
- Parameters:
ignore_rank (bool)
ignore_quals (bool)
ignore_refs (bool)
- Return type:
bool
- 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
- class pywikibot.Coordinate(lat, lon, alt=None, precision=None, globe=None, typ='', name='', dim=None, site=None, globe_item=None, primary=False)[source]#
Bases:
WbRepresentation
Class for handling and storing Coordinates.
Represent a geo coordinate.
- Parameters:
lat (float) – Latitude
lon (float) – Longitude
alt (float | None) – Altitude
precision (float | None) – precision
globe (str | None) – Which globe the point is on
typ (str) – The type of coordinate point
name (str) – The name
dim (int | None) – Dimension (in meters)
site (DataSite | None) – The Wikibase site
globe_item (ItemPageStrNoneType) – The Wikibase item for the globe, or the entity URI of this Wikibase item. Takes precedence over ‘globe’ if present.
primary (bool) – True for a primary set of coordinates
- property entity: str#
Return the entity uri of the globe.
- classmethod fromWikibase(data, site=None)[source]#
Constructor to create an object from Wikibase’s JSON output.
- Parameters:
data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site
- Return type:
- 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.
- property precision: float | None#
Return the precision of the geo coordinate.
The precision is calculated if the Coordinate does not have a precision, and self._dim is set.
When no precision and no self._dim exists, None is returned.
The biggest error (in degrees) will be given by the longitudinal error; the same error in meters becomes larger (in degrees) further up north. We can thus ignore the latitudinal error.
The longitudinal can be derived as follows:
In small angle approximation (and thus in radians):
\(M{Δλ ≈ Δpos / r_φ}\), where \(r_φ\) is the radius of earth at the given latitude. \(Δλ\) is the error in longitude.
\(M{r_φ = r cos(φ)}\), where \(r\) is the radius of earth, \(φ\) the latitude
Therefore:
precision = math.degrees( self._dim / (radius * math.cos(math.radians(self.lat))))
- precisionToDim()[source]#
Convert precision from Wikibase to GeoData’s dim 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:
int | None
- 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 byrun()
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 (bool | None) – Ignore save related errors and automatically print a message. If None uses this instances default.
ignore_server_errors (bool | None) – Ignore server errors and automatically print a message. If None uses this instances default.
kwargs (Any) – Additional parameters directly given to
Bot.userPut
.
- Returns:
whether the page was saved successfully
- Return type:
bool
- class pywikibot.FilePage(source, title='', *, ignore_extension=False)[source]#
Bases:
Page
A subclass of Page representing a file description page.
Supports the same interface as Page except ns; some added methods.
Changed in version 8.4: check for valid extensions.
Changed in version 9.3: ignore_extension parameter was added
- Parameters:
source (pywikibot.page.BaseLink (or subclass), pywikibot.page.Page (or subclass), or pywikibot.page.Site) – the source of the page
title (str) – normalized title of the page; required if source is a Site, ignored otherwise
ignore_extension (bool) – prevent extension check
- Raises:
ValueError – Either the title is not in the file namespace or does not have a valid extension and ignore_extension was not set.
- data_item()[source]#
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 the behavior of
BasePage.data_item()
.Added in version 6.5.
- Return type:
pywikibot.page.WikibaseEntity
- download(filename=None, chunk_size=102400, revision=None, *, url_width=None, url_height=None, url_param=None)[source]#
Download to filename file of FilePage.
Usage examples:
Download an image:
>>> site = pywikibot.Site('wikipedia:test') >>> file = pywikibot.FilePage(site, 'Pywikibot MW gear icon.svg') >>> file.download() True
Pywikibot_MW_gear_icon.svg was downloaded.
Download a thumnail:
>>> file.download(url_param='120px') True
The suffix has changed and Pywikibot_MW_gear_icon.png was downloaded.
Added in version 8.2: url_width, url_height and url_param parameters.
Changed in version 8.2: filename argument may be also a path-like object or an iterable of path segments.
Note
filename suffix is adjusted if target url’s suffix is different which may be the case if a thumbnail is loaded.
Warning
If a file already exists, it will be overridden without further notes.
See also
API:Imageinfo for new parameters
- Parameters:
filename (str | PathLike | Iterable[str] | None) – filename where to save file. If
None
,self.title(as_filename=True, with_ns=False)
will be used. If an Iterable is specified the items will be used as path segments. To specify the user directory path you have to use either~
or~user
as first path segment e.g.~/foo
or('~', 'foo')
as filename. If only the user directory specifier is given, the title is used as filename like for None. If the suffix is missing or different from url (which can happen if a url_width, url_height or url_param argument is given), the file suffix is adjusted.chunk_size (int) – the size of each chunk to be received and written to file.
revision (FileInfo | None) – file revision to download. If None
latest_file_info
will be used; otherwise provided revision will be used.url_width (int | None) – download thumbnail with given width
url_height (int | None) – download thumbnail with given height
url_param (str | None) – download thumbnail with given param
- Returns:
True if download is successful, False otherwise.
- Raises:
IOError – if filename cannot be written for any reason.
- Return type:
bool
Check if the file is stored on any known shared repository.
Changed in version 7.0: return False if file does not exist on shared image repository instead raising NoPageError.
- Return type:
bool
- property file_is_used: bool#
Check whether the file is used at this site.
Added in version 7.1.
- getFileVersionHistoryTable()[source]#
Return the version history in the form of a wiki table.
- Return type:
str
- getImagePageHtml()[source]#
Download the file page, and return the HTML, as a string.
Caches the HTML code, so that if you run this method twice on the same FilePage object, the page will only be downloaded once.
- Return type:
str
- get_file_history()[source]#
Return the file’s version history.
- Returns:
dictionary with: key: timestamp of the entry value: instance of FileInfo()
- Return type:
dict
- get_file_info(ts)[source]#
Retrieve and store information of a specific Image rev. of FilePage.
This function will load also metadata. It is also used as a helper in FileInfo to load metadata lazily.
Added in version 8.6.
- Parameters:
ts – timestamp of the Image rev. to retrieve
- Returns:
instance of FileInfo()
- Return type:
dict
- get_file_url(url_width=None, url_height=None, url_param=None)[source]#
Return the url or the thumburl of the file described on this page.
Fetch the information if not available.
Once retrieved, file information will also be accessible as
latest_file_info
attributes, named as in API:Imageinfo. If url_width, url_height or url_param is given, additional propertiesthumbwidth
,thumbheight
,thumburl
andresponsiveUrls
are provided.Note
Parameters validation and error handling left to the API call.
See also
- Parameters:
url_width (int | None) – get info for a thumbnail with given width
url_height (int | None) – get info for a thumbnail with given height
url_param (str | None) – get info for a thumbnail with given param
- Returns:
latest file url or thumburl
- Return type:
str
- globalusage(total=None)[source]#
Iterate all global usage for this page.
See also
- 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: 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) 2 >>> used[0].title() 'Pywikibot'
See also
Changed in version 7.2: all parameters from
APISite.imageusage()
are available.Changed in version 7.4: renamed from
usingPages()
.
- class pywikibot.ItemPage(site, title=None, ns=None)[source]#
Bases:
WikibasePage
Wikibase entity of type ‘item’.
A Wikibase item may be defined by either a ‘Q’ id (qid), or by a site & title.
If an item is defined by site & title, once an item’s qid has been looked up, the item is then defined by the qid.
- Parameters:
site (pywikibot.site.DataSite) – data repository
title (str) – identifier of item, “Q###”, -1 or None for an empty item.
- DATA_ATTRIBUTES: dict[str, Any] = {'aliases': <class 'pywikibot.page._collections.AliasesDict'>, 'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'descriptions': <class 'pywikibot.page._collections.LanguageDict'>, 'labels': <class 'pywikibot.page._collections.LanguageDict'>, 'sitelinks': <class 'pywikibot.page._collections.SiteLinkCollection'>}#
- entity_type = 'item'#
- classmethod fromPage(page, lazy_load=False)[source]#
Get the ItemPage for a Page that links to it.
- Parameters:
page (pywikibot.page.Page) – Page to look for corresponding data item
lazy_load (bool) – Do not raise NoPageError if either page or corresponding ItemPage does not exist.
- Return type:
pywikibot.page.ItemPage
- Raises:
pywikibot.exceptions.NoPageError – There is no corresponding ItemPage for the page
pywikibot.exceptions.WikiBaseError – The site of the page has no data repository.
- classmethod from_entity_uri(site, uri, lazy_load=False)[source]#
Get the ItemPage from its entity uri.
- Parameters:
site (pywikibot.site.DataSite) – The Wikibase site for the item.
uri (str) – Entity uri for the Wikibase item.
lazy_load (bool) – Do not raise NoPageError if ItemPage does not exist.
- Return type:
pywikibot.page.ItemPage
- Raises:
TypeError – Site is not a valid DataSite.
ValueError – Site does not match the base of the provided uri.
pywikibot.exceptions.NoPageError – Uri points to non-existent item.
- get(force=False, get_redirect=False, *args, **kwargs)[source]#
Fetch all item data, and cache it.
- Parameters:
force (bool) – override caching
get_redirect (bool) – return the item content, do not follow the redirect, do not raise an exception.
- Raises:
NotImplementedError – a value in args or kwargs
IsRedirectPageError – instance is a redirect page and get_redirect is not True
- Returns:
actual data which entity holds
- Return type:
dict[str, Any]
Note
dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content
- getID(numeric=False, force=False)[source]#
Get the entity identifier.
- Parameters:
numeric (bool) – Strip the first letter and return an int
force (bool) – Force an update of new data
- getRedirectTarget(*, ignore_section=True)[source]#
Return the redirect target for this page.
Added in version 9.3: ignore_section parameter
See also
- Parameters:
ignore_section (bool) – do not include section to the target even the link has one
- Raises:
CircularRedirectError – page is a circular redirect
InterwikiRedirectPageError – the redirect target is on another site
Error – target page has wrong content model
IsNotRedirectPageError – page is not a redirect
RuntimeError – no redirects found
SectionError – the section is not found on target page and ignore_section is not set
- getSitelink(site, force=False)[source]#
Return the title for the specific site.
If the item doesn’t have a link to that site, raise NoSiteLinkError.
Changed in version 8.1: raises NoSiteLinkError instead of NoPageError.
- Parameters:
site (pywikibot.Site or database name) – Site to find the linked page of.
force (bool) – override caching
get_redirect – return the item content, do not follow the redirect, do not raise an exception.
- Raises:
IsRedirectPageError – instance is a redirect page
NoSiteLinkError – site is not in
sitelinks
- Return type:
str
- iterlinks(family=None)[source]#
Iterate through all the sitelinks.
- Parameters:
family (str|pywikibot.family.Family) – string/Family object which represents what family of links to iterate
- Returns:
iterator of pywikibot.Page objects
- Return type:
iterator
- mergeInto(item, **kwargs)[source]#
Merge the item into another item.
- Parameters:
item (pywikibot.page.ItemPage) – The item to merge into
- Return type:
None
- removeSitelink(site, **kwargs)[source]#
Remove a sitelink.
A site can either be a Site object, or it can be a dbName.
- Parameters:
site (LANGUAGE_IDENTIFIER)
- Return type:
None
- removeSitelinks(sites, **kwargs)[source]#
Remove sitelinks.
Sites should be a list, with values either being Site objects, or dbNames.
- Parameters:
sites (list[LANGUAGE_IDENTIFIER])
- Return type:
None
- setSitelink(sitelink, **kwargs)[source]#
Set sitelinks. Calls
setSitelinks()
.A sitelink can be a Page object, a BaseLink object or a
{'site': dbname, 'title': title}
dictionary.Refer
WikibasePage.editEntity()
for asynchronous and callback usage.- Parameters:
sitelink (SITELINK_TYPE)
- Return type:
None
- setSitelinks(sitelinks, **kwargs)[source]#
Set sitelinks.
sitelinks should be a list. Each item in the list can either be a Page object, a BaseLink object, or a dict with key for ‘site’ and a value for ‘title’.
Refer
editEntity()
for asynchronous and callback usage.- Parameters:
sitelinks (list[SITELINK_TYPE])
- Return type:
None
- set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, botflag='[deprecated name of bot]', **kwargs)[source]#
Make the item redirect to another item.
You need to define an extra argument to make this work, like
save=True
.Changed in version 9.3: botflag keyword parameter was renamed to bot.
- Parameters:
target_page (ItemPage | str) – target of the redirect, this argument is required.
force (bool) – if true, it sets the redirect target even the page is not redirect.
create (bool)
keep_section (bool)
save (bool)
- title(**kwargs)[source]#
Return ID as title of the ItemPage.
If the ItemPage was lazy-loaded via ItemPage.fromPage, this method will fetch the Wikibase item ID for the page, potentially raising NoPageError with the page on the linked wiki if it does not exist, or does not have a corresponding Wikibase item ID.
This method also refreshes the title if the id property was set. i.e. item.id = ‘Q60’
All optional keyword parameters are passed to the superclass.
- title_pattern = 'Q[1-9]\\d*'#
- class pywikibot.LexemeForm(repo, id_=None)[source]#
Bases:
LexemeSubEntity
Wikibase lexeme form.
- DATA_ATTRIBUTES: dict[str, Any] = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'representations': <class 'pywikibot.page._collections.LanguageDict'>}#
- edit_elements(data, **kwargs)[source]#
Update form elements.
- Parameters:
data (dict) – Data to be saved
- Return type:
None
- entity_type = 'form'#
- get(force=False)[source]#
Fetch all form data, and cache it.
- Parameters:
force (bool) – override caching
- Return type:
dict
Note
dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content
- title_pattern = 'L[1-9]\\d*-F[1-9]\\d*'#
- class pywikibot.LexemePage(site, title=None)[source]#
Bases:
WikibasePage
Wikibase entity of type ‘lexeme’.
Basic usage sample:
>>> import pywikibot >>> repo = pywikibot.Site('wikidata') >>> L2 = pywikibot.LexemePage(repo, 'L2') # create a Lexeme page >>> list(L2.claims) # access the claims ['P5402', 'P5831', 'P12690'] >>> len(L2.forms) # access the forms 3 >>> F1 = L2.forms[0] # access the first form >>> list(F1.claims) # access its claims ['P898'] >>> len(L2.senses) # access the senses 2 >>> S1 = L2.senses[0] # access the first sense >>> list(S1.claims) # and its claims ['P5137', 'P5972', 'P2888']
- Parameters:
site (pywikibot.site.DataSite) – data repository
title (str or None) – identifier of lexeme, “L###”, -1 or None for an empty lexeme.
- DATA_ATTRIBUTES: dict[str, Any] = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'forms': <class 'pywikibot.page._wikibase.LexemeFormCollection'>, 'lemmas': <class 'pywikibot.page._collections.LanguageDict'>, 'senses': <class 'pywikibot.page._wikibase.LexemeSenseCollection'>}#
- add_form(form, **kwargs)[source]#
Add a form to the lexeme.
- Parameters:
form (Form) – The form to add
- Keyword Arguments:
bot – Whether to flag as bot (if possible)
asynchronous – if True, launch a separate thread to add form asynchronously
callback – a callable object that will be called after the claim has been added. It must take two arguments: (1) a LexemePage object, and (2) an exception instance, which will be None if the entity was saved successfully. This is intended for use by bots that need to keep track of which saves were successful.
- Return type:
None
- entity_type = 'lexeme'#
- get(force=False, get_redirect=False, *args, **kwargs)[source]#
Fetch all lexeme data, and cache it.
- Parameters:
force (bool) – override caching
get_redirect (bool) – return the lexeme content, do not follow the redirect, do not raise an exception.
- Raises:
NotImplementedError – a value in args or kwargs
Note
dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content
- 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*'#
- class pywikibot.LexemeSense(repo, id_=None)[source]#
Bases:
LexemeSubEntity
Wikibase lexeme sense.
- DATA_ATTRIBUTES: dict[str, Any] = {'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'glosses': <class 'pywikibot.page._collections.LanguageDict'>}#
- entity_type = 'sense'#
- title_pattern = 'L[1-9]\\d*-S[1-9]\\d*'#
- class pywikibot.Link(text, source=None, default_namespace=0)[source]#
Bases:
BaseLink
A MediaWiki wikitext link (local or interwiki).
Constructs a Link object based on a wikitext link and a source site.
Extends BaseLink by the following attributes:
section: The section of the page linked to (str or None); this contains any text following a ‘#’ character in the title
anchor: The anchor text (str or None); this contains any text following a ‘|’ character inside the link
- Parameters:
text (str) – the link text (everything appearing between [[ and ]] on a wiki page)
source (Site or BasePage) – the Site on which the link was found (not necessarily the site to which the link refers)
default_namespace (int) – a namespace to use if the link does not contain one (defaults to 0)
- Raises:
UnicodeError – text could not be converted to unicode.
- property anchor: str#
Return the anchor of the link.
- astext(onsite=None)[source]#
Return a text representation of the link.
- Parameters:
onsite – if specified, present as a (possibly interwiki) link from the given site; otherwise, present as an internal link on the source site.
- classmethod create_separated(link, source, default_namespace=0, section=None, label=None)[source]#
Create a new instance but overwrite section or label.
The returned Link instance is already parsed.
- Parameters:
link (str) – The original link text.
source (Site) – The source of the link.
default_namespace (int) – The namespace this link uses when no namespace is defined in the link text.
section (None or str) – The new section replacing the one in link. If None (default) it doesn’t replace it.
label – The new label replacing the one in link. If None (default) it doesn’t replace it.
- classmethod fromPage(page, source=None)[source]#
Create a Link to a Page.
- Parameters:
page (pywikibot.page.Page) – target Page
source – Link from site source
source – Site
- Return type:
pywikibot.page.Link
- illegal_titles_pattern = re.compile('[\\x00-\\x1f\\x23\\x3c\\x3e\\x5b\\x5d\\x7b\\x7c\\x7d\\x7f]|%[0-9A-Fa-f]{2}|&[A-Za-z0-9\x80-ÿ]+;|&#[0-9]+;|&#x[0-9A-Fa-f]+;')#
- classmethod langlinkUnsafe(lang, title, source)[source]#
Create a “lang:title” Link linked from source.
Assumes that the lang & title come clean, no checks are made.
- Parameters:
lang (str) – target site code (language)
title (str) – target Page
source – Link from site source
source – Site
- Return type:
pywikibot.page.Link
- property namespace#
Return the namespace of the link.
- Return type:
pywikibot.Namespace
- parse_site()[source]#
Parse only enough text to determine which site the link points to.
This method does not parse anything after the first “:”; links with multiple interwiki prefixes (such as “wikt:fr:Parlais”) need to be re-parsed on the first linked wiki to get the actual site.
- Returns:
The family name and site code for the linked site. If the site is not supported by the configured families it returns None instead of a str.
- Return type:
tuple
- property section: str#
Return the section of the link.
- property site#
Return the site of the link.
- Return type:
pywikibot.Site
- property title: str#
Return the title of the link.
- class pywikibot.MediaInfo(repo, id_=None)[source]#
Bases:
WikibaseEntity
Interface for MediaInfo entities on Commons.
Added in version 6.5.
- Parameters:
repo (DataSite) – Entity repository.
id (str or None, -1 and None mean non-existing) – Entity identifier.
id_ (str | None)
- DATA_ATTRIBUTES: dict[str, Any] = {'labels': <class 'pywikibot.page._collections.LanguageDict'>, 'statements': <class 'pywikibot.page._collections.ClaimCollection'>}#
- addClaim(claim, bot=True, **kwargs)[source]#
Add a claim to the MediaInfo.
Added in version 8.5.
- Parameters:
claim (pywikibot.page.Claim) – The claim to add
bot (bool) – Whether to flag as bot (if possible)
- editLabels(labels, **kwargs)[source]#
Edit MediaInfo labels (eg. captions).
labels should be a dict, with the key as a language or a site object. The value should be the string to set it to. You can set it to
''
to remove the label.Usage:
>>> repo = pywikibot.Site('commons','commons') >>> page = pywikibot.FilePage(repo, 'File:Sandbox-Test.svg') >>> item = page.data_item() >>> item.editLabels({'en': 'Test file.'})
Added in version 8.5.
- Parameters:
labels (LANGUAGE_TYPE)
- Return type:
None
- entity_type = 'mediainfo'#
- get(force=False)[source]#
Fetch all MediaInfo entity data and cache it.
Note
dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content
Changed in version 9.0: Added pageid, ns, title, lastrevid, modified, id values to
_content
attribute when it is loaded.- Parameters:
force (bool) – override caching
- Raises:
NoWikibaseEntityError – if this entity doesn’t exist
- Returns:
actual data which entity holds
- Return type:
dict
- getID(numeric=False)[source]#
Get the entity identifier.
See also
- Parameters:
numeric (bool) – Strip the first letter and return an int
- Raises:
NoWikibaseEntityError – if this entity is associated with a non-existing file
- Return type:
str | int
- removeClaims(claims, **kwargs)[source]#
Remove the claims from the MediaInfo.
Added in version 8.5.
- Parameters:
claims (list or Claim) – list of claims to be removed
- Return type:
None
- title()[source]#
Return ID as title of the MediaInfo.
Added in version 9.4.
See also
- Raises:
NoWikibaseEntityError – if this entity is associated with a non-existing file
- Returns:
the entity identifier
- Return type:
str
- title_pattern = 'M[1-9]\\d*'#
- class pywikibot.Page(source, title='', ns=0)[source]#
Bases:
BasePage
,WikiBlameMixin
Page: A MediaWiki page.
Instantiate a Page object.
- Parameters:
title (str)
- get_best_claim(prop)[source]#
Return the first best Claim for this page.
Return the first ‘preferred’ ranked Claim specified by Wikibase property or the first ‘normal’ one otherwise.
Added in version 3.0.
- Parameters:
prop (str) – property id, “P###”
- Returns:
Claim object given by Wikibase property number for this page object.
- Return type:
Claim or None
- Raises:
UnknownExtensionError – site has no Wikibase extension
- property raw_extracted_templates#
Extract templates and parameters.
This method is using
textlib.extract_templates_and_params()
. Disabled parts and whitespace are stripped, except for whitespace in anonymous positional arguments.- Return type:
list of (str, OrderedDict)
- set_redirect_target(target_page, create=False, force=False, keep_section=False, save=True, botflag='[deprecated name of bot]', **kwargs)[source]#
Change the page’s text to point to the redirect page.
Changed in version 9.3: botflag keyword parameter was renamed to bot.
- Parameters:
target_page (Page | str) – target of the redirect, this argument is required.
create (bool) – if true, it creates the redirect even if the page doesn’t exist.
force (bool) – if true, it set the redirect target even the page doesn’t exist or it’s not redirect.
keep_section (bool) – if the old redirect links to a section and the new one doesn’t it uses the old redirect’s section.
save (bool) – if true, it saves the page immediately.
kwargs – Arguments which are used for saving the page directly afterwards, like summary for edit summary.
- templatesWithParams()[source]#
Return templates used on this Page.
The templates are extracted by
raw_extracted_templates()
, with positional arguments placed first in order, and each named argument appearing as ‘name=value’.All parameter keys and values for each template are stripped of whitespace.
- Returns:
a list of tuples with one tuple for each template invocation in the page, with the template Page as the first entry and a list of parameters as the second entry.
- Return type:
list[tuple[Page, list[str]]]
- class pywikibot.PropertyPage(source, title=None, datatype=None)[source]#
Bases:
WikibasePage
,Property
A Wikibase entity in the property namespace.
Should be created as:
PropertyPage(DataSite, 'P21')
or:
PropertyPage(DataSite, datatype='url')
- Parameters:
source (pywikibot.site.DataSite) – data repository property is on
title (str) – identifier of property, like “P##”, “-1” or None for an empty property.
datatype (str) – Datatype for a new property.
- DATA_ATTRIBUTES: dict[str, Any] = {'aliases': <class 'pywikibot.page._collections.AliasesDict'>, 'claims': <class 'pywikibot.page._collections.ClaimCollection'>, 'descriptions': <class 'pywikibot.page._collections.LanguageDict'>, 'labels': <class 'pywikibot.page._collections.LanguageDict'>}#
- entity_type = 'property'#
- get(force=False, *args, **kwargs)[source]#
Fetch the property entity, and cache it.
- Parameters:
force (bool) – override caching
- Raises:
NotImplementedError – a value in args or kwargs
- Returns:
actual data which entity holds
- Return type:
dict
Note
dicts returned by this method are references to content of this entity and their modifying may indirectly cause unwanted change to the live content
- getID(numeric=False)[source]#
Get the identifier of this property.
- Parameters:
numeric (bool) – Strip the first letter and return an int
- newClaim(*args, **kwargs)[source]#
Helper function to create a new claim object for this property.
- Return type:
- 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. Referpywikibot.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')
orSite('wikidata')
.- Parameters:
code (str | None) – language code (override config.mylang) code may also be a sitename like ‘wikipedia:test’
fam (str | Family | None) – family name or object (override config.family)
user (str | None) – bot user name to use on this site (override config.usernames)
interface (str | BaseSite | None) – site class or name of class in
pywikibot.site
(override config.site_interface)url (str | None) – Instead of code and fam, does try to get a Site based on the URL. Still requires that the family supporting that URL exists.
- Raises:
ValueError – URL and pair of code and family given
ValueError – Invalid interface name
ValueError – Missing Site code
ValueError – Missing Site family
- Return type:
- class pywikibot.SiteLink(title, site=None, badges=None)[source]#
Bases:
BaseLink
A single sitelink in a Wikibase item.
Extends BaseLink by the following attribute:
badges: Any badges associated with the sitelink
Added in version 3.0.
- Parameters:
title (str) – the title of the linked page including namespace
site (pywikibot.Site or str) – the Site object for the wiki linked to. Can be provided as either a Site instance or a db key, defaults to pywikibot.Site().
badges ([ItemPage]) – list of badges
- class pywikibot.Timestamp[source]#
Bases:
datetime
Class for handling MediaWiki timestamps.
This inherits from datetime.datetime, so it can use all of the methods and operations of a
datetime
object. To ensure that the results of any operation are also a Timestamp object, be sure to use only Timestamp objects (and datetime.timedelta) in any operation.Use
Timestamp.fromISOformat()
andTimestamp.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 fromTimestamp
,datetime.datetime
object, or strings compliant with ISO8601, MediaWiki, or POSIX formats.Use
Site.server_time()
for the current time; this is more reliable than usingTimestamp.utcnow()
orTimestamp.nowutc()
.Changed in version 7.5: moved to
time
module- ISO8601Format = '%Y-%m-%dT%H:%M:%SZ'#
- clone()[source]#
Clone this instance.
Deprecated since version 8.0: Use
replace()
method instead.- Return type:
- classmethod fromISOformat(ts, sep='T')[source]#
Convert an ISO 8601 timestamp to a Timestamp object.
- classmethod fromtimestamp(timestamp, tz=None)[source]#
Return the local date and time corresponding to the POSIX ts.
This class method is for Python 3.7 to upcast the class if a tz is given.
Added in version 9.0.
See also
- Parameters:
timestamp (int | float)
- Return type:
- classmethod fromtimestampformat(ts, strict=False)[source]#
Convert a MediaWiki internal timestamp to a Timestamp object.
Changed in version 3.0: create a Timestamp if only year, month and day are given.
Changed in version 8.0: the strict parameter was added which discards missing element tolerance.
Example
>>> Timestamp.fromtimestampformat('20220705082234') Timestamp(2022, 7, 5, 8, 22, 34) >>> Timestamp.fromtimestampformat('20220927') Timestamp(2022, 9, 27, 0, 0) >>> Timestamp.fromtimestampformat('20221109', strict=True) Traceback (most recent call last): ... ValueError: time data '20221109' does not match MW format.
- param ts:
the timestamp to be converted
- param strict:
If true, do not ignore missing timestamp elements for hours, minutes or seconds
- return:
return the Timestamp object from given ts.
- raises ValueError:
The timestamp is invalid, e.g. missing or invalid timestamp component.
- isoformat(sep='T')[source]#
Convert object to an ISO 8601 timestamp accepted by MediaWiki.
datetime.datetime.isoformat does not postfix the ISO formatted date with a ‘Z’ unless a timezone is included, which causes MediaWiki ~1.19 and earlier to fail.
- Parameters:
sep (str)
- Return type:
str
- mediawikiTSFormat = '%Y%m%d%H%M%S'#
- classmethod now(tz=None)[source]#
Return the current local date and time.
This class method is for Python 3.7 to upcast the class if a tz is given.
Added in version 9.0.
See also
- Return type:
- classmethod nowutc(*, with_tz=True)[source]#
Return the current UTC date and time.
If with_tz is True it returns an aware
Timestamp
object with UTC timezone by callingnow(datetime.UTC)
. As such this is just a short way to get it.Otherwise the UTC timestamp is returned as a naive Timestamp object with timezone of None. This is equal to the
Timestamp.utcnow()
.Warning
Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware Timestamps or datetimes to represent times in UTC. As such, it is not recommended to set with_tz to False.
Caution
You cannot compare, add or subtract offset-naive and offset- aware Timestamps/datetimes (i.e. missing or having timezone). A TypeError will be raised in such cases.
Added in version 9.0.
See also
- Parameters:
with_tz (bool) – Whether to include UTC timezone or not
- Return type:
- posix_timestamp()[source]#
Convert object to a POSIX timestamp.
See Note in datetime.timestamp().
Added in version 7.5.
- Return type:
float
- posix_timestamp_format()[source]#
Convert object to a POSIX timestamp format.
Added in version 7.5.
- Return type:
str
- classmethod set_timestamp(ts)[source]#
Set Timestamp from input object.
ts is converted to a datetime naive object representing UTC time. String shall be compliant with:
Mediwiki timestamp format:
YYYYMMDDHHMMSS
ISO8601 format:
YYYY-MM-DD[T ]HH:MM:SS[Z|±HH[MM[SS[.ffffff]]]]
POSIX format: seconds from Unix epoch
S{1,13}[.ffffff]]
Added in version 7.5.
Changed in version 8.0: raises TypeError instead of ValueError.
- classmethod utcnow()[source]#
Return the current UTC date and time, with
tzinfo
None
.This is like
Timestamp.now()
, but returns the current UTC date and time, as a naiveTimestamp
object. An aware current UTC datetime can be obtained by callingTimestamp.nowutc()
.Note
This method is deprecated since Python 3.12 but held here for backward compatibility because
utcnow
is widely used inside the framework to compare MediaWiki timestamps which are UTC-based. Neither datetime.fromisoformat() implementations of Python < 3.11 norTimestamp
specificfromISOformat()
supports timezone.Warning
Because naive datetime objects are treated by many datetime methods as local times, it is preferred to use aware Timestamps or datetimes to represent times in UTC. As such, the recommended way to create an object representing the current time in UTC is by calling
Timestamp.nowutc()
.Hint
This method might be deprecated later.
Added in version 9.0.
See also
- Return type:
- 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, the edit timestamp and the comment. Pages returned are not guaranteed to be unique.
Example:
>>> site = pywikibot.Site('wikipedia:test') >>> user = pywikibot.User(site, 'pywikibot-test') >>> contrib = next(user.contributions(reverse=True)) >>> len(contrib) 4 >>> contrib[0].title() 'User:John Vandenberg/appendtext test' >>> contrib[1] 504588 >>> str(contrib[2]) '2022-03-04T17:36:02Z' >>> contrib[3] ''
See also
- Parameters:
total (int | None) – limit result to this number of pages
- Keyword Arguments:
start – Iterate contributions starting at this Timestamp
end – Iterate contributions ending at this Timestamp
reverse – Iterate oldest contributions first (default: newest)
namespaces – only iterate pages in these namespaces
showMinor – if True, iterate only minor edits; if False and not None, iterate only non-minor edits (default: iterate both)
top_only – if True, iterate only edits which are the latest revision (default: False)
- Returns:
tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
- Return type:
Generator[tuple[Page, int, Timestamp, str | None], None, None]
- deleted_contributions(*, total=500, **kwargs)[source]#
Yield tuples describing this user’s deleted edits.
Added in version 5.5.
- Parameters:
total (int | None) – Limit results to this number of pages
- Keyword Arguments:
start – Iterate contributions starting at this Timestamp
end – Iterate contributions ending at this Timestamp
reverse – Iterate oldest contributions first (default: newest)
namespaces – Only iterate pages in these namespaces
- Return type:
- editCount(force=False)[source]#
Return edit count for a registered user.
Always returns 0 for ‘anonymous’ users.
- Parameters:
force (bool) – if True, forces reloading the data from API
- Return type:
int
- property first_edit: tuple[Page, int, Timestamp, str | None] | None#
Return first user contribution.
- Returns:
first user contribution entry
- Returns:
tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
- gender(force=False)[source]#
Return the gender of the user.
- Parameters:
force (bool) – if True, forces reloading the data from API
- Returns:
return ‘male’, ‘female’, or ‘unknown’
- Return type:
str
- getUserPage(subpage='')[source]#
Return a Page object relative to this user’s main page.
- Parameters:
subpage (str) – subpage part to be appended to the main page title (optional)
- Returns:
Page object of user page or user subpage
- Return type:
- 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:
- 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
- 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.
Added in version 7.0.
- Parameters:
force (bool) – if True, forces reloading the data from API
- Return type:
bool
- property is_thankable: bool#
Determine if the user has thanks notifications enabled.
Note
This doesn’t accurately determine if thanks is enabled for user. Privacy of thanks preferences is under discussion, please see T57401#2216861 and T120753#1863894.
- property last_edit: tuple[Page, int, Timestamp, str | None] | None#
Return last user contribution.
- Returns:
last user contribution entry
- Returns:
tuple of pywikibot.Page, revid, pywikibot.Timestamp, comment
- property last_event#
Return last user activity.
- Returns:
last user log entry
- Return type:
LogEntry or None
- logevents(**kwargs)[source]#
Yield user activities.
- Keyword Arguments:
logtype – only iterate entries of this type (see mediawiki api documentation for available types)
page – only iterate entries affecting this page
namespace – namespace to retrieve logevents from
start – only iterate entries from and after this Timestamp
end – only iterate entries up to and through this Timestamp
reverse – if True, iterate oldest entries first (default: newest)
tag – only iterate entries tagged with this tag
total – maximum number of events to iterate
- Return type:
iterable
- registration(force=False)[source]#
Fetch registration date for this user.
- Parameters:
force (bool) – if True, forces reloading the data from API
- Return type:
Timestamp | None
- renamed_target()[source]#
Return a User object for the target this user was renamed to.
If this user was not renamed, it will raise a
NoRenameTargetError
.Usage:
>>> site = pywikibot.Site('wikipedia:de') >>> user = pywikibot.User(site, 'Foo') >>> user.isRegistered() False >>> target = user.renamed_target() >>> target.isRegistered() True >>> target.title(with_ns=False) 'Foo~dewiki' >>> target.renamed_target() Traceback (most recent call last): ... pywikibot.exceptions.NoRenameTargetError: Rename target user ...
See also
BasePage.moved_target()
BasePage.getRedirectTarget()
Added in version 9.4.
- Raises:
NoRenameTargetError – user was not renamed
- Return type:
- rights(force=False)[source]#
Return user rights.
- Parameters:
force (bool) – if True, forces reloading the data from API
- Returns:
return user rights
- Return type:
list
- send_email(subject, text, ccme=False)[source]#
Send an email to this user via MediaWiki’s email interface.
- Parameters:
subject (str) – the subject header of the mail
text (str) – mail body
ccme (bool) – if True, sends a copy of this email to the bot
- Raises:
NotEmailableError – the user of this User is not emailable
UserRightsError – logged in user does not have ‘sendemail’ right
- Returns:
operation successful indicator
- Return type:
bool
- unblock(reason=None)[source]#
Remove the block for the user.
- Parameters:
reason (str | None) – Reason for the unblock.
- Return type:
None
- uploadedImages(total=10)[source]#
Yield tuples describing files uploaded by this user.
Each tuple is composed of a pywikibot.Page, the timestamp (str in ISO8601 format), comment (str) and a bool for pageid > 0. Pages returned are not guaranteed to be unique.
- Parameters:
total (int) – limit result to this number of pages
- property username: str#
The username.
Convenience method that returns the title of the page with namespace prefix omitted, which is the username.
- class pywikibot.WbGeoShape(page, site=None)[source]#
Bases:
WbDataPage
A Wikibase geo-shape representation.
Create a new WbDataPage object.
- 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
- class pywikibot.WbQuantity(amount, unit=None, error=None, site=None)[source]#
Bases:
WbRepresentation
A Wikibase quantity representation.
Create a new WbQuantity object.
- Parameters:
amount (ToDecimalType) – number representing this quantity
unit (ItemPageStrNoneType) – the Wikibase item for the unit or the entity URI of this Wikibase item.
error (ToDecimalType | tuple[ToDecimalType, ToDecimalType]) – the uncertainty of the amount (e.g. ±1)
site (DataSite | None) – The Wikibase site
- classmethod fromWikibase(data, site=None)[source]#
Create a WbQuantity from the JSON data given by the Wikibase API.
- Parameters:
data (dict[str, Any]) – Wikibase JSON
site (DataSite | None) – The Wikibase site
- Return type:
- 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.
- 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.
- class pywikibot.WbTime(year=None, month=None, day=None, hour=None, minute=None, second=None, precision=None, before=0, after=0, timezone=0, calendarmodel=None, site=None)[source]#
Bases:
WbRepresentation
A Wikibase time representation.
Make a WbTime object from the current time:
current_ts = pywikibot.Timestamp.now() wbtime = pywikibot.WbTime.fromTimestamp(current_ts)
For converting python datetime objects to WbTime objects, see
pywikibot.Timestamp
andfromTimestamp()
.Create a new WbTime object.
The precision can be set by the Wikibase int value (0-14) or by a human readable string, e.g.,
hour
. If no precision is given, it is set according to the given time units.Timezone information is given in three different ways depending on the time:
Times after the implementation of UTC (1972): as an offset from UTC in minutes;
Times before the implementation of UTC: the offset of the time zone from universal time;
Before the implementation of time zones: The longitude of the place of the event, in the range −180° to 180°, multiplied by 4 to convert to minutes.
Note
Comparison information: When using the greater than or equal to operator, or the less than or equal to operator, two different time objects with the same UTC time after factoring in timezones are considered equal. However, the equality operator will return false if the timezone is different.
- Parameters:
year (int | None) – The year as a signed integer of between 1 and 16 digits.
month (int | None) – Month of the timestamp, if it exists.
day (int | None) – Day of the timestamp, if it exists.
hour (int | None) – Hour of the timestamp, if it exists.
minute (int | None) – Minute of the timestamp, if it exists.
second (int | None) – Second of the timestamp, if it exists.
precision (int | str | None) – The unit of the precision of the time.
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.
- FORMATSTR = '{0:+012d}-{1:02d}-{2:02d}T{3:02d}:{4:02d}:{5:02d}Z'#
- PRECISION = {'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}#
- equal_instant(other)[source]#
Checks if the two times represent the same instant in time.
This is different from the equality operator, which will return false for two times that are the same number of UTC seconds, but with different timezone information.
For example, a time with at 10:00 UTC-5 would return false if checked with == with a time at 15:00 UTC, but would return true with this method.
Added in version 9.0.
- Parameters:
other (WbTime)
- Return type:
bool
- classmethod fromTimestamp(timestamp, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None, copy_timezone=False)[source]#
Create a new WbTime object from a pywikibot.Timestamp.
Changed in version 8.0: Added copy_timezone parameter.
- Parameters:
timestamp (Timestamp) – Timestamp
precision (int | str) – The unit of the precision of the time. Defaults to 14 (second).
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.
copy_timezone (bool) – Whether to copy the timezone from the timestamp if it has timezone information. Defaults to False to maintain backwards compatibility. If a timezone is given, timezone information is discarded.
- Return type:
- classmethod fromTimestr(datetimestr, precision=14, before=0, after=0, timezone=0, calendarmodel=None, site=None)[source]#
Create a new WbTime object from a UTC date/time string.
The timestamp differs from ISO 8601 in that:
The year is always signed and having between 1 and 16 digits;
The month, day and time are zero if they are unknown;
The Z is discarded since time zone is determined from the timezone param.
- Parameters:
datetimestr (str) – Timestamp in a format resembling ISO 8601, e.g. +2013-01-01T00:00:00Z
precision (int | str) – The unit of the precision of the time. Defaults to 14 (second).
before (int) – Number of units after the given time it could be, if uncertain. The unit is given by the precision.
after (int) – Number of units before the given time it could be, if uncertain. The unit is given by the precision.
timezone (int) – Timezone information in minutes.
calendarmodel (str | None) – URI identifying the calendar model.
site (DataSite | None) – The Wikibase site. If not provided, retrieves the data repository from the default site from user-config.py. Only used if calendarmodel is not given.
- Return type:
- classmethod fromWikibase(data, site=None)[source]#
Create a WbTime from the JSON data given by the Wikibase API.
- normalize()[source]#
Normalizes the WbTime object to account for precision.
Normalization is needed because WbTime objects can have hidden values that affect naive comparisons, such as an object set to a precision of YEAR but containing a month and day value.
This function returns a new normalized object and does not do any modification in place.
Normalization will delete timezone information if the precision is less than or equal to DAY.
Note: Normalized WbTime objects can only be compared to other normalized WbTime objects of the same precision. Normalization might make a WbTime object that was less than another WbTime object before normalization, greater than it after normalization, or vice versa.
- Return type:
- toTimestamp(timezone_aware=False)[source]#
Convert the data to a pywikibot.Timestamp.
Changed in version 8.0.1: timezone_aware parameter was added.
- Parameters:
timezone_aware (bool) – Whether the timezone should be passed to the Timestamp object.
- Raises:
ValueError – instance value cannot be represented using Timestamp
- Return type:
- toTimestr(force_iso=False)[source]#
Convert the data to a UTC date/time string.
See also
fromTimestr()
for differences between output with and without force_iso parameter.Changed in version 8.0: normalize parameter was added.
- Parameters:
force_iso (bool) – whether the output should be forced to ISO 8601
- Returns:
Timestamp in a format resembling ISO 8601
- Return type:
str
- class pywikibot.WbUnknown(json, warning='')[source]#
Bases:
WbRepresentation
A Wikibase representation for unknown data type.
This will prevent the bot from breaking completely when a new type is introduced.
This data type is just a json container
Added in version 3.0.
Changed in version 9.4: warning parameter was added
Create a new WbUnknown object.
- Parameters:
json (dict[str, Any]) – Wikibase JSON
warning (str) – a warning message which is shown once if
toWikibase()
is called
- class pywikibot.WikidataBot(**kwargs)[source]#
Bases:
Bot
,ExistingPageBot
Generic Wikidata Bot to be subclassed.
Source claims (P143) can be created for specific sites
- Variables:
use_from_page – If True (default) it will apply ItemPage.fromPage for every item. If False it assumes that the pages are actually already ItemPage (page in treat_page_and_item will be None). If None it’ll use ItemPage.fromPage when the page is not in the site’s item namespace.
treat_missing_item – Whether pages without items should be treated. Note that this is checked after create_missing_item.
create_missing_item – If True, new items will be created if the current page doesn’t have one. Subclasses should override this in the initializer with a bool value or using self.opt attribute.
- Parameters:
kwargs (Any)
Initializer of the WikidataBot.
- cacheSources()[source]#
Fetch the sources from the list on Wikidata.
It is stored internally and reused by getSource()
- Return type:
None
- create_item_for_page(page, data=None, summary=None, **kwargs)[source]#
Create an ItemPage with the provided page as the sitelink.
- Parameters:
page (BasePage) – the page for which the item will be created
data (dict[str, Any] | None) – additional data to be included in the new item (optional). Note that data created from the page have higher priority.
summary (str | None) – optional edit summary to replace the default one
kwargs (Any)
- Returns:
pywikibot.ItemPage or None
- Return type:
ItemPage | None
- getSource(site)[source]#
Create a Claim usable as a source for Wikibase statements.
- Parameters:
site (BaseSite) – site that is the source of assertions.
- Returns:
pywikibot.Claim or None
- Return type:
pywikibot.page.Claim | None
- get_property_by_name(property_name)[source]#
Find given property and return its ID.
Method first uses site.search() and if the property isn’t found, then asks user to provide the property ID.
- Parameters:
property_name (str) – property to find
- Return type:
str
- treat_missing_item = False#
- treat_page_and_item(page, item)[source]#
Treat page together with its item (if it exists).
Must be implemented in subclasses.
- use_from_page = True#
- user_add_claim(item, claim, source=None, bot=True, **kwargs)[source]#
Add a claim to an item, with user confirmation as required.
- Parameters:
item (pywikibot.page.ItemPage) – page to be edited
claim (pywikibot.page.Claim) – claim to be saved
source (BaseSite | None) – site where the claim comes from
bot (bool) – whether to flag as bot (if possible)
kwargs (Any)
- Keyword Arguments:
ignore_server_errors – if True, server errors will be reported and ignored (default: False)
ignore_save_related_errors – if True, errors related to page save will be reported and ignored (default: False)
- Returns:
whether the item was saved successfully
- Return type:
bool
Note
calling this method sets the current_page property to the item which changes the site property
Note
calling this method with the ‘source’ argument modifies the provided claim object in place
- user_add_claim_unless_exists(item, claim, exists_arg='', source=None, logger_callback=<function 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 (BaseSite | None)
kwargs (Any)
- Returns:
whether the claim could be added
- Return type:
bool
Note
calling this method may change the current_page property to the item which will also change the site property
Note
calling this method with the ‘source’ argument modifies the provided claim object in place
- user_edit_entity(entity, data=None, ignore_save_related_errors=None, ignore_server_errors=None, **kwargs)[source]#
Edit entity with data provided, with user confirmation as required.
- Parameters:
entity (WikibasePage) – page to be edited
data (dict[str, str] | None) – data to be saved, or None if the diff should be created automatically
ignore_save_related_errors (bool | None) – Ignore save related errors and automatically print a message. If None uses this instances default.
ignore_server_errors (bool | None) – Ignore server errors and automatically print a message. If None uses this instances default.
kwargs (Any)
- Keyword Arguments:
summary – revision comment, passed to ItemPage.editEntity
show_diff – show changes between oldtext and newtext (default: True)
- Returns:
whether the item was saved successfully
- Return type:
bool
- pywikibot.async_manager(block=True)[source]#
Daemon to take requests from the queue and execute them in background.
- Parameters:
block – If true, block
page_put_queue
if necessary until a request is available to process. Otherwise process a request if one is immediately available, else leave the function.- Return type:
None
- pywikibot.async_request(request, *args, **kwargs)[source]#
Put a request on the queue, and start the daemon if necessary.
- Parameters:
request (Callable)
args (Any)
kwargs (Any)
- Return type:
None
- pywikibot.calledModuleName()[source]#
Return the name of the module calling this function.
This is required because the -help option loads the module’s docstring and because the module name will be used for the filename of the log.
- 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 viapywikibot.userinterfaces
. The arguments are interpreted as forlogoutput()
.Changed in version 7.2:
text
was renamed tomsg
; only keyword arguments are allowed except formsg
. Keyword parameter layer was added.See also
- 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 tomsg
; only keyword arguments are allowed except formsg
.See also
- 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 viapywikibot.userinterfaces
. The arguments are interpreted as forlogoutput()
.Changed in version 7.2:
text
was renamed tomsg
; only keyword arguments are allowed except formsg
. Keyword parameter layer was added.See also
- 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 likeerror()
except that themsg
parameter may be omitted. This function should only be called from an Exception handler.msg
will be sent to stderr viapywikibot.userinterfaces
. The arguments are interpreted as forlogoutput()
.Changed in version 7.2: only keyword arguments are allowed except for
msg
;exc_info
keyword is to be used instead oftb
. Keyword parameter layer was added.Changed in version 7.3:
exc_info
is True by defaultSee also
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 global command line arguments and return the rest as a list.
Takes the command line arguments as strings, processes all global parameters such as
-lang
or-log
, initialises the logging layer, which emits startup information into log at level ‘verbose’. This function makes sure that global arguments are applied first, regardless of the order in which the arguments were given.args
may be passed as an argument, thereby overridingsys.argv
.>>> local_args = pywikibot.handle_args() # sys.argv is used >>> local_args [] >>> local_args = pywikibot.handle_args(['-simulate', '-myoption']) >>> local_args # global optons are handled, show the remaining ['-myoption'] >>> for arg in local_args: pass # do whatever is wanted with local_args
Caution
Global options might be introduced without warning period. It is up to developers to verify that global options do not interfere with local script options of private scripts.
Tip
Avoid using this method in your private scripts and use the
pwb
wrapper instead. In directory mode:python pwb.py <global options> <name_of_script> <local options>
With installed site package:
pwb <global options> <name_of_script> <local options>
Note
the
pwb
wrapper can be used even if thehandle_args
method is used within the script.Changed in version 5.2: -site global option was added
Changed in version 7.1: -cosmetic_changes and -cc may be set directly instead of toggling the value. Refer
tools.strtobool()
for valid values.Changed in version 7.7: -config global option was added.
Changed in version 8.0: Short site value can be given if site code is equal to family like
-site:meta
.Changed in version 8.1:
-nolog
option also discards command.log.- Parameters:
args (Iterable[str] | None) – Command line arguments. If None,
pywikibot.argvu
is used which is a copy ofsys.argv
do_help (bool) – Handle parameter ‘-help’ to show help and invoke sys.exit
- Returns:
list of arguments not recognised globally
- Return type:
list[str]
- pywikibot.html2unicode(text, ignore=None, exceptions=None)[source]#
Replace HTML entities with equivalent unicode.
- Parameters:
ignore – 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 viapywikibot.userinterfaces
. It may be omitted and a newline is printed in that case. The arguments are interpreted as forlogoutput()
.Added in version 7.2: was renamed from
output()
. Positional arguments for decoder and newline are deprecated; keyword arguments should be used. Keyword parameter layer was added.See also
- 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 (str | None) – The default answer if none was entered. None to require an answer.
force (bool) – Automatically use the default
- Return type:
str
- pywikibot.input_choice(question, answers, default=None, return_shortcut=True, automatic_quit=True, force=False)[source]#
Ask the user the question and return one of the valid answers.
See also
- Parameters:
question (str) – The question asked without trailing spaces.
answers (AnswerType) – The valid answers each containing a full length answer and a shortcut. Each value must be unique.
default (str | None) – The result if no answer was entered. It must not be in the valid answers and can be disabled by setting it to None. If it should be linked with the valid answers it must be its shortcut.
return_shortcut (bool) – Whether the shortcut or the index of the answer is returned.
automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) and throw a
bot.QuitKeyboardInterrupt
if selected.force (bool) – Automatically use the default.
- Returns:
The selected answer shortcut or index. Is -1 if the default is selected, it does not return the shortcut and the default is not a valid shortcut.
- Return type:
Any
- pywikibot.input_yn(question, default=None, automatic_quit=True, force=False)[source]#
Ask the user a yes/no question and return the answer as a bool.
Example:
>>> input_yn('Do you like Pywikibot?', 'y', False, force=True) ... Do you like Pywikibot? ([Y]es, [n]o) True >>> input_yn('More examples?', False, automatic_quit=False, force=True) ... Some more examples? ([y]es, [N]o) False
See also
- Parameters:
question (str) – The question asked without trailing spaces.
default (bool | str | None) – The result if no answer was entered. It must be a bool or
'y'
,'n'
,0
or1
and can be disabled by setting it to None.automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) and throw a
bot.QuitKeyboardInterrupt
if selected.force (bool) – Automatically use the default.
- Returns:
Return True if the user selected yes and False if the user selected no. If the default is not None it’ll return True if default is True or ‘y’ and False if default is False or ‘n’.
- Return type:
bool
- pywikibot.log(msg, 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 tomsg
; only keyword arguments are allowed except formsg
. Keyword parameter layer was added.See also
- 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 viapywikibot.userinterfaces
. It may be omitted and a newline is printed in that case. The arguments are interpreted as forlogoutput()
.Added in version 7.2: was renamed from
output()
. Positional arguments for decoder and newline are deprecated; keyword arguments should be used. Keyword parameter layer was added.See also
- Parameters:
msg (Any)
args (Any)
kwargs (Any)
- pywikibot.page_put_queue: Queue = <queue.Queue object>#
Queue to hold pending requests
- pywikibot.showDiff(oldtext, newtext, context=0)[source]#
Output a string showing the differences between oldtext and newtext.
The differences are highlighted (only on compatible systems) to show which changes were made.
- Parameters:
oldtext (str)
newtext (str)
context (int)
- Return type:
None
- pywikibot.show_help(module_name=None, show_global=False)[source]#
Show help for the Bot.
Changed in version 4.0: Renamed from showHelp() to show_help().
Changed in version 8.0: Do not show version changes.
- Parameters:
module_name (str | None)
show_global (bool)
- Return type:
None
- pywikibot.sleep(secs)[source]#
Suspend execution of the current thread for the given number of seconds.
Drop this process from the throttle log if wait time is greater than 30 seconds by calling
stopme()
.- Parameters:
secs (int)
- Return type:
None
- pywikibot.stdout(msg='', 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) viapywikibot.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 tomsg
;msg
parameter may be omitted; only keyword arguments are allowed except formsg
. Keyword parameter layer was added.See also
- Parameters:
msg (Any)
args (Any)
kwargs (Any)
- pywikibot.stopme()[source]#
Drop this process from the throttle log, after pending threads finish.
Can be called manually if desired but usually it is not necessary. Does not clean
async_manager()
. This should be run when a bot does not interact with the Wiki, or when it has stopped doing so. After a bot has runstopme()
it will not slow down other bots instances any more.stopme()
is called withsleep()
function during long delays and withbot.BaseBot.exit()
to wait for pending write threads.- Return type:
None
- pywikibot.translate(code, xdict, parameters=None, fallback=False)[source]#
Return the most appropriate localization from a localization dict.
Given a site code and a dictionary, returns the dictionary’s value for key ‘code’ if this key exists; otherwise tries to return a value for an alternative code that is most applicable to use on the wiki in language ‘code’ except fallback is False.
The code itself is always checked first, then these codes that have been defined to be alternatives, and finally English.
If fallback is False and the code is not found in the
For PLURAL support have a look at the twtranslate method.
- Parameters:
code (str | BaseSite) – The site code as string or Site object. If xdict is an extended dictionary the Site object should be used in favour of the code string. Otherwise localizations from a wrong family might be used.
xdict (str | Mapping[str, str]) – dictionary with language codes as keys or extended dictionary with family names as keys containing code dictionaries or a single string. May contain PLURAL tags as described in twtranslate
parameters (Mapping[str, int] | None) – For passing (plural) parameters
fallback (bool | Iterable[str]) – Try an alternate language code. If it’s iterable it’ll also try those entries and choose the first match.
- Returns:
the localized string
- Raises:
IndexError – If the language supports and requires more plurals than defined for the given PLURAL pattern.
KeyError – No fallback key found if fallback is not False
- Return type:
str | None
- 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 viapywikibot.userinterfaces
. The arguments are interpreted as forlogoutput()
.Changed in version 7.2:
text
was renamed tomsg
; only keyword arguments are allowed except formsg
. Keyword parameter layer was added.See also
- Parameters:
msg (Any)
args (Any)
kwargs (Any)