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
+
+
+