pywikibot.site package¶
Library module representing MediaWiki sites (wikis).
-
class
pywikibot.site.
APISite
(code, fam=None, user=None)[source]¶ Bases:
pywikibot.site._basesite.BaseSite
,pywikibot.site._extensions.EchoMixin
,pywikibot.site._extensions.FlowMixin
,pywikibot.site._generators.GeneratorsMixin
,pywikibot.site._extensions.GeoDataMixin
,pywikibot.site._extensions.GlobalUsageMixin
,pywikibot.site._extensions.LinterMixin
,pywikibot.site._extensions.PageImagesMixin
,pywikibot.site._extensions.ProofreadPageMixin
,pywikibot.site._extensions.ThanksFlowMixin
,pywikibot.site._extensions.ThanksMixin
,pywikibot.site._extensions.UrlShortenerMixin
,pywikibot.site._extensions.WikibaseClientMixin
API interface to MediaWiki site.
Do not instantiate directly; use
pywikibot.Site
function.-
class
OnErrorExc
(exception, on_new_page)¶ Bases:
tuple
Create new instance of OnErrorExc(exception, on_new_page)
-
exception
¶ Alias for field number 0
-
on_new_page
¶ Alias for field number 1
-
-
property
article_path
¶ Get the nice article path without $1.
-
static
assert_valid_iter_params
(msg_prefix, start, end, reverse, is_ts=True)[source]¶ Validate iterating API parameters.
- Parameters
msg_prefix (str) – The calling method name
start – The start value to compare
end – The end value to compare
reverse (bool) – The reverse option
is_ts (bool) – When comparing timestamps (with is_ts=True) the start is usually greater than end. Comparing titles this is vice versa.
- Raises
AssertionError – start/end values are in wrong order
-
blockuser
(user, expiry, reason: str, anononly=True, nocreate=True, autoblock=True, noemail=False, reblock=False, allowusertalk=False)[source]¶ Block a user for certain amount of time and for a certain reason.
- See
- Parameters
user (
pywikibot.User
) – The username/IP to be blocked without a namespace.expiry (Timestamp/datetime (absolute), str (relative/absolute) or False ('never')) –
The length or date/time when the block expires. If ‘never’, ‘infinite’, ‘indefinite’ it never does. If the value is given as a str it’s parsed by php’s strtotime function:
The relative format is described there:
It is recommended to not use a str if possible to be independent of the API.
reason – The reason for the block.
anononly (boolean) – Disable anonymous edits for this IP.
nocreate (boolean) – Prevent account creation.
autoblock (boolean) – Automatically block the last used IP address and all subsequent IP addresses from which this account logs in.
noemail (boolean) – Prevent user from sending email through the wiki.
reblock (boolean) – If the user is already blocked, overwrite the existing block.
allowusertalk (boolean) – Whether the user can edit their talk page while blocked.
- Returns
The data retrieved from the API request.
- Return type
dict
-
compare
(old, diff)[source]¶ Corresponding method to the ‘action=compare’ API action.
See: https://en.wikipedia.org/w/api.php?action=help&modules=compare Use pywikibot.diff’s html_comparator() method to parse result. :param old: starting revision ID, title, Page, or Revision :type old: int, str, pywikibot.Page, or pywikibot.Page.Revision :param diff: ending revision ID, title, Page, or Revision :type diff: int, str, pywikibot.Page, or pywikibot.Page.Revision :return: Returns an HTML string of a diff between two revisions. :rtype: str
-
data_repository
()[source]¶ Return the data repository connected to this site.
- Returns
The data repository if one is connected or None otherwise.
- Return type
pywikibot.site.DataSite or None
-
delete
(page, reason: str, *, oldimage: Optional[str] = None)[source]¶ Delete a page or a specific old version of a file from the wiki.
Requires appropriate privileges.
Page to be deleted can be given either as Page object or as pageid. To delete a specific version of an image the oldimage identifier must be provided.
Renamed in version 6.1.
New in version 6.1: keyword only parameter oldimage was added.
- Parameters
page (
pywikibot.page.BasePage
or, for pageid, int or str) – Page to be deleted or its pageid.reason – Deletion reason.
oldimage – oldimage id of the file version to be deleted. If a BasePage object is given with page parameter, it has to be a FilePage.
- Raises
TypeError, ValueError – page has wrong type/value.
-
deleterevs
(targettype: str, ids, *, hide=None, show=None, reason='', target=None)[source]¶ Delete or undelete specified page revisions, file versions or logs.
If more than one target id is provided, the same action is taken for all of them.
New in version 6.0.
- Parameters
targettype – Type of target. One of “archive”, “filearchive”, “logging”, “oldimage”, “revision”.
ids (int, str, or list of int or str) – Identifiers for the revision, log, file version or archive.
hide (str or list of str) – What to delete. Can be “comment”, “content”, “user” or a combination of them in pipe-separate form such as “comment|user”.
show (str or list of str) – What to undelete. Can be “comment”, “content”, “user” or a combination of them in pipe-separate form such as “comment|user”.
reason – Deletion reason.
target – Page object or page title, if required for the type.
-
editpage
(page, summary=None, minor=True, notminor=False, bot=True, recreate=True, createonly=False, nocreate=False, watch=None, **kwargs) → bool[source]¶ Submit an edit to be saved to the wiki.
- See
- Parameters
page – The Page to be saved. By default its .text property will be used as the new text to be saved to the wiki
summary – the edit summary
minor – if True (default), mark edit as minor
notminor – if True, override account preferences to mark edit as non-minor
recreate – if True (default), create new page even if this title has previously been deleted
createonly – if True, raise an error if this title already exists on the wiki
nocreate – if True, raise an error if the page does not exist
watch – Specify how the watchlist is affected by this edit, set to one of “watch”, “unwatch”, “preferences”, “nochange”: * watch: add the page to the watchlist * unwatch: remove the page from the watchlist * preferences: use the preference settings (default) * nochange: don’t change the watchlist
bot – if True, mark edit with bot flag
- Keyword Arguments
text – Overrides Page.text
section – Edit an existing numbered section or a new section (‘new’)
prependtext – Prepend text. Overrides Page.text
appendtext – Append text. Overrides Page.text.
undo – Revision id to undo. Overrides Page.text
- Returns
True if edit succeeded, False if it failed
- Raises
pywikibot.exceptions.Error – No text to be saved
pywikibot.exceptions.NoPageError – recreate is disabled and page does not exist
pywikibot.exceptions.CaptchaError – config.solve_captcha is False and saving the page requires solving a captcha
-
expand_text
(text: str, title=None, includecomments=None, string='[deprecated name of text]')[source]¶ Parse the given text for preprocessing and rendering.
e.g expand templates and strip comments if includecomments parameter is not True. Keeps text inside <nowiki></nowiki> tags unchanges etc. Can be used to parse magic parser words like {{CURRENTTIMESTAMP}}.
- Parameters
text (str) – text to be expanded
title (str) – page title without section
includecomments (bool) – if True do not strip comments
-
classmethod
fromDBName
(dbname, site=None)[source]¶ Create a site from a database name using the sitematrix.
- Parameters
dbname (str) – database name
site (pywikibot.site.APISite) – Site to load sitematrix from. (Default meta.wikimedia.org)
- Returns
site object for the database name
- Return type
-
get_property_names
(force: bool = False)[source]¶ Get property names for pages_with_property().
- See
- Parameters
force – force to retrieve userinfo ignoring cache
-
get_searched_namespaces
(force=False)[source]¶ Retrieve the default searched namespaces for the user.
If no user is logged in, it returns the namespaces used by default. Otherwise it returns the user preferences. It caches the last result and returns it, if the username or login status hasn’t changed.
- Parameters
force – Whether the cache should be discarded.
- Returns
The namespaces which are searched by default.
- Return type
set
ofNamespace
-
get_tokens
(types: list, all: bool = False) → dict[source]¶ Preload one or multiple tokens.
For MediaWiki version 1.23, only one token can be retrieved at once. For MediaWiki versions since 1.24wmfXXX a new token system was introduced which reduced the amount of tokens available. Most of them were merged into the ‘csrf’ token. If the token type in the parameter is not known it will default to the ‘csrf’ token.
- The other token types available are:
createaccount
deleteglobalaccount
login
patrol
rollback
setglobalaccountstatus
userrights
watch
- See
- Parameters
types – the types of token (e.g., “edit”, “move”, “delete”); see API documentation for full list of types
all – load all available tokens, if None only if it can be done in one request.
return: a dict with retrieved valid tokens.
-
getcurrenttimestamp
()[source]¶ Return the server time as a MediaWiki timestamp string.
It calls
server_time
first so it queries the server to get the current server time.- Returns
the server time
- Return type
str (as ‘yyyymmddhhmmss’)
-
getredirtarget
(page)[source]¶ Return page object for the redirect target of page.
- Parameters
page (pywikibot.page.BasePage) – page to search redirects for
- Returns
redirect target of page
- Return type
- Raises
pywikibot.exceptions.IsNotRedirectPageError – page is not a redirect
RuntimeError – no redirects found
pywikibot.exceptions.CircularRedirectError – page is a circular redirect
pywikibot.exceptions.InterwikiRedirectPageError – the redirect target is on another site
-
property
globaluserinfo
¶ Retrieve globaluserinfo from site and cache it.
self._globaluserinfo will be a dict with the following keys and values:
id: user id (numeric str)
home: dbname of home wiki
registration: registration date as Timestamp
groups: list of groups (could be empty)
rights: list of rights (could be empty)
editcount: global editcount
-
has_all_mediawiki_messages
(keys, lang=None)[source]¶ Confirm that the site defines a set of MediaWiki messages.
- Parameters
keys (iterable of str) – names of MediaWiki messages
lang (str or None) – a language code, default is self.lang
- Return type
bool
-
property
has_data_repository
¶ Return True if site has a shared data repository like Wikidata.
-
has_extension
(name)[source]¶ Determine whether extension
name
is loaded.- Parameters
name (str) – The extension to check for, case sensitive
- Returns
If the extension is loaded
- Return type
bool
-
has_group
(group)[source]¶ Return true if and only if the user is a member of specified group.
Possible values of ‘group’ may vary depending on wiki settings, but will usually include bot. https://www.mediawiki.org/wiki/API:Userinfo
-
property
has_image_repository
¶ Return True if site has a shared image repository like Commons.
-
has_mediawiki_message
(key, lang=None)[source]¶ Determine if the site defines a MediaWiki message.
- Parameters
key (str) – name of MediaWiki message
lang (str or None) – a language code, default is self.lang
- Return type
bool
-
has_right
(right)[source]¶ Return true if and only if the user has a specific right.
Possible values of ‘right’ may vary depending on wiki settings. https://www.mediawiki.org/wiki/API:Userinfo
- Parameters
right (str) – a specific right to be validated
-
interwiki
(prefix)[source]¶ Return the site for a corresponding interwiki prefix.
- Raises
pywikibot.exceptions.SiteDefinitionError – if the url given in the interwiki table doesn’t match any of the existing families.
KeyError – if the prefix is not an interwiki prefix.
-
interwiki_prefix
(site)[source]¶ Return the interwiki prefixes going to that site.
The interwiki prefixes are ordered first by length (shortest first) and then alphabetically.
interwiki(prefix)
is not guaranteed to equalsite
(i.e. the parameter passed to this function).- Parameters
site (
BaseSite
) – The targeted site, which might be it’s own.- Returns
The interwiki prefixes
- Return type
list (guaranteed to be not empty)
- Raises
KeyError – if there is no interwiki prefix for that site.
-
is_blocked
()[source]¶ Return True when logged in user is blocked.
To check whether a user can perform an action, the method has_right should be used. https://www.mediawiki.org/wiki/API:Userinfo
- Return type
bool
-
is_oauth_token_available
()[source]¶ Check whether OAuth token is set for this site.
- Return type
bool
-
is_uploaddisabled
()[source]¶ Return True if upload is disabled on site.
When the version is at least 1.27wmf9, uses general siteinfo. If not called directly, it is cached by the first attempted upload action.
-
property
lang
¶ Return the code for the language of this Site.
-
list_to_text
(args: Iterable[str]) → str[source]¶ Convert a list of strings into human-readable text.
The MediaWiki messages ‘and’ and ‘word-separator’ are used as separator between the last two arguments. If more than two arguments are given, other arguments are joined using MediaWiki message ‘comma-separator’.
- Parameters
args – text to be expanded
-
loadimageinfo
(page, history=False, url_width=None, url_height=None, url_param=None)[source]¶ Load image info from api and save in page attributes.
Parameters correspond to iiprops in: [1] https://www.mediawiki.org/wiki/API:Imageinfo
Parameters validation and error handling left to the API call.
- Parameters
history – if true, return the image’s version history
url_width – see iiurlwidth in [1]
url_height – see iiurlheigth in [1]
url_param – see iiurlparam in [1]
-
local_interwiki
(prefix)[source]¶ Return whether the interwiki prefix is local.
A local interwiki prefix is handled by the target site like a normal link. So if that link also contains an interwiki link it does follow it as long as it’s a local link.
- Raises
pywikibot.exceptions.SiteDefinitionError – if the url given in the interwiki table doesn’t match any of the existing families.
KeyError – if the prefix is not an interwiki prefix.
-
logged_in
()[source]¶ Verify the bot is logged into the site as the expected user.
The expected usernames are those provided as the user parameter at instantiation.
- Return type
bool
-
login
(autocreate: bool = False, user: Optional[str] = None)[source]¶ Log the user in if not already logged in.
- Parameters
autocreate – if true, allow auto-creation of the account using unified login
user – bot user name. Overrides the username set by BaseSite initializer parameter or user-config.py setting
- Raises
pywikibot.exceptions.NoUsernameError – Username is not recognised by the site.
- See
-
logout
()[source]¶ Logout of the site and load details for the logged out user.
Also logs out of the global account if linked to the user. https://www.mediawiki.org/wiki/API:Logout
- Raises
APIError – Logout is not available when OAuth enabled.
-
property
logtypes
¶ Return a set of log types available on current site.
-
mediawiki_message
(key, lang=None, forceReload=NotImplemented)[source]¶ Fetch the text for a MediaWiki message.
- Parameters
key (str) – name of MediaWiki message
lang (str or None) – a language code, default is self.lang
-
mediawiki_messages
(keys, lang: Optional[str] = None)[source]¶ Fetch the text of a set of MediaWiki messages.
The returned dict uses each key to store the associated message.
- See
- Parameters
keys (iterable of str) – MediaWiki messages to fetch
lang – a language code, default is self.lang
- Return type
OrderedDict
-
merge_history
(source, dest, timestamp=None, reason: Optional[str] = None)[source]¶ Merge revisions from one page into another.
Revisions dating up to the given timestamp in the source will be moved into the destination page history. History merge fails if the timestamps of source and dest revisions overlap (all source revisions must be dated before the earliest dest revision).
- Parameters
source (pywikibot.Page) – Source page from which revisions will be merged
dest (pywikibot.Page) – Destination page to which revisions will be merged
timestamp (pywikibot.Timestamp) – Revisions from this page dating up to this timestamp will be merged into the destination page (if not given or False, all revisions will be merged)
reason – Optional reason for the history merge
-
property
months_names
¶ Obtain month names from the site messages.
The list is zero-indexed, ordered by month in calendar, and should be in the original site language.
- Returns
list of tuples (month name, abbreviation)
- Return type
list
-
movepage
(page, newtitle: str, summary, movetalk=True, noredirect=False)[source]¶ Move a Page to a new title.
- See
- Parameters
page – the Page to be moved (must exist)
newtitle – the new title for the Page
summary – edit summary (required!)
movetalk – if True (default), also move the talk page if possible
noredirect – if True, suppress creation of a redirect from the old title to the new one
- Returns
Page object with the new title
- Return type
-
property
mw_version
¶ Return self.version() as a MediaWikiVersion object.
Cache the result for 24 hours. :rtype: MediaWikiVersion
-
namespace
(num, all=False)[source]¶ Return string containing local name of namespace ‘num’.
If optional argument ‘all’ is true, return all recognized values for this namespace.
- Parameters
num (int) – Namespace constant.
all – If True return a Namespace object. Otherwise return the namespace name.
- Returns
local name or Namespace object
- Return type
str or Namespace
-
page_can_be_edited
(page, action='edit')[source]¶ Determine if the page can be modified.
Return True if the bot has the permission of needed restriction level for the given action type.
- Parameters
page (pywikibot.Page) – a pywikibot.Page object
action (str) – a valid restriction type like ‘edit’, ‘move’
- Return type
bool
- Raises
ValueError – invalid action parameter
-
page_from_repository
(item)[source]¶ Return a Page for this site object specified by Wikibase item.
- Parameters
item (str) – id number of item, “Q###”,
- Returns
Page, or Category object given by Wikibase item number for this site object.
- Return type
pywikibot.Page or None
- Raises
pywikibot.exceptions.UnknownExtensionError – site has no Wikibase extension
NotimplementedError – method not implemented for a Wikibase site
-
protect
(page, protections: dict, reason: str, expiry=None, summary='[deprecated name of reason]', **kwargs)[source]¶ (Un)protect a wiki page. Requires administrator status.
- See
- Parameters
protections – A dict mapping type of protection to protection level of that type. Valid restriction types are ‘edit’, ‘create’, ‘move’ and ‘upload’. Valid restriction levels are ‘’ (equivalent to ‘none’ or ‘all’), ‘autoconfirmed’, and ‘sysop’. If None is given, however, that protection will be skipped.
reason – Reason for the action
expiry (pywikibot.Timestamp, string in GNU timestamp format (including ISO 8601)) – When the block should expire. This expiry will be applied to all protections. If None, ‘infinite’, ‘indefinite’, ‘never’, or ‘’ is given, there is no expiry.
-
protection_levels
()[source]¶ Return the protection levels available on this site.
- Returns
protection types available
- Return type
set of str instances
- See
Siteinfo._get_default()
-
protection_types
()[source]¶ Return the protection types available on this site.
- Returns
protection types available
- Return type
set of str instances
- See
Siteinfo._get_default()
-
purgepages
(pages, forcelinkupdate: bool = False, forcerecursivelinkupdate: bool = False, converttitles: bool = False, redirects: bool = False) → bool[source]¶ Purge the server’s cache for one or multiple pages.
- Parameters
pages – list of Page objects
redirects (bool) – Automatically resolve redirects.
converttitles – Convert titles to other variants if necessary. Only works if the wiki’s content language supports variant conversion.
forcelinkupdate – Update the links tables.
forcerecursivelinkupdate – Update the links table, and update the links tables for any page that uses this page as a template.
- Returns
True if API returned expected response; False otherwise
-
property
redirect_regex
¶ Return a compiled regular expression matching on redirect pages.
Group 1 in the regex match object will be the target title.
-
rollbackpage
(page, **kwargs)[source]¶ Roll back page to version before last user’s edits.
The keyword arguments are those supported by the rollback API.
As a precaution against errors, this method will fail unless the page history contains at least two revisions, and at least one that is not by the same user who made the last edit.
- Parameters
page – the Page to be rolled back (must exist)
- Keyword Arguments
user – the last user to be rollbacked; default is page.latest_revision.user
-
server_time
()[source]¶ Return a Timestamp object representing the current server time.
It uses the ‘time’ property of the siteinfo ‘general’. It’ll force a reload before returning the time.
- Returns
the current server time
- Return type
Timestamp
-
property
siteinfo
¶ Site information dict.
-
unblockuser
(user, reason: Optional[str] = None)[source]¶ Remove the block for the user.
- See
- Parameters
user (
pywikibot.User
) – The username/IP without a namespace.reason – Reason for the unblock.
-
undelete
(page, reason: str, *, revisions=None, fileids=None)[source]¶ Undelete page from the wiki. Requires appropriate privilege level.
Renamed in version 6.1.
New in version 6.1: fileids parameter was added.
Changed in verson 6.1: keyword argument required for revisions.
- Parameters
page (pywikibot.BasePage) – Page to be deleted.
reason – Undeletion reason.
revisions (list) – List of timestamps to restore. If None, restores all revisions.
fileids (list) – List of fileids to restore.
-
upload
(filepage, imagepage='[deprecated name of filepage]', *, source_filename: Optional[str] = None, source_url: Optional[str] = None, comment: Optional[str] = None, text: Optional[str] = None, watch: bool = False, ignore_warnings=False, chunk_size: int = 0, asynchronous: bool = False, _file_key: Optional[str] = None, _offset: Union[bool, int] = 0, _verify_stash: Optional[bool] = None, report_success: Optional[bool] = None)[source]¶ Upload a file to the wiki.
Either source_filename or source_url, but not both, must be provided.
Changed in version 6.0: keyword arguments required for all parameters except filepage.
Changed in version 6.2: asynchronous upload is used if asynchronous parameter is set.
- Parameters
filepage – a FilePage object from which the wiki-name of the file will be obtained.
source_filename – path to the file to be uploaded
source_url – URL of the file to be uploaded
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 (bool or callable or iterable of str) – 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: 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 bytes for chunked uploading (see https://www.mediawiki.org/wiki/API:Upload#Chunked_uploading). It will only upload in chunks, if the chunk size is positive but lower than the file size.
asynchronous – Make potentially large file operations asynchronous on the server side when possible.
_file_key – Reuses an already uploaded file using the filekey. If None (default) it will upload the file.
_offset – When file_key is not None this can be an integer to continue a previously canceled chunked upload. If False it treats that as a finished upload. If True it requests the stash info from the server to determine the offset. By default starts at 0.
_verify_stash – Requests the SHA1 and file size uploaded and compares it to the local file. Also verifies that _offset is matching the file size if the _offset is an int. If _offset is False if verifies that the file size match with the local file. If None it’ll verifies the stash when a file key and offset is given.
report_success – If the upload was successful it’ll print a success message and if ignore_warnings is set to False it’ll raise an 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.
-
property
userinfo
¶ Retrieve userinfo from site and store in _userinfo attribute.
To force retrieving userinfo ignoring cache, just delete this property.
self._userinfo will be a dict with the following keys and values:
id: user id (numeric str)
name: username (if user is logged in)
anon: present if user is not logged in
groups: list of groups (could be empty)
rights: list of rights (could be empty)
message: present if user has a new message on talk page
blockinfo: present if user is blocked (dict)
-
validate_tokens
(types: list) → list[source]¶ Validate if requested tokens are acceptable.
Valid tokens depend on mw version.
-
version
() → str[source]¶ Return live project version number as a string.
Use
pywikibot.site.mw_version
to compare MediaWiki versions.
-
watch
(pages, unwatch: bool = False) → bool[source]¶ Add or remove pages from watchlist.
- See
- Parameters
pages (A page object, a page-title string, or sequence of them. Also accepts a single pipe-separated string like 'title1|title2'.) – A single page or a sequence of pages.
unwatch – If True, remove pages from watchlist; if False add them (default).
- Returns
True if API returned expected response; False otherwise
- Raises
KeyError – ‘watch’ isn’t in API response
-
class
-
class
pywikibot.site.
BaseSite
(code: str, fam=None, user=None)[source]¶ Bases:
pywikibot.tools.ComparableMixin
Site methods that are independent of the communication interface.
- Parameters
code (str) – the site’s language code
fam (str or pywikibot.family.Family) – wiki family name (optional)
user (str) – bot user name (optional)
-
property
code
¶ The identifying code for this Site equal to the wiki prefix.
By convention, this is usually an ISO language code, but it does not have to be.
-
property
doc_subpage
¶ Return the documentation subpage for this Site.
- Return type
tuple
-
property
family
¶ The Family object for this Site’s wiki family.
-
isInterwikiLink
(text)[source]¶ Return True if text is in the form of an interwiki link.
If a link object constructed using “text” as the link text parses as belonging to a different site, this method returns True.
-
property
lang
¶ The ISO language code for this Site.
Presumed to be equal to the site code, but this can be overridden.
-
lock_page
(page, block=True)[source]¶ Lock page for writing. Must be called before writing any page.
We don’t want different threads trying to write to the same page at the same time, even to different sections.
- Parameters
page (pywikibot.Page) – the page to be locked
block – if true, wait until the page is available to be locked; otherwise, raise an exception if page can’t be locked
-
property
namespaces
¶ Return dict of valid namespaces on this wiki.
-
ns_normalize
(value)[source]¶ Return canonical local form of namespace name.
- Parameters
value (str) – A namespace name
-
redirectRegex
(pattern=None)[source]¶ Return a compiled regular expression matching on redirect pages.
Group 1 in the regex match object will be the target title.
-
sametitle
(title1: str, title2: str) → bool[source]¶ Return True if title1 and title2 identify the same wiki page.
title1 and title2 may be unequal but still identify the same page, if they use different aliases for the same namespace.
-
property
sitename
¶ String representing this Site’s name and code.
-
property
throttle
¶ Return this Site’s throttle. Initialize a new one if needed.
-
unlock_page
(page)[source]¶ Unlock page. Call as soon as a write operation has completed.
- Parameters
page (pywikibot.Page) – the page to be locked
-
class
pywikibot.site.
ClosedSite
(code, fam, user=None)[source]¶ Bases:
pywikibot.site._apisite.APISite
Site closed to read-only mode.
-
class
pywikibot.site.
DataSite
(*args, **kwargs)[source]¶ Bases:
pywikibot.site._apisite.APISite
Wikibase data capable site.
-
addClaim
(entity, claim, bot=True, summary=None)[source]¶ Add a claim.
- Parameters
entity (WikibaseEntity) – Entity to modify
claim (pywikibot.Claim) – Claim to be added
bot (bool) – Whether to mark the edit as a bot edit
summary (str) – Edit summary
-
changeClaimTarget
(claim, snaktype='value', bot=True, summary=None)[source]¶ Set the claim target to the value of the provided claim target.
- Parameters
claim (pywikibot.Claim) – The source of the claim target value
snaktype (str ('value', 'novalue' or 'somevalue')) – An optional snaktype. Default: ‘value’
bot (bool) – Whether to mark the edit as a bot edit
summary (str) – Edit summary
-
property
concept_base_uri
¶ Return the base uri for concepts/entities.
- Returns
concept base uri
- Return type
str
-
editEntity
(entity, data, bot=True, identification='[deprecated name of entity]', **kwargs)[source]¶ Edit entity.
Note: This method is unable to create entities other than ‘item’ if dict with API parameters was passed to ‘entity’ parameter.
- Parameters
entity (WikibaseEntity or dict) – Page to edit, or dict with API parameters to use for entity identification
data (dict) – data updates
bot (bool) – Whether to mark the edit as a bot edit
- Returns
New entity data
- Return type
dict
-
getPropertyType
(prop)[source]¶ Obtain the type of a property.
This is used specifically because we can cache the value for a much longer time (near infinite).
-
get_entity_for_entity_id
(entity_id)[source]¶ Return a new instance for given entity id.
- Raises
pywikibot.exceptions.NoWikibaseEntityError – there is no entity with the id
- Returns
a WikibaseEntity subclass
- Return type
WikibaseEntity
-
get_namespace_for_entity_type
(entity_type)[source]¶ Return namespace for given entity type.
- Returns
corresponding namespace
- Return type
-
linkTitles
(page1, page2, bot=True)[source]¶ Link two pages together.
- Parameters
page1 (pywikibot.Page) – First page to link
page2 (pywikibot.Page) – Second page to link
bot (bool) – Whether to mark the edit as a bot edit
- Returns
dict API output
- Return type
dict
-
loadcontent
(identification, *props)[source]¶ Fetch the current content of a Wikibase item.
This is called loadcontent since wbgetentities does not support fetching old revisions. Eventually this will get replaced by an actual loadrevisions.
- Parameters
identification (dict) – Parameters used to identify the page(s)
props – the optional properties to fetch.
-
mergeItems
(from_item, to_item, ignore_conflicts=None, summary=None, bot=True, ignoreconflicts='[deprecated name of ignore_conflicts]', fromItem='[deprecated name of from_item]', toItem='[deprecated name of to_item]')[source]¶ Merge two items together.
- Parameters
from_item (pywikibot.ItemPage) – Item to merge from
to_item (pywikibot.ItemPage) – Item to merge into
ignore_conflicts (list of str) – Which type of conflicts (‘description’, ‘sitelink’, and ‘statement’) should be ignored
summary (str) – Edit summary
bot (bool) – Whether to mark the edit as a bot edit
- Returns
dict API output
- Return type
dict
-
preload_entities
(pagelist, groupsize=50)[source]¶ Yield subclasses of WikibaseEntity’s with content prefilled.
Note that pages will be iterated in a different order than in the underlying pagelist.
- Parameters
pagelist – an iterable that yields either WikibaseEntity objects, or Page objects linked to an ItemPage.
groupsize (int) – how many pages to query at a time
-
property
property_namespace
¶ Return namespace for properties.
- Returns
property namespace
- Return type
-
save_claim
(claim, summary=None, bot=True)[source]¶ Save the whole claim to the wikibase site.
- Parameters
claim (pywikibot.Claim) – The claim to save
bot (bool) – Whether to mark the edit as a bot edit
summary (str) – Edit summary
-
search_entities
(search: str, language: str, total: Optional[int] = None, limit='[deprecated name of total]', **kwargs)[source]¶ Search for pages or properties that contain the given text.
- Parameters
search – Text to find.
language – Language to search in.
total – Maximum number of pages to retrieve in total, or None in case of no limit.
- Returns
‘search’ list from API output.
- Return type
Generator
-
set_redirect_target
(from_item, to_item, bot=True)[source]¶ Make a redirect to another item.
- Parameters
to_item (pywikibot.ItemPage) – title of target item.
from_item (pywikibot.ItemPage) – Title of the item to be redirected.
bot (bool) – Whether to mark the edit as a bot edit
-
property
sparql_endpoint
¶ Return the sparql endpoint url, if any has been set.
- Returns
sparql endpoint url
- Return type
str|None
-
tabular_data_repository
()[source]¶ Return Site object for the tabular-datas repository e.g. commons.
-
wbsetaliases
(itemdef, aliases, **kwargs)[source]¶ Set aliases for a single Wikibase entity.
See self._wbset_action() for parameters
-
wbsetdescription
(itemdef, description, **kwargs)[source]¶ Set description for a single Wikibase entity.
See self._wbset_action()
-
-
class
pywikibot.site.
Namespace
(id, canonical_name: Optional[str] = None, custom_name: Optional[str] = None, aliases: Optional[list] = None, **kwargs)[source]¶ Bases:
collections.abc.Iterable
,pywikibot.tools.ComparableMixin
Namespace site data object.
This is backwards compatible with the structure of entries in site._namespaces which were a list of:
[customised namespace, canonical namespace name?, namespace alias*]
If the canonical_name is not provided for a namespace between -2 and 15, the MediaWiki built-in names are used. Image and File are aliases of each other by default.
If only one of canonical_name and custom_name are available, both properties will have the same value.
- Parameters
canonical_name – Canonical name
custom_name – Name defined in server LocalSettings.php
aliases – Aliases
-
CATEGORY
= 14¶
-
CATEGORY_TALK
= 15¶
-
FILE
= 6¶
-
FILE_TALK
= 7¶
-
HELP
= 12¶
-
HELP_TALK
= 13¶
-
MAIN
= 0¶
-
MEDIA
= -2¶
-
MEDIAWIKI
= 8¶
-
MEDIAWIKI_TALK
= 9¶
-
PROJECT
= 4¶
-
PROJECT_TALK
= 5¶
-
SPECIAL
= -1¶
-
TALK
= 1¶
-
TEMPLATE
= 10¶
-
TEMPLATE_TALK
= 11¶
-
USER
= 2¶
-
USER_TALK
= 3¶
-
classmethod
builtin_namespaces
(case='first-letter')[source]¶ Return a dict of the builtin namespaces.
-
canonical_namespaces
= {-2: 'Media', -1: 'Special', 0: '', 1: 'Talk', 2: 'User', 3: 'User talk', 4: 'Project', 5: 'Project talk', 6: 'File', 7: 'File talk', 8: 'MediaWiki', 9: 'MediaWiki talk', 10: 'Template', 11: 'Template talk', 12: 'Help', 13: 'Help talk', 14: 'Category', 15: 'Category talk'}¶
-
class
pywikibot.site.
NamespacesDict
(namespaces)[source]¶ Bases:
collections.abc.Mapping
,pywikibot.tools.SelfCallMixin
An immutable dictionary containing the Namespace instances.
It adds a deprecation message when called as the ‘namespaces’ property of APISite was callable.
Create new dict using the given namespaces.
-
lookup_name
(name: str) → Optional[pywikibot.site._namespace.Namespace][source]¶ Find the Namespace for a name also checking aliases.
- Parameters
name – Name of the namespace.
-
lookup_normalized_name
(name: str) → Optional[pywikibot.site._namespace.Namespace][source]¶ Find the Namespace for a name also checking aliases.
The name has to be normalized and must be lower case.
- Parameters
name – Name of the namespace.
-
resolve
(identifiers) → list[source]¶ Resolve namespace identifiers to obtain Namespace objects.
Identifiers may be any value for which int() produces a valid namespace id, except bool, or any string which Namespace.lookup_name successfully finds. A numerical string is resolved as an integer.
- Parameters
identifiers (iterable of str or Namespace key, or a single instance of those types) – namespace identifiers
- Returns
list of Namespace objects in the same order as the identifiers
- Raises
KeyError – a namespace identifier was not resolved
TypeError – a namespace identifier has an inappropriate type such as NoneType or bool
-
-
class
pywikibot.site.
RemovedSite
(code: str, fam=None, user=None)[source]¶ Bases:
pywikibot.site._basesite.BaseSite
Site removed from a family.
- Parameters
code (str) – the site’s language code
fam (str or pywikibot.family.Family) – wiki family name (optional)
user (str) – bot user name (optional)
-
class
pywikibot.site.
Siteinfo
(site)[source]¶ Bases:
collections.abc.Container
A ‘dictionary’ like container for siteinfo.
This class queries the server to get the requested siteinfo property. Optionally it can cache this directly in the instance so that later requests don’t need to query the server.
All values of the siteinfo property ‘general’ are directly available.
Initialise it with an empty cache.
-
BOOLEAN_PROPS
= {'general': ['imagewhitelistenabled', 'langconversion', 'titleconversion', 'rtl', 'readonly', 'writeapi', 'variantarticlepath', 'misermode', 'uploadsenabled'], 'magicwords': ['case-sensitive'], 'namespaces': ['subpages', 'content', 'nonincludable']}¶
-
WARNING_REGEX
= re.compile('Unrecognized values? for parameter ["\\\']siprop["\\\']: (.+?)\\.?$')¶
-
get
(key: str, get_default: bool = True, cache: bool = True, expiry=False)[source]¶ Return a siteinfo property.
It will never throw an APIError if it only stated, that the siteinfo property doesn’t exist. Instead it will use the default value.
- Parameters
key – The name of the siteinfo property.
get_default – Whether to throw an KeyError if the key is invalid.
cache – Caches the result internally so that future accesses via this method won’t query the server.
expiry (int/float (days),
datetime.timedelta
, False (never expired), True (always expired)) – If the cache is older than the expiry it ignores the cache and queries the server to get the newest value.
- Returns
The gathered property
- Return type
various
- Raises
KeyError – If the key is not a valid siteinfo property and the get_default option is set to False.
- See
_get_siteinfo
-
get_requested_time
(key: str)[source]¶ Return when ‘key’ was successfully requested from the server.
If the property is actually in the siprop ‘general’ it returns the last request from the ‘general’ siprop.
- Parameters
key – The siprop value or a property of ‘general’.
- Returns
The last time the siprop of ‘key’ was requested.
- Return type
None (never), False (default),
datetime.datetime
(cached)
-