Pywikibot
The Pywikibot framework is a Python library that interfaces with the MediaWiki API version 1.31 or higher.
Also included are various general function scripts that can be adapted for different tasks.
For further information about the library excluding scripts see the full code documentation.
Quick start
git clone https://gerrit.wikimedia.org/r/pywikibot/core.git
cd core
git submodule update --init
pip install -r requirements.txt
python pwb.py <script_name>Or to install using PyPI (excluding scripts)
pip install pywikibot
pwb <scriptname>Our installation guide has more details for advanced usage.
Basic Usage
If you wish to write your own script it’s very easy to get started:
import pywikibot
site = pywikibot.Site('en', 'wikipedia') # The site we want to run our bot on
page = pywikibot.Page(site, 'Wikipedia:Sandbox')
page.text = page.text.replace('foo', 'bar')
page.save('Replacing "foo" with "bar"') # Saves the pageWikibase Usage
Wikibase is a flexible knowledge base software that drives Wikidata. A sample pywikibot script for getting data from Wikibase:
import pywikibot
site = pywikibot.Site('wikipedia:en')
repo = site.data_repository() # the Wikibase repository for given site
page = repo.page_from_repository('Q91') # create a local page for the given item
item = pywikibot.ItemPage(repo, 'Q91') # a repository item
data = item.get() # get all item data from repository for this itemScript example
Pywikibot provides bot classes to develop your own script easily:
import pywikibot
from pywikibot import pagegenerators
from pywikibot.bot import ExistingPageBot
class MyBot(ExistingPageBot):
update_options = {
'text': 'This is a test text',
'summary': 'Bot: a bot test edit with Pywikibot.'
}
def treat_page(self):
"""Load the given page, do some changes, and save it."""
text = self.current_page.text
text += '\n' + self.opt.text
self.put_current(text, summary=self.opt.summary)
def main(*args: str) -> None:
"""Parse command line arguments and invoke bot."""
options = {}
gen_factory = pagegenerators.GeneratorFactory()
# Option parsing
local_args = pywikibot.handle_args(args) # global options
local_args = gen_factory.handle_args(local_args) # generators options
for arg in local_args:
opt, sep, value = arg.partition(':')
if opt in ('-summary', '-text'):
options[opt[1:]] = value
MyBot(generator=gen_factory.getCombinedGenerator(), **options).run()
if __name__ == '__main__':
main()For more documentation on Pywikibot see our docs.
Roadmap
Release 11.8
Various performance, stability, and code quality improvements.
Raise ServerError instead of AssertionError for invalid APISite.userinfo() API response. (T423061)
Load only current revision ID with page.BasePage.latest_revision_id.
Return non-option defaults with bot.input_list_choice. (T305937)
Add APISite.geosearch() method. (T438772)
Preserve labels with different prefixes in textlib.replace_links. (T396719)
Resolve i18n.bundlespaths from package.
Add pywikibot.User.is_globally_blockedand APISite.is_globally_blocked() to support GlobalBlocking extension. (T394628)
Initialize the wrapped generator once per lifecycle with tools.collections.GeneratorWrapper.
Use functools.cache for date.escapePattern2.
Avoid mutating request inputs in comms.http.fetch.
Buffer textlib.GetDataHTMLoutput in textlib.GetDataHTML.textdata.
Short-circuit intersection cache checks in tools.itertools.intersect_generators.
Add PageViewInfoextension support with page.BasePage.pageviews and site.PageViewInfoMixin. (T325473)
Use plain dictionaries for Wikibase pywikibot.Claimmappings.
Add page.BasePage.flagged_stateand APSite.flagged_state() site method for FlaggedRevsinfo. (T410893)
Disable maxlag for meta queries, paraminfo and help. (T421642)
Added Ukrainian Vikidia and updated testing subdomains for that family.
Correctly propagate reference group hashes after page.WikibaseEntity.editEntity. (T367324)
Prevent recursive logging handler initialization. (T436130)
Avoid duplicate revision updates and avoid constructing cached file revisions again in FilePage.
Stop pre-encoding API titles because data.api.Requestnormalizes byte parameters back to strings before serialization.
Isolate cached tables by server URL in data.wikistatsmodule.
Exceptions from the tools.threading.ThreadedGenerator.runproducer are re-raised during iteration after yielding any queued results.
Release bounded capacity in tools.threading.BoundedPoolExecutor.submit when submission fails with any Exception.
Avoid duplicate key evaluation in tools.itertools.filter_unique.
Replace tools.strtoboolvalue checks with constant mapping.
Avoid unnecessary request if total is 0 in Category.articles().
Reject invalid tools.threading.ThreadListlimits.
Public reason and comment parameters used for page-action and upload summaries were renamed to summary. The old parameter names remain available as deprecated aliases. (T62442)
Cache valid site codes in titletranslate.translate.
Normalize family aliases in data.wikistats.WikiStats.getbefore cache lookup.
Preserve Windows commands without a file placeholder in editor.TextEditor.
Preserve existing endpoint query parameters in data.sparql.SparqlQuery.query.
Reset the retry counter for each query in data.sparql.SparqlQuery.
Deduplicate intersections with a single input in tools.itertools.intersect_generators.
Accept path-like filenames and detect suffixes case-insensitively in tools.open_archive.
Add support for all existing Beta Cluster wikis. (T225892)
Support selective page preloading of APISite.preloadpages with pagegenerators.PreloadingGeneratorand pagegenerators.DequePreloadingGenerator.
Apply title filters first in pagegenerators.GeneratorFactory.getCombinedGenerator and avoid loading page data for titles rejected by title filters.
Support immutable sequences in data.api.encode_url.
Clear bundle cache when switching packages with i18n.set_messages_package.
Use pathlib for path containment in config.shortpathand version.get_module_filename.
Add depth parameter to pagegenerators.PetScanPageGenerator.
The specialbots.UploadRobotclass now cleans up temporary download files after upload completion or failure, while preserving caller-provided local files.
Fix APISite.loadrevisions step handling.
Keep preload groupsize per site in pagegenerators.PreloadingGenerator.
Preserve colliding intersection items without hash() in tools.itertools.intersect_generators.
page.BasePage.getno longer validates section fragments or raises exceptions.SectionErrorfor them, as the method always retrieves the complete page text (T422856, T422859).
Update translations (i18n).
Add new family.WikimediaSubdomainFamily.
Update documentation for page.BasePage.exists. (T334341)
Deprecations
This section lists features, methods, parameters, or attributes that are deprecated and scheduled for removal in future Pywikibot releases.
Deprecated items may still work in the current release but are no longer recommended for use. Users should update their code according to the recommended alternatives.
Pywikibot follows a clear deprecation policy: features are typically deprecated in one release and removed in the third subsequent major release, remaining available for the two releases in between.
Pending removal in Pywikibot 12
9.6.0: BaseSite.languages()will be removed in favour of BaseSite.codes
9.5.0: DataSite.getPropertyType()will be removed in favour of DataSite.get_property_type()
9.3.0: page.BasePage.userNameand page.BasePage.isIpEditare deprecated in favour of user or anon attributes of page.BasePage.latest_revisionproperty
9.3.0: botflag parameter of Page.save(), Page.put() and Page.set_redirect_target()was renamed to bot
9.2.0: All parameters of Page.templatesand Page.itertemplates()must be given as keyworded arguments
9.2.0: Imports of loggingfunctions from the botmodule are deprecated and will be desupported
9.2.0: total argument in -logevents pagegenerators option is deprecated; use -limit instead (T128981)
9.0.0: The content parameter of proofreadpage.IndexPage.page_genis deprecated and will be ignored (T358635)
9.0.0: next parameter of userinterfaces.transliteration.Transliterator.transliteratewas renamed to succ
9.0.0: userinterfaces.transliteration.transliterator object was renamed to Transliterator
9.0.0: The type parameter of site.APISite.protectedpages() was renamed to protect_type
9.0.0: The all parameter of site.APISite.namespace() was renamed to all_ns
9.0.0: filter parameter of date.dhwas renamed to filter_func
9.0.0: dict parameter of data.api.OptionSetwas renamed to data
9.0.0: version.get_toolforge_hostnameis deprecated with no replacement
9.0.0: allrevisions parameter of xmlreader.XmlDumpis deprecated, use revisions instead (T340804)
9.0.0: iteritems method of data.api.Requestwill be removed in favour of items
9.0.0: SequenceOutputter.output() is deprecated in favour of the tools.formatter.SequenceOutputter.outproperty
Pending removal in Pywikibot 13
10.7.0: The old (type, value, traceback) signature in tools.collections.GeneratorWrapper.throwwill be removed in Pywikibot 13, or earlier if it is dropped from a future Python release. (T340641)
10.6.0: Family.isPublic()will be removed (T407049)
10.6.0: Family.interwiki_replacementsis deprecated; use Family.code_aliasesinstead.
Keyword argument for char parameter of Transliterator.transliterate and positional arguments for prev and succ parameters are deprecated.
10.6.0: Positional arguments of daemonize()are deprecated and must be given as keyword arguments.
10.5.0: Accessing the fallback ‘*’ keys in ‘languages’, ‘namespaces’, ‘namespacealiases’, and ‘skins’ properties of APISite.siteinfoare deprecated and will be removed.
10.5.0: The methods APISite.protection_types() and APISite.protection_levels() are deprecated. APISite.restrictionsshould be used instead.
10.4.0: Require all parameters of Site.allpages() except start to be keyword arguments.
10.4.0: Positional arguments of pywikibot.Coordinateare deprecated and must be given as keyword arguments.
10.3.0: throttle.Throttle.getDelayand throttle.Throttle.setDelayswere renamed to get_delay()and set_delays() ; the old methods will be removed (T289318)
10.3.0: throttle.Throttle.next_multiplicityattribute is unused and will be removed (T289318)
10.3.0: requestsize parameter of throttle.Throttlecall is deprecated and will be dropped (T289318)
10.3.0: textlib.to_latin_digitswill be removed in favour of textlib.to_ascii_digits, NON_LATIN_DIGITS of userinterfaces.transliteration will be removed in favour of NON_ASCII_DIGITS (T398146#10958283)
10.2.0: tools.threading.RLockis deprecated and moved to backports module. The backports.RLock.countmethod is also deprecated. For Python 3.14+ use RLock from Python library threading instead. (T395182)
10.1.0: revid and date parameters of Page.authorship() were dropped
10.0.0: last_id of comms.eventstreams.EventStreamswas renamed to last_event_id (T309380)
10.0.0: ‘millenia’ argument for precision parameter of pywikibot.WbTimeis deprecated; ‘millennium’ must be used instead
10.0.0: includeredirects parameter of pagegenerators.AllpagesPageGeneratorand pagegenerators.PrefixingPageGeneratoris deprecated and should be replaced by filterredir
Pending removal in Pywikibot 14
11.8.0: Public reason and comment parameters used for page-action and upload summaries were renamed to summary. The old parameter names will be removed. (T62442)
11.7.0: page.BasePage.getOldVersionis now deprecated in favour of get_revision(oldid, content=True).text. (T433799)
11.7.0: The lang parameter of the i18n.altlangfunction is positional-only. Passing lang as a keyword argument is deprecated.
11.7.0: The interface of APISite.assert_valid_iter_params() was changed. The msg_prefix parameter is now positional-only and the is_ts parameter is now keyword-only. The previous interface is deprecated.
11.6.0: The top_only parameter of APISite.usercontribs has been deprecated; use top instead (T308961)
11.5.0: family.Family.post_get_convertand family.Family.pre_put_convertfunctions are deprecated and will be removed (T431188)
11.5.0: exceptions.TimeoutError is deprecated in favour of exceptions.ApiTimeoutError
11.5.0: config``textfile_encoding`` variable will be removed; use ‘utf-8’ directly instead (T430454)
11.4.0: The signature of APISite.allusers() was changed; all parameters are keyword-only.
11.4.0: The signature of tools.open_archivewas changed. filename parameter is positional only, use_extension is keyword only.
11.0.0: The User-Agent variable script_product is deprecated; use script instead. The User-Agent variable version is deprecated; use revision instead. The User-Agent variables lang, code and family are deprecated; use site instead.
11.0.0: Positional argument for block parameter of pywikibot.async_manageris deprecated; use a keyword argument instead.
11.0.0: Keyword parameters for text_a and text_b of diff.PatchManagerare deprecated. Positional parameters for by_letter and replace_invisible are deprecated.
Release history
See https://github.com/wikimedia/pywikibot/blob/stable/HISTORY.rst
Contributing
Our code is maintained on Wikimedia’s Gerrit installation, learn how to get started.
Code of Conduct
The development of this software is covered by a MediaWiki Code of Conduct.
5 maintainers
Metadata
5 maintainers
Release files for pywikibot 11.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pywikibot-11.8.0.tar.gz | 662.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pywikibot-11.8.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / pywikibot-11.8.0.tar.gz
| Download URL | pywikibot-11.8.0.tar.gz |
|---|---|
| Size | 662.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f91930d1591efea475f48f294f3287d82f7ee6240b3d38a40e5d31b52cb8ccc1
|
|
BLAKE2b-256 checksum How to use checksums |
da2f4f90513419eac7418a6165e1c5e055fc7b25fb47db9d5a487350aa3844d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.15.0a1
|
Release files / pywikibot-11.8.0-py3-none-any.whl
| Download URL | pywikibot-11.8.0-py3-none-any.whl |
|---|---|
| Size | 764.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9420694d59df59ae46327376c277a5169495a0aeaa15565d94ad2ef5e54a30fd
|
|
BLAKE2b-256 checksum How to use checksums |
9528f6123afa73aebd5d56c3893bb5e0b3ce10403cef34224137d10ddbaca9c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.15.0a1
|
