wiki

Classes for use by a client to interact with a MediaWiki instance's API

Wiki

General wiki-interfacing functionality and config data

__del__()

Finalizer, releases resources used by the internal requests session

__init__(domain='en.wikipedia.org', username=None, password=None, cookie_jar=Path('.'), api_endpoint=None)

Initializer, creates a new Wiki object.

Parameters:

Name	Type	Description	Default
domain	str	The shorthand domain of the Wiki to target. Defaults to "en.wikipedia.org".	'en.wikipedia.org'
username	str	The username to login as. If password is not set, then attempt to use an env var named <USERNAME>_PW, where <USERNAME> is username capitalized and all spaces are replaced with _. Defaults to None.	None
password	str	The password to use when logging in. Does nothing if username is not set. Defaults to None.	None
cookie_jar	Path	The directory to save/read cookies to/from. Disable by setting this to None. Note that in order to save cookies you still have to call self.save_cookies(). Defaults to Path(".").	Path('.')
api_endpoint	str	The base API endpoint on your wiki. This usually looks something like https://<YOUR_DOMAIN>/w/api.php. Useful if your wiki uses a non-standard endpoint. If set, domain will be ignored. Defaults to None.	None

Raises:

Type	Description
RuntimeError	If username and/or password was set and login failed.

__repr__()

Generate a str representation of this Wiki object. Useful for logging.

Returns:

Name	Type	Description
str	str	A str representation of this Wiki object.

all_users(groups=[])

Lists all users on a wiki. Can filter users by right(s) they have been assigned.

Parameters:

Name	Type	Description	Default
groups	Union[list[str], str]	The group(s) to filter by (e.g. sysop, bot). Optional, leave empty to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: a list containing usernames (without the User: prefix) that match the specified crteria.

categories_on_page(title)

Fetch the categories used on a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query.	required

Returns:

Type	Description
list[str]	list[str]: The list of categories used on title.

category_members(title, ns=[])

Fetches the elements in a category.

Parameters:

Name	Type	Description	Default
title	str	The title of the category to fetch elements from. Must include Category: prefix.	required
ns	Union[list[Union[NS, str]], NS, str]	Only return results that are in these namespaces. Optional, set empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: a list containing title's category members.

category_size(title)

Queries the wiki and gets the number of pages categorized in title.

Parameters:

Name	Type	Description	Default
title	str	The category to get the size of. Must start with Category: prefix.	required

Returns:

Name	Type	Description
int	int	The number of pages in this category.

clear_cookies()

Deletes any saved cookies from disk.

contribs(user, older_first=False, ns=[])

Fetches contributions of a user. Warning: this fetches all of user's contributions!

Parameters:

Name	Type	Description	Default
user	str	The username to query, excluding the User: prefix.	required
older_first	bool	Set True to fetch older elements first. Defaults to False.	False
ns	list[Union[NS, str]]	Only return results that are in these namespaces. Optional, set empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[Contrib]	list[Contrib]: The contributions of user.

convert_ns(title, ns)

Converts the namespace of the specified title to another namespace. PRECONDITION: title is well-formed.

Parameters:

Name	Type	Description	Default
title	str	The title to convert	required
ns	Union[str, NS]	The namespace to convert title to.	required

Returns:

Name	Type	Description
str	str	title, converted to namespace ns

delete(title, reason)

Deletes a page. PRECONDITION: wiki must be logged in and have the ability to delete pages for this to work.

Parameters:

Name	Type	Description	Default
title	str	The title to delete	required
reason	str	The reason for deleting this page.	required

Returns:

Name	Type	Description
bool	bool	True if this action succeeded.

deleted_revisions(title, older_first=False, include_text=False)

Fetches all the deleted revisions of title. Plan accordingly when querying pages that have many deleted revisions! PRECONDITION: You must be logged in and have admin rights in order for this to work.

Parameters:

