2.1 Writing Python script and module files – syntax basics

The point of Python (and programming in general) is to create automated solutions to problems that involve data and processing. Further, the software we write is a kind of knowledge representation; this means clarity is perhaps the most important quality aspect of software.

In Python, we implement automated solutions by creating script files. These are the top-level, main programs of Python programming. In addition to main scripts, we may also create modules (and packages of modules) to help organize the software into intellectually manageable chunks. A script is a module; however, it has a distinct intent to do useful processing when started by the OS.

A key part of creating clear, readable Python files is making sure our code follows the widely adopted conventions.

For example, we need to be sure to save our files in UTF-8 encoding. While ASCII encoding is still supported by Python,...

2.2 Writing long lines of code

There are many times when we need to write lines of code that are so long that they’re very hard to read. Many people like to limit the length of a line of code to 80 characters or fewer. It’s a well-known principle of graphic design that a narrower area of text is easier to read. See http://webtypography.net/2.1.2 for a deeper discussion of line width and readability.

While fewer characters per line is easier on the eyes, our code can refuse to cooperate with this principle. How can we break long Python statements into more manageable pieces?

>>> import math
>>> example_value = (63/25) * (17+15*math.sqrt(5)) / (7+15*math.sqrt(5))
>>> mantissa_fraction, exponent = math.frexp(example_value)
>>> mantissa_whole = int(mantissa_fraction*2**53)
>>> message_text = f’...

2.3 Including descriptions and documentation

When we have a useful script, we often need to leave notes for ourselves—and others—on what it does, how it solves some particular problem, and when it should be used. This recipe contains a suggested outline to help make the documentation reasonably complete.

2.4 Writing better docstrings with RST markup

When we have a useful script, we often need to leave notes on what it does, how it works, and when it should be used. Many tools for producing documentation, including Docutils, work with RST markup. This allows us to write plain text documentation. It can include some special punctuation to pick a bold or italic font variant to call attention to details. In addition, RST permits organizing content via lists and section headings.

2.5 Designing complex if...elif chains

In most cases, our scripts will involve a number of choices. Sometimes the choices are simple, and we can judge the quality of the design with a glance at the code. In other cases, the choices are more complicated, and it’s not easy to determine whether or not our if statements are designed properly to handle all of the conditions.

In the simplest case, we have one condition, C, and its inverse, ¬C. These are the two conditions for an if...else statement. One condition, C, is stated in the if clause; the inversion condition, ¬C, is implied in the else clause.

This follows the Law of the Excluded Middle: we’re claiming there’s no missing alternative between the two conditions, C and ¬C. For a complex condition, though, this can be difficult to visualize.

If we have something like:

 
 
if weather == Weather.RAIN and plan == Plan.GO_OUT: 
 
    ...

2.6 Saving intermediate results with the := ”walrus” operator

Sometimes we’ll have a complex condition where we want to preserve an expensive intermediate result for later use. Imagine a condition that involves a complex calculation; the cost of computing is high measured in time, input-output operations, memory resources, or all three.

An example includes doing repetitive searches using the Regular Expression (re) package. A match() method can do quite a bit of computation before returning either a Match object or a None object to show the pattern wasn’t found. Once this computation is completed, we may have several uses for the result, and we emphatically do not want to perform the computation again. Often, the initial use is the simple check to see if the result is a Match object or None.

This is an example where it can be helpful to assign a name to the value of an expression and also use the expression in an if statement. We...

2.7 Avoiding a potential problem with break statements

The common way to understand a for statement is that it creates a for all condition. At the end of the statement, we can assert that, for all items in a collection, the processing in the body of the statement has been done.

This isn’t the only meaning a for statement can have. When the break statement is used inside the body of a for statement, it changes the semantics to there exists. When the break statement leaves the for (or while) statement, we can assert there exists at least one item that caused the enclosing statement to end.

There’s a side issue here. What if the for statement ends without executing the break statement? Either way, we’re at the statement after the for statement. The condition that’s true upon leaving a for or while statement with a break statement can be ambiguous. We can’t easily tell; this recipe gives some design guidance.

The problem...

2.8 Leveraging exception matching rules

The try statement lets us capture an exception. When an exception is raised, we have a number of choices for handling it:

• Ignore it: If we do nothing, the program stops. We can do this in two ways—don’t use a try statement in the first place, or don’t have a matching except clause in the try statement.

• Log it: We can write a message and use a raise statement to let the exception propagate after writing to a log. The expectation is that this will stop the program.

• Recover from it: We can write an except clause to do some recovery action to undo any effects of the partially completed try clause.

• Silence it: If we do nothing (that is, use the pass statement), then processing is resumed after the try statement. This silences the exception, but does not correct the underlying problem, or supply alternative results as a recovery attempt.

• Rewrite it: We can raise a different...

2.9 Avoiding a potential problem with an except: clause

There are some common mistakes in exception handling. These can cause programs to become unresponsive.

One of the mistakes we can make is to use the except: clause with no named exception class to match. There are a few other mistakes that we can make if we’re not cautious about the exceptions we try to handle.

This recipe will show some common exception handling errors that we can avoid.

2.10 Concealing an exception root cause

Exceptions contain a root cause. The default behavior of internally raised exceptions is to use an implicit __context__ attribute to include the root cause of an exception. In some cases, we may want to deemphasize the root cause because it’s misleading or unhelpful for debugging.

This technique is almost always paired with an application or library that defines a unique exception. The idea is to show the unique exception without the clutter of an irrelevant exception from outside the application or library.

2.11 Managing a context using the with statement

There are many instances where our scripts will be entangled with external resources. The most common examples are disk files and network connections to external hosts. A common bug is retaining these entanglements forever, tying up these resources uselessly. These are sometimes called a memory leak because the available memory is reduced each time a new file is opened without closing a previously used file.

We’d like to isolate each entanglement so that we can be sure that the resource is acquired and released properly. The idea is to create a context in which our script uses an external resource. At the end of the context, our program is no longer bound to the resource and we want to be guaranteed that the resource is released.