Noissue - Extend Python style guide

pages/coding-style.html

 title=Coding Style
 
 
 <h2 id="precedence">{{s1 Precedence}}</h2>
 
 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both general and language specific) always overrule referenced style guides. The language specific sections overrule the general section.}}</p>
 
 <h2 id="consistency">{{s3 Consistency}}</h2>
 
 <p>{{s4 Consistency is most important: Be consistent within functions, files, modules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or project at once.}}</p>
@@ skipping 25 matching lines @@
   <li>{{html-css-optional-tag Don't omit optional HTML tags.}}</li>
   <li>{{html-css-hexadecimal CSS color values should be specified in hexadecimal where possible.}}</li>
   <li>{{html-css-shorthand CSS shorthand properties usage is optional.}}</li>
   <li>{{html-css-order CSS rule declaration order should follow the <a href="https://make.wordpress.org/core/handbook/best-practices/coding-standards/css/#property-ordering">WordPress CSS Coding Standards</a>.}}</li>
   <li>{{html-css-units CSS number values should specify units where possible.}}</li>
   <li>{{html-css-leading-zero Don't omit the optional leading 0 for decimal numbers.}}</li>
 </ul>
 
 <h2 id="python">{{s19 Python}}</h2>
 <ul>
-  <li>{{python-general Follow <a href="https://www.python.org/dev/peps/pep-0008/">PEP-8</a> and the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#Python_Practices">Python practices</a>.}}</li>
+  <li>{{python-general Follow <a href="https://www.python.org/dev/peps/pep-0008/">PEP-8</a> and the recommendations in the offical Python documentation.}}</li>
+  <li>{{python-strings Write string literals so that they match the behaviour of <a href="https://docs.python.org/2/library/functions.html#func-repr"><code><fix>repr()</fix></code></a> in Python 2, or <a href="https://docs.python.org/3/library/functions.html#ascii"><code><fix>ascii()</fix></code></a> in Python 3, i.e. use single quotes except to avoid escaping of embedded quotes and escape special and non-ascii characters. For docstrings, however, follow <a href="https://www.python.org/dev/peps/pep-0257/">PEP-257</a>.}}</li>
   <li>{{python-prefix In modules, prefix private functions and variables with a single underscore.}}</li>
   <li>{{python-concatenation Use the <code><fix>+</fix></code> operator when concatenating exactly two strings, use the <a href="https://docs.python.org/2/library/stdtypes.html#str.format"><code><fix>format()</fix></code> method</a> for more complex string formatting, use the <a href="https://docs.python.org/2/library/stdtypes.html#str.join"><code><fix>join()</fix></code> method</a> when concatenating pre-existing sequences.}}</li>
   <li>{{python-tuple-vs-list Use tuples for data that have structure, use lists for data that have order.}}</li>
-  <li>{{python-regexp Use <a href="https://docs.python.org/2/library/re.html#re.search"><code><fix>re.search()</fix></code></a> instead <a href="https://docs.python.org/2/library/re.html#re.match"><code><fix>re.match()</fix></code></a> to avoid confusion about implied begin of string.}}</li>

[Vasily Kuznetsov, 2016/04/20 12:11:18]

I think "beginning of the string" would be better than "begin of string".

Also, perhaps we should add "but not the ending" (so the final result would be
"to avoid confusion about implied beginning of the string but not the ending")
-- at least for me the confusion is actually about the inconsistency and not
doing what "match" implies (string as a whole matches the regexp).

Not sure if we should also reference this part of the python doc:
https://docs.python.org/2/library/re.html#search-vs-match -- you do already give
two links so perhaps that's enough.

[Sebastian Noack, 2016/05/11 16:20:02]

Yeah, I agree. I was just tried to keep in short, but fair enough.
I added that link and removed the link to re.match. No point linking to docs of
an API we advise against anyway.

+  <li>{{python-builtins Don't override builtins except for <a href="https://docs.python.org/2/library/functions.html#non-essential-built-in-funcs">non-essential builtins</a> and <code><fix>file</fix></code> which is superfluos in modern code as well.}}</li>
+  <li>{{python-map-filter Use list comprehensions or generator expressions instead of calling <code><fix>map()</fix></code> or <code><fix>filter()</fix></code> with a lambda function.}}</li>
+  <li>{{python-regexp Use <a href="https://docs.python.org/2/library/re.html#re.search"><code><fix>re.search()</fix></code></a> instead of <code><fix>re.match()</fix></code> to avoid <a href="https://docs.python.org/2/library/re.html#search-vs-match">confusion</a> about implied beginning of the string but not the ending.}}</li>
+  <li>{{python-flake8 Run <a href="https://pypi.python.org/pypi/flake8">flake8</a> with the <a href="https://hg.adblockplus.org/codingtools/file/tip/flake8-abp">flake8-abp</a> and <a href="https://pypi.python.org/pypi/pep8-naming">pep8-naming</a> extensions and fix any warning.}}</li>
+  <li>{{python-tests Write tests and have them run along flake8 using <a href="https://pypi.python.org/pypi/tox">tox</a>.}}</li>
 </ul>
 
 <h2 id="java">{{s22 Java}}</h2>
 <ul>
   <li>{{s23 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#Java_practices">Java practices</a>.}}</li>
   <li>{{s24 Imports should be organised consistently per file, we don't use global rules.}}</li>
 </ul>
 
 <h2 id="cpp">{{s25 C++}}</h2>
 <ul>
   <li>{{s26 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#C.2FC.2B.2B_practices">C++ practices</a>.}}</li>
   <li>{{s27 Indent namespace bodies.}}</li>
   <li>{{s28 Avoid manual memory management: Use references and values when possible, smart pointers when necessary, raw pointers only for weak references.}}</li>
   <li>{{s29 Don't use C-style casts unless its exact semantics are required.}}</li>
   <li>{{s30 We tend to use anonymous namespaces instead of static.}}</li>
 </ul>
 
 <h2 id="objc">{{objective-c Objective-C}}</h2>
 <ul>
   <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html">conventions</a>}}.</li>
 </ul>
 
 <h2 id="puppet">{{s31 Puppet}}</h2>
 <ul>
   <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.html">Puppet Style Guide</a>.}}</li>
   <li>{{s33 Opening braces don't go on their own line.}}</li>
   <li>{{s34 Arrows should not be aligned.}}</li>
 </ul>