Name	Type	Description	Default
title	str	The title to get deleted revisions for.	required
older_first	bool	Set True to get older revisions first. Defaults to False.	False
include_text	bool	If True, then also fetch the wikitext of each revision. Will populate the Revision.text field. Warning: enabling this is expensive for large pages with many deleted revisions. Defaults to False.	False

Returns:

Type	Description
list[Revision]	list[Revision]: A list containing the (deleted) Revision objects of title

duplicate_files(title, local_only=True)

Find dupliates of title if possible.

Parameters:

Name	Type	Description	Default
title	str	The title to get duplicates of. Must start with File: prefix.	required
local_only	bool	Set False to also search the associated shared media repository wiki. If that sounded like a foreign language to you, then ignore this parameter. Defaults to True.	True

Returns:

Type	Description
list[str]	list[str]: The list of files that duplicate title.

edit(title, text=None, summary='', prepend=None, append=None, minor=False)

Attempts to edit a page on the Wiki. Can replace text or append/prepend text.

Parameters:

Name	Type	Description	Default
title	str	The title to edit.	required
text	str	Text to replace the current page's contents with. Mutually exclusive with prepend/append. Defaults to None.	None
summary	str	The edit summary to use. Defaults to "".	''
prepend	str	Text to prepend to the page. Mutually exclusive with text. Defaults to None.	None
append	str	Text to append to the page. Mutually exclusive with text. Defaults to None.	None
minor	bool	Set True to mark this edit as minor. Defaults to False.	False

Returns:

Name	Type	Description
bool	bool	True if the edit was successful.

exists(title)

Query the wiki and determine if title exists on the wiki.

Parameters:

Name	Type	Description	Default
title	str	the title to query.	required

Returns:

Name	Type	Description
bool	bool	True if title exists on the wiki.

external_links(title)

Fetches external links on a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required

Returns:

Type	Description
list[str]	list[str]: The list of external links contained in the text of title.

file_usage(title)

Fetch the titles of all pages embedding/displaying title.

Parameters:

Name	Type	Description	Default
title	str	The file to query.	required

Returns:

Type	Description
list[str]	list[str]: The list of all pages displaying title.

filter_by_ns(titles, *nsl)

Creates a copy of titles and strips out any title that isn't in the namespaces specified in nsl.

Parameters:

Name	Type	Description	Default
titles	list[str]	The list of titles to process.	required

Returns:

Type	Description
list[str]	list[str]: A copy of titles with any titles in nsl excluded.

first_editor_of(title)

Gets the user who created title.

Parameters:

Name	Type	Description	Default
title	str	The title of the page to query	required

Returns:

Name	Type	Description
str	str	The username of the user who created title. Does not include User: prefix. Returns None if the page does not exist.

global_usage(title)

Fetch the global file usage of a media file. Only works with wikis that utilize a shared media respository wiki.

Parameters:

Name	Type	Description	Default
title	str	The file to get global usage usage of. Must start with File: prefix.	required

Returns:

Type	Description
list[tuple]	list[tuple]: A list of tuple (page title, wiki hostname) containing the global usages of the file.

image_info(title)

Fetch image (file) info for media files. This is basically image metadata for each uploaded media file under the specified title. See dwrap.ImageInfo for details.

Parameters:

Name	Type	Description	Default
title	str	The file to get image info of. Must start with the File: prefix	required

Returns:

Type	Description
list[ImageInfo]	list[ImageInfo]: The list of ImageInfo objects associated with title.

images_on_page(title)

Fetch images/media files used on a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required

Returns:

Type	Description
list[str]	list[str]: The list of images/files that are used on title.

in_ns(title, ns)

Checks if a title belongs to a namespace or namespaces. This is a lexical operation only, so title must be well-formed.

Parameters:

Name	Type	Description	Default
title	str	The title to check.	required
ns	Union[int, NS, str, tuple[Union[int, NS, str]]]	The namespace or namespaces (pass as a tuple) to check	required

Returns:

