Manual:Pywikibot/Development/Guidelines

This contains Development guidelines for helping people who want to help and improve pywikibot. The development of this software is covered by a Code of Conduct.

Bug triage
If you like to help, pywikibot is not just writing code. You can help easily by categorizing, confirming, prioritizing bugs. Just go to the browse projects in phabricator and get the list. For more info see Bug management/How to triage.

Broken tests always get a High priority to be solved instantly. Priority of the framework library parts should be higher than that of scripts. Bugs should have higher priority than feature requests.

Making a patch
Read Manual:Pywikibot/Gerrit.

Commit messages should follow the Gerrit Commit message guidelines.

You may prefix the subject with indicator enclosed by square brackets. Here are some examples:

Deprecation Policy
Pywikibot provides lengthy backward compatibility. To make a backward incompatible changes to our library (the pywikibot directory) please do the following...


 * 1) Register a DeprecationWarning. Our tools module provides several mechanisms to do so...
 * 2) * @deprecated
 * 3) * issue_deprecation_warning
 * 4) * ModuleDeprecationWrapper


 * 1) After two years deprecations are eligible to be escalated to a FutureWarning by adding  . Doing so informs our users that the deprecated behavior will be removed after two releases.

For example, code that receives a warning with version 6.1 might break upon upgrading to 6.3.

All code within the pywikibot directory must be deprecated unless it is private. Deprecations might be expedited when necessary, such as to address critical bugs or support version changes (MediaWiki or Python releases).

Scripts provide backward compatibility with regard to their behavior as well, but implementations can change at any time. Never import a script aside from testing.

Scripts can raise FutureWarnings without a proceeding deprecation period.

Follow pep8
These are some standards for writing code - pep8 is mainly about writing your code in a way that would be easy to read. Most of the rules are enforced by Jenkins. Accepted code by Jenkins is voted with +2 (not +1!). Some of the most important things are:
 * Add a space before and after an equal sign ("=") when you want to define a variable except in function/method signatures which don't use any spaces around the equal sign.
 * Line breaks should be done before a binary operator, readability counts:
 * All lines are shorter than 80 characters.
 * Indentation is really important about readability of code, use it properly, use 4 spaces instead of tab character
 * Imports should be sorted by “source” (first standard libraries, then third party and then local (pywikibot)), “type” (first normal  then  ) and then alphabetical. Between the sources (and preferably between types) should be a newline. Also, each import has to be in a separated line. For example:

Follow pep257
This standard is mainly about docstrings (documentation inside code). There are two kinds of docstring, one-line docstring and multi-line docstring. A one-line docstring has to be like: and a multi-line docstring has to be like: Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

Naming style

 * Names of classes has to be CapWord (use DataPage instead of Datapage, datapage or data_page)
 * Names of functions and methods has to be lowercase with underscores for better readability (e.g. set_label instead setLabel, or SetLabel)
 * Names of errors has to be CapWord with "Error" suffix (like NoPageError)

Documentation
Don't forget to update the documentation both in mediawiki.org and in the code.

For adding the documentation you need to add it at the top of the class or file or function you're working on it as an example:

Type annotations introduced with Python 3 due to PEP 3107 are highly recommended. Every method or function must have a documentation string. Documentation of a class constructor should be placed at the class documentation itself. Documentation should follow Epytext Markup Language.Epydoc fields decorators should be used. The pywikibot API reference is generated using the markup language. There is a help page about decorators also in python.org help wiki.

Major changes to the framework (except scripts and tests) should be noted in the ROADMAP.rst file.

Test via pyflakes
pyflakes is a tool to check correct usage of variables in code - for example if you define a variable and don't use it (or don't define a variable and use it), it returns an error for you.

You can easily install and run the check, there is a manual for it.

Miscellaneous

 * Use "bot" instead of "robot" in naming variables, documentation, etc.
 * Never use tab character, use 4 spaces instead.
 * For any changes or new lines use single quotes for strings, or double quotes if the string contains a single quote.
 * Do not use a  prefix on strings, as it is meaningless in Python 3.
 * Prefer  instead of modulo operator   for string formatting which is quasi standard in Python 3.
 * If you want to remove a part of code, don't comment it out. Just remove it. Probably deprecate their usage first.
 * Don't use  (carriage return character) in code; some code editors add it automatically, check and delete them.

Programming Recommendations

 * Code should be written in a way that it is executable for Python 3.5+.
 * Avoid using global variables with defining "global variable" at the beginning of the function.
 * Comparisons to singletons must always be done with  or.
 * Use built-in string methods  and   to check for prefixes or suffixes instead of string slicing.
 * Avoid deeply nested blocks:
 * Yes:
 * To be avoided:


 * Avoid unnecessary  /   blocks   the leading if block has a ,   or   statement which leaves the control flow:
 * Yes:
 * To be avoided:


 * As contributor you may add yourself to the CREDITS.rst list.