Manual:Pywikibot/Development/Guidelines

From MediaWiki.org
Jump to navigation Jump to search

This makes 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[edit]

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[edit]

Read Manual:Pywikibot/Gerrit#For developers.

Commit messages should follow the Gerrit Commit message guidelines.

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

Prefix Meaning
[bugfix] or [FIX] Fixes a bug – refer the related phabricator task. This patch should be priorized.
[cleanup] Code cleanup – does not affect the behavior but improves the code.
[compat2core] Compat to core relationship – scripts merged from compat or some compat functionality merged to core.
[i18n] Internationalisation issues – translating related code, translation dictionaries, interface to translatewiki.net.
[FEAT] Feature – new options, additional behavior. A bit like [IMPR] below.
[IMPR] Improvement – new options, additional behavior or code cleanup.
[L10N] Localisation issues – project related code mostly done in config or family files.
[PEP8] PEP8 related changes – code style changes, looks nicer.
[POC] Proof of concept – indicates a new concept or new library part.
[TEST] or [tests] Tests related code – mostly found in tests folder.
[WIP] Working in Process – you may review it but don't submit it with CR+2. The patch author or committer is grateful for reviewing his code, suggestions and remarks.

Coding style guideline[edit]

Follow pep8[edit]

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:
# No, operator is far away from their operands
result = (isinstance(precision, int) and
          precision in self.PRECISION.values())

result = isinstance(precision, int) and (
    precision in self.PRECISION.values())

# Yes, easy to read
result = (isinstance(precision, int)
          and precision in self.PRECISION.values())
  • 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 import X then from X import Y) 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:
import re
import math

import pywikibot

from pywikibot.site import Namespace

Follow pep257[edit]

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:

def function(a, b):
    """Do X and return a list."""

and a multi-line docstring has to be like:

def function(argument1='Foo', argument2='Bar'):
    """
    This function does something.

    Keyword arguments:
    argument1 -- the first argument (default "Foo")
    argument2 -- the second argument (default "Bar")
    """

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[edit]

  • 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[edit]

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:

class WikibasePage(BasePage):

    """The base page for the Wikibase extension."""

    def __init__(self, site, title='', **kwargs):
        """
        Initializer.

        If title is provided, either ns or entity_type must also be provided,
        and will be checked against the title parsed.

        @param site: Wikibase data site
        @type site: DataSite
        @param title: normalized title of the page
        @type title: unicode
        @keyword ns: namespace
        @type ns: Namespace instance, or int
        @keyword entity_type: Wikibase entity type
        @type entity_type: str ('item' or 'property')

        @raises TypeError: incorrect use of parameters
        @raises ValueError: incorrect namespace
        """

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. Using Epydoc fields decorators is highly recommended. 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) can be noted in the HISTORY.rst file.

Test via pyflakes[edit]

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[edit]

  • Use "bot" instead of "robot" in naming variables, documentation, etc.
  • Don't 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 u'' prefix on strings, as it is meaningless due to __future__.unicode_literals.
  • Prefer string.format() 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.
  • Don't use \r (carriage return character) in code; some code editors add it automatically, check and delete them.

Programming Recommendations[edit]

  • Code should be written in a way that it is executable for Python version 2.7.4 and higher and 3.4 and higher.
  • Avoid using global variables with defining "global variable" at the beginning of the function.
  • Comparisons to singletons must always done with is or is not.
  • Use built-in string methods startswith() and endswith() to check for prefixes or suffixes instead of string slicing.
  • Avoid deeply nested blocks:
    Yes:
if not page.exists():
    pywikibot.output('Page does not exist.')
elif page.isRedirectPage():
    pywikibot.output('Redirect page.')
else:
    treat(page)
To be avoided:
if page.exists():
    if page.isRedirectPage():
        pywikibot.output('Redirect page.')
    else:
        treat(page)
else:
    pywikibot.output('Page does not exist.')
  • As contributor you may add yourself to the CREDITS list.

References[edit]

See also[edit]