Name	Type	Description
bool	bool	True if title is a member of the namespace(s), ns.

is_talk_page(title)

Determines if title is part of a talk page namespace. This is a lexical operation and does not perform an api query.

Parameters:

Name	Type	Description	Default
title	str	The title to check	required

Returns:

Name	Type	Description
bool	bool	True if title is a talk page.

last_editor_of(title)

Gets the user who most recently edited title.

Parameters:

Name	Type	Description	Default
title	str	The title of the page to query	required

Returns:

Name	Type	Description
str	str	The username of the user who most recently edited title. Does not include User: prefix. Returns None if the page does not exist.

links_on_page(title, ns=[])

Fetch wiki links on a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required
ns	Union[list[Union[NS, str]], NS, str]	Restrict returned output to titles in these namespaces. Optional, set to empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: The list of wiki links contained in the text of title

list_duplicate_files()

List files on a wiki which have duplicates by querying the Special page Special:ListDuplicatedFiles. This reads the entire list, and may return up to 5000 elements.

Returns:

Type	Description
list[str]	list[str]: A list containing files that have duplicates on the wiki.

list_user_rights(username=None)

Lists user rights for the specified user.

Parameters:

Name	Type	Description	Default
username	str	The user to get rights for. Usernames must be well formed (e.g. no wacky capitalization), and must not contain the User: prefix. If set to None, then Wiki's username will be used. Defaults to None.	None

Returns:

Type	Description
list[str]	list[str]: The rights for the specified user. None if something went wrong.

login(username, password=None)

Attempts to login this Wiki object. If successful, all future calls will be automatically include authentication. If password is not set, then the method will try looking using an environment variable of the form <username>_PW, where <username> is username capitalized, with all spaces replaced with _. If username and/or password are evaluated to be empty/None, then False will be returned immediately.

Parameters:

Name	Type	Description	Default
username	str	The username to login with	required
password	str	The password to login with. Defaults to None.	None

Returns:

Name	Type	Description
bool	bool	True if login was successful.

logs(title=None, log_type=None, log_action=None, user=None, ns=None, tag=None, start=None, end=None, older_first=False)

Fetches Special:Log entries from a wiki. PRECONDITION: if start and end are both set, then start must occur before end. WARNING: Not recommended to call this with no arguments on large Wikis, this methods returns all matching logs.

Parameters:

Name	Type	Description	Default
title	str	The title of the page to get logs for, if applicable. Defaults to None.	None
log_type	str	The type of log to fetch (e.g. "delete"). Defaults to None.	None
log_action	str	The type and sub-action of the log to fetch (e.g. "delete/restore"). Overrides log_type. Defaults to None.	None
user	str	The user associated with the log action, if applicable. Do not include User: prefix. Defaults to None.	None
ns	Union[NS, str]	Only return results that are in this namespace. Defaults to None.	None
tag	str	Only return results that are tagged with this tag. Defaults to None.	None
start	datetime	Set to filter out revisions older than this date. If no timezone is specified in the datetime, then UTC is assumed. Defaults to None.	None
end	datetime	Set to filter out revisions newer than this date. If no timezone is specified in the datetime, then UTC is assumed. Defaults to None.	None
older_first	bool	Set to True to fetch older log entries first. Defaults to False.	False

Returns:

Type	Description
list[Log]	list[Log]: A list of Log as specified.

normalize_title(title)

Normalizes titles to match their canonical versions. Usually this means fixing capitalization or replacing underscores with spaces.

Parameters:

Name	Type	Description	Default
title	str	The title to normalize.	required

Returns:

Name	Type	Description
str	str	The normalized version of title.

not_in_ns(title, ns)

Checks if a title does not belong to a namespace or namespaces. This is a lexical operation only, so title must be well-formed.

Parameters:

Name	Type	Description	Default
title	str	The title to check.	required
ns	Union[int, NS, str, tuple[Union[int, NS, str]]]	The namespace or namespaces (pass as a tuple) to check	required

