#summary Style guide for Python code contributed to Melange
#labels Contents-Complete,Phase-Guidelines,Importance-Featured,Featured

Melange follows the [http://google-styleguide.googlecode.com/svn/trunk/pyguide.html Google Python Style Guide]; this document describes only those respects in which Melange's style differs from what is laid out in that document.

The [SoCOverview SoC framework], and
[MelangeIntro Melange web applications] built upon it, are implemented in
Python (it is one of the programming language besides Java and Go which are currently supported by
[http://code.google.com/appengine/ Google App Engine]). The Google Python Style Guide and these amendments to it are a
list of dos and don'ts for Python contributions to the Melange project.

The rules below are not guidelines or recommendations, but strict rules. You
may not disregard the rules we list below except as approved on a need-to-use
basis. But note also the advice on consistency at the end of the guide.

If you have questions about these guidelines, you can send mail to the
[MailingListsGuidelines#Developer_list developer mailing list].
Please put *Python style:* in the subject line to make it easier to locate
these discussions in the mailing list archives.

Since this style guide is documented in the Melange wiki, it can be changed via
the existing [DocumentationReviews documentation review process].  However,
changes to the style guide should not be made lightly, since
[PythonStyleGuide#Conclusion consistency] is one of the key goals
of this style guide, and old code will not necessarily be updated for new
style guide changes.

= Summary =

== Python Language Rules ==

 # [PythonStyleGuide#Imports Imports]: _Import only modules and only by name *(no wildcard imports)*_
 # [PythonStyleGuide#Function_Arguments Function Arguments]: _Pass positional arguments positionally and keyword arguments by keyword._
 # [PythonStyleGuide#Threading Threading]: _*For now, do not use* (but it is on its way as part of [https://code.google.com/p/soc/issues/detail?id=1596 issue 1596])_

== Python Style Rules ==

Programs are much easier to maintain when all files have a consistent
style. Here is the canonical Melange Python style.

 # [PythonStyleGuide#Indentation Indentation]: _*2* spaces (*no tabs*),_ *differs from [http://www.python.org/dev/peps/pep-0008/ PEP8]*
 # [PythonStyleGuide#Python_Interpreter Python Interpreter]: _Variable, either omitted, `#!/usr/bin/python`, or `#!/usr/bin/python2.7`_
 # [PythonStyleGuide#Copyright_And_License_Notices Copyright And License Notices]: _Include in every file._
 # [PythonStyleGuide#Imports_grouping_and_order Imports grouping, order and sorting]: _One per line, grouped and ordered by packages, sorted alphabetically_
 # [PythonStyleGuide#Naming Naming]: _`foo_bar.py` not `foo-bar.py`,_ *some differ from [http://www.python.org/dev/peps/pep-0008/ PEP8]*
 # [PythonStyleGuide#Conclusion Conclusion]: _Look at what's around you!_

= Python Language Rules =

== Imports ==

*What it is:* Mechanism for making use of code between modules.

*Pros:* Very flexible relative to other languages. Packages, modules, classes,
functions, and fields all may be imported.

*Cons:* `from foo import *` or `import bar.baz.Spar` is very nasty and can
lead to serious maintenance issues because it makes it hard to find module
dependencies.

*Decision:* Import only modules. Use `as` to resolve name conflicts if
necessary. Use `from` for all imports below top-level. Use only absolute
imports; do not use relative imports. Do not import packages, classes,
functions, fields, or anything that is not a module.

{{{
import os
import sys

from models.graphics import views as graphics_views
from models.sounds import views as sounds_views
from sound.effects import echo
...
echo.echofilter(input, output, delay=0.7, atten=4)
}}} 

Even if the module is in the same package, do not directly import the module
without the full package name. This might cause the package to be imported
twice and have unintended side effects.

== Function Arguments ==

*What they are:* Arguments passed to functions either by position or by name.

*Pros:* Passing arguments always by name can help code be self-documenting.

*Cons:* Passing positional arguments by name can make a call site appear as
though all arguments are optional. Passing keyword arguments by position can
make a call site appear as though all arguments are required.

*Decision:* Always pass positional arguments positionally and keyword
arguments by keyword.

== Threading ==

Melange as of January 2013 is not thread-safe. Work to support thread safety
is happening as part of [https://code.google.com/p/soc/issues/detail?id=1596
issue 1596], but for now avoid threading.

= Python Style Rules =

== Indentation ==

_Note that this differs from
[http://www.python.org/dev/peps/pep-0008/ PEP8]
and instead follows the original Google Python Style guide from which
this style guide originated._

Indent your code blocks with 2 spaces. Never use tabs or mix tabs and
spaces. In cases of implied line continuation, you should align wrapped
elements either vertically, as per the examples in the line length
section; or using a hanging indent of *4* spaces (not 2, so as not to be
confused with an immediately-following nested block), in which case there
should be no argument on the first line.

*Yes:*

{{{
# Aligned with opening delimiter 
foo = longFunctionName(var_one, var_two,
                       var_three, var_four)

# 4-space hanging indent; nothing on first line
foo = longFunctionName(
    var_one, var_two, var_three,
    var_four)
}}}

*No:*

{{{
# Stuff on first line forbidden
foo = longFunctionName(var_one, var_two,
    var_three, var_four)

# 2-space hanging indent forbidden
foo = longFunctionName(
  var_one, var_two, var_three,
  var_four)
}}}    

=== Python Interpreter ==

Modules which are not intended for direct execution (and which have no effect if executed) should not include a shebang line.

Modules intended for direct execution should begin with a shebang line specifying the Python interpreter used to execute the program, most likely `#!/usr/bin/python` or `#!/usr/bin/python2.7`.

== Copyright And License Notices ==

Every module should feature the following either at the top or just below
the module's shebang and blank-comment-following-shebang lines.

{{{
# Copyright [current year] the Melange authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#   http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
}}}

== Imports grouping and order ==

Imports should be on separate lines, e.g.:

*Yes:*

{{{
import os
import sys
}}}

*No:*

{{{
import sys, os
}}}    

Imports are always put at the top of the file, just after any module
comments and `__doc__` strings and before module globals and constants.
Imports should be grouped with the order being most generic to least
generic:

 * standard library imports
 * third-party library imports
 * Google App Engine imports
 * django framework imports
 * SoC framework imports
 * SoC-based module imports
 * application specific imports

Sorting should be done alphabetically.

{{{
import a_standard
import b_standard

import a_third_party
import b_third_party

from a_soc import f
from a_soc import g
from b_soc import d
}}}

Resolution of clashing names between soc-framework and soc-module modules should be done by prefixing the soc-module module with the name of the soc-module from which it was imported:

{{{
from soc.views.helper import url_patterns
from soc.modules.gsoc.views.helper import url_patterns as gsoc_url_patterns
}}}

== Naming ==

=== Names to avoid ===

 * single character names, except for counters or iterators
 * dashes (`-`) in any package/module name
 * `__double_leading_and_trailing_underscore__` names (reserved by Python) 

=== Naming convention ===

_Note that some naming conventions differ from
[http://www.python.org/dev/peps/pep-0008/ PEP8]
and instead follow the original Google Python Style guide from which
this style guide originated._

 * "Internal" means internal to a module or protected or private within a class.
 * Prepending a single underscore (`_`) has some support for protecting module variables and functions (not included with `import * from`).
 * Prepending a double underscore (`__`) to an instance variable or method effectively serves to make the variable or method private to its class (using name mangling).
 * Place related classes and top-level functions together in a module. Unlike Java, there is no need to limit yourself to one class per module. However, make sure the classes and top-level functions in the same module have [http://en.wikipedia.org/wiki/Cohesion_(computer_science) high cohesion].
 * Use `CapWords` for class names, but `lower_with_under.py` for module names.

=== Naming examples ===

|| *Type* || *Public* || *Internal* ||
|| _Packages_ || `lower_with_under` || ||
|| _Modules_ || `lower_with_under` || `_lower_with_under` ||
|| _Classes_ || `CapWords` || `_CapWords` ||
|| _Exceptions_ || `CapWords` || ||
|| _Functions_ || `firstLowerCapWords()` || `_firstLowerCapWords()` ||
|| _Global/Class Constants_ || `CAPS_WITH_UNDER` || `_CAPS_WITH_UNDER` ||
|| _Global/Class Variables_ || `lower_with_under` || `_lower_with_under` ||
|| _Instance Variables_ || `lower_with_under` || `_lower_with_under` _(protected)_ or `__lower_with_under` _(private)_ ||
|| _Method Names_^*^ || `firstLowerCapWords()` || `_firstLowerCapWords()` _(protected)_ or `__firstLowerCapWords()` _(private)_ ||
|| _Function/Method Parameters_ || `lower_with_under` || ||
|| _Local Variables_ || `lower_with_under` || ||

^*^ Consider just using
[PythonStyleGuide#Access_control direct access to public attributes]
in preference to getters and setters, as function calls are expensive
in Python, and `property` can be used later to turn attribute access into a
function call without changing the access syntax.

== Conclusion ==

_BE CONSISTENT._

If you are editing code, take a few minutes to look at the code around
you and determine its style. If spaces are used around the `if` clauses,
you should, too. If the comments have little boxes of stars around them,
make your comments have little boxes of stars around them, too.

The point of having style guidelines is to have a common vocabulary
of coding so people can concentrate on what you are saying rather than
on how you are saying it. We present global style rules here so people
know the vocabulary, but local style is also important. If code you add
to a file looks drastically different from the existing code around it,
it throws readers out of their rhythm when they go to read it. Try to
avoid this.

----
_Copyright 2008 Google Inc._
_This work is licensed under a_
[http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-attribution-2_5.html Creative Commons Attribution 2.5 License].
[http://creativecommons.org/licenses/by/2.5/ http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-2_5-88x31.png]