1 .. _tut-brieftour:

     2 

     3 **********************************

     4 Brief Tour of the Standard Library

     5 **********************************

     6 

     7 

     8 .. _tut-os-interface:

     9 

    10 Operating System Interface

    11 ==========================

    12 

    13 The :mod:`os` module provides dozens of functions for interacting with the

    14 operating system::

    15 

    16    >>> import os

    17    >>> os.system('time 0:02')

    18    0

    19    >>> os.getcwd()      # Return the current working directory

    20    'C:\\Python26'

    21    >>> os.chdir('/server/accesslogs')

    22 

    23 Be sure to use the ``import os`` style instead of ``from os import *``.  This

    24 will keep :func:`os.open` from shadowing the builtin :func:`open` function which

    25 operates much differently.

    26 

    27 .. index:: builtin: help

    28 

    29 The builtin :func:`dir` and :func:`help` functions are useful as interactive

    30 aids for working with large modules like :mod:`os`::

    31 

    32    >>> import os

    33    >>> dir(os)

    34    <returns a list of all module functions>

    35    >>> help(os)

    36    <returns an extensive manual page created from the module's docstrings>

    37 

    38 For daily file and directory management tasks, the :mod:`shutil` module provides

    39 a higher level interface that is easier to use::

    40 

    41    >>> import shutil

    42    >>> shutil.copyfile('data.db', 'archive.db')

    43    >>> shutil.move('/build/executables', 'installdir')

    44 

    45 

    46 .. _tut-file-wildcards:

    47 

    48 File Wildcards

    49 ==============

    50 

    51 The :mod:`glob` module provides a function for making file lists from directory

    52 wildcard searches::

    53 

    54    >>> import glob

    55    >>> glob.glob('*.py')

    56    ['primes.py', 'random.py', 'quote.py']

    57 

    58 

    59 .. _tut-command-line-arguments:

    60 

    61 Command Line Arguments

    62 ======================

    63 

    64 Common utility scripts often need to process command line arguments. These

    65 arguments are stored in the :mod:`sys` module's *argv* attribute as a list.  For

    66 instance the following output results from running ``python demo.py one two

    67 three`` at the command line::

    68 

    69    >>> import sys

    70    >>> print sys.argv

    71    ['demo.py', 'one', 'two', 'three']

    72 

    73 The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix

    74 :func:`getopt` function.  More powerful and flexible command line processing is

    75 provided by the :mod:`optparse` module.

    76 

    77 

    78 .. _tut-stderr:

    79 

    80 Error Output Redirection and Program Termination

    81 ================================================

    82 

    83 The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*.

    84 The latter is useful for emitting warnings and error messages to make them

    85 visible even when *stdout* has been redirected::

    86 

    87    >>> sys.stderr.write('Warning, log file not found starting a new one\n')

    88    Warning, log file not found starting a new one

    89 

    90 The most direct way to terminate a script is to use ``sys.exit()``.

    91 

    92 

    93 .. _tut-string-pattern-matching:

    94 

    95 String Pattern Matching

    96 =======================

    97 

    98 The :mod:`re` module provides regular expression tools for advanced string

    99 processing. For complex matching and manipulation, regular expressions offer

   100 succinct, optimized solutions::

   101 

   102    >>> import re

   103    >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')

   104    ['foot', 'fell', 'fastest']

   105    >>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')

   106    'cat in the hat'

   107 

   108 When only simple capabilities are needed, string methods are preferred because

   109 they are easier to read and debug::

   110 

   111    >>> 'tea for too'.replace('too', 'two')

   112    'tea for two'

   113 

   114 

   115 .. _tut-mathematics:

   116 

   117 Mathematics

   118 ===========

   119 

   120 The :mod:`math` module gives access to the underlying C library functions for

   121 floating point math::

   122 

   123    >>> import math

   124    >>> math.cos(math.pi / 4.0)

   125    0.70710678118654757

   126    >>> math.log(1024, 2)

   127    10.0

   128 

   129 The :mod:`random` module provides tools for making random selections::

   130 

   131    >>> import random

   132    >>> random.choice(['apple', 'pear', 'banana'])

   133    'apple'

   134    >>> random.sample(xrange(100), 10)   # sampling without replacement

   135    [30, 83, 16, 4, 8, 81, 41, 50, 18, 33]

   136    >>> random.random()    # random float

   137    0.17970987693706186

   138    >>> random.randrange(6)    # random integer chosen from range(6)

   139    4   

   140 

   141 

   142 .. _tut-internet-access:

   143 

   144 Internet Access

   145 ===============

   146 

   147 There are a number of modules for accessing the internet and processing internet

   148 protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls

   149 and :mod:`smtplib` for sending mail::

   150 

   151    >>> import urllib2

   152    >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):

   153    ...     if 'EST' in line or 'EDT' in line:  # look for Eastern Time

   154    ...         print line

   155 

   156    <BR>Nov. 25, 09:43:32 PM EST

   157 

   158    >>> import smtplib

   159    >>> server = smtplib.SMTP('localhost')

   160    >>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',

   161    ... """To: jcaesar@example.org

   162    ... From: soothsayer@example.org

   163    ...

   164    ... Beware the Ides of March.

   165    ... """)

   166    >>> server.quit()

   167 

   168 (Note that the second example needs a mailserver running on localhost.)

   169 

   170 

   171 .. _tut-dates-and-times:

   172 

   173 Dates and Times

   174 ===============

   175 

   176 The :mod:`datetime` module supplies classes for manipulating dates and times in

   177 both simple and complex ways. While date and time arithmetic is supported, the

   178 focus of the implementation is on efficient member extraction for output

   179 formatting and manipulation.  The module also supports objects that are timezone

   180 aware. ::

   181 

   182    # dates are easily constructed and formatted

   183    >>> from datetime import date

   184    >>> now = date.today()

   185    >>> now

   186    datetime.date(2003, 12, 2)

   187    >>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")

   188    '12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'

   189 

   190    # dates support calendar arithmetic

   191    >>> birthday = date(1964, 7, 31)

   192    >>> age = now - birthday

   193    >>> age.days

   194    14368

   195 

   196 

   197 .. _tut-data-compression:

   198 

   199 Data Compression

   200 ================

   201 

   202 Common data archiving and compression formats are directly supported by modules

   203 including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and

   204 :mod:`tarfile`. ::

   205 

   206    >>> import zlib

   207    >>> s = 'witch which has which witches wrist watch'

   208    >>> len(s)

   209    41

   210    >>> t = zlib.compress(s)

   211    >>> len(t)

   212    37

   213    >>> zlib.decompress(t)

   214    'witch which has which witches wrist watch'

   215    >>> zlib.crc32(s)

   216    226805979

   217 

   218 

   219 .. _tut-performance-measurement:

   220 

   221 Performance Measurement

   222 =======================

   223 

   224 Some Python users develop a deep interest in knowing the relative performance of

   225 different approaches to the same problem. Python provides a measurement tool

   226 that answers those questions immediately.

   227 

   228 For example, it may be tempting to use the tuple packing and unpacking feature

   229 instead of the traditional approach to swapping arguments. The :mod:`timeit`

   230 module quickly demonstrates a modest performance advantage::

   231 

   232    >>> from timeit import Timer

   233    >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()

   234    0.57535828626024577

   235    >>> Timer('a,b = b,a', 'a=1; b=2').timeit()

   236    0.54962537085770791

   237 

   238 In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and

   239 :mod:`pstats` modules provide tools for identifying time critical sections in

   240 larger blocks of code.

   241 

   242 

   243 .. _tut-quality-control:

   244 

   245 Quality Control

   246 ===============

   247 

   248 One approach for developing high quality software is to write tests for each

   249 function as it is developed and to run those tests frequently during the

   250 development process.

   251 

   252 The :mod:`doctest` module provides a tool for scanning a module and validating

   253 tests embedded in a program's docstrings.  Test construction is as simple as

   254 cutting-and-pasting a typical call along with its results into the docstring.

   255 This improves the documentation by providing the user with an example and it

   256 allows the doctest module to make sure the code remains true to the

   257 documentation::

   258 

   259    def average(values):

   260        """Computes the arithmetic mean of a list of numbers.

   261 

   262        >>> print average([20, 30, 70])

   263        40.0

   264        """

   265        return sum(values, 0.0) / len(values)

   266 

   267    import doctest

   268    doctest.testmod()   # automatically validate the embedded tests

   269 

   270 The :mod:`unittest` module is not as effortless as the :mod:`doctest` module,

   271 but it allows a more comprehensive set of tests to be maintained in a separate

   272 file::

   273 

   274    import unittest

   275 

   276    class TestStatisticalFunctions(unittest.TestCase):

   277 

   278        def test_average(self):

   279            self.assertEqual(average([20, 30, 70]), 40.0)

   280            self.assertEqual(round(average([1, 5, 7]), 1), 4.3)

   281            self.assertRaises(ZeroDivisionError, average, [])

   282            self.assertRaises(TypeError, average, 20, 30, 70)

   283 

   284    unittest.main() # Calling from the command line invokes all tests

   285 

   286 

   287 .. _tut-batteries-included:

   288 

   289 Batteries Included

   290 ==================

   291 

   292 Python has a "batteries included" philosophy.  This is best seen through the

   293 sophisticated and robust capabilities of its larger packages. For example:

   294 

   295 * The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing

   296   remote procedure calls into an almost trivial task.  Despite the modules

   297   names, no direct knowledge or handling of XML is needed.

   298 

   299 * The :mod:`email` package is a library for managing email messages, including

   300   MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and

   301   :mod:`poplib` which actually send and receive messages, the email package has

   302   a complete toolset for building or decoding complex message structures

   303   (including attachments) and for implementing internet encoding and header

   304   protocols.

   305 

   306 * The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for

   307   parsing this popular data interchange format. Likewise, the :mod:`csv` module

   308   supports direct reads and writes in a common database format. Together, these

   309   modules and packages greatly simplify data interchange between python

   310   applications and other tools.

   311 

   312 * Internationalization is supported by a number of modules including

   313   :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package.

   314 

   315