Manual:Pywikibot/Development guidelines

This makes contains Development guidelines for helping people who want to help and improve pywikibot.

Reporting a bug

You have seen a problem in pywikibot? it's not the end of the world, just keep calm and report it in phabricator (compat core) the important notes for reporting bugs are:

• Get output of version.py and amend it to your report
• Include exact steps to reproduce the bug
• Include the difference between expected output and real output

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 (core and compat) and get the list. For more info see Bug management/How to triage

Making a patch

Read Manual:Pywikibot/Gerrit#For developers.

Code writing guideline

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. Some of the most important things are:

• Add a space before and after an equal sign ("=") when you want to define a variable
• Don't make very long lines, split them into several lines based on what they are
• Indentation are really important about readability of code, use it properly, use 4 spaces instead of tab character
• Each import has to be in a separated line for example:

import re
import math
import pywikibot

• If you want to import a group of classes, make a blank line. for example:

import re
import math
 
from pywikibot import pagegenerators
from pywikibot import i18n

The proposed order of imports is: standard libraries first, then third parties, and locals at the end. We usually begin locals with pywikibot.

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:

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

• 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:

class ImagePage(Page):
    """A subclass of Page representing an image descriptor wiki page.
 
    Supports the same interface as Page, with the following added methods:
 
    getImagePageHtml          : Download image page and return raw HTML text.
    fileURL                   : Return the URL for the image described on this
                                page.
    fileIsShared              : Return True if image stored on a shared
                                repository like Wikimedia Commons or Wikitravel.
    getFileMd5Sum             : Return image file's MD5 checksum.
    getFileVersionHistory     : Return the image file's version history.
    getFileVersionHistoryTable: Return the version history in the form of a
                                wiki table.
    usingPages                : Iterate Pages on which the image is displayed.
 
    """

It's really important to list all of usable methods of a class or arguments in a script.

Using decorator is highly recommended. There is a help page about them in python.org help wiki

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.
• Don't use tab character, use 4 spaces instead
• 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.
• Avoid using global variables with defining "global variable" at the beginning of the function.

References

• https://github.com/edx/edx-platform/wiki/Python-Guidelines
• https://docs.djangoproject.com/en/1.5/internals/contributing/writing-code/coding-style/
• http://legacy.python.org/dev/peps/pep-0257/
• https://www.python.org/dev/peps/pep-0008
• http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

See also

• A few python tips