Metadata-Version: 2.1
Name: pywikibot
Version: 8.4.0
Summary: Python MediaWiki Bot Framework
Home-page: https://www.mediawiki.org/wiki/Manual:Pywikibot
Download-URL: https://pywikibot.toolforge.org/
Maintainer: The Pywikibot team
Maintainer-email: pywikibot@lists.wikimedia.org
License: MIT License
Project-URL: Documentation, https://doc.wikimedia.org/pywikibot/stable/
Project-URL: Source, https://gerrit.wikimedia.org/r/plugins/gitiles/pywikibot/core/
Project-URL: GitHub Mirror, https://github.com/wikimedia/pywikibot
Project-URL: Tracker, https://phabricator.wikimedia.org/tag/pywikibot/
Keywords: API,bot,client,framework,mediawiki,pwb,pybot,python,pywiki,pywikibase,pywikibot,pywikipedia,pywikipediabot,wiki,wikibase,wikidata,wikimedia,wikipedia
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: Afrikaans
Classifier: Natural Language :: Arabic
Classifier: Natural Language :: Basque
Classifier: Natural Language :: Bengali
Classifier: Natural Language :: Bosnian
Classifier: Natural Language :: Bulgarian
Classifier: Natural Language :: Cantonese
Classifier: Natural Language :: Catalan
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Natural Language :: Chinese (Traditional)
Classifier: Natural Language :: Croatian
Classifier: Natural Language :: Czech
Classifier: Natural Language :: Danish
Classifier: Natural Language :: Dutch
Classifier: Natural Language :: English
Classifier: Natural Language :: Esperanto
Classifier: Natural Language :: Finnish
Classifier: Natural Language :: French
Classifier: Natural Language :: Galician
Classifier: Natural Language :: German
Classifier: Natural Language :: Greek
Classifier: Natural Language :: Hebrew
Classifier: Natural Language :: Hindi
Classifier: Natural Language :: Hungarian
Classifier: Natural Language :: Icelandic
Classifier: Natural Language :: Indonesian
Classifier: Natural Language :: Irish
Classifier: Natural Language :: Italian
Classifier: Natural Language :: Japanese
Classifier: Natural Language :: Javanese
Classifier: Natural Language :: Korean
Classifier: Natural Language :: Latin
Classifier: Natural Language :: Latvian
Classifier: Natural Language :: Lithuanian
Classifier: Natural Language :: Macedonian
Classifier: Natural Language :: Malay
Classifier: Natural Language :: Marathi
Classifier: Natural Language :: Nepali
Classifier: Natural Language :: Norwegian
Classifier: Natural Language :: Panjabi
Classifier: Natural Language :: Persian
Classifier: Natural Language :: Polish
Classifier: Natural Language :: Portuguese
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Natural Language :: Romanian
Classifier: Natural Language :: Russian
Classifier: Natural Language :: Serbian
Classifier: Natural Language :: Slovak
Classifier: Natural Language :: Slovenian
Classifier: Natural Language :: Spanish
Classifier: Natural Language :: Swedish
Classifier: Natural Language :: Tamil
Classifier: Natural Language :: Telugu
Classifier: Natural Language :: Thai
Classifier: Natural Language :: Tibetan
Classifier: Natural Language :: Turkish
Classifier: Natural Language :: Ukrainian
Classifier: Natural Language :: Urdu
Classifier: Natural Language :: Vietnamese
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Wiki
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.6.1
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: mwparserfromhell>=0.5.2
Requires-Dist: requests<2.28.0,>=2.21.0; python_version < "3.7"
Requires-Dist: requests>=2.21.0; python_version >= "3.7"
Requires-Dist: setuptools>=48.0.0; python_version >= "3.10"
Requires-Dist: setuptools>=40.8.0; python_version >= "3.7" and python_version < "3.10"
Requires-Dist: setuptools<59.7.0,>=40.8.0; python_version < "3.7"
Provides-Extra: eventstreams
Requires-Dist: sseclient<0.0.23,>=0.0.18; extra == "eventstreams"
Provides-Extra: isbn
Requires-Dist: python-stdnum>=1.18; extra == "isbn"
Provides-Extra: graphviz
Requires-Dist: pydot>=1.4.1; extra == "graphviz"
Provides-Extra: google
Requires-Dist: google>=1.7; extra == "google"
Provides-Extra: memento
Requires-Dist: memento_client==0.6.1; extra == "memento"
Provides-Extra: wikitextparser
Requires-Dist: wikitextparser>=0.47.0; extra == "wikitextparser"
Provides-Extra: mysql
Requires-Dist: PyMySQL>=0.9.3; extra == "mysql"
Provides-Extra: tkinter
Requires-Dist: Pillow<10.0.0,>=8.1.2; platform_machine == "AMD32" and extra == "tkinter"
Requires-Dist: Pillow>=8.1.2; platform_machine != "AMD32" and extra == "tkinter"
Provides-Extra: mwoauth
Requires-Dist: mwoauth!=0.3.1,>=0.2.4; extra == "mwoauth"
Provides-Extra: html
Requires-Dist: beautifulsoup4>=4.7.1; extra == "html"
Provides-Extra: http
Requires-Dist: fake-useragent<0.1.14; python_version < "3.7" and extra == "http"
Requires-Dist: fake-useragent>1.2.1; python_version >= "3.7" and extra == "http"
Provides-Extra: flake8
Requires-Dist: flake8>=5.0.4; extra == "flake8"
Requires-Dist: darglint; extra == "flake8"
Requires-Dist: pydocstyle>=6.2.3; extra == "flake8"
Requires-Dist: flake8-bugbear!=23.1.14; extra == "flake8"
Requires-Dist: flake8-coding; extra == "flake8"
Requires-Dist: flake8-comprehensions; extra == "flake8"
Requires-Dist: flake8-docstrings>=1.4.0; extra == "flake8"
Requires-Dist: flake8-mock-x2; extra == "flake8"
Requires-Dist: flake8-print>=4.0.1; extra == "flake8"
Requires-Dist: flake8-quotes>=3.3.2; extra == "flake8"
Requires-Dist: flake8-string-format; extra == "flake8"
Requires-Dist: flake8-tuple>=0.4.1; extra == "flake8"
Requires-Dist: flake8-no-u-prefixed-strings>=0.2; extra == "flake8"
Requires-Dist: pep8-naming<0.13.0,>=0.12.1; python_version < "3.7" and extra == "flake8"
Requires-Dist: pep8-naming>=0.13.3; python_version >= "3.7" and extra == "flake8"
Provides-Extra: hacking
Requires-Dist: hacking; extra == "hacking"
Provides-Extra: create-isbn-edition-py
Requires-Dist: isbnlib; extra == "create-isbn-edition-py"
Requires-Dist: unidecode; extra == "create-isbn-edition-py"
Provides-Extra: weblinkchecker-py
Requires-Dist: memento_client==0.6.1; extra == "weblinkchecker-py"
Provides-Extra: scripts
Requires-Dist: isbnlib; extra == "scripts"
Requires-Dist: unidecode; extra == "scripts"
Requires-Dist: memento_client==0.6.1; extra == "scripts"

