View source for Manual:Creating a bot/fr

<languages/>
{{Notice|1=Cet article est basé sur la [[w:Help:Creating_a_bot|Création d'un bot]] sur Wikipedia anglais et a été synchronisé pour la dernière fois en octobre 2022.}}
'''Robots MediaWiki ''' ou simplement '''[[Special:MyLanguage/Manual:Bots|bots]]''' sont des processus automatiques qui interagissent avec Wikipedia (et d'autres projets Wikimedia) comme s'ils étaient des éditeurs humains.
Cette page explique comment mener à bien le développement d'un bot pour une utilisation sur les projets Wikimedia et une grande partie est transférable à d'autres wikis basés sur MediaWiki.
L'explication s'adresse principalement à ceux et celles qui ont déjà une certaine expérience de la programmation, mais qui ne savent pas comment appliquer ces connaissances à la création d'un robot MediaWiki.

<span id="Why_would_I_need_to_create_a_bot?"></span>
== Pourquoi aurais-je besoin de créer un bot ? ==
Les bots peuvent automatiser des tâches et les exécuter beaucoup plus rapidement que les humains.
Si vous avez une tâche simple que vous devez exécuter plusieurs fois (par exemple, ajouter un [[Special:MyLanguage/Manual:Templates|template]] à toutes les pages d'une catégorie qui en comporte 1000), il s'agit d'une tâche qui convient mieux à un robot qu'à un humain.

<span id="Considerations_before_creating_a_bot"></span>
== Considérations avant de créer un bot ==

<span id="Reuse_existing_bots"></span>
=== Réutiliser les bots existants ===

Il est souvent beaucoup plus simple de demander une tâche à un bot existant. Si vous n'avez que des demandes périodiques ou si vous n'êtes pas à l'aise avec la programmation, c'est généralement la meilleure solution. Certains wikis ont une page dédiée où l'on peut faire de telles demandes.
Il existe aussi un certain nombre d'outils à la disposition de tous et toutes.
La plupart d'entre eux prennent la forme de navigateurs Web améliorés avec des fonctionnalités spécifiques à MediaWiki.
The most popular of these is [[Project:AutoWikiBrowser|AutoWikiBrowser]] (AWB), a browser specifically designed to assist with editing on Wikipedia and other Wikimedia projects.
Une liste complète des outils se trouve à [[w:Wikipedia:Tools/Editing tools]] sur la Wikipédia anglaise.
Les outils, tels que l'AWB, peuvent souvent être utilisés avec peu ou pas de connaissances en programmation.

{{Tip|Use [https://toolhub.wikimedia.org/ Toolhub] to explore available tools for Wikimedia wikis.}}

<span id="Reuse_codebase"></span>
=== Réutiliser la base de code ===

Si vous décidez de créer votre propre bot en raison de la fréquence ou de la nouveauté de vos besoins, vous n'avez pas besoin d'en écrire un de toutes pièces.
De nombreux bots publient leur code source, qui peut parfois être réutilisé avec peu de temps de développement supplémentaire.
Il existe également un certain nombre de modèles de bots standard disponibles au téléchargement.
Ces modèles comprennent la grande majorité du code d'un bot.
Comme ces modèles de bots sont couramment utilisés, que le codage complexe a été effectué par d'autres et qu'il a été largement testé, il est beaucoup plus facile de faire approuver l'utilisation de bots basés sur ces cadres.
The most popular and common of these frameworks is {{ll|Manual:Pywikibot|Pywikibot}} (PWB), a bot framework written in [[w:Python (programming language)|Python]]. It is thoroughly documented and tested and many standardized Pywikibot scripts (bot instructions) are already available. 
<span lang="en" dir="ltr" class="mw-content-ltr">Other examples of bot frameworks can be found [[#Programming languages and libraries|below]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For some of these bot frameworks, such as PWB, a general familiarity with scripts is all that is necessary to run the bot successfully (it is important to update these frameworks regularly).</span>

<span id="Important_questions"></span>
=== Questions importantes ===

<span lang="en" dir="ltr" class="mw-content-ltr">Writing a new bot requires significant programming ability. A completely new bot must undergo substantial testing before it will be approved for regular operation.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Planning is crucial to obtain an error-free, efficient, and effective program.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The following initial considerations are important:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">Will the bot be manually assisted or fully automated?</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Will you create the bot alone, or with the help of other programmers?</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">What language will be used to implement the bot?</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Will the bot's requests, edits, or other actions be logged? If so, will the logs be stored on local media, or on wiki pages?</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Will the bot run inside a web browser (for example, written in JavaScript), or will it be a standalone program?</span>
* If the bot is a standalone program, will it run on your local computer, or on a remote server such as the [[Wikitech:Help:Toolforge|Toolforge]]?
* <span lang="en" dir="ltr" class="mw-content-ltr">If the bot runs on a remote server, will other editors be able to operate the bot or start it running?</span>

<span id="How_does_a_MediaWiki_bot_work?"></span>
== Comment fonctionne un bot MediaWiki ? ==

<div lang="en" dir="ltr" class="mw-content-ltr">
===Overview of operation===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Just like a human editor, a MediaWiki bot reads wiki pages, and makes changes where it thinks changes need to be made.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The difference is that although bots are faster and less prone to fatigue than humans, they are nowhere near as bright as we are.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Bots are good at repetitive tasks that have easily defined patterns, where few decisions have to be made.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">In the most typical case, a bot logs in to its own account and requests pages from the wiki in much the same way as a browser does – although it does not display the page on screen, but works on it in memory – and then programmatically examines the page code to see if any changes need to be made.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It then makes and submits whatever edits it was designed to do, again in much the same way a browser would.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Because bots access pages the same way people do, bots can experience the same kind of difficulties that human users do.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">They can get caught in edit conflicts, have page timeouts, or run across other unexpected complications while requesting pages or making edits.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Because the volume of work done by a bot is larger than that done by a live person, the bot is more likely to encounter these issues.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Thus, it is important to consider these situations when writing a bot.</span>

<span id="APIs_for_bots"></span>
=== APIs pour les bots ===
<span lang="en" dir="ltr" class="mw-content-ltr">In order to make changes to wiki pages, a bot necessarily has to retrieve pages from the wiki and send edits back.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There are several Application Programming Interfaces (APIs) available for that purpose.</span>

* [[API|MediaWiki Action API]] (api.php). <span lang="en" dir="ltr" class="mw-content-ltr">This web service was specifically written to permit automated processes such as bots to make queries and post changes.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Data is returned in [[w:JSON|JSON]] format (see [[Special:MyLanguage/API:Data formats#Output|output formats]] for more details).</span>
*: '''Status:''' <span lang="en" dir="ltr" class="mw-content-ltr">Built-in feature of MediaWiki, available on all Wikimedia servers.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Other non-Wikimedia wikis may disable or restrict write access.</span>
*: <span lang="en" dir="ltr" class="mw-content-ltr">There is also an [[Special:ApiSandbox|API sandbox]] for those wanting to test api.php's features.</span>
* [[Special:Export]] can be used to obtain bulk export of page content in XML form. See [[Manual:Parameters to Special:Export]] for arguments;
*: '''Status:''' <span lang="en" dir="ltr" class="mw-content-ltr">Built-in feature of MediaWiki, available on all Wikimedia servers.</span>
* Raw (Wikitext) page processing: sending a <code>action=raw</code> or a <code>action=raw&templates=expand</code> GET request to index.php will give the unprocessed wikitext source code of a page. For example: <code>https://en.wikipedia.org/w/index.php?title=Help:Creating_a_bot&action=raw</code>. An API query with <code>action=query&prop=revisions&rvprop=content</code> or <code>action=query&prop=revisions&rvprop=content&rvexpandtemplates=1</code> is roughly equivalent, and allows for retrieving additional information.
*: '''Status:''' <span lang="en" dir="ltr" class="mw-content-ltr">Built-in feature of MediaWiki, available on all Wikimedia servers.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Some web servers are configured to grant requests for compressed ([[w:gzip|gzip]]) content.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This can be done by including a line "Accept-Encoding: gzip" in the HTTP request header; if the HTTP reply header contains "Content-Encoding: gzip", the document is in gzip form, otherwise, it is in the regular uncompressed form.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Note that this is specific to the web server and not to the MediaWiki software.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Other sites employing MediaWiki may not have this feature.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If you are using an existing bot framework, it should handle low-level operations like this.</span>

<span id="Logging_in"></span>
=== Connexion ===
<span lang="en" dir="ltr" class="mw-content-ltr">Approved bots need to be logged in to make edits.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Although a bot can make read requests without logging in, bots that have completed testing should log in for all activities.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Bots logged in from an account with the bot flag (see [[#Bot Flag|#Bot Flag]] below) can obtain more results per query from the Mediawiki API (api.php).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Most bot frameworks should handle login and cookies automatically, but if you are not using an existing framework, you will need to follow these steps.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">For security, login data must be passed using the [[w:HTTP POST|HTTP POST]] method.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Because parameters of [[w:HTTP GET|HTTP GET]] requests are easily visible in URL, logins via GET are disabled.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">To log a bot in using the MediaWiki API, 2 POST requests are needed:</span>

'''Request 1 – this is a GET request to obtain a login token'''
* URL: <code>https://en.wikipedia.org/w/api.php?action=query&format=json&meta=tokens&type=login</code>

This will return a "logintoken" parameter in JSON form, as documented at [[API:Login]].
<span lang="en" dir="ltr" class="mw-content-ltr">Other output formats are available.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It will also return HTTP cookies as described below.</span>

'''Request 2 – this is a POST to complete the login'''
* URL: <code>https://en.wikipedia.org/w/api.php?action=login&format=json</code>
* POST parameters:
** <code>lgname=BOTUSERNAME</code>
** <code>lgpassword=BOTPASSWORD</code>
** <code>lgtoken=TOKEN</code>
<span lang="en" dir="ltr" class="mw-content-ltr">where TOKEN is the token from the previous result.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The HTTP cookies from the previous request must also be passed with the second request.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">A successful login attempt will result in the Wikimedia server setting several [[w:HTTP cookie|HTTP cookie]]s.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The bot must save these cookies and send them back every time it makes a request (this is particularly crucial for editing).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">On the English Wikipedia, the following cookies should be used: '''enwikiUserID''', '''enwikiToken''', and '''enwikiUserName'''.</span>
The '''enwikisession''' cookie is required to actually send an edit or commit some change, otherwise the [[MediaWiki:Session fail preview]] error message will be returned.

Main-account login via <code>action=login</code> is deprecated and may stop working without warning. To continue using bot code which logs in with <code>action=login</code>, see [[Special:BotPasswords]].

<div lang="en" dir="ltr" class="mw-content-ltr">
===Editing; edit tokens===
</div>
MediaWiki uses a system of [[Manual:Edit token|edit tokens]] for making edits to MediaWiki pages, as well as other operations that modify existing content such as rollback.
The token looks like a long hexadecimal number followed by '+\', for example:

:'''d41d8cd98f00b204e9800998ecf8427e+\'''

<div lang="en" dir="ltr" class="mw-content-ltr">
The role of edit tokens is to prevent "edit hijacking", where users are tricked into making an edit by clicking a single link.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The editing process involves two HTTP requests.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">First, a request for an edit token must be made.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Then, a second HTTP request must be made that sends the new content of the page along with the edit token just obtained.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is not possible to make an edit in a single HTTP request.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">An edit token remains the same for the duration of a logged-in session, so the edit token needs to be retrieved only once and can be used for all subsequent edits.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">To obtain an edit token, follow these steps:</span>

<ul>
<li>'''MediaWiki API (api.php)'''. Make a request with the following parameters (see [[API:Edit - Create&Edit pages]]).
<ul>
<li><code>action=query</code></li>
<li><code>meta=tokens</code></li>
</ul>
The token will be returned in the <code>edittoken</code> attribute of the response.
</li>
</ul>

If the edit token the bot receives does not have the hexadecimal string (''i.e.'', the edit token is just '+\') then the bot most likely is not logged in.
<span lang="en" dir="ltr" class="mw-content-ltr">This might be due to a number of factors: failure in authentication with the server, a dropped connection, a timeout of some sort, or an error in storing or returning the correct cookies.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If it is not because of a programming error, just log in again to refresh the login cookies.</span>
The bots ''must'' use [[API:Assert|assertion]] to make sure that they are logged in.

<div lang="en" dir="ltr" class="mw-content-ltr">
===Edit conflicts===
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Edit conflicts occur when multiple, overlapping edit attempts are made on the same page.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Almost every bot ''will'' eventually get caught in an edit conflict of one sort or another, and should include some mechanism to test for and accommodate these issues.</span>

Bots that use the Mediawiki API (api.php) should retrieve the edit token, along with the <code>starttimestamp</code> and the last revision "base" timestamp, ''before'' loading the page text in preparation for the edit; <code>prop=info|revisions</code> can be used to retrieve both the token and page contents in one query (<span class="plainlinks">[https://en.wikipedia.org/w/api.php?action=query&titles=Wikipedia:Sandbox&prop=info|revisions&inprop=&intoken=edit&rvprop=timestamp|content example]</span>).
When submitting the edit, set the <code>starttimestamp</code> and <code>basetimestamp</code> attributes, and check the server responses for indications of errors.
For more details, see [[API:Edit - Create&Edit pages]].

<span lang="en" dir="ltr" class="mw-content-ltr">Generally speaking, if an edit fails to complete the bot should check the page again before trying to make a new edit, to make sure the edit is still appropriate.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Further, if a bot rechecks a page to resubmit a change, it should be careful to avoid any behavior that could lead to an infinite loop and any behavior that could even resemble [[w:WP:EW|edit warring]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Overview of the process of developing a bot==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Actually, coding or writing a bot is only one part of developing a bot.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">The development cycle below is a recommendation from English Wikipedia.</span>
[[Image:Bot_development_cycle.svg|thumb|none|600px|Overview of English Wikipedia bot development cycle]]

<div lang="en" dir="ltr" class="mw-content-ltr">
On Wikimedia wikis, ensure that your bot follows any potential bot policies of the wiki.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Idea====
</div>
* <span lang="en" dir="ltr" class="mw-content-ltr">The first task in creating a MediaWiki bot is extracting the requirements or coming up with an idea.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Make sure an existing bot isn't already doing what you think your bot should do.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Specification====
</div>
* [[w:Formal specification|Specification]] is the task of precisely describing the software to be written, possibly in a rigorous way. <span lang="en" dir="ltr" class="mw-content-ltr">You should come up with a detailed proposal of what you want it to do.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Try to discuss this proposal with some editors and refine it based on feedback.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Even a great idea can be made better by incorporating ideas from other editors.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">In the most basic form, your specified bot must meet the following criteria:</span>
:* <span lang="en" dir="ltr" class="mw-content-ltr">The bot is harmless (it must not make edits that could be considered disruptive to the smooth running of the wiki)</span>
:* <span lang="en" dir="ltr" class="mw-content-ltr">The bot is useful (it provides a useful service more effectively than a human editor could)</span>
:* <span lang="en" dir="ltr" class="mw-content-ltr">The bot does not waste server resources.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Software architecture====
</div>
* Think about '''how''' you might create it and which programming language(s) and tools you would use. [[w:Software architecture|Architecture]] is concerned with making sure the software system will meet the requirements of the product as well as ensuring that future requirements can be addressed. <span lang="en" dir="ltr" class="mw-content-ltr">Certain programming languages are better suited to some tasks than others, for more details see [[#Programming languages and libraries|the section on programming languages below]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Implementation====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:Computer programming|Implementation]] (or coding) involves turning design and planning into code.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It may be the most obvious part of the software engineering job, but it is not necessarily the largest portion.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">In the implementation stage you should:</span>

* Create an account for your bot. Go to the [[Special:CreateAccount|sign up page]] when logged in to create the account, linking it to yours. (If you do not create the bot account while logged in, it might be blocked on some wikis according to their policies)
* <span lang="en" dir="ltr" class="mw-content-ltr">Create a user page for your bot.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Your bot's edits must not be made under your own account.</span> <span lang="en" dir="ltr" class="mw-content-ltr">Your bot will need its own account with its own username and password.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Add the same information to the user page of the bot.</span> <span lang="en" dir="ltr" class="mw-content-ltr">It would be a good idea to add a link to the approval page (whether approved or not) for each function.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Code your bot in your chosen programming language.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Testing====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">A good way of testing your bot as you are developing is to have it show the changes (if any) it would have made to a page, rather than actually editing the live wiki.</span>
Some bot frameworks (such as [[Manual:Pywikibot | pywikibot]]) have pre-coded methods for showing diffs.

<div lang="en" dir="ltr" class="mw-content-ltr">
====Documentation====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">An important (and often overlooked) task is [[w:software documentation|documenting]] the internal design of your bot for the purpose of future maintenance and enhancement.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is especially important if you are going to allow clones of your bot.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Ideally, you should post the source code of your bot on its userpage or in a revision control system (see [[#Open-source bots|#Open-source bots]]) if you want others to be able to run clones of it.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This code should be well documented (usually using comments) for ease of use.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Queries/Complaints ====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">You should be ready to respond to queries about or objections to your bot on your user talk page, especially if it is operating in a potentially sensitive area.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Maintenance====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:software maintenance|Maintaining]] and enhancing your bot to cope with newly discovered bugs or new requirements can take far more time than the initial development of the software.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Not only may it be necessary to add code that does not fit the original design, but just determining how software works at some point after it is completed may require significant effort (this is another reason to document your code as you go along).</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==General guidelines for running a bot==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
In addition to the official bot policy, which covers the main points to consider when developing your bot, there are a number of more general advisory points to consider when developing your bot.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
===Bot best practices===
</div>
* Set a custom [[w:User agent|User-Agent]] header for your bot (per the [[meta:User-Agent policy|Wikimedia User-Agent policy]], if your bot will be operating on Wikimedia wikis). If you don't, your bot may encounter errors and may end up blocked at the server level.
* Use the [[Manual:Maxlag parameter|maxlag parameter]] with a maximum lag of 5 seconds. This will enable the bot to run quickly when server load is low, and throttle the bot when server load is high.
**If writing a bot in a framework that does not support maxlag, limit the total requests (read and write requests together) to no more than 10/minute.
* Use the [[API|MediaWiki API]] whenever possible, and set the query limits to the largest values that the server permits, to minimize the total number of requests that must be made.
* Edit (write) requests are more expensive in server time than read requests. Be edit-light and design your code to keep edits to a minimum.
** Try to consolidate edits. One single large edit is better than 10 smaller ones.
* Enable [[w:HTTP persistent connection|HTTP persistent connection]]s and [[w:HTTP compression|compression]] in your HTTP client library, if possible.
* Do not make multi-threaded requests. Wait for one server request to complete before beginning another
* Back off upon receiving errors from the server. Errors such as timeouts are often an indication of heavy server load. Use [[w:exponential backoff|a sequence of increasingly longer delays between repeated requests]].
* Make use of [[API:Assert|assertion]] to ensure your bot is logged in.
* Test your code thoroughly before making large automated runs. Individually examine all edits on trial runs to verify they are perfect.

<div lang="en" dir="ltr" class="mw-content-ltr">
===Common bot features you should consider implementing===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Manual assistance====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">If your bot is doing anything that requires judgment or evaluation of context (e.g., correcting spelling) then you should consider making your bot manually-assisted, which means that a human verifies all edits before they are saved.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This significantly reduces the bot's speed, but it also significantly reduces errors.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Disabling the bot====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">It is good bot policy to have a feature to disable the bot's operation if it is requested.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Remember that if your bot goes bad, it is your responsibility to clean up after it!</span>
<span class="plainlinks">You could have the bot refuse to run if a message has been left on its talk page, on the assumption that the message may be a complaint against its activities; this can be checked using the API <code>meta=userinfo</code> query ([https://en.wikipedia.org/w/api.php?action=query&meta=userinfo&uiprop=hasmsg example on English Wikipedia]).</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Or you could have a page that will turn the bot off if text on the page is changed (e.g. require the page be empty, contain only the word "True", or something similar); this can be checked by loading the page contents before each edit.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Signature====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Just like a human, if your bot makes edits to a talk page in MediaWiki, it should sign its post with four tildes <nowiki>(~~~~)</nowiki>.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Signatures usually belong '''only''' on talk namespaces.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
====Bot Flag====
</div>
A bot's edits will be visible at [[Special:RecentChanges]], unless the edits are set to indicate a bot. Once the bot has been approved and given its bot flag permission, one can add the "bot-True" to the API call - see [[API:Edit#Parameters]] in order to hide the bot's edits in [[Special:RecentChanges]].
In Python, using either mwclient or wikitools, then adding '''{{Green|<nowiki>Bot=True</nowiki>}}''' to the edit/save command will set the edit as a bot edit - e.g. {{code|1=PageObject.edit(text=pagetext, bot=True, summary=pagesummary)}}

<div lang="en" dir="ltr" class="mw-content-ltr">
====Monitoring the bot status====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If the bot is fully automated and performs regular edits, you should periodically check it runs as specified, and its behavior has not been altered by software changes.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Open-source bots==
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">Many bot operators choose to make their code open source, and occasionally it may be required before approval for particularly complex bots.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Making your code open source has several advantages:</span>

* <span lang="en" dir="ltr" class="mw-content-ltr">It allows others to review your code for potential bugs.</span> <span lang="en" dir="ltr" class="mw-content-ltr">As with prose, it is often difficult for the author of code to adequately review it.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">Others can use your code to build their own bots.</span> <span lang="en" dir="ltr" class="mw-content-ltr">A user new to bot writing may be able to use your code as an example or a template for their own bots.</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">It encourages good security practices, rather than [[w:security through obscurity|security through obscurity]].</span>
* <span lang="en" dir="ltr" class="mw-content-ltr">If you leave the project, it allows other users to run your bot tasks without having to write new code.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Open-source code, while rarely required, is typically encouraged in keeping with the open and transparent nature of wikis, though there are some cases when code should not be made public.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, the open proxy-finding code of [[w:User:ProcseeBot|ProcseeBot]] could be used for malicious purposes on other sites.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Making code open source can add some extra work to coding.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">One has to make sure that sensitive information such as passwords is separated into a file that isn't made public.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">There are several options available for users wishing to make their code open.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Some users choose to put the code in a subpage of the bot's userspace, although this can be a hassle to maintain if not automated and results in the code being multi-licensed under the wiki's licensing terms in addition to any other terms you may specify.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Another solution is to use a [[w:Revision Control System|revision control system]] such as [[w:Apache Subversion|SVN]], [[w:Git|Git]], or [[w:Mercurial|Mercurial]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Wikipedia has articles comparing the different [[w:Comparison of revision control software|software options]] and [[w:Comparison of open source software hosting facilities|websites for code hosting]], many of which have no cost.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Wikimedia also offers Git code repository hosting for its users and running Wikimedia related software tools via [[wikitech:Help:Cloud Services introduction|Wikimedia Cloud Services]].</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
==Programming languages and libraries==
</div>
:''See also: [[API:Client code]]''
<span lang="en" dir="ltr" class="mw-content-ltr">Bots can be written in almost any programming language.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The choice of a language often depends on the experience of the bot writer (which languages are familiar) or on the availability of pre-developed libraries to perform the desired task.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The following list includes some languages that have libraries to assist with bot tasks.</span>

====Awk====

* Framework and libraries: [[w:WP:BOTWIKIAWK|BotWikiAwk]]
* Example bots in the GitHub account of [[User:GreenC]] at [https://github.com/greencardamom?tab=repositories GitHub]

<div lang="en" dir="ltr" class="mw-content-ltr">
====Perl====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">If located on a webserver, you can start your program running and interface with your program while it is running via the [[w:Common Gateway Interface]] from your browser.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">If your internet service provider provides you with webspace, the chances are good that you have access to a perl build on the webserver from which you can run your Perl programs.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Libraries:</span>
* [https://metacpan.org/pod/MediaWiki::API MediaWiki::API]&nbsp;– Basic interface to the API, allowing scripts to automate editing and extraction of data from MediaWiki driven sites.
* [https://metacpan.org/pod/MediaWiki::Bot MediaWiki::Bot]&nbsp;– A fairly complete MediaWiki bot framework written in Perl. Provides a higher level of abstraction than MediaWiki::API. Plugins provide administrator and steward functionality. Currently unsupported.

<div lang="en" dir="ltr" class="mw-content-ltr">
====PHP====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:PHP|PHP]] can also be used for programming bots.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">MediaWiki developers are already familiar with PHP, since that is the language MediaWiki and its extensions are written in.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">PHP is an especially good choice if you wish to provide a webform-based interface to your bot.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">For example, suppose you wanted to create a bot for renaming categories.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You could create an HTML form into which you will type the current and desired names of a category.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">When the form is submitted, your bot could read these inputs, then edit all the articles in the current category and move them to the desired category.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">(Obviously, any bot with a form interface would need to be secured somehow from random web surfers.)</span>

<span lang="en" dir="ltr" class="mw-content-ltr">The [[w:Wikipedia:PHP bot functions|PHP bot functions]] table on English Wikipedia may provide some insight into the capabilities of the major bot frameworks.</span>

{| class="wikitable sortable" border="1"
|+ PHP Bot frameworks
! Key people<ref group="php">Does not include those who worked on frameworks forked to create listed framework.</ref> !! Name !! PHP Version !! last update !! Uses API<ref group="php">Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.</ref> !! [[w:Template:Bots|Exclusion compliant]] !! Admin functions !! Plugins !! Repository !! Notes
|-
| [[w:User:Cyberpower678|Cyberpower678]], [[w:User:Addshore|Addshore]], and [[w:User:Jarry1250|Jarry1250]]       || [[w:WP:Peachy|Peachy]]                             || 5.2.1 || 2015    || {{yes}} || {{yes}} || {{yes}} || {{yes}} || GitHub || Large framework, currently undergoing rewrite. Documentation currently non-existent, so poke [[w:User:Cyberpower678]] for help.
|-
| [[w:User:Addshore|Addshore]] || [https://github.com/addwiki/mediawiki-api-base mediawiki-api-base] || 7.4+ || 2021 || {{yes}} || {{no|N/A}} || {{no|N/A}}  || {{yes|extra libs}} || [https://github.com/addwiki GitHub] || Base library for interaction with the mediawiki api, provides you with ways to handle logging in, out and handling tokens as well as easily getting and posting requests.
|-
| [[w:User:Addshore|Addshore]]|| [https://github.com/addwiki/mediawiki-api mediawiki-api] || 7.4+ || 2021 || {{yes}} || {{no}} || {{yes|some}} || {{yes|extra libs}} || [https://github.com/addwiki GitHub] || Build on top of mediawiki-api-base this adds more advanced services for the api such as RevisionGetter, UserGetter, PageDeleter, RevisionPatroller, RevisionSaver etc.
|-
| [[w:User:Kaspo|Kaspo]]         || [[w:User:Kaspo/Phpwikibot|Phpwikibot]]             || {{unk}}       || 2009 || {{partial}} || {{no}} || {{no}} || {{no}} || Google Code || Uses a single class.
|-
| [[w:User:Jarry1250|Jarry1250]] || [[w:User:LivingBot/Wikibot|Wikibot]]               || 5     || 2009 || {{yes}} || {{yes}} || {{no}} || {{no}} || enwiki || Used solely by [[w:User:LivingBot|LivingBot]]. A fork of Phpwikibot. Uses a single class.
|-
| [[w:User:Foxy Loxy|Foxy Loxy]] || [https://pwiki.sourceforge.net/ PHPediaWiki] || 5     || 2009 || {{yes}} || {{no}} || {{yes}} || {{no}} || SourceForge || Fork of SxWiki
|-
| [[w:User:Nzhamstar|Nzhamstar]], [[w:User:Xymph|Xymph]], [[w:User:Waldyrious|Waldyrious]] || [https://github.com/hamstar/Wikimate Wikimate]   || 5.3-5.6,<br>7.x, 8.x || 2023 || {{yes}} || {{no}} || {{no}} || {{no}} || GitHub || Supports main article and file stuff. Authentication, checking if pages exist, reading and editing pages/sections. Getting file information, downloading and uploading files. Aims to be easy to use.
|-
| [[w:User:kalebheitzman|Kaleb Heitzman]]  || [http://github.com/kalebheitzman/mediawikibot MediaWIkiBot] || 5 || 2012 || {{yes}} || {{no}} || {{no}} || {{no}} || [[GitHub]] || Supports the entire API including uploading and importing. Also supports Semantic MediaWiki. Single Class that creates dynamic methods to work with any of the API calls.
|-
| [[w:User:Edward_Z._Yang|Edward Z. Yang]] || [[w:User:Edward_Z._Yang/Wikipedia_Bot_in_PHP|Wikipedia Bot in PHP]] || {{unk}} || 2005 || {{no}} || {{no}} || {{no}} || {{no}} || enwiki || "Probably stale" source code
|-
| [[w:User:Cobi|Cobi]]                     || [[w:user:ClueBot/Source#Classes_(wikibot.classes.php)|wikibot.classes]] || 5 || 2010 || {{yes}} || {{yes}} || {{no}} || {{no}} || enwiki || Used by multiple large bots (e.g. [[w:User:ClueBot|ClueBot]] and [[w:User:SoxBot|SoxBot]]). Uses several [[w:class (programming)|class]]es.
|-
| [[meta:User:Valerio Bozzolan|Valerio Bozzolan]] || [https://github.com/valerio-bozzolan/boz-mw/ boz-mw] || 5.6 || 2019 || {{Yes}} || {{no|N/A}} || {{Yes}} || {{Yes|extra libs}} || GitHub || Object-oriented. 80+ classes also to handle Wikidata. Inline documentation. Support for file uploading.
|}

{{reflist|group=php}}

<div lang="en" dir="ltr" class="mw-content-ltr">
====Python====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
[[w:Python (programming language)|Python]] is a popular interpreted language with object-oriented features.
</div>

;Libraries
:''Please help update this table.''
{| class="wikitable sortable"
|+ Python Bot frameworks
! Key people<ref group="py">Does not include those who worked on frameworks forked to create listed framework.</ref> !! Name !! Python Version !! last update !! Uses API<ref group="py">Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.</ref> !! [[w:Template:Bots|Exclusion compliant]] !! Admin functions !! Plugins !! Repository !! Notes
|-
|| [[user:xqt|xqt]] || {{ll|Manual:Pywikibot|Pywikibot}} || {{Yes|{{Pywikibot/Compatibility}}or PyPy}} || {{Yes|2023}} || {{Yes}} || {{Yes}} || {{Yes}} || {{Yes}}
||
* [https://gerrit.wikimedia.org/r/q/project:pywikibot%252Fcore Gerrit]
* [https://phabricator.wikimedia.org/diffusion/PWBC/ Diffusion]
* [https://github.com/wikimedia/pywikibot Github] (Mirror)
* [https://pywikibot.toolforge.org/ Toolforge] (Nightly)
* [https://pypi.org/project/pywikibot/ PyPI]
||
<span lang="en" dir="ltr" class="mw-content-ltr">The most used Python bot framework. Includes ready to use scripts.</span>
* [https://doc.wikimedia.org/pywikibot/master/ Documentation master]
* [https://doc.wikimedia.org/pywikibot/stable/ Documentation stable]
|-
|| [[User:Myst|Myst]] || WikibaseIntegrator || {{Yes|Python 3.7 or higher}} || {{Yes|2022}} || {{Yes}} || Not applicable || {{Yes}} || {{No}} || [https://github.com/LeMyst/WikibaseIntegrator GitHub]|| Only to interact with Wikibase instances like Wikidata
|-
|| [[User:Mr.Z-man|Mr.Z-man]] || wikitools || 2 || 2016 || || || || || [https://github.com/alexz-enwp/wikitools GitHub]|| Incompatible with Python 3. ([https://pypi.python.org/pypi/wikitools downloads])
|-
|| [[w:User:Bryan|Bryan]] || mwclient || || 2021 || || || || || [https://github.com/mwclient/mwclient GitHub] || An API-based framework
|-
|| [[w:User:The Earwig|The Earwig]] || mwparserfromhell || || 2021 || || || || || [https://github.com/earwig/mwparserfromhell GitHub] || A Python parser for MediaWiki text
|}

{{reflist|group=py}}

<div lang="en" dir="ltr" class="mw-content-ltr">
====Microsoft .NET====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:Microsoft .NET|Microsoft .NET]] is a set of languages including [[w:Microsoft Visual C Sharp|C#]], [[w:C++/CLI|C++/CLI]], [[w:Visual Basic .NET|Visual Basic .NET]], [[w:J Sharp|J#]], [[w:JScript .NET|JScript .NET]], [[w:IronPython|IronPython]], and [[w:Windows PowerShell|Windows PowerShell]].</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The [[w:Microsoft Visual Studio|Microsoft Visual Studio]] [[w:integrated development environment|integrated development environment]] is often used, or the free [[w:Microsoft Visual Studio Express|Microsoft Visual Studio Express]] versions.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Using [[w:Mono (software)|Mono Project]], .NET programs can also run on [[w:Linux|Linux]], [[w:Unix|Unix]], [[w:BSD|BSD]], [[w:Solaris|Solaris]] and [[w:Mac OS X|Mac OS X]] as well as under [[w:Windows|Windows]].</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Libraries:</span>
* [https://dotnetwikibot.sourceforge.net/ DotNetWikiBot Framework]&nbsp;– a full-featured client [[API]] on .NET, that allows to build programs and web robots easily to manage information on MediaWiki-powered sites. Now translated to several languages. Detailed compiled documentation is available in English.
* [https://sourceforge.net/projects/autowikibrowser/files/ WikiFunctions .NET library]&nbsp;– Bundled with [[w:WP:AWB|AWB]], is a library of stuff useful for bots, such as generating lists, loading/editing articles, connecting to the recent changes IRC channel and more.

<div lang="en" dir="ltr" class="mw-content-ltr">
====Java====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
[[w:Java (programming language)|Java]] programs are generally developed with an IDE, such as [[w:Eclipse (software)|Eclipse]] or [[w:NetBeans|NetBeans]]; development using a command line console (with the [[w:javac|javac]] and java programs) is also an option.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Libraries:
</div>
* [https://github.com/eldur/jwbf Java Wiki Bot Framework]&nbsp;– A Java wiki bot framework
* [https://github.com/mer-c/wiki-java wiki-java]&nbsp;– A Java wiki bot framework that is only one file
* [https://github.com/WPCleaner/wpcleaner WPCleaner]&nbsp;– The library used by the WPCleaner tool
* [https://github.com/fastily/jwiki jwiki]&nbsp;– A simple and easy-to-use Java wiki bot framework

<div lang="en" dir="ltr" class="mw-content-ltr">
====JavaScript (Node.js)====
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">[[w:JavaScript|JavaScript]] is a [[w:scripting language|scripting language]] used mainly on web pages, such as for user scripts added to [[Special:MyPage/vector.js|your vector.js]] or [[Special:MyPage/monobook.js|your monobook.js]] pages.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">Using [[w:Node.js|Node.js]] it is possible to use JavaScript server-side, such as for developing bots.</span>

:''Please help to update this table.''
{| class="wikitable sortable" border="1"
|+ NodeJS Bot frameworks
! Key people<ref group="js">Does not include those who worked on frameworks forked to create listed framework.</ref> !! Name !! Nodejs Version !! last update !! Uses API<ref group="js">Where possible. Excludes uploading images and other such tasks which are not currently supported by the API.</ref> !! [[w:Template:Bots|Exclusion compliant]] !! Admin functions !! Package !! Repository !! Notes
|-
|  [[:en:User:SD0001|SD0001]] || mwn || 10+ || {{yes|2021}} || {{Yes}} || {{Yes}} || {{Yes}} || [https://www.npmjs.com/package/mwn npm] || [https://github.com/siddharthvp/mwn GitHub] || Large library with classes for working with page titles and wikitext. Works with [[TypeScript]] also. Promise-based API (<code>async</code>–<code>await</code>). Limited wikitext parsing capabilities.
|-
| [[user:kanashimi|kanashimi]] || wikiapi || 0.10–15.x || {{yes|2021}} || {{yes}} || {{yes}} || {{partial}} || [https://www.npmjs.com/package/wikiapi npm] || [https://github.com/kanasimi/wikiapi GitHub] || JavaScript MediaWiki API for node.js with modern [[w:en:ECMAScript 2016|ECMAScript 2016]] <code>async</code>–<code>await</code> and [https://kanasimi.github.io/CeJS/_test%20suite/wikitext_parser.html wikitext parser].
|-
| || MediaWiki module || || {{no|2014}} || || || || || [https://github.com/oliver-moran/mediawiki GitHub] || Provides a [[w:Software framework|framework]] of standard requests (e.g. log in, log out, etc.) as well as a general wrapper method for the MediaWiki API and includes throttling. The module can also be added to your Wikimedia .js page and used as library for on-wiki JS calls.
|}

{{reflist|group=js}}

<div lang="en" dir="ltr" class="mw-content-ltr">
====Ruby====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:Ruby (programming language)|Ruby]] is a popular [[w:dynamic programming language|dynamic]], [[w:object-oriented programming language|object-oriented]] programming language.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Libraries:</span>
* [https://github.com/ftb-gamepedia/mediawiki-butt-ruby MediaWiki::Butt] - Ruby framework for the API in active development. Tested with versions as up-to-date as CurseGamepedia is.
* [https://github.com/wikimedia/mediawiki-ruby-api mediawiki/ruby/api],  Ruby API client library. Last updated December 2017, no longer maintained, but still works.
* [https://github.com/jpatokal/mediawiki-gateway MediaWiki::Gateway]&nbsp;– Ruby framework for the API. Last updated January 2016. No longer in active development, tested up to MediaWiki 1.22, compatible with Wikimedia wikis. Unknown if still works.
* [https://github.com/kenpratt/wikipedia-client wikipedia-client] - Ruby framework using the API. Last updated March 2018. Unknown if still works.

<div lang="en" dir="ltr" class="mw-content-ltr">
====Common Lisp====
</div>
* [https://www.cliki.net/CL-MediaWiki CL-MediaWiki] implements MediaWiki API as a [[w:Common Lisp|Common Lisp]] package. Is planned to use [[w:JSON|JSON]] as a query data format. Supports maxlag and assertion.

<div lang="en" dir="ltr" class="mw-content-ltr">
====Haskell====
</div>
* https://hackage.haskell.org/package/mediawiki

<div lang="en" dir="ltr" class="mw-content-ltr">
====VBScript====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:VBScript|VBScript]] is a [[w:scripting language|scripting language]] based on the [[w:Visual Basic|Visual Basic]] programming language.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">There are no published bot frameworks for VBScript, but some examples of bots that use it can be seen below:</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Examples:</span>
* [[w:User:Smallman12q/Scripts/cleanuplistingtowiki]] (2013) - Login and give preview of edit
* [[w:User:Smallman12q/VBS/Savewatchlist]] (2012) - Login, get raw watchlist, save to file, logout, close IE
* [[w:Commons:User:Smallbot#Sources]] - Several scripts showing the usage of VBScript (JavaScript, XMLHTTP, MSHTML, XMLDOM, COM) for batch uploads.

<div lang="en" dir="ltr" class="mw-content-ltr">
====Bash====
</div>
<span lang="en" dir="ltr" class="mw-content-ltr">[[w:Bash (Unix shell)|Bash]] is a [[w:Unix shell|Unix shell]].</span>
* See [[API:Client_code/Bash]]. Requires [[w:cURL|cURL]] package.

[[Category:Bots{{#translation:}}]]