Returns:

Name	Type	Description
bool	bool	True if title is NOT a member of the namespace(s), ns.

nss(title)

Strips the namespace prefix from a title.

Parameters:

Name	Type	Description	Default
title	str	The title to remove the namespace from.	required

Returns:

Name	Type	Description
str	str	title, without a namespace.

page_of(title)

Gets the content page associated with title. If title is a content page, then None will be returned.

Parameters:

Name	Type	Description	Default
title	str	The content page associated with title.	required

Returns:

Name	Type	Description
str	str	The content page associated with title, or None if title is already a content page.

page_text(title)

Queries the Wiki for the text of title.

Parameters:

Name	Type	Description	Default
title	str	The title to get page text of.	required

Returns:

Name	Type	Description
str	str	The text of title. None if title does not exist.

parse(title=None, text=None)

Parses the title or text into WikiText/WTemplate objects. If title and text are both specified, then text will be parsed as if it was on title.

Parameters:

Name	Type	Description	Default
title	str	The title to use. If text is not specified, then the text of title will be automatically fetched and parsed. Defaults to None.	None
text	str	The text to parse. If title is specified, then the text will be parsed as if it is was published on title. Defaults to None.	None

Returns:

Name	Type	Description
WikiText	WikiText	The result of the parsing operation. None if something went wrong.

prefix_index(ns, prefix)

Performs a prefix index query and returns all matching titles.

Parameters:

Name	Type	Description	Default
ns	Union[NS, str]	The namespace to search in.	required
prefix	str	Fetches all titles in the specified namespace that start with this str. To return subpages only, append a / character to this param.	required

Returns:

Type	Description
list[str]	list[str]: A list containing files that match the specified prefix index.

purge(titles)

Attempts to purge the server-side caches of titles. Exits and outputs messages to standard out on the first failure.

Parameters:

Name	Type	Description	Default
titles	Iterable[str]	The titles to purge	required

Returns:

Name	Type	Description
bool	bool	True if all pages in titles were successfully purged.

random(ns=[])

Fetches a random page from the wiki.

Parameters:

Name	Type	Description	Default
ns	list[Union[NS, str]]	Only return results that are in these namespaces. Optional, set empty list to disable. Defaults to [].	[]

Returns:

Name	Type	Description
str	str	A random page from the wiki as specified, or None if this was not possible.

replace_text(title, pattern, replacement='', summary='')

Convenience method, edits title and replaces all instances of target_text with replacement in its text.

Parameters:

Name	Type	Description	Default
title	str	The page to edit.	required
pattern	Union[Pattern, str]	The regular expression describing the text to replace on title.	required
replacement	str	The text to replace all matches of pattern with. Defaults to "".	''
summary	str	The edit summary to use. Defaults to "".	''

Returns:

Name	Type	Description
bool	bool	True if the operation was successful.

resolve_redirect(title)

Fetch the target of a redirect page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required

Returns:

Name	Type	Description
str	str	The redirect target. If title was not a redirect, then title will be returned.

revisions(title, older_first=False, start=None, end=None, include_text=False)

Fetches all the revisions of title. Plan accordingly when querying pages that have many revisions!

Parameters:

Name	Type	Description	Default
title	str	The title to get revisions for.	required
older_first	bool	Set True to get older revisions first. Defaults to False.	False
start	datetime	Set to filter out revisions older than this date. If no timezone is specified in the datetime, then UTC is assumed. Defaults to None.	None
end	datetime	Set to filter out revisions newer than this date. If no timezone is specified in the datetime, then UTC is assumed. Defaults to None.	None
include_text	bool	If True, then also fetch the wikitext of each revision. Will populate the Revision.text field. Warning: enabling this is expensive for large pages with many revisions. Defaults to False.	False

Returns:

Type	Description
list[Revision]	list[Revision]: A list containing the Revision objects of title

save_cookies()

