Mercurial > cpython-lru_cache-weakref

annotate Doc/tutorial/stdlib2.rst @ 87690:66c1c9f32567 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859
author Radomir Dopieralski <devel@sheep.art.pl>
date Tue, 03 Dec 2013 16:02:48 +0100
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