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