README.rst
1.. image:: https://ci.appveyor.com/api/projects/status/xo2g4ctoom8k6yvw/branch/master?svg=true
2 :alt: AppVeyor Build Status
3 :target: https://ci.appveyor.com/project/ladsgroup/pywikibot-g4xqx
4.. image:: https://codecov.io/gh/wikimedia/pywikibot/branch/master/graph/badge.svg
5 :alt: Code coverage
6 :target: https://app.codecov.io/gh/wikimedia/pywikibot
7.. image:: https://api.codeclimate.com/v1/badges/de6ca4c66e7c7bee4156/maintainability
8 :alt: Maintainability
9 :target: https://codeclimate.com/github/wikimedia/pywikibot
10.. image:: https://img.shields.io/pypi/pyversions/pywikibot.svg
11 :alt: Python
12 :target: https://www.python.org/downloads/
13.. image:: https://img.shields.io/pypi/v/pywikibot.svg
14 :alt: Pywikibot release
15 :target: https://pypi.org/project/pywikibot/
16.. image:: https://static.pepy.tech/badge/pywikibot
17 :alt: Total downloads
18 :target: https://pepy.tech/project/pywikibot
19.. image:: https://static.pepy.tech/personalized-badge/pywikibot?period=month&units=international_system&left_color=black&right_color=blue&left_text=monthly
20 :alt: Monthly downloads
21 :target: https://pepy.tech/project/pywikibot
22
23Pywikibot
24=========
25
26The Pywikibot framework is a Python library that interfaces with the
27`MediaWiki API <https://www.mediawiki.org/wiki/API:Main_page>`_
28version 1.23 or higher.
29
30Also included are various general function scripts that can be adapted for
31different tasks.
32
33For further information about the library excluding scripts see
34the full `code documentation <https://doc.wikimedia.org/pywikibot/>`_.
35
36Quick start
37-----------
38
39::
40
41 pip install requests
42 git clone https://gerrit.wikimedia.org/r/pywikibot/core.git
43 cd core
44 git submodule update --init
45 python pwb.py script_name
46
47Or to install using PyPI (excluding scripts)
48
49::
50
51 pip install -U setuptools
52 pip install pywikibot
53
54In addition a MediaWiki markup parser is required. Please install one of them:
55
56::
57
58 pip install mwparserfromhell
59
60or
61
62::
63
64 pip install wikitextparser
65
66Our `installation
67guide <https://www.mediawiki.org/wiki/Manual:Pywikibot/Installation>`_
68has more details for advanced usage.
69
70Basic Usage
71-----------
72
73If you wish to write your own script it's very easy to get started:
74
75::
76
77 import pywikibot
78 site = pywikibot.Site('en', 'wikipedia') # The site we want to run our bot on
79 page = pywikibot.Page(site, 'Wikipedia:Sandbox')
80 page.text = page.text.replace('foo', 'bar')
81 page.save('Replacing "foo" with "bar"') # Saves the page
82
83Wikibase Usage
84--------------
85
86Wikibase is a flexible knowledge base software that drives Wikidata.
87A sample pywikibot script for getting data from Wikibase:
88
89::
90
91 import pywikibot
92 site = pywikibot.Site('wikipedia:en')
93 repo = site.data_repository() # the Wikibase repository for given site
94 page = repo.page_from_repository('Q91') # create a local page for the given item
95 item = pywikibot.ItemPage(repo, 'Q91') # a repository item
96 data = item.get() # get all item data from repository for this item
97
98Script example
99--------------
100
101Pywikibot provides bot classes to develop your own script easily:
102
103::
104
105 import pywikibot
106 from pywikibot import pagegenerators
107 from pywikibot.bot import ExistingPageBot
108
109 class MyBot(ExistingPageBot):
110
111 update_options = {
112 'text': 'This is a test text',
113 'summary: 'Bot: a bot test edit with Pywikbot.'
114 }
115
116 def treat_page(self):
117 """Load the given page, do some changes, and save it."""
118 text = self.current_page.text
119 text += '\n' + self.opt.text
120 self.put_current(text, summary=self.opt.summary)
121
122 def main():
123 """Parse command line arguments and invoke bot."""
124 options = {}
125 gen_factory = pagegenerators.GeneratorFactory()
126 # Option parsing
127 local_args = pywikibot.handle_args(args) # global options
128 local_args = gen_factory.handle_args(local_args) # generators options
129 for arg in local_args:
130 opt, sep, value = arg.partition(':')
131 if opt in ('-summary', '-text'):
132 options[opt[1:]] = value
133 MyBot(generator=gen_factory.getCombinedGenerator(), **options).run()
134
135 if __name == '__main__':
136 main()
137
138
139For more documentation on Pywikibot see our `docs <https://doc.wikimedia.org/pywikibot/>`_.
140
141
142Required external programs
143---------------------------
144
145It may require the following programs to function properly:
146
147* `7za`: To extract 7z files
148
149Roadmap
150-------
151
152.. include:: ROADMAP.rst
153
154Release history
155---------------
156
157See https://github.com/wikimedia/pywikibot/blob/stable/HISTORY.rst
158
159Contributing
160------------
161
162Our code is maintained on Wikimedia's `Gerrit installation <https://gerrit.wikimedia.org/>`_,
163`learn <https://www.mediawiki.org/wiki/Developer_account>`_ how to get
164started.
165
166.. include:: CODE_OF_CONDUCT.rst
167
