Packages are a way of structuring Python’s module namespace by using “dotted module names”. For example, the module name A.Bdesignates a submodule namedBin a package namedA. Just like the use of modules saves the authors of different modules from having to worry about each other’s global variable names, the use of dotted module names saves the authors of multi-module packages like NumPy or the Python Imaging Library from having to worry about each other’s module names.
Suppose you want to design a collection of modules (a “package”) for the uniform handling of sound files and sound data. There are many different sound file formats (usually recognized by their extension, for example:
.wav,.aiff,.au), so you may need to create and maintain a growing collection of modules for the conversion between the various file formats. There are also many different operations you might want to perform on sound data (such as mixing, adding echo, applying an equalizer function, creating an artificial stereo effect), so in addition you will be writing a never-ending stream of modules to perform these operations. Here’s a possible structure for your package (expressed in terms of a hierarchical filesystem):
sound/ Top-level package
__init__.py Initialize the sound package
formats/ Subpackage for file format conversions __init__.py
wavread.py wavwrite.py aiffread.py aiffwrite.py auread.py auwrite.py ...
effects/ Subpackage for sound effects __init__.py
echo.py surround.py reverse.py ...
filters/ Subpackage for filters
__init__.py equalizer.py vocoder.py karaoke.py ...
When importing the package, Python searches through the directories onsys.pathlooking for the package
Python Tutorial, Release 3.6.4
subdirectory.
The__init__.pyfiles are required to make Python treat the directories as containing packages; this is done to prevent directories with a common name, such asstring, from unintentionally hiding valid modules that occur later on the module search path. In the simplest case,__init__.py can just be an empty file, but it can also execute initialization code for the package or set the__all__variable, described later.
Users of the package can import individual modules from the package, for example:
import sound.effects.echo
This loads the submodulesound.effects.echo. It must be referenced with its full name.
sound.effects.echo.echofilter(input, output, delay=0.7, atten=4) An alternative way of importing the submodule is:
from sound.effects import echo
This also loads the submoduleecho, and makes it available without its package prefix, so it can be used as follows:
echo.echofilter(input, output, delay=0.7, atten=4)
Yet another variation is to import the desired function or variable directly:
from sound.effects.echo import echofilter
Again, this loads the submoduleecho, but this makes its functionechofilter() directly available:
echofilter(input, output, delay=0.7, atten=4)
Note that when using from package import item, the item can be either a submodule (or subpackage) of the package, or some other name defined in the package, like a function, class or variable. The import statement first tests whether the item is defined in the package; if not, it assumes it is a module and attempts to load it. If it fails to find it, anImportErrorexception is raised.
Contrarily, when using syntax like import item.subitem.subsubitem, each item except for the last must be a package; the last item can be a module or a package but can’t be a class or function or variable defined in the previous item.
6.4.1 Importing * From a Package
Now what happens when the user writesfrom sound.effects import *? Ideally, one would hope that this somehow goes out to the filesystem, finds which submodules are present in the package, and imports them all. This could take a long time and importing sub-modules might have unwanted side-effects that should only happen when the sub-module is explicitly imported.
The only solution is for the package author to provide an explicit index of the package. Theimportstatement uses the following convention: if a package’s__init__.pycode defines a list named__all__, it is taken to be the list of module names that should be imported whenfrom package import *is encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don’t see a use for importing * from their package. For example, the filesound/effects/__init__.py could contain the following code:
__all__ = ["echo", "surround", "reverse"]
6.4. Packages 49
This would mean that from sound.effects import *would import the three named submodules of the soundpackage.
If__all__is not defined, the statementfrom sound.effects import *doesnotimport all submodules from the package sound.effectsinto the current namespace; it only ensures that the package sound.effects has been imported (possibly running any initialization code in __init__.py) and then imports whatever names are defined in the package. This includes any names defined (and submodules explicitly loaded) by __init__.py. It also includes any submodules of the package that were explicitly loaded by previousimport statements. Consider this code:
import sound.effects.echo import sound.effects.surround from sound.effects import *
In this example, the echoand surroundmodules are imported in the current namespace because they are defined in the sound.effects package when the from...import statement is executed. (This also works when__all__is defined.)
Although certain modules are designed to export only names that follow certain patterns when you use import *, it is still considered bad practice in production code.
Remember, there is nothing wrong with usingfrom Package import specific_submodule! In fact, this is the recommended notation unless the importing module needs to use submodules with the same name from different packages.
6.4.2 Intra-package References
When packages are structured into subpackages (as with thesound package in the example), you can use absolute imports to refer to submodules of siblings packages. For example, if the modulesound.filters.
vocoder needs to use the echo module in the sound.effects package, it can use from sound.effects import echo.
You can also write relative imports, with thefrom module import nameform of import statement. These imports use leading dots to indicate the current and parent packages involved in the relative import. From thesurroundmodule for example, you might use:
from . import echo from .. import formats
from ..filters import equalizer
Note that relative imports are based on the name of the current module. Since the name of the main module is always "__main__", modules intended for use as the main module of a Python application must always use absolute imports.
6.4.3 Packages in Multiple Directories
Packages support one more special attribute,__path__. This is initialized to be a list containing the name of the directory holding the package’s __init__.py before the code in that file is executed. This variable can be modified; doing so affects future searches for modules and subpackages contained in the package.
While this feature is not often needed, it can be used to extend the set of modules found in a package.
CHAPTER
SEVEN
INPUT AND OUTPUT
There are several ways to present the output of a program; data can be printed in a human-readable form, or written to a file for future use. This chapter will discuss some of the possibilities.
7.1 Fancier Output Formatting
So far we’ve encountered two ways of writing values: expression statements and the print() function.
(A third way is using the write() method of file objects; the standard output file can be referenced as sys.stdout. See the Library Reference for more information on this.)
Often you’ll want more control over the formatting of your output than simply printing space-separated values. There are two ways to format your output; the first way is to do all the string handling yourself;
using string slicing and concatenation operations you can create any layout you can imagine. The string type has some methods that perform useful operations for padding strings to a given column width; these will be discussed shortly. The second way is to use formatted string literals, or thestr.format()method.
Thestringmodule contains aTemplateclass which offers yet another way to substitute values into strings.
One question remains, of course: how do you convert values to strings? Luckily, Python has ways to convert any value to a string: pass it to therepr()or str()functions.
The str() function is meant to return representations of values which are fairly human-readable, while repr()is meant to generate representations which can be read by the interpreter (or will force aSyntaxError if there is no equivalent syntax). For objects which don’t have a particular representation for human con-sumption,str()will return the same value asrepr(). Many values, such as numbers or structures like lists and dictionaries, have the same representation using either function. Strings, in particular, have two distinct representations.
Some examples:
>>> s = 'Hello, world.'
>>> str(s)
'Hello, world.'
>>> repr(s)
"'Hello, world.'"
>>> str(1/7)
'0.14285714285714285'
>>> x = 10 * 3.25
>>> y = 200 * 200
>>> s = 'The value of x is ' + repr(x) + ', and y is ' + repr(y) + '...'
>>> print(s)
The value of x is 32.5, and y is 40000...
>>> # The repr() of a string adds string quotes and backslashes:
... hello = 'hello, world\n'
>>> hellos = repr(hello)
51
>>> print(hellos) 'hello, world\n'
>>> # The argument to repr() may be any Python object:
... repr((x, y, ('spam', 'eggs')))
"(32.5, 40000, ('spam', 'eggs'))"
Here are two ways to write a table of squares and cubes:
>>> for x in range(1, 11):
... print(repr(x).rjust(2), repr(x*x).rjust(3), end=' ') ... # Note use of 'end' on previous line
... print(repr(x*x*x).rjust(4)) ...
1 1 1
2 4 8
3 9 27
4 16 64 5 25 125 6 36 216 7 49 343 8 64 512 9 81 729 10 100 1000
>>> for x in range(1, 11):
... print('{0:2d} {1:3d} {2:4d}'.format(x, x*x, x*x*x)) ...
1 1 1
2 4 8
3 9 27
4 16 64 5 25 125 6 36 216 7 49 343 8 64 512 9 81 729 10 100 1000
(Note that in the first example, one space between each column was added by the way print()works: it always adds spaces between its arguments.)
This example demonstrates the str.rjust() method of string objects, which right-justifies a string in a field of a given width by padding it with spaces on the left. There are similar methods str.ljust() and str.center(). These methods do not write anything, they just return a new string. If the input string is too long, they don’t truncate it, but return it unchanged; this will mess up your column lay-out but that’s usually better than the alternative, which would be lying about a value. (If you really want truncation you can always add a slice operation, as inx.ljust(n)[:n].)
There is another method,str.zfill(), which pads a numeric string on the left with zeros. It understands about plus and minus signs:
>>> '12'.zfill(5)
'00012'
>>> '-3.14'.zfill(7)
'-003.14'
>>> '3.14159265359'.zfill(5)
'3.14159265359'
Basic usage of thestr.format()method looks like this:
Python Tutorial, Release 3.6.4
>>> print('We are the {} who say "{}!"'.format('knights', 'Ni'))
We are the knights who say "Ni!"
The brackets and characters within them (called format fields) are replaced with the objects passed into the str.format()method. A number in the brackets can be used to refer to the position of the object passed into thestr.format()method.
>>> print('{0} and {1}'.format('spam', 'eggs'))
spam and eggs
>>> print('{1} and {0}'.format('spam', 'eggs'))
eggs and spam
If keyword arguments are used in thestr.format()method, their values are referred to by using the name of the argument.
>>> print('This {food} is {adjective}.'.format(
... food='spam', adjective='absolutely horrible')) This spam is absolutely horrible.
Positional and keyword arguments can be arbitrarily combined:
>>> print('The story of {0}, {1}, and {other}.'.format('Bill', 'Manfred',
other='Georg')) The story of Bill, Manfred, and Georg.
'!a'(applyascii()),'!s'(applystr()) and'!r'(applyrepr()) can be used to convert the value before it is formatted:
>>> contents = 'eels'
>>> print('My hovercraft is full of {}.'.format(contents))
My hovercraft is full of eels.
>>> print('My hovercraft is full of {!r}.'.format(contents))
My hovercraft is full of 'eels'.
An optional ':' and format specifier can follow the field name. This allows greater control over how the value is formatted. The following example rounds Pi to three places after the decimal.
>>> import math
>>> print('The value of PI is approximately {0:.3f}.'.format(math.pi))
The value of PI is approximately 3.142.
Passing an integer after the':' will cause that field to be a minimum number of characters wide. This is useful for making tables pretty.
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
>>> for name, phone in table.items():
... print('{0:10} ==> {1:10d}'.format(name, phone)) ...
Jack ==> 4098
Dcab ==> 7678
Sjoerd ==> 4127
If you have a really long format string that you don’t want to split up, it would be nice if you could reference the variables to be formatted by name instead of by position. This can be done by simply passing the dict and using square brackets'[]'to access the keys
7.1. Fancier Output Formatting 53
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {0[Jack]:d}; Sjoerd: {0[Sjoerd]:d}; '
... 'Dcab: {0[Dcab]:d}'.format(table)) Jack: 4098; Sjoerd: 4127; Dcab: 8637678
This could also be done by passing the table as keyword arguments with the ‘**’ notation.
>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
>>> print('Jack: {Jack:d}; Sjoerd: {Sjoerd:d}; Dcab: {Dcab:d}'.format(**table))
Jack: 4098; Sjoerd: 4127; Dcab: 8637678
This is particularly useful in combination with the built-in function vars(), which returns a dictionary containing all local variables.
For a complete overview of string formatting withstr.format(), see formatstrings.
7.1.1 Old string formatting
The%operator can also be used for string formatting. It interprets the left argument much like a sprintf()-style format string to be applied to the right argument, and returns the string resulting from this formatting operation. For example:
>>> import math
>>> print('The value of PI is approximately %5.3f.' % math.pi)
The value of PI is approximately 3.142.
More information can be found in the old-string-formatting section.