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.9
Add support for mlwwikivoyage. (T441175)
Update translations (i18n).
Various performance, stability, and code quality improvements.
Fix ZIP discovery and duplicate import paths in config.register_families_folder.
Unify negative page generator options. (T219282)
Keep the sign of negative POSIX timestamps.
Use the page.BasePage.sitein page.BasePage.change_categorywhen calling textlib.replaceCategoryLinksto respect category namespaces and footer rules.
Validate pywikibot.Link.titlelength in UTF-8 bytes within pywikibot.Link.parse.
Normalize usernames in pagegenerators.UserEditFilterGeneratorto match canonical API names.
Verify zero-byte stashes against the empty hash in tools.compute_file_hash.
Accept optional leading hyphens and period or hyphen separators in beta/rc suffixes in tools.MediaWikiVersion. Raise ValueError instead of AssertionError for malformed suffixes.
Prevent setting a class property on an instance with tools.classproperty.
Make API cache writes of data.api.CachedRequestatomic and failure-safe. (T438266)
Map claims for wbeditentity of page.MediaInfo. (T376955)
Avoid reading streamed HTTP responses to detect encoding in comms.http.fetch.
Add timespec parameter to Timestamp.isoformat() method. (T439983, T440120)
Allow global -user optionto override OAuth authentication. (T420084)
The force parameter of pywikibot.Usermethods was renamed to refresh (T433225)
Support custom Timestamp ISO separators and restores round-trip compatibility between Timestamp.isoformat()and Timestamp.fromISOformat(). (T396723)
Suggest installing all requirements for missing dependencies with pwbwrapper.
Support legacy encoded section titles. (T133276)
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.9.0: The force parameter of pywikibot.Usermethods was renamed to refresh. The old parameter name will be removed. (T433225)
11.8.0: The config.maxlag setting was renamed to write_maxlag . The old setting variable will be dropped. (T421642)
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://doc.wikimedia.org/pywikibot/stable/changelog.html
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.9.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 | Provenance | |
|---|---|---|---|---|
| pywikibot-11.9.0.tar.gz | 664.8 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pywikibot-11.9.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / pywikibot-11.9.0.tar.gz
| Download URL | pywikibot-11.9.0.tar.gz |
|---|---|
| Size | 664.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
58ed43c60e67e781cc9c9d50d9d979b4e736193189885752288ed62ef6d4c01c
|
|
BLAKE2b-256 checksum How to use checksums |
599da860e9b38b120c494f9fee76da1e2699607ceaea2c1185e21746374fe0bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / pywikibot-11.9.0-py3-none-any.whl
| Download URL | pywikibot-11.9.0-py3-none-any.whl |
|---|---|
| Size | 769.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
398fa8974bf7ae70c57872f2f0390610d29ae18ed987d29b6c9a1bb65851a35b
|
|
BLAKE2b-256 checksum How to use checksums |
f15eb3be5761073b14f93b067ce71f9175bb0f0268dea01da73d05d98950cc83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Security for pywikibot 11.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