.. image:: https://github.com/wikimedia/pywikibot/actions/workflows/pywikibot-ci.yml/badge.svg?branch=master
   :alt: GitHub CI
   :target: https://github.com/wikimedia/pywikibot/actions/workflows/pywikibot-ci.yml
.. image:: https://ci.appveyor.com/api/projects/status/xo2g4ctoom8k6yvw/branch/master?svg=true
   :alt: AppVeyor Build Status
   :target: https://ci.appveyor.com/project/pywikibot-core/pywikibot
.. image:: https://codecov.io/gh/wikimedia/pywikibot/branch/master/graph/badge.svg
   :alt: Code coverage
   :target: https://app.codecov.io/gh/wikimedia/pywikibot
.. image:: https://api.codeclimate.com/v1/badges/de6ca4c66e7c7bee4156/maintainability
   :alt: Maintainability
   :target: https://codeclimate.com/github/wikimedia/pywikibot
.. image:: https://img.shields.io/pypi/pyversions/pywikibot.svg
   :alt: Python
   :target: https://www.python.org/downloads/
.. image:: https://img.shields.io/github/languages/top/wikimedia/pywikibot
   :alt: Top language
   :target: https://www.python.org/downloads/
.. image:: https://img.shields.io/pypi/v/pywikibot.svg
   :alt: Pywikibot release
   :target: https://pypi.org/project/pywikibot/
