Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/stdlib2.rst @ 87488:124e51c19e4f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #19734: Also run pip version check in isolated mode
author Nick Coghlan <ncoghlan@gmail.com>
date Sun, 24 Nov 2013 16:49:20 +1000
parents e338a5c8fcfa
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 .. _tut-brieftourtwo:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 *********************************************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 Brief Tour of the Standard Library -- Part II
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 *********************************************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7 This second tour covers more advanced modules that support professional
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 programming needs. These modules rarely occur in small scripts.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. _tut-output-formatting:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 Output Formatting
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 =================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
47088
4f1a079df427 Rename the repr module to reprlib.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46899
diff changeset
16 The :mod:`reprlib` module provides a version of :func:`repr` customized for
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 abbreviated displays of large or deeply nested containers::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18
47088
4f1a079df427 Rename the repr module to reprlib.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46899
diff changeset
19 >>> import reprlib
4f1a079df427 Rename the repr module to reprlib.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46899
diff changeset
20 >>> reprlib.repr(set('supercalifragilisticexpialidocious'))
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 "set(['a', 'c', 'd', 'e', 'f', 'g', ...])"
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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.
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 and indentation to more clearly reveal data structure::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 >>> import pprint
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 ... 'yellow'], 'blue']]]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 >>> pprint.pprint(t, width=30)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 [[[['black', 'cyan'],
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 'white',
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 ['green', 'red']],
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 [['magenta', 'yellow'],
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 'blue']]]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 width::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 >>> import textwrap
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45 ... the wrapped lines."""
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46 ...
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 43201
diff changeset
47 >>> print(textwrap.fill(doc, width=40))
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 The wrap() method is just like fill()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 except that it returns a list of strings
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 instead of one big string with newlines
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 to separate the wrapped lines.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k 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.
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 formatting numbers with group separators::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 >>> import locale
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59 'English_United States.1252'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 >>> conv = locale.localeconv() # get a mapping of conventions
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 >>> x = 1234567.8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 >>> locale.format("%d", x, grouping=True)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 '1,234,567'
55615
56e8c22df71f Merged revisions 74405 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
64 >>> locale.format_string("%s%.*f", (conv['currency_symbol'],
56e8c22df71f Merged revisions 74405 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
65 ... conv['frac_digits'], x), grouping=True)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 '$1,234,567.80'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 .. _tut-templating:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 Templating
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 ==========
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
74 The :mod:`string` module includes a versatile :class:`~string.Template` class
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
75 with a simplified syntax suitable for editing by end-users. This allows users
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
76 to customize their applications without having to alter the application.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 (alphanumeric characters and underscores). Surrounding the placeholder with
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 spaces. Writing ``$$`` creates a single escaped ``$``::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 >>> from string import Template
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 >>> t = Template('${village}folk send $$10 to $cause.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 >>> t.substitute(village='Nottingham', cause='the ditch fund')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 'Nottinghamfolk send $10 to the ditch fund.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
88 The :meth:`~string.Template.substitute` method raises a :exc:`KeyError` when a
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
89 placeholder is not supplied in a dictionary or a keyword argument. For
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
90 mail-merge style applications, user supplied data may be incomplete and the
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
91 :meth:`~string.Template.safe_substitute` method may be more appropriate ---
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
92 it will leave placeholders unchanged if data is missing::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94 >>> t = Template('Return the $item to $owner.')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 >>> d = dict(item='unladen swallow')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 >>> t.substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 Traceback (most recent call last):
79147
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
98 ...
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 KeyError: 'owner'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 >>> t.safe_substitute(d)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 'Return the unladen swallow to $owner.'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
44112
a1c3bd382771 Remove all definitions of raw_input() that were still scattered throughout the docs
Georg Brandl <georg@python.org>
parents: 44104
diff changeset
107 >>> import time, os.path
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 >>> photofiles = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 >>> class BatchRename(Template):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 ... delimiter = '%'
44112
a1c3bd382771 Remove all definitions of raw_input() that were still scattered throughout the docs
Georg Brandl <georg@python.org>
parents: 44104
diff changeset
111 >>> fmt = input('Enter rename style (%d-date %n-seqnum %f-format): ')
42604
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 >>> t = BatchRename(fmt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 >>> date = time.strftime('%d%b%y')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 >>> for i, filename in enumerate(photofiles):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 ... base, ext = os.path.splitext(filename)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 ... newname = t.substitute(d=date, n=i, f=ext)
47283
f28cbab11acd Merged revisions 63655 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 47088
diff changeset
119 ... print('{0} --> {1}'.format(filename, newname))
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 img_1074.jpg --> Ashley_0.jpg
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 img_1076.jpg --> Ashley_1.jpg
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 img_1077.jpg --> Ashley_2.jpg
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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
9e1529bf0442 Move the 3k 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.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 .. _tut-binary-formats:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 Working with Binary Data Record Layouts
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 =======================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
135 The :mod:`struct` module provides :func:`~struct.pack` and
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
136 :func:`~struct.unpack` functions for working with variable length binary
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
137 record formats. The following example shows
44914
c33f2779a938 Merged revisions 60234-60244 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44112
diff changeset
138 how to loop through header information in a ZIP file without using the
c33f2779a938 Merged revisions 60234-60244 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44112
diff changeset
139 :mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four
c33f2779a938 Merged revisions 60234-60244 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44112
diff changeset
140 byte unsigned numbers respectively. The ``"<"`` indicates that they are
c33f2779a938 Merged revisions 60234-60244 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44112
diff changeset
141 standard size and in little-endian byte order::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 import struct
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
68376
c3d28c84a372 Use with statement where it improves the documentation (closes #10461)
Éric Araujo <merwok@netwok.org>
parents: 68070
diff changeset
145 with open('myfile.zip', 'rb') as f:
c3d28c84a372 Use with statement where it improves the documentation (closes #10461)
Éric Araujo <merwok@netwok.org>
parents: 68070
diff changeset
146 data = f.read()
c3d28c84a372 Use with statement where it improves the documentation (closes #10461)
Éric Araujo <merwok@netwok.org>
parents: 68070
diff changeset
147
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 start = 0
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 for i in range(3): # show the first 3 file headers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 start += 14
44914
c33f2779a938 Merged revisions 60234-60244 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44112
diff changeset
151 fields = struct.unpack('<IIIHH', data[start:start+16])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152 crc32, comp_size, uncomp_size, filenamesize, extra_size = fields
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 start += 16
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 filename = data[start:start+filenamesize]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 start += filenamesize
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 extra = data[start:start+extra_size]
43219
655071bf6c45 Convert all print statements in the docs.
Georg Brandl <georg@python.org>
parents: 43201
diff changeset
158 print(filename, hex(crc32), comp_size, uncomp_size)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160 start += extra_size + comp_size # skip to the next header
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163 .. _tut-multi-threading:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 Multi-threading
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 ===============
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 Threading is a technique for decoupling tasks which are not sequentially
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 dependent. Threads can be used to improve the responsiveness of applications
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170 that accept user input while other tasks run in the background. A related use
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 case is running I/O in parallel with computations in another thread.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 The following code shows how the high level :mod:`threading` module can run
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 tasks in background while the main program continues to run::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 import threading, zipfile
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 class AsyncZip(threading.Thread):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 def __init__(self, infile, outfile):
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
180 threading.Thread.__init__(self)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 self.infile = infile
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 self.outfile = outfile
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 def run(self):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 f = zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 f.write(self.infile)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 f.close()
43201
4902671dd678 Tutorial formatting patch by Robin Stocker.
Georg Brandl <georg@python.org>
parents: 43115
diff changeset
187 print('Finished background zip of:', self.infile)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 background = AsyncZip('mydata.txt', 'myarchive.zip')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 background.start()
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
191 print('The main program continues to run in foreground.')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 background.join() # Wait for the background task to finish
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
194 print('Main program waited until background was done.')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 The principal challenge of multi-threaded applications is coordinating threads
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 that share data or other resources. To that end, the threading module provides
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 a number of synchronization primitives including locks, events, condition
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 variables, and semaphores.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 While those tools are powerful, minor design errors can result in problems that
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 are difficult to reproduce. So, the preferred approach to task coordination is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 to concentrate all access to a resource in a single thread and then use the
46899
bd2c95c165ea Rename Queue module to queue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 45435
diff changeset
204 :mod:`queue` module to feed that thread with requests from other threads.
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
205 Applications using :class:`~queue.Queue` objects for inter-thread communication and
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 coordination are easier to design, more readable, and more reliable.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 .. _tut-logging:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 Logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212 =======
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 The :mod:`logging` module offers a full featured and flexible logging system.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 At its simplest, log messages are sent to a file or to ``sys.stderr``::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217 import logging
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218 logging.debug('Debugging information')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 logging.info('Informational message')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 logging.warning('Warning:config file %s not found', 'server.conf')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 logging.error('Error occurred')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 logging.critical('Critical error -- shutting down')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
79147
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
224 This produces the following output:
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
225
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
226 .. code-block:: none
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 WARNING:root:Warning:config file server.conf not found
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 ERROR:root:Error occurred
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 CRITICAL:root:Critical error -- shutting down
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232 By default, informational and debugging messages are suppressed and the output
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 is sent to standard error. Other output options include routing messages
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 through email, datagrams, sockets, or to an HTTP Server. New filters can select
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
235 different routing based on message priority: :const:`~logging.DEBUG`,
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
236 :const:`~logging.INFO`, :const:`~logging.WARNING`, :const:`~logging.ERROR`,
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
237 and :const:`~logging.CRITICAL`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 The logging system can be configured directly from Python or can be loaded from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240 a user editable configuration file for customized logging without altering the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 application.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 .. _tut-weak-references:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 Weak References
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 ===============
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 Python does automatic memory management (reference counting for most objects and
44104
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43219
diff changeset
250 :term:`garbage collection` to eliminate cycles). The memory is freed shortly
ff1766eb2fce Merged revisions 59259-59274 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 43219
diff changeset
251 after the last reference to it has been eliminated.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 This approach works fine for most applications but occasionally there is a need
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 to track objects only as long as they are being used by something else.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 Unfortunately, just tracking them creates a reference that makes them permanent.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 The :mod:`weakref` module provides tools for tracking objects without creating a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 reference. When the object is no longer needed, it is automatically removed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258 from a weakref table and a callback is triggered for weakref objects. Typical
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 applications include caching objects that are expensive to create::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 >>> import weakref, gc
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 >>> class A:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263 ... def __init__(self, value):
79890
2015db05d954 Closes #16294: 8 space indent in tutorial
Jesus Cea <jcea@jcea.es>
parents: 79147
diff changeset
264 ... self.value = value
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 ... def __repr__(self):
79890
2015db05d954 Closes #16294: 8 space indent in tutorial
Jesus Cea <jcea@jcea.es>
parents: 79147
diff changeset
266 ... return str(self.value)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 >>> a = A(10) # create a reference
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269 >>> d = weakref.WeakValueDictionary()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 >>> d['primary'] = a # does not create a reference
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 >>> d['primary'] # fetch the object if it is still alive
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273 >>> del a # remove the one reference
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 >>> gc.collect() # run garbage collection right away
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 0
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 >>> d['primary'] # entry was automatically removed
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 Traceback (most recent call last):
45435
42b3b117391d Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60789,60793,60796,60799-60809,60812-60813,60815-60821,60823-60826,60828-60829,60831-60834,60836,60838-60839,60846-60849,60852-60854,60856-60859,60861-60870,60874-60875,60880-60881,60886,60888-60890,60892,60894-60898,60900-60931,60933-60958 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44914
diff changeset
278 File "<stdin>", line 1, in <module>
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279 d['primary'] # entry was automatically removed
79240
1085b0e475d8 Bump version to 3.4.0 alpha 0.
Georg Brandl <georg@python.org>
parents: 79148
diff changeset
280 File "C:/python34/lib/weakref.py", line 46, in __getitem__
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
281 o = self.data[key]()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
282 KeyError: 'primary'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
283
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
284
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
285 .. _tut-list-tools:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
286
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
287 Tools for Working with Lists
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
288 ============================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
289
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
290 Many data structure needs can be met with the built-in list type. However,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
291 sometimes there is a need for alternative implementations with different
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
292 performance trade-offs.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
293
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
294 The :mod:`array` module provides an :class:`~array.array()` object that is like
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
295 a list that stores only homogeneous data and stores it more compactly. The
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
296 following example shows an array of numbers stored as two byte unsigned binary
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
297 numbers (typecode ``"H"``) rather than the usual 16 bytes per entry for regular
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
298 lists of Python int objects::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
299
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
300 >>> from array import array
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301 >>> a = array('H', [4000, 10, 700, 22222])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> sum(a)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 26932
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 >>> a[1:3]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 array('H', [10, 700])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
307 The :mod:`collections` module provides a :class:`~collections.deque()` object
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
308 that is like a list with faster appends and pops from the left side but slower
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
309 lookups in the middle. These objects are well suited for implementing queues
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
310 and breadth first tree searches::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
311
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
312 >>> from collections import deque
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
313 >>> d = deque(["task1", "task2", "task3"])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
314 >>> d.append("task4")
43115
95d6fe2e8e0e Tutorial update for 3.0 by Paul Dubois.
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
315 >>> print("Handling", d.popleft())
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
316 Handling task1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
317
79147
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
318 ::
101354f95a07 #16019, #16020: fix syntax highlight.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 57798
diff changeset
319
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320 unsearched = deque([starting_node])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
321 def breadth_first_search(unsearched):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
322 node = unsearched.popleft()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
323 for m in gen_moves(node):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
324 if is_goal(m):
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
325 return m
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
326 unsearched.append(m)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
327
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
328 In addition to alternative list implementations, the library also offers other
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
329 tools such as the :mod:`bisect` module with functions for manipulating sorted
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
330 lists::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
331
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
332 >>> import bisect
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
333 >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
334 >>> bisect.insort(scores, (300, 'ruby'))
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
335 >>> scores
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
336 [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
337
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
338 The :mod:`heapq` module provides functions for implementing heaps based on
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
339 regular lists. The lowest valued entry is always kept at position zero. This
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
340 is useful for applications which repeatedly access the smallest element but do
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
341 not want to run a full list sort::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
342
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 >>> from heapq import heapify, heappop, heappush
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344 >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 >>> heapify(data) # rearrange the list into heap order
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 >>> heappush(data, -5) # add a new entry
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347 >>> [heappop(data) for i in range(3)] # fetch the three smallest entries
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 [-5, 0, 1]
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351 .. _tut-decimal-fp:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353 Decimal Floating Point Arithmetic
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
354 =================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
355
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
356 The :mod:`decimal` module offers a :class:`~decimal.Decimal` datatype for
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
357 decimal floating point arithmetic. Compared to the built-in :class:`float`
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
358 implementation of binary floating point, the class is especially helpful for
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
359
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
360 * financial applications and other uses which require exact decimal
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
361 representation,
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
362 * control over precision,
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
363 * control over rounding to meet legal or regulatory requirements,
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
364 * tracking of significant decimal places, or
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
365 * applications where the user expects the results to match calculations done by
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54933
diff changeset
366 hand.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368 For example, calculating a 5% tax on a 70 cent phone charge gives different
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
369 results in decimal floating point and binary floating point. The difference
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370 becomes significant if the results are rounded to the nearest cent::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
372 >>> from decimal import *
54927
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50515
diff changeset
373 >>> round(Decimal('0.70') * Decimal('1.05'), 2)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50515
diff changeset
374 Decimal('0.74')
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50515
diff changeset
375 >>> round(.70 * 1.05, 2)
e3025a4c0ad7 Merged revisions 73636 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 50515
diff changeset
376 0.73
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
378 The :class:`~decimal.Decimal` result keeps a trailing zero, automatically
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
379 inferring four place significance from multiplicands with two place
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
380 significance. Decimal reproduces mathematics as done by hand and avoids
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
381 issues that can arise when binary floating point cannot exactly represent
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
382 decimal quantities.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
383
86171
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
384 Exact representation enables the :class:`~decimal.Decimal` class to perform
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
385 modulo calculations and equality tests that are unsuitable for binary floating
012380d57e44 Issue #19193: Improved cross-references in the tutorial.
Serhiy Storchaka <storchaka@gmail.com>
parents: 79891
diff changeset
386 point::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388 >>> Decimal('1.00') % Decimal('.10')
54933
d7496cc10dfe Merged revisions 73642 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 54927
diff changeset
389 Decimal('0.00')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390 >>> 1.00 % 0.10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
391 0.09999999999999995
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
392
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393 >>> sum([Decimal('0.1')]*10) == Decimal('1.0')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394 True
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
395 >>> sum([0.1]*10) == 1.0
50514
c3d3b760d8bf Remove trailing whitespace.
Georg Brandl <georg@python.org>
parents: 49946
diff changeset
396 False
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
397
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398 The :mod:`decimal` module provides arithmetic with as much precision as needed::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
399
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
400 >>> getcontext().prec = 36
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
401 >>> Decimal(1) / Decimal(7)
54933
d7496cc10dfe Merged revisions 73642 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 54927
diff changeset
402 Decimal('0.142857142857142857142857142857142857')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
403
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
404