Write the cookies of the Wiki object to disk, so they can be used in the future. Does nothing if self.cookie_jar is set to None. Raises RuntimeError if the Wiki is not logged in.

search(phrase, ns=[])

Perform a search on the wiki.

Parameters:

Name	Type	Description	Default
phrase	str	The phrase to query with	required
ns	list[Union[NS, str]]	Only return results that are in these namespaces. Optional, set empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: A list containing the results of the search.

stashed_files()

Fetch the user's stashed files. PRECONDITION: You must be logged in for this to work

Returns:

Type	Description
list[tuple[str, int, str]]	list[tuple[str, int]]: a list of 3-tuple where each tuple is of the form (file key, file size, status). Known values for status: "finished", "chunks"

talk_page_of(title)

Gets the talk page of title. If title is a talk page, then None will be returned.

Parameters:

Name	Type	Description	Default
title	str	The talk page associated with title.	required

Returns:

Name	Type	Description
str	str	The talk page of title, or None if title is already a talk page.

templates_on_page(title)

Fetch templates transcluded on a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required

Returns:

Type	Description
list[str]	list[str]: A list of tempalates transcluded on title.

undelete(title, reason, revs=None)

Undeletes a page. PRECONDITION: wiki must be logged in and have the ability to restore pages for this to work.

Parameters:

Name	Type	Description	Default
title	str	The title to restore	required
reason	str	The reason for restoring this page.	required
revs	list[Revision]	A list of revisions to restore. If not set, then all deleted revisions will be restored. Defaults to None.	None

Returns:

Name	Type	Description
bool	bool	True if this action succeeded.

upload(path, title, desc='', summary='', max_retries=5)

Uploads a file to the target Wiki.

Parameters:

Name	Type	Description	Default
path	Path	the local path on your computer pointing to the file to upload	required
title	str	The title to upload the file to, excluding the "File:" namespace.	required
desc	str	The text to go on the file description page. Defaults to "".	''
summary	str	The upload log summary to use. Defaults to "".	''
max_retries	int	The maximum number of retry attempts in the event of an error. Defaults to 5.	5

Returns:

Name	Type	Description
bool	bool	True if the upload was successful.

uploadable_filetypes()

Queries the Wiki for all acceptable file types which may be uploaded to this Wiki. PRECONDITION: the target Wiki permits file uploads.

Returns:

Name	Type	Description
set	set	A set containing all acceptable file types as their extensions (. prefix is not included)

user_uploads(user)

Gets the uploads of a user.

Parameters:

Name	Type	Description	Default
user	str	The username to query, without the User: prefix.	required

Returns:

Type	Description
list[str]	list[str]: A list containing the files uploaded by user.

what_links_here(title, redirects_only=False, ns=[])

Fetch pages that wiki link (locally) to a page.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required
redirects_only	bool	Set True to get the titles that redirect to this page. Defaults to False.	False
ns	Union[list[Union[NS, str]], NS, str]	Restrict returned output to titles in these namespaces. Optional, set to empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: The list of pages that link to title.

what_transcludes_here(title, ns=[])

Fetch pages that translcude a page. If querying for templates, you must include the Template: prefix.

Parameters:

Name	Type	Description	Default
title	str	The title to query	required
ns	Union[list[Union[NS, str]], NS, str]	Restrict returned output to titles in these namespaces. Optional, set to empty list to disable. Defaults to [].	[]

Returns:

Type	Description
list[str]	list[str]: The list of pages that transclude title.

which_ns(title)

Determines which namespace a title belongs to.

Parameters:

Name	Type	Description	Default
title	str	The title to get the namespace of	required

Returns:

Name	Type	Description
str	str	The namespace, without it's : suffix. If main namespace, then "Main" will be returned

whoami()

Get this Wiki's username from the server. If not logged in, then this will return your external IP address.

Returns:

Name	Type	Description
str	str	If logged in, this Wiki's username. Otherwise, the external IP address of your device.