diff --git a/doc/Pacemaker_Development/en-US/Book_Info.xml b/doc/Pacemaker_Development/en-US/Book_Info.xml index 13334d724f..2f8cbf35d5 100644 --- a/doc/Pacemaker_Development/en-US/Book_Info.xml +++ b/doc/Pacemaker_Development/en-US/Book_Info.xml @@ -1,36 +1,36 @@ %BOOK_ENTITIES; ]> Pacemaker Development Working with the Pacemaker Code Base 1 - 0 + 1 This document has guidelines and tips for developers interested in editing Pacemaker source code and submitting changes for inclusion in the project. diff --git a/doc/Pacemaker_Development/en-US/Ch-Python.txt b/doc/Pacemaker_Development/en-US/Ch-Python.txt new file mode 100644 index 0000000000..1cc6b1c04c --- /dev/null +++ b/doc/Pacemaker_Development/en-US/Ch-Python.txt @@ -0,0 +1,99 @@ += Python Coding Guidelines = + +//// +We prefer [[ch-NAME]], but older versions of asciidoc don't deal well +with that construct for chapter headings +//// +anchor:ch-python-coding[Chapter 3, Python Coding Guidelines] + +== Python Compatibility == + +indexterm:[python,2] +indexterm:[python,3] +indexterm:[python,versions] + +Pacemaker targets compatibility with python 2.6 and later, and python 3.2 and +later. These versions have added features to be more compatible with each +other, allowing us to support both the 2 and 3 series with the same code. It is +a good idea to test any changes with both python 2 and 3. + +=== Include in All Python Code === + +==== +[source,Python] +---- +# Pacemaker targets compatibility with python 2.6+ and 3.2+ +from __future__ import print_function, unicode_literals, absolute_import, division +---- +==== + +That means: + +* All print statements must use parentheses, and printing without a newline + is accomplished with the +end=' '+ parameter rather than a trailing comma. +* All string literals will be treated as Unicode (the +u+ prefix is + unnecessary, and must not be used, because it is not available in Python 3.2). +* Local modules must be imported using +from . import+ (rather than just + +import+). To import one item from a local module, use + +from .modulename import+ (rather than +from modulename import+). +* Division using +/+ will always return a floating-point result (use +//+ if + you want the integer floor instead). + +=== Other Python Compatibility Requirements === + +* When specifying an exception variable, always use +as+ instead of a comma + (e.g. +except Exception as e+ or +except (TypeError, IOError) as e+). + Use +e.args+ to access the error arguments (instead of iterating over or + subscripting +e+). +* Use +in+ (not +has_key()+) to determine if a dictionary has a particular key. +* Always use the I/O functions from the +io+ module rather than the native + I/O functions (e.g. +io.open()+ rather than +open()+). +* When opening a file, always use the +t+ (text) or +b+ (binary) mode flag. +* Be aware of the bytes type added in Python 3. Many places where strings are + used in Python 2 use bytes or bytearrays in Python 3 (for example, the pipes + used with +subprocess.Popen()+). Code should handle both possibilities. +* Be aware that the +items()+, +keys()+, and +values()+ methods of dictionaries + return lists in Python 2 and views in Python 3. In many case, no special + handling is required, but if the code needs to use list methods on the + result, cast the result to list first. +* Do not name variables +with+ or +as+. +* Do not raise or catch strings as exceptions (e.g. +raise "Bad thing"+). +* Do not use the +cmp+ parameter of sorting functions (use +key+ instead, if + needed) or the +$$__cmp__()$$+ method of classes (implement rich comparison + methods such as +$$__lt__()$$+ instead, if needed). +* Do not use the +buffer+ type. +* Do not use features not available in all targeted Python versions. Common + examples include: +** The +argparse+, +html+, +ipaddress+, +sysconfig+, and +UserDict+ modules +** The +collections.OrderedDict+ class +** The +subprocess.run()+ function +** The +subprocess.DEVNULL+ constant +** +subprocess+ module-specific exceptions +** Set literals (+{1, 2, 3}+) + +=== Python Usages to Avoid === + +Avoid the following if possible, otherwise research the compatibility issues +involved (hacky workarounds are often available): + +* long integers +* octal integer literals +* mixed binary and string data in one data file or variable +* metaclasses +* +locale.strcoll+ and +locale.strxfrm+ +* the +configparser+ and +ConfigParser+ modules +* importing compatibility modules such as +six+ (so we don't have + to add them to Pacemaker's dependencies) + +== Formatting Python Code == + +indexterm:[Python,formatting] + +* Indentation must be 4 spaces, no tabs. +* Do not leave trailing whitespace. +* Lines should be no longer than 80 characters unless limiting line length + significantly impacts readability. For Python, this limitation is + flexible since breaking a line often impacts readability, but + definitely keep it under 120 characters. +* Where not conflicting with this style guide, it is recommended (but not + required) to follow https://www.python.org/dev/peps/pep-0008/:[PEP 8]. diff --git a/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml b/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml index 4370d10a8e..854d77aca5 100644 --- a/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml +++ b/doc/Pacemaker_Development/en-US/Pacemaker_Development.xml @@ -1,12 +1,13 @@ %BOOK_ENTITIES; ]> + diff --git a/doc/Pacemaker_Development/en-US/Revision_History.xml b/doc/Pacemaker_Development/en-US/Revision_History.xml index 150234932d..fcf382dcbf 100644 --- a/doc/Pacemaker_Development/en-US/Revision_History.xml +++ b/doc/Pacemaker_Development/en-US/Revision_History.xml @@ -1,27 +1,40 @@ %BOOK_ENTITIES; ]> Revision History 1-0 Tue Jul 26 2016 KenGaillot kgaillot@redhat.com Convert coding guidelines and developer FAQ to Publican document + + 1-1 + Wed Aug 17 2016 + + KenGaillot + kgaillot@redhat.com + + + Add chapter for python coding + guidelines + + +