.. image:: https://img.shields.io/pypi/wheel/pywikibot
   :alt: wheel
   :target: https://pypi.org/project/pywikibot/
.. image:: https://static.pepy.tech/badge/pywikibot
   :alt: Total downloads
   :target: https://pepy.tech/project/pywikibot
.. image:: https://static.pepy.tech/personalized-badge/pywikibot?period=month&units=international_system&left_color=black&right_color=blue&left_text=monthly
   :alt: Monthly downloads
   :target: https://pepy.tech/project/pywikibot
.. image:: https://img.shields.io/github/last-commit/wikimedia/pywikibot
   :alt: Last commit
   :target: https://gerrit.wikimedia.org/r/plugins/gitiles/pywikibot/core/

*********
Pywikibot
*********

The Pywikibot framework is a Python library that interfaces with the
`MediaWiki API <https://www.mediawiki.org/wiki/API:Main_page>`_
version 1.27 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 <https://doc.wikimedia.org/pywikibot/stable/>`_.

Quick start
===========

.. code:: text

    pip install requests
    git clone https://gerrit.wikimedia.org/r/pywikibot/core.git
    cd core
    git submodule update --init
    python pwb.py script_name

Or to install using PyPI (excluding scripts)

.. code:: text

    pip install -U setuptools
    pip install pywikibot
    pwb <scriptname>

Our `installation
guide <https://www.mediawiki.org/wiki/Manual:Pywikibot/Installation>`_
has more details for advanced usage.

Basic Usage
===========

If you wish to write your own script it's very easy to get started:

.. code:: python

    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 page

Wikibase Usage
==============

Wikibase is a flexible knowledge base software that drives Wikidata.
A sample pywikibot script for getting data from Wikibase:

.. code:: python

    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 item

Script example
==============

Pywikibot provides bot classes to develop your own script easily:

.. code:: python

    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():
        """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 <https://doc.wikimedia.org/pywikibot/>`_.


Roadmap
=======

Current release
---------------

* Add support for fonwiki (T347941)
* site.BaseSite.redirects()and
  site.APISite.redirects()
  methods were added (T347226)
* Upcast to pywikibot.FilePagefor a proper extension only (T346889)
* Handle missing SDC mediainfo (T345038)
* *modules_only_mode* parameter of data.api.ParamInfo, its *paraminfo_keys* class attribute
  and its *preloaded_modules* property was deprecated, the data.api.ParamInfo.normalize_paraminfo
  method became a staticmethod (T306637)
* raise ValueError when pywikibot.FilePagetitle doesn't have a valid file extension (T345786)
* site.APISite.file_extensions property was added (T345786)
* ``dropdelay`` and ``releasepid`` attributes of throttle.Throttlewhere deprecated
  in favour of `expiry` class attribute
* Add https scheme if missing in url asked by pywikibot.scripts.generate_family_file
* L10N updates and i18n updates
* use inline re.IGNORECASE flag in textlib.case_escapefunction (T308265)
* Convert URL-encoded characters also for links outside main namespace with
  cosmetic_changes.CosmeticChangesToolkit.cleanUpLinks(T342470)
* Implement Flow topic summaries (T109443)


Deprecations
------------

* 8.4.0: *Python 3.6 support is deprecated* and will be dropped soon with Pywikibot 9
* 8.4.0: *modules_only_mode* parameter of data.api.ParamInfo, its *paraminfo_keys* class attribute
  and its preloaded_modules property will be removed
* 8.4.0: *dropdelay* and *releasepid* attributes of throttle.Throttlewill be removed
  in favour of *expiry* class attribute
* 8.2.0: tools.itertools.itergroupwill be removed in favour of backports.batched
* 8.2.0: *normalize* parameter of WbTime.toTimestrand WbTime.toWikibasewill be removed
* 8.1.0: Dependency of exceptions.NoSiteLinkErrorfrom exceptions.NoPageErrorwill be removed
* 8.1.0: ``exceptions.Server414Error`` is deprecated in favour of exceptions.Client414Error
* 8.0.0: Timestamp.clone()method is deprecated
  in favour of ``Timestamp.replace()`` method.
* 8.0.0: family.Family.maximum_GET_lengthmethod is deprecated in favour of
  config.maximum_GET_length(T325957)
* 8.0.0: ``addOnly`` parameter of textlib.replaceLanguageLinksand
  textlib.replaceCategoryLinksare deprecated in favour of ``add_only``
* 8.0.0: textlib.TimeStripperregex attributes ``ptimeR``, ``ptimeznR``, ``pyearR``, ``pmonthR``,
  ``pdayR`` are deprecated in favour of ``patterns`` attribute which is a
  textlib.TimeStripperPatterns.
* 8.0.0: textlib.TimeStripper``groups`` attribute is deprecated in favour of ``textlib.TIMEGROUPS``
* 8.0.0: LoginManager.get_login_tokenwas
  replaced by ``login.ClientLoginManager.site.tokens['login']``
* 8.0.0: ``data.api.LoginManager()`` is deprecated in favour of login.ClientLoginManager
* 8.0.0: APISite.messages()method is deprecated in favour of
  userinfo['messages']
* 8.0.0: Page.editTime()method is deprecated and should be replaced by
  Page.latest_revision.timestamp
* 7.7.0: tools.threadingclasses should no longer imported from tools
* 7.6.0: tools.itertoolsdatatypes should no longer imported from tools
* 7.6.0: tools.collectionsdatatypes should no longer imported from tools
* 7.5.0: textlib.tzoneFixedOffset class will be removed in favour of time.TZoneFixedOffset
* 7.4.0: ``FilePage.usingPages()`` was renamed to using_pages()
* 7.2.0: ``tb`` parameter of exception()function was renamed to ``exc_info``
* 7.2.0: XMLDumpOldPageGenerator is deprecated in favour of a ``content`` parameter of
  XMLDumpPageGenerator(T306134)
* 7.2.0: RedirectPageBot and NoRedirectPageBot bot classes are deprecated in favour of
  use_redirectsattribute
* 7.2.0: tools.formatter.color_formatis deprecated and will be removed
* 7.1.0: Unused ``get_redirect`` parameter of Page.getOldVersion()will be removed
* 7.0.0: User.isBlocked() method is renamed to is_blocked for consistency
* 7.0.0: A boolean watch parameter in Page.save() is deprecated and will be desupported
* 7.0.0: baserevid parameter of editSource(), editQualifier(), removeClaims(), removeSources(), remove_qualifiers() DataSite methods will be removed
* 7.0.0: Values of APISite.allpages() parameter filterredir other than True, False and None are deprecated
* 7.0.0: The i18n identifier 'cosmetic_changes-append' will be removed in favour of 'pywikibot-cosmetic-changes'

Will be removed in Pywikibot 9
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* 6.5.0: OutputOption.output() method will be removed in favour of OutputOption.out property
* 6.5.0: Infinite rotating file handler with logfilecount of -1 is deprecated
* 6.4.0: 'allow_duplicates' parameter of tools.itertools.intersect_generatorsas positional argument is deprecated, use keyword argument instead
* 6.4.0: 'iterables' of tools.itertools.intersect_generatorsgiven as a list or tuple is deprecated, either use consecutive iterables or use '*' to unpack
* 6.2.0: outputter of OutputProxyOption without out property is deprecated
* 6.2.0: ContextOption.output_range() and HighlightContextOption.output_range() are deprecated
* 6.2.0: Error messages with '%' style is deprecated in favour for str.format() style
* 6.2.0: page.url2unicode() function is deprecated in favour of tools.chars.url2string()
* 6.2.0: Throttle.multiplydelay attribute is deprecated
* 6.2.0: SequenceOutputter.format_list() is deprecated in favour of 'out' property
* 6.0.0: config.register_family_file() is deprecated

Release history
===============

See https://github.com/wikimedia/pywikibot/blob/stable/HISTORY.rst

Contributing
============

Our code is maintained on Wikimedia's `Gerrit installation <https://gerrit.wikimedia.org/>`_,
`learn <https://www.mediawiki.org/wiki/Developer_account>`_ how to get
started.

Code of Conduct
===============

The development of this software is covered by a
`Code of Conduct <https://www.mediawiki.org/wiki/Special:MyLanguage/Code_of_Conduct>`_.

