forked from openedx/edx-platform
-
Notifications
You must be signed in to change notification settings - Fork 0
Python Guidelines
Ned Batchelder edited this page Apr 8, 2014
·
27 revisions
Generally, don't edit files just to change the style. But do aim for this style with new or modified code.
Follow PEP 8
- 4-space indents (no tabs)
- Names like this: modules_and_packages, functions_and_methods, local_variables, GLOBALS, CONSTANTS, MultiWordClasses
- Acronyms should count as one word: RobustHtmlParser, not RobustHTMLParser
- Trailing commas are good: they prevent having to edit the last line in a list when adding a new last line. You can use them in lists, dicts, function calls, etc.
- EXCEPT: we aren't (yet) limiting code lines to 79 characters. Use 120 as a limit for code. Please use 79 chars as a limit for docstring lines though, so that the text remains readable.
Follow these guidelines:
- Try to refactor the code to not need such long lines. This is often the best option, and is often overlooked for some reason. More, shorter lines are good.
- If you need to break a function call over more than one line, put a newline after the open paren, and move the arguments to their own line. DO NOT indent everything to where the open paren is. This makes the code too indented, and makes different function calls near each other indented different amounts.
# NO NO NO!:
results = my_object.some_method(arg1, # this is very
arg2, # very ugly and makes
arg3, # the code squished over on the right.
)
# YES:
results = my_object.some_method(
arg1,
arg2,
arg3,
)
# OR:
results = my_object.some_method(
arg1, arg2, arg3
)
Important points:
- Don't over-indent to make things line up with punctuation on the first line.
- Closing paren should be on a line by itself, indented the same as the first line.
- The first line ends with the open paren.
PEP 8 recommends a most-general to most-specific import order, which means this order:
- Standard library imports
- Third Party Library imports
- Core Django imports
- Third party Django app imports
- Other edX repo imports
- Local imports
Follow PEP 257
- Write docstrings for all modules, classes, and functions.
- Use three double-quotes for all docstrings.
- Start with a one-line summary. If you can't fit a summary in one line, think harder, or refactor the code.
- Write in Sphinx-friendly prose style. Put backquotes around code names (variables, parameters, methods, etc).
The preferred style is so-called "Google Style" with readable headers for different sections, and all arguments and return values defined:
def func(arg1, arg2):
"""
Summary line.
Extended description of function.
Arguments:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
Most of our code using an older style:
def calculate_grade(course, student):
"""
Sum up the grade for a student in a particular course.
Navigates the entire course, adding up the student's grades. Note that
blah blah blah, and also beware that blah blah blah.
`course` is an `EdxCourseThingy`. The student must be registered in the
course, or a `NotRegistered` exception will be raised.
`student` is an `EdxStudentThingy`.
Returns a dict with two keys: `total` is a float, the student's total
score, and `outof` is the maximum possible score.
"""
- For unused args, you can prefix the arguments with _ to mark them as unused (as convention), and pylint will accept that.
- Adding a TODO in one place requires you to make a pylint fix in another (just to force us to clean up more code)
- No bare except clauses. except: should be except Exception:, which will prevent it from catching system-exiting exceptions, which we probably shouldn't be doing anyway. If we need to, we can catch BaseException (There's no point in catching BaseException, that includes the exceptions we didn't want to catch with except: in the first place.) (ref: http://docs.python.org/2/library/exceptions.html#bltin-exceptions). Catching Exception, however, will still generate a pylint warning "W0703: catching too general exception." If you still feel that catching Exception is justified, silence the pylint warning with a pragma: "# pylint: disable=W0703"
- Fat Models, Helper Modules, Thin Views, Stupid Templates