| programming needs. These modules rarely occur in small scripts. |
| |
| |
| .. _tut-output-formatting: |
| |
| Output Formatting |
| ================= |
| |
n | The :mod:`repr` (XXX reference: ../lib/module-repr.html) module provides a |
n | The :mod:`repr` module provides a version of :func:`repr` customized for |
| version of :func:`repr` customized for abbreviated displays of large or deeply |
| abbreviated displays of large or deeply nested containers:: |
| nested containers:: |
| |
n | >>> import repr |
n | >>> import repr |
| >>> repr.repr(set('supercalifragilisticexpialidocious')) |
| "set(['a', 'c', 'd', 'e', 'f', 'g', ...])" |
| |
n | The :mod:`pprint` (XXX reference: ../lib/module-pprint.html) module offers more |
n | The :mod:`pprint` module offers more sophisticated control over printing both |
| sophisticated control over printing both built-in and user defined objects in a |
| built-in and user defined objects in a way that is readable by the interpreter. |
| way that is readable by the interpreter. When the result is longer than one |
| When the result is longer than one line, the "pretty printer" adds line breaks |
| line, the "pretty printer" adds line breaks and indentation to more clearly |
| and indentation to more clearly reveal data structure:: |
| reveal data structure:: |
| |
| >>> import pprint |
| >>> t = [[[['black', 'cyan'], 'white', ['green', 'red']], [['magenta', |
| ... 'yellow'], 'blue']]] |
| ... |
| >>> pprint.pprint(t, width=30) |
| [[[['black', 'cyan'], |
| 'white', |
| ['green', 'red']], |
| [['magenta', 'yellow'], |
| 'blue']]] |
| |
n | The :mod:`textwrap` (XXX reference: ../lib/module-textwrap.html) module formats |
n | The :mod:`textwrap` module formats paragraphs of text to fit a given screen |
| paragraphs of text to fit a given screen width:: |
| width:: |
| |
| >>> import textwrap |
| >>> doc = """The wrap() method is just like fill() except that it returns |
| ... a list of strings instead of one big string with newlines to separate |
| ... the wrapped lines.""" |
| ... |
| >>> print textwrap.fill(doc, width=40) |
| The wrap() method is just like fill() |
| except that it returns a list of strings |
| instead of one big string with newlines |
| to separate the wrapped lines. |
| |
n | The :mod:`locale` (XXX reference: ../lib/module-locale.html) module accesses a |
n | The :mod:`locale` module accesses a database of culture specific data formats. |
| database of culture specific data formats. The grouping attribute of locale's |
| The grouping attribute of locale's format function provides a direct way of |
| format function provides a direct way of formatting numbers with group |
| formatting numbers with group separators:: |
| separators:: |
| |
| >>> import locale |
| >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252') |
| 'English_United States.1252' |
| >>> conv = locale.localeconv() # get a mapping of conventions |
| >>> x = 1234567.8 |
| >>> locale.format("%d", x, grouping=True) |
| '1,234,567' |
| >>> locale.format("%s%.*f", (conv['currency_symbol'], |
n | ... conv['frac_digits'], x), grouping=True) |
n | ... conv['frac_digits'], x), grouping=True) |
| '$1,234,567.80' |
| |
| |
| .. _tut-templating: |
| |
| Templating |
| ========== |
| |
n | The :mod:`string` (XXX reference: ../lib/module-string.html) module includes a |
n | The :mod:`string` module includes a versatile :class:`Template` class with a |
| versatile :class:`Template` class with a simplified syntax suitable for editing |
| simplified syntax suitable for editing by end-users. This allows users to |
| by end-users. This allows users to customize their applications without having |
| customize their applications without having to alter the application. |
| to alter the application. |
| |
| The format uses placeholder names formed by ``$`` with valid Python identifiers |
| (alphanumeric characters and underscores). Surrounding the placeholder with |
| braces allows it to be followed by more alphanumeric letters with no intervening |
| spaces. Writing ``$$`` creates a single escaped ``$``:: |
| |
| >>> from string import Template |
| >>> t = Template('${village}folk send $$10 to $cause.') |
| >>> fmt = raw_input('Enter rename style (%d-date %n-seqnum %f-format): ') |
| Enter rename style (%d-date %n-seqnum %f-format): Ashley_%n%f |
| |
| >>> t = BatchRename(fmt) |
| >>> date = time.strftime('%d%b%y') |
| >>> for i, filename in enumerate(photofiles): |
| ... base, ext = os.path.splitext(filename) |
| ... newname = t.substitute(d=date, n=i, f=ext) |
n | ... print '%s --> %s' % (filename, newname) |
n | ... print '{0} --> {1}'.format(filename, newname) |
| |
| img_1074.jpg --> Ashley_0.jpg |
| img_1076.jpg --> Ashley_1.jpg |
| img_1077.jpg --> Ashley_2.jpg |
| |
| Another application for templating is separating program logic from the details |
| of multiple output formats. This makes it possible to substitute custom |
| templates for XML files, plain text reports, and HTML web reports. |
| |
| |
| .. _tut-binary-formats: |
| |
| Working with Binary Data Record Layouts |
| ======================================= |
| |
n | The :mod:`struct` (XXX reference: ../lib/module-struct.html) module provides |
n | The :mod:`struct` module provides :func:`pack` and :func:`unpack` functions for |
| :func:`pack` and :func:`unpack` functions for working with variable length |
| working with variable length binary record formats. The following example shows |
| binary record formats. The following example shows how to loop through header |
| how to loop through header information in a ZIP file without using the |
| information in a ZIP file (with pack codes ``"H"`` and ``"L"`` representing two |
| :mod:`zipfile` module. Pack codes ``"H"`` and ``"I"`` represent two and four |
| and four byte unsigned numbers respectively):: |
| byte unsigned numbers respectively. The ``"<"`` indicates that they are |
| standard size and in little-endian byte order:: |
| |
| import struct |
| |
| data = open('myfile.zip', 'rb').read() |
| start = 0 |
| for i in range(3): # show the first 3 file headers |
| start += 14 |
n | fields = struct.unpack('LLLHH', data[start:start+16]) |
n | fields = struct.unpack('<IIIHH', data[start:start+16]) |
| crc32, comp_size, uncomp_size, filenamesize, extra_size = fields |
| |
| start += 16 |
| filename = data[start:start+filenamesize] |
| start += filenamesize |
| extra = data[start:start+extra_size] |
| print filename, hex(crc32), comp_size, uncomp_size |
| |
| The principal challenge of multi-threaded applications is coordinating threads |
| that share data or other resources. To that end, the threading module provides |
| a number of synchronization primitives including locks, events, condition |
| variables, and semaphores. |
| |
| While those tools are powerful, minor design errors can result in problems that |
| are difficult to reproduce. So, the preferred approach to task coordination is |
| to concentrate all access to a resource in a single thread and then use the |
n | :mod:`Queue` (XXX reference: ../lib/module-Queue.html) module to feed that |
n | :mod:`Queue` module to feed that thread with requests from other threads. |
| thread with requests from other threads. Applications using :class:`Queue` |
| Applications using :class:`Queue.Queue` objects for inter-thread communication |
| objects for inter-thread communication and coordination are easier to design, |
| and coordination are easier to design, more readable, and more reliable. |
| more readable, and more reliable. |
| |
| |
| .. _tut-logging: |
| |
| Logging |
| ======= |
| |
n | The :mod:`logging` (XXX reference: ../lib/module-logging.html) module offers a |
n | The :mod:`logging` module offers a full featured and flexible logging system. |
| full featured and flexible logging system. At its simplest, log messages are |
| At its simplest, log messages are sent to a file or to ``sys.stderr``:: |
| sent to a file or to ``sys.stderr``:: |
| |
| import logging |
| logging.debug('Debugging information') |
| logging.info('Informational message') |
| logging.warning('Warning:config file %s not found', 'server.conf') |
| logging.error('Error occurred') |
| logging.critical('Critical error -- shutting down') |
| |
| >>> d['primary'] = a # does not create a reference |
| >>> d['primary'] # fetch the object if it is still alive |
| 10 |
| >>> del a # remove the one reference |
| >>> gc.collect() # run garbage collection right away |
| 0 |
| >>> d['primary'] # entry was automatically removed |
| Traceback (most recent call last): |
n | File "<pyshell#108>", line 1, in -toplevel- |
n | File "<stdin>", line 1, in <module> |
| d['primary'] # entry was automatically removed |
n | File "C:/PY24/lib/weakref.py", line 46, in __getitem__ |
n | File "C:/python26/lib/weakref.py", line 46, in __getitem__ |
| o = self.data[key]() |
| KeyError: 'primary' |
| |
| |
| .. _tut-list-tools: |
| |
| Tools for Working with Lists |
| ============================ |
| |
| Many data structure needs can be met with the built-in list type. However, |
| sometimes there is a need for alternative implementations with different |
| performance trade-offs. |
| |
n | The :mod:`array` (XXX reference: ../lib/module-array.html) module provides an |
n | The :mod:`array` module provides an :class:`array()` object that is like a list |
| :class:`array()` object that is like a list that stores only homogenous data and |
| that stores only homogeneous data and stores it more compactly. The following |
| stores it more compactly. The following example shows an array of numbers |
| example shows an array of numbers stored as two byte unsigned binary numbers |
| stored as two byte unsigned binary numbers (typecode ``"H"``) rather than the |
| (typecode ``"H"``) rather than the usual 16 bytes per entry for regular lists of |
| usual 16 bytes per entry for regular lists of python int objects:: |
| python int objects:: |
| |
| >>> from array import array |
| >>> a = array('H', [4000, 10, 700, 22222]) |
| >>> sum(a) |
| 26932 |
| >>> a[1:3] |
| array('H', [10, 700]) |
| |
n | The :mod:`collections` (XXX reference: ../lib/module-collections.html) module |
n | The :mod:`collections` module provides a :class:`deque()` object that is like a |
| provides a :class:`deque()` object that is like a list with faster appends and |
| list with faster appends and pops from the left side but slower lookups in the |
| pops from the left side but slower lookups in the middle. These objects are well |
| middle. These objects are well suited for implementing queues and breadth first |
| suited for implementing queues and breadth first tree searches:: |
| tree searches:: |
| |
| >>> from collections import deque |
| >>> d = deque(["task1", "task2", "task3"]) |
| >>> d.append("task4") |
| >>> print "Handling", d.popleft() |
| Handling task1 |
| |
| unsearched = deque([starting_node]) |
| def breadth_first_search(unsearched): |
| node = unsearched.popleft() |
| for m in gen_moves(node): |
| if is_goal(m): |
| return m |
| unsearched.append(m) |
| |
| In addition to alternative list implementations, the library also offers other |
n | tools such as the :mod:`bisect` (XXX reference: ../lib/module-bisect.html) |
n | tools such as the :mod:`bisect` module with functions for manipulating sorted |
| module with functions for manipulating sorted lists:: |
| lists:: |
| |
| >>> import bisect |
| >>> scores = [(100, 'perl'), (200, 'tcl'), (400, 'lua'), (500, 'python')] |
| >>> bisect.insort(scores, (300, 'ruby')) |
| >>> scores |
| [(100, 'perl'), (200, 'tcl'), (300, 'ruby'), (400, 'lua'), (500, 'python')] |
| |
n | The :mod:`heapq` (XXX reference: ../lib/module-heapq.html) module provides |
n | The :mod:`heapq` module provides functions for implementing heaps based on |
| functions for implementing heaps based on regular lists. The lowest valued |
| regular lists. The lowest valued entry is always kept at position zero. This |
| entry is always kept at position zero. This is useful for applications which |
| is useful for applications which repeatedly access the smallest element but do |
| repeatedly access the smallest element but do not want to run a full list sort:: |
| not want to run a full list sort:: |
| |
| >>> from heapq import heapify, heappop, heappush |
| >>> data = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0] |
| >>> heapify(data) # rearrange the list into heap order |
| >>> heappush(data, -5) # add a new entry |
| >>> [heappop(data) for i in range(3)] # fetch the three smallest entries |
| [-5, 0, 1] |
| |
| |
| .. _tut-decimal-fp: |
| |
| Decimal Floating Point Arithmetic |
| ================================= |
| |
n | The :mod:`decimal` (XXX reference: ../lib/module-decimal.html) module offers a |
n | The :mod:`decimal` module offers a :class:`Decimal` datatype for decimal |
| :class:`Decimal` datatype for decimal floating point arithmetic. Compared to |
| floating point arithmetic. Compared to the built-in :class:`float` |
| the built-in :class:`float` implementation of binary floating point, the new |
| implementation of binary floating point, the new class is especially helpful for |
| class is especially helpful for financial applications and other uses which |
| financial applications and other uses which require exact decimal |
| require exact decimal representation, control over precision, control over |
| representation, control over precision, control over rounding to meet legal or |
| rounding to meet legal or regulatory requirements, tracking of significant |
| regulatory requirements, tracking of significant decimal places, or for |
| decimal places, or for applications where the user expects the results to match |
| applications where the user expects the results to match calculations done by |
| calculations done by hand. |
| hand. |
| |
| For example, calculating a 5% tax on a 70 cent phone charge gives different |
| results in decimal floating point and binary floating point. The difference |
| becomes significant if the results are rounded to the nearest cent:: |
| |
n | >>> from decimal import * |
n | >>> from decimal import * |
| >>> Decimal('0.70') * Decimal('1.05') |
| Decimal("0.7350") |
| >>> .70 * 1.05 |
n | 0.73499999999999999 |
n | 0.73499999999999999 |
| |
| The :class:`Decimal` result keeps a trailing zero, automatically inferring four |
| place significance from multiplicands with two place significance. Decimal |
| reproduces mathematics as done by hand and avoids issues that can arise when |
| binary floating point cannot exactly represent decimal quantities. |
| |
| Exact representation enables the :class:`Decimal` class to perform modulo |
| calculations and equality tests that are unsuitable for binary floating point:: |