Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/stdlib2.rst @ 86317:d513149e0c19 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Refer to strftime(3) manpage for platform specific format codes. Suggested by Skip Montanaro on docs@.
author Georg Brandl <georg@python.org>
date Sun, 13 Oct 2013 18:28:25 +0200
parents ac826284fdd1
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-brieftourtwo:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 *********************************************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Brief Tour of the Standard Library -- Part II
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 *********************************************
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 This second tour covers more advanced modules that support professional
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 programming needs. These modules rarely occur in small scripts.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. _tut-output-formatting:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 Output Formatting
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 =================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
47221
9fbc41abdd4b Revert the renaming of repr to reprlib.
Brett Cannon <bcannon@gmail.com>
parents: 47085
diff changeset
16 The :mod:`repr` module provides a version of :func:`repr` customized for
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 abbreviated displays of large or deeply nested containers::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
19 >>> import repr
47221
9fbc41abdd4b Revert the renaming of repr to reprlib.
Brett Cannon <bcannon@gmail.com>
parents: 47085
diff changeset
20 >>> repr.repr(set('supercalifragilisticexpialidocious'))
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 "set(['a', 'c', 'd', 'e', 'f', 'g', ...])"
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 The :mod:`pprint` module offers more sophisticated control over printing both
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24 built-in and user defined objects in a way that is readable by the interpreter.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 When the result is longer than one line, the "pretty printer" adds line breaks
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 and indentation to more clearly reveal data structure::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 >>> import pprint
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 ... 'yellow'], 'blue']]]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 >>> pprint.pprint(t, width=30)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 [[[['black', 'cyan'],
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 'white',
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 ['green', 'red']],
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 [['magenta', 'yellow'],
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 'blue']]]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 The :mod:`textwrap` module formats paragraphs of text to fit a given screen
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 width::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 >>> import textwrap
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 >>> doc = """The wrap() method is just like fill() except that it returns
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 ... a list of strings instead of one big string with newlines to separate
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 ... the wrapped lines."""
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 >>> print textwrap.fill(doc, width=40)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 The wrap() method is just like fill()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 except that it returns a list of strings
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 instead of one big string with newlines
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 to separate the wrapped lines.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 The :mod:`locale` module accesses a database of culture specific data formats.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54 The grouping attribute of locale's format function provides a direct way of
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 formatting numbers with group separators::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> import locale
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 'English_United States.1252'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 >>> conv = locale.localeconv() # get a mapping of conventions
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 >>> x = 1234567.8
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> locale.format("%d", x, grouping=True)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 '1,234,567'
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
64 >>> locale.format_string("%s%.*f", (conv['currency_symbol'],
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
65 ... conv['frac_digits'], x), grouping=True)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 '$1,234,567.80'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 .. _tut-templating:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 Templating
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 ==========
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
74 The :mod:`string` module includes a versatile :class:`~string.Template` class
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
75 with a simplified syntax suitable for editing by end-users. This allows users
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
76 to customize their applications without having to alter the application.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 The format uses placeholder names formed by ``$`` with valid Python identifiers
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 (alphanumeric characters and underscores). Surrounding the placeholder with
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 braces allows it to be followed by more alphanumeric letters with no intervening
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 spaces. Writing ``$$`` creates a single escaped ``$``::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 >>> from string import Template
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 >>> t = Template('${village}folk send $$10 to $cause.')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 >>> t.substitute(village='Nottingham', cause='the ditch fund')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 'Nottinghamfolk send $10 to the ditch fund.'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
88 The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
89 placeholder is not supplied in a dictionary or a keyword argument. For
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
90 mail-merge style applications, user supplied data may be incomplete and the
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
91 :meth:`~string.Template.safe_substitute` method may be more appropriate ---
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
92 it will leave placeholders unchanged if data is missing::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 >>> t = Template('Return the $item to $owner.')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 >>> d = dict(item='unladen swallow')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 >>> t.substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 Traceback (most recent call last):
79146
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
98 ...
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 KeyError: 'owner'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 >>> t.safe_substitute(d)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 'Return the unladen swallow to $owner.'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 Template subclasses can specify a custom delimiter. For example, a batch
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 renaming utility for a photo browser may elect to use percent signs for
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 placeholders such as the current date, image sequence number, or file format::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 >>> import time, os.path
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 >>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 >>> class BatchRename(Template):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 ... delimiter = '%'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 >>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format): ')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 >>> t = BatchRename(fmt)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 >>> date = time.strftime('%d%b%y')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 >>> for i, filename in enumerate(photofiles):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 ... base, ext = os.path.splitext(filename)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 ... newname = t.substitute(d=date, n=i, f=ext)
47282
70f9a5db279c update the tutorial to use str.format
Benjamin Peterson <benjamin@python.org>
parents: 47248
diff changeset
119 ... print '{0} --> {1}'.format(filename, newname)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 img_1074.jpg --> Ashley_0.jpg
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 img_1076.jpg --> Ashley_1.jpg
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 img_1077.jpg --> Ashley_2.jpg
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 Another application for templating is separating program logic from the details
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 of multiple output formats. This makes it possible to substitute custom
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 templates for XML files, plain text reports, and HTML web reports.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 .. _tut-binary-formats:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 Working with Binary Data Record Layouts
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 =======================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
135 The :mod:`struct` module provides :func:`~struct.pack` and
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
136 :func:`~struct.unpack` functions for working with variable length binary
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
137 record formats. The following example shows
44904
063ed377fd3d Fix issue1789: The tutorial contained a misuse of the struct module.
Gregory P. Smith <greg@mad-scientist.com>
parents: 44103
diff changeset
138 how to loop through header information in a ZIP file without using the
063ed377fd3d Fix issue1789: The tutorial contained a misuse of the struct module.
Gregory P. Smith <greg@mad-scientist.com>
parents: 44103
diff changeset
139 :mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four
063ed377fd3d Fix issue1789: The tutorial contained a misuse of the struct module.
Gregory P. Smith <greg@mad-scientist.com>
parents: 44103
diff changeset
140 byte unsigned numbers respectively. The ``"<"`` indicates that they are
063ed377fd3d Fix issue1789: The tutorial contained a misuse of the struct module.
Gregory P. Smith <greg@mad-scientist.com>
parents: 44103
diff changeset
141 standard size and in little-endian byte order::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 import struct
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 data = open('myfile.zip', 'rb').read()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146 start = 0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 for i in range(3): # show the first 3 file headers
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 start += 14
44904
063ed377fd3d Fix issue1789: The tutorial contained a misuse of the struct module.
Gregory P. Smith <greg@mad-scientist.com>
parents: 44103
diff changeset
149 fields = struct.unpack('<IIIHH', data[start:start+16])
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 crc32, comp_size, uncomp_size, filenamesize, extra_size = fields
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 start += 16
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 filename = data[start:start+filenamesize]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 start += filenamesize
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 extra = data[start:start+extra_size]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 print filename, hex(crc32), comp_size, uncomp_size
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 start += extra_size + comp_size # skip to the next header
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 .. _tut-multi-threading:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 Multi-threading
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 ===============
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 Threading is a technique for decoupling tasks which are not sequentially
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 dependent. Threads can be used to improve the responsiveness of applications
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 that accept user input while other tasks run in the background. A related use
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 case is running I/O in parallel with computations in another thread.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 The following code shows how the high level :mod:`threading` module can run
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 tasks in background while the main program continues to run::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 import threading, zipfile
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 class AsyncZip(threading.Thread):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177 def __init__(self, infile, outfile):
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
178 threading.Thread.__init__(self)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 self.infile = infile
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 self.outfile = outfile
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 def run(self):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 f.write(self.infile)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 f.close()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 print 'Finished background zip of: ', self.infile
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 background = AsyncZip('mydata.txt', 'myarchive.zip')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 background.start()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 print 'The main program continues to run in foreground.'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 background.join() # Wait for the background task to finish
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 print 'Main program waited until background was done.'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 The principal challenge of multi-threaded applications is coordinating threads
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 that share data or other resources. To that end, the threading module provides
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 a number of synchronization primitives including locks, events, condition
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 variables, and semaphores.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 While those tools are powerful, minor design errors can result in problems that
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 are difficult to reproduce. So, the preferred approach to task coordination is
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 to concentrate all access to a resource in a single thread and then use the
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
202 :mod:`Queue` module to feed that thread with requests from other threads.
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
203 Applications using :class:`Queue.Queue` objects for inter-thread communication
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
204 and coordination are easier to design, more readable, and more reliable.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 .. _tut-logging:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 Logging
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 =======
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 The :mod:`logging` module offers a full featured and flexible logging system.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 At its simplest, log messages are sent to a file or to ``sys.stderr``::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 import logging
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 logging.debug('Debugging information')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 logging.info('Informational message')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 logging.warning('Warning:config file %s not found', 'server.conf')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 logging.error('Error occurred')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 logging.critical('Critical error -- shutting down')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
79146
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
222 This produces the following output:
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
223
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
224 .. code-block:: none
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 WARNING:root:Warning:config file server.conf not found
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227 ERROR:root:Error occurred
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 CRITICAL:root:Critical error -- shutting down
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 By default, informational and debugging messages are suppressed and the output
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 is sent to standard error. Other output options include routing messages
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 through email, datagrams, sockets, or to an HTTP Server. New filters can select
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
233 different routing based on message priority: :const:`~logging.DEBUG`,
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
234 :const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
235 and :const:`~logging.CRITICAL`.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 The logging system can be configured directly from Python or can be loaded from
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238 a user editable configuration file for customized logging without altering the
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 application.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242 .. _tut-weak-references:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 Weak References
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 ===============
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 Python does automatic memory management (reference counting for most objects and
44103
1e266015cf5b Add more entries to the glossary.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
248 :term:`garbage collection` to eliminate cycles). The memory is freed shortly
1e266015cf5b Add more entries to the glossary.
Georg Brandl <georg@python.org>
parents: 42603
diff changeset
249 after the last reference to it has been eliminated.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 This approach works fine for most applications but occasionally there is a need
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 to track objects only as long as they are being used by something else.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 Unfortunately, just tracking them creates a reference that makes them permanent.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 The :mod:`weakref` module provides tools for tracking objects without creating a
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 reference. When the object is no longer needed, it is automatically removed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 from a weakref table and a callback is triggered for weakref objects. Typical
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 applications include caching objects that are expensive to create::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 >>> import weakref, gc
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 >>> class A:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 ... def __init__(self, value):
79889
1a3f48c6ef16 Closes #16294: 8 space indent in tutorial
Jesus Cea <jcea@jcea.es>
parents: 79146
diff changeset
262 ... self.value = value
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 ... def __repr__(self):
79889
1a3f48c6ef16 Closes #16294: 8 space indent in tutorial
Jesus Cea <jcea@jcea.es>
parents: 79146
diff changeset
264 ... return str(self.value)
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 ...
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266 >>> a = A(10) # create a reference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 >>> d = weakref.WeakValueDictionary()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 >>> d['primary'] = a # does not create a reference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 >>> d['primary'] # fetch the object if it is still alive
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 10
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 >>> del a # remove the one reference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 >>> gc.collect() # run garbage collection right away
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 0
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 >>> d['primary'] # entry was automatically removed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 Traceback (most recent call last):
45430
bc9fd84afdec Don't reference pyshell.
Georg Brandl <georg@python.org>
parents: 44904
diff changeset
276 File "<stdin>", line 1, in <module>
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 d['primary'] # entry was automatically removed
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 File "C:/python26/lib/weakref.py", line 46, in __getitem__
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 o = self.data[key]()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
280 KeyError: 'primary'
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283 .. _tut-list-tools:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 Tools for Working with Lists
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
286 ============================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
287
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 Many data structure needs can be met with the built-in list type. However,
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289 sometimes there is a need for alternative implementations with different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 performance trade-offs.
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
292 The :mod:`array` module provides an :class:`~array.array()` object that is like
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
293 a list that stores only homogeneous data and stores it more compactly. The
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
294 following example shows an array of numbers stored as two byte unsigned binary
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
295 numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
296 lists of Python int objects::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
297
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
298 >>> from array import array
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299 >>> a = array('H', [4000, 10, 700, 22222])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 >>> sum(a)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 26932
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> a[1:3]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 array('H', [10, 700])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
305 The :mod:`collections` module provides a :class:`~collections.deque()` object
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
306 that is like a list with faster appends and pops from the left side but slower
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
307 lookups in the middle. These objects are well suited for implementing queues
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
308 and breadth first tree searches::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
310 >>> from collections import deque
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311 >>> d = deque(["task1", "task2", "task3"])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 >>> d.append("task4")
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 >>> print "Handling", d.popleft()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 Handling task1
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
315
79146
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
316 ::
ce943bce76c9 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
317
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
318 unsearched = deque([starting_node])
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
319 def breadth_first_search(unsearched):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 node = unsearched.popleft()
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 for m in gen_moves(node):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 if is_goal(m):
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 return m
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 unsearched.append(m)
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 In addition to alternative list implementations, the library also offers other
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327 tools such as the :mod:`bisect` module with functions for manipulating sorted
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 lists::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 >>> import bisect
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331 >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 >>> bisect.insort(scores, (300, 'ruby'))
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 >>> scores
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 The :mod:`heapq` module provides functions for implementing heaps based on
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337 regular lists. The lowest valued entry is always kept at position zero. This
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 is useful for applications which repeatedly access the smallest element but do
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 not want to run a full list sort::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 >>> from heapq import heapify, heappop, heappush
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342 >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 >>> heapify(data) # rearrange the list into heap order
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 >>> heappush(data, -5) # add a new entry
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 >>> [heappop(data) for i in range(3)] # fetch the three smallest entries
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 [-5, 0, 1]
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 .. _tut-decimal-fp:
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 Decimal Floating Point Arithmetic
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 =================================
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
354 The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
355 decimal floating point arithmetic. Compared to the built-in :class:`float`
56819
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
356 implementation of binary floating point, the class is especially helpful for
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
357
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
358 * financial applications and other uses which require exact decimal
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
359 representation,
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
360 * control over precision,
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
361 * control over rounding to meet legal or regulatory requirements,
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
362 * tracking of significant decimal places, or
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
363 * applications where the user expects the results to match calculations done by
9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54944
diff changeset
364 hand.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
365
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366 For example, calculating a 5% tax on a 70 cent phone charge gives different
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 results in decimal floating point and binary floating point. The difference
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 becomes significant if the results are rounded to the nearest cent::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
370 >>> from decimal import *
57428
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
371 >>> x = Decimal('0.70') * Decimal('1.05')
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
372 >>> x
54944
dcf7121edb2e Merged revisions 73653 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
373 Decimal('0.7350')
57428
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
374 >>> x.quantize(Decimal('0.01')) # round to nearest cent
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
375 Decimal('0.74')
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
376 >>> round(.70 * 1.05, 2) # same calculation with floats
337ebb829b8c Fix some documentation examples involving the repr of a float.
Mark Dickinson <dickinsm@gmail.com>
parents: 55613
diff changeset
377 0.73
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
378
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
379 The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
380 inferring four place significance from multiplicands with two place
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
381 significance. Decimal reproduces mathematics as done by hand and avoids
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
382 issues that can arise when binary floating point cannot exactly represent
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
383 decimal quantities.
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384
86170
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
385 Exact representation enables the :class:`~decimal.Decimal` class to perform
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
386 modulo calculations and equality tests that are unsuitable for binary floating
ac826284fdd1 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79889
diff changeset
387 point::
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
389 >>> Decimal('1.00') % Decimal('.10')
54944
dcf7121edb2e Merged revisions 73653 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
390 Decimal('0.00')
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 >>> 1.00 % 0.10
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392 0.09999999999999995
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 >>> sum([Decimal('0.1')]*10) == Decimal('1.0')
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 True
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396 >>> sum([0.1]*10) == 1.0
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 47221
diff changeset
397 False
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399 The :mod:`decimal` module provides arithmetic with as much precision as needed::
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
401 >>> getcontext().prec = 36
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
402 >>> Decimal(1) / Decimal(7)
54944
dcf7121edb2e Merged revisions 73653 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50522
diff changeset
403 Decimal('0.142857142857142857142857142857142857')
42603
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404
c62f6669ae22 Move the 2.6 reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
405