/Doc/tutorial/stdlib.rst

  1.. _tut-brieftour:
  2
  3**********************************
  4Brief Tour of the Standard Library
  5**********************************
  6
  7
  8.. _tut-os-interface:
  9
 10Operating System Interface
 11==========================
 12
 13The :mod:`os` module provides dozens of functions for interacting with the
 14operating 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
 23Be sure to use the ``import os`` style instead of ``from os import *``.  This
 24will keep :func:`os.open` from shadowing the built-in :func:`open` function which
 25operates much differently.
 26
 27.. index:: builtin: help
 28
 29The built-in :func:`dir` and :func:`help` functions are useful as interactive
 30aids 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
 38For daily file and directory management tasks, the :mod:`shutil` module provides
 39a 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
 48File Wildcards
 49==============
 50
 51The :mod:`glob` module provides a function for making file lists from directory
 52wildcard searches::
 53
 54   >>> import glob
 55   >>> glob.glob('*.py')
 56   ['primes.py', 'random.py', 'quote.py']
 57
 58
 59.. _tut-command-line-arguments:
 60
 61Command Line Arguments
 62======================
 63
 64Common utility scripts often need to process command line arguments. These
 65arguments are stored in the :mod:`sys` module's *argv* attribute as a list.  For
 66instance the following output results from running ``python demo.py one two
 67three`` at the command line::
 68
 69   >>> import sys
 70   >>> print sys.argv
 71   ['demo.py', 'one', 'two', 'three']
 72
 73The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
 74:func:`getopt` function.  More powerful and flexible command line processing is
 75provided by the :mod:`optparse` module.
 76
 77
 78.. _tut-stderr:
 79
 80Error Output Redirection and Program Termination
 81================================================
 82
 83The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*.
 84The latter is useful for emitting warnings and error messages to make them
 85visible 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
 90The most direct way to terminate a script is to use ``sys.exit()``.
 91
 92
 93.. _tut-string-pattern-matching:
 94
 95String Pattern Matching
 96=======================
 97
 98The :mod:`re` module provides regular expression tools for advanced string
 99processing. For complex matching and manipulation, regular expressions offer
100succinct, 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
108When only simple capabilities are needed, string methods are preferred because
109they are easier to read and debug::
110
111   >>> 'tea for too'.replace('too', 'two')
112   'tea for two'
113
114
115.. _tut-mathematics:
116
117Mathematics
118===========
119
120The :mod:`math` module gives access to the underlying C library functions for
121floating 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
129The :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
144Internet Access
145===============
146
147There are a number of modules for accessing the internet and processing internet
148protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls
149and :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
173Dates and Times
174===============
175
176The :mod:`datetime` module supplies classes for manipulating dates and times in
177both simple and complex ways. While date and time arithmetic is supported, the
178focus of the implementation is on efficient member extraction for output
179formatting and manipulation.  The module also supports objects that are timezone
180aware. ::
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
199Data Compression
200================
201
202Common data archiving and compression formats are directly supported by modules
203including: :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
221Performance Measurement
222=======================
223
224Some Python users develop a deep interest in knowing the relative performance of
225different approaches to the same problem. Python provides a measurement tool
226that answers those questions immediately.
227
228For example, it may be tempting to use the tuple packing and unpacking feature
229instead of the traditional approach to swapping arguments. The :mod:`timeit`
230module 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
238In 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
240larger blocks of code.
241
242
243.. _tut-quality-control:
244
245Quality Control
246===============
247
248One approach for developing high quality software is to write tests for each
249function as it is developed and to run those tests frequently during the
250development process.
251
252The :mod:`doctest` module provides a tool for scanning a module and validating
253tests embedded in a program's docstrings.  Test construction is as simple as
254cutting-and-pasting a typical call along with its results into the docstring.
255This improves the documentation by providing the user with an example and it
256allows the doctest module to make sure the code remains true to the
257documentation::
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
270The :mod:`unittest` module is not as effortless as the :mod:`doctest` module,
271but it allows a more comprehensive set of tests to be maintained in a separate
272file::
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
289Batteries Included
290==================
291
292Python has a "batteries included" philosophy.  This is best seen through the
293sophisticated 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