/Doc/tutorial/stdlib.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 315 lines · 223 code · 92 blank · 0 comment · 0 complexity · cb52207aeaf36c5fe14f901840db1d80 MD5 · raw file

  1. .. _tut-brieftour:
  2. **********************************
  3. Brief Tour of the Standard Library
  4. **********************************
  5. .. _tut-os-interface:
  6. Operating System Interface
  7. ==========================
  8. The :mod:`os` module provides dozens of functions for interacting with the
  9. operating system::
  10. >>> import os
  11. >>> os.system('time 0:02')
  12. 0
  13. >>> os.getcwd() # Return the current working directory
  14. 'C:\\Python26'
  15. >>> os.chdir('/server/accesslogs')
  16. Be sure to use the ``import os`` style instead of ``from os import *``. This
  17. will keep :func:`os.open` from shadowing the built-in :func:`open` function which
  18. operates much differently.
  19. .. index:: builtin: help
  20. The built-in :func:`dir` and :func:`help` functions are useful as interactive
  21. aids for working with large modules like :mod:`os`::
  22. >>> import os
  23. >>> dir(os)
  24. <returns a list of all module functions>
  25. >>> help(os)
  26. <returns an extensive manual page created from the module's docstrings>
  27. For daily file and directory management tasks, the :mod:`shutil` module provides
  28. a higher level interface that is easier to use::
  29. >>> import shutil
  30. >>> shutil.copyfile('data.db', 'archive.db')
  31. >>> shutil.move('/build/executables', 'installdir')
  32. .. _tut-file-wildcards:
  33. File Wildcards
  34. ==============
  35. The :mod:`glob` module provides a function for making file lists from directory
  36. wildcard searches::
  37. >>> import glob
  38. >>> glob.glob('*.py')
  39. ['primes.py', 'random.py', 'quote.py']
  40. .. _tut-command-line-arguments:
  41. Command Line Arguments
  42. ======================
  43. Common utility scripts often need to process command line arguments. These
  44. arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For
  45. instance the following output results from running ``python demo.py one two
  46. three`` at the command line::
  47. >>> import sys
  48. >>> print sys.argv
  49. ['demo.py', 'one', 'two', 'three']
  50. The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix
  51. :func:`getopt` function. More powerful and flexible command line processing is
  52. provided by the :mod:`optparse` module.
  53. .. _tut-stderr:
  54. Error Output Redirection and Program Termination
  55. ================================================
  56. The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*.
  57. The latter is useful for emitting warnings and error messages to make them
  58. visible even when *stdout* has been redirected::
  59. >>> sys.stderr.write('Warning, log file not found starting a new one\n')
  60. Warning, log file not found starting a new one
  61. The most direct way to terminate a script is to use ``sys.exit()``.
  62. .. _tut-string-pattern-matching:
  63. String Pattern Matching
  64. =======================
  65. The :mod:`re` module provides regular expression tools for advanced string
  66. processing. For complex matching and manipulation, regular expressions offer
  67. succinct, optimized solutions::
  68. >>> import re
  69. >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest')
  70. ['foot', 'fell', 'fastest']
  71. >>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat')
  72. 'cat in the hat'
  73. When only simple capabilities are needed, string methods are preferred because
  74. they are easier to read and debug::
  75. >>> 'tea for too'.replace('too', 'two')
  76. 'tea for two'
  77. .. _tut-mathematics:
  78. Mathematics
  79. ===========
  80. The :mod:`math` module gives access to the underlying C library functions for
  81. floating point math::
  82. >>> import math
  83. >>> math.cos(math.pi / 4.0)
  84. 0.70710678118654757
  85. >>> math.log(1024, 2)
  86. 10.0
  87. The :mod:`random` module provides tools for making random selections::
  88. >>> import random
  89. >>> random.choice(['apple', 'pear', 'banana'])
  90. 'apple'
  91. >>> random.sample(xrange(100), 10) # sampling without replacement
  92. [30, 83, 16, 4, 8, 81, 41, 50, 18, 33]
  93. >>> random.random() # random float
  94. 0.17970987693706186
  95. >>> random.randrange(6) # random integer chosen from range(6)
  96. 4
  97. .. _tut-internet-access:
  98. Internet Access
  99. ===============
  100. There are a number of modules for accessing the internet and processing internet
  101. protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls
  102. and :mod:`smtplib` for sending mail::
  103. >>> import urllib2
  104. >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'):
  105. ... if 'EST' in line or 'EDT' in line: # look for Eastern Time
  106. ... print line
  107. <BR>Nov. 25, 09:43:32 PM EST
  108. >>> import smtplib
  109. >>> server = smtplib.SMTP('localhost')
  110. >>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org',
  111. ... """To: jcaesar@example.org
  112. ... From: soothsayer@example.org
  113. ...
  114. ... Beware the Ides of March.
  115. ... """)
  116. >>> server.quit()
  117. (Note that the second example needs a mailserver running on localhost.)
  118. .. _tut-dates-and-times:
  119. Dates and Times
  120. ===============
  121. The :mod:`datetime` module supplies classes for manipulating dates and times in
  122. both simple and complex ways. While date and time arithmetic is supported, the
  123. focus of the implementation is on efficient member extraction for output
  124. formatting and manipulation. The module also supports objects that are timezone
  125. aware. ::
  126. # dates are easily constructed and formatted
  127. >>> from datetime import date
  128. >>> now = date.today()
  129. >>> now
  130. datetime.date(2003, 12, 2)
  131. >>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.")
  132. '12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.'
  133. # dates support calendar arithmetic
  134. >>> birthday = date(1964, 7, 31)
  135. >>> age = now - birthday
  136. >>> age.days
  137. 14368
  138. .. _tut-data-compression:
  139. Data Compression
  140. ================
  141. Common data archiving and compression formats are directly supported by modules
  142. including: :mod:`zlib`, :mod:`gzip`, :mod:`bz2`, :mod:`zipfile` and
  143. :mod:`tarfile`. ::
  144. >>> import zlib
  145. >>> s = 'witch which has which witches wrist watch'
  146. >>> len(s)
  147. 41
  148. >>> t = zlib.compress(s)
  149. >>> len(t)
  150. 37
  151. >>> zlib.decompress(t)
  152. 'witch which has which witches wrist watch'
  153. >>> zlib.crc32(s)
  154. 226805979
  155. .. _tut-performance-measurement:
  156. Performance Measurement
  157. =======================
  158. Some Python users develop a deep interest in knowing the relative performance of
  159. different approaches to the same problem. Python provides a measurement tool
  160. that answers those questions immediately.
  161. For example, it may be tempting to use the tuple packing and unpacking feature
  162. instead of the traditional approach to swapping arguments. The :mod:`timeit`
  163. module quickly demonstrates a modest performance advantage::
  164. >>> from timeit import Timer
  165. >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit()
  166. 0.57535828626024577
  167. >>> Timer('a,b = b,a', 'a=1; b=2').timeit()
  168. 0.54962537085770791
  169. In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and
  170. :mod:`pstats` modules provide tools for identifying time critical sections in
  171. larger blocks of code.
  172. .. _tut-quality-control:
  173. Quality Control
  174. ===============
  175. One approach for developing high quality software is to write tests for each
  176. function as it is developed and to run those tests frequently during the
  177. development process.
  178. The :mod:`doctest` module provides a tool for scanning a module and validating
  179. tests embedded in a program's docstrings. Test construction is as simple as
  180. cutting-and-pasting a typical call along with its results into the docstring.
  181. This improves the documentation by providing the user with an example and it
  182. allows the doctest module to make sure the code remains true to the
  183. documentation::
  184. def average(values):
  185. """Computes the arithmetic mean of a list of numbers.
  186. >>> print average([20, 30, 70])
  187. 40.0
  188. """
  189. return sum(values, 0.0) / len(values)
  190. import doctest
  191. doctest.testmod() # automatically validate the embedded tests
  192. The :mod:`unittest` module is not as effortless as the :mod:`doctest` module,
  193. but it allows a more comprehensive set of tests to be maintained in a separate
  194. file::
  195. import unittest
  196. class TestStatisticalFunctions(unittest.TestCase):
  197. def test_average(self):
  198. self.assertEqual(average([20, 30, 70]), 40.0)
  199. self.assertEqual(round(average([1, 5, 7]), 1), 4.3)
  200. self.assertRaises(ZeroDivisionError, average, [])
  201. self.assertRaises(TypeError, average, 20, 30, 70)
  202. unittest.main() # Calling from the command line invokes all tests
  203. .. _tut-batteries-included:
  204. Batteries Included
  205. ==================
  206. Python has a "batteries included" philosophy. This is best seen through the
  207. sophisticated and robust capabilities of its larger packages. For example:
  208. * The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing
  209. remote procedure calls into an almost trivial task. Despite the modules
  210. names, no direct knowledge or handling of XML is needed.
  211. * The :mod:`email` package is a library for managing email messages, including
  212. MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and
  213. :mod:`poplib` which actually send and receive messages, the email package has
  214. a complete toolset for building or decoding complex message structures
  215. (including attachments) and for implementing internet encoding and header
  216. protocols.
  217. * The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for
  218. parsing this popular data interchange format. Likewise, the :mod:`csv` module
  219. supports direct reads and writes in a common database format. Together, these
  220. modules and packages greatly simplify data interchange between python
  221. applications and other tools.
  222. * Internationalization is supported by a number of modules including
  223. :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package.