Coding Style (Python)¶

Absolute and relative imports¶

In Python 2, importing modules can be ambiguous when a module of that name exists in the same package and elsewhere in the module search path sys.path. To work around this ambiguity, programmers often resorted to adding paths private to the project to the beginning of sys.path to force loading modules from a project-internal location (which adds unwanted noise and can make e.g. testing code that isn’t installed difficult). Python 3 introduces new syntax for import statements which makes both cases distinct, this is available since version 2.5 from the __future__ module:

from __future__ import absolute_import

# Import the sys module from the module search path
import sys

# Import the foo module from the same directory
from . import foo

# Import snafu from the bar module one directory above
from ..bar import snafu

Print function¶

Python 3 did away with print as a statement and introduced it as a function. In order to use it the same way in Python 2.7, add the following to the top of source code files where you use print:

from __future__ import print_function

Numbers¶

Python 2 has two integer types, `int` which is whatever integer-type is native to the system (which has certain maximal and minimal values and can overflow) and `long` which can store arbitrary integer numbers. Python 3 only the latter type, but it’s called int.

Dividing integer numbers using / truncates the result to an integer in Python 2 by default, but yields a floating point number in Python 3. In order for code to do the same thing on either version, include the following line at the top of your source files where you divide numbers, and use / for normal divisions and // for divisions that should truncate the result:

from __future__ import division

Strings¶

Some consider this the main difference between Python 2 and 3: Both versions have a type for strings of bytes and strings of Unicode character points. They are called str and unicode in version 2 and bytes and str in version 3, respectively.

# a byte string in Python 2 and 3
string1 = b"abc"

# a byte string in Python 2, but a text string in Python 3
string2 = "def"

# a text string in Python 2 and 3
string3 = u"ghi"

from __future__ import unicode_literals

from __future__ import print_function
text_string = u"Hello, world!"
print(text_string.replace("world", "gang"))

from __future__ import print_function, unicode_literals
text_string = "Hello, world!"
print(text_string.replace(b"world".decode('utf-8'), b"gang".decode('ascii')))

Old- and New-style Classes¶

Python 2 and earlier knows two types of classes, old-style which have no base class, and new-style which have object as the base class. Because their behavior is slightly different in some places, and some things can’t be done with old-style classes, we want to stick to new-style classes wherever possible.

The syntactical difference is that new-style classes have to explicitly be derived from object or another new-style class.

# old-style classes
class OldFoo:
    pass

class OldBar(OldFoo):
    pass

# new-style classes
class NewFoo(object):
    pass

class NewBar(NewFoo):
    pass

Python 3 only knows new-style classes and the requirement to explicitly derive from object was dropped. In projects that will only ever run on Python 3, it’s acceptable not to explicitly derive classes without parents from object, but if in doubt, do it just the same.

Literals and Comprehensions¶

Python has special syntax for literals for a couple of built-in compound data types: lists, tuples, dictionaries, strings, sets. It’s customary to use that syntax instead of the class constructor to create objects for these data types unless you have good reason not to. Apart from how it looks, the literal syntax is performing a little bit better (because it doesn’t have to look up the class name in the current scope). NB: Set literals are peculiar in that you can’t create empty ones­—they would look the same as empty dicts.

Table: Creating compound objects

Often the initial contents of a compound object are only known when it’s created at runtime. For simple cases like mere type conversions, calling the class constructors are the way to go:

• Converting a tuple to a list or vice versa:

• Convert a list to a set, e.g. to filter out duplicates:

For more involved cases, say some values need to be filtered or a specific attribute of the objects is wanted, Python has so-called comprehensions to create compound objects in a syntactically “nice” way. These largely supersede the old (ugly) way of using map() and filter() in conjunction with class constructors.

Table: Using comprehensions to create compound objects

Looping¶

Languages like C normally use incremented indices to loop over arrays:

float pixels[NUMBER_OF_PIXELS] = [...];

for (int i = 0; i < NUMBER_OF_PIXELS; i++)
{
    do_something_with_a_pixel(pixels[i]);
}

Implementing the loop like this would give away that you’ve programmed in C or a similar language before:

pixels = [...]

for i in range(len(pixels)):
    do_something_with_a_pixel(pixels[i])

Here’s the “native” way to implement the above loop:

pixels = [...]

for p in pixels:
    do_something_with_a_pixel(p)

It yields pairs of count (starting at 0 by default) and the current value like this:

pixels = [...]

for p_no, p in enumerate(pixels, 1):
    print("Working on pixel no. {}".format(p_no))
    do_something_with_a_pixel(p)

Properties rather than explicit accessor methods¶

In order to allow future changes in how object attributes (member variables) are set, some languages encourage always using getter and/or setter methods. This is unnecessary in Python, as you can intercept access to an attribute by wrapping it into a property if and when this becomes necessary. Properties allow having accessor methods without making the user of the class have to use them explicitly. This way you can validate values when an attribute is set, or translate back and forth between the interface used on the attribute and an internal representation.

class Employee(object):

    @property
    def salary(self):
        return self._salary

    @salary.setter
    def salary(self, salary):
        if salary <= 0:
            raise ValueError("Salary must be positive.")
        self._salary = salary

class Point(object):
    def __init__(self, x, y):
        self.x = x
        self.y = y

class Circle(object):
    def __init__(self, point, radius):
        self.point = point
        self.radius = radius

...
class Circle(object):
    def __init__(self, point, radius=None, diameter=None):
        self.point = point
        if (radius is None) == (diameter is None):
            raise ValueError("Exactly one of radius or diameter must be set")
        if radius is not None:
            self.radius = radius
        else:
            self.diameter = diameter

    @property
    def diameter(self):
        return self.radius * 2

    @diameter.setter
    def diameter(self, diameter):
        self.radius = diameter / 2.0
...