| aids for working with large modules like :mod:`os`:: |
| |
| >>> import os |
| >>> dir(os) |
| <returns a list of all module functions> |
| >>> help(os) |
| <returns an extensive manual page created from the module's docstrings> |
| |
n | For daily file and directory management tasks, the :mod:`shutil` (XXX |
n | For daily file and directory management tasks, the :mod:`shutil` module provides |
| reference: ../lib/module-shutil.html) module provides a higher level interface |
| a higher level interface that is easier to use:: |
| that is easier to use:: |
| |
| >>> import shutil |
| >>> shutil.copyfile('data.db', 'archive.db') |
| >>> shutil.move('/build/executables', 'installdir') |
| |
| |
| .. _tut-file-wildcards: |
| |
| File Wildcards |
| ============== |
| |
n | The :mod:`glob` (XXX reference: ../lib/module-glob.html) module provides a |
n | The :mod:`glob` module provides a function for making file lists from directory |
| function for making file lists from directory wildcard searches:: |
| wildcard searches:: |
| |
| >>> import glob |
| >>> glob.glob('*.py') |
| ['primes.py', 'random.py', 'quote.py'] |
| |
| |
| .. _tut-command-line-arguments: |
| |
| Command Line Arguments |
| ====================== |
| |
| Common utility scripts often need to process command line arguments. These |
n | arguments are stored in the :mod:`sys` (XXX reference: ../lib/module-sys.html) |
n | arguments are stored in the :mod:`sys` module's *argv* attribute as a list. For |
| module's *argv* attribute as a list. For instance the following output results |
| instance the following output results from running ``python demo.py one two |
| from running ``python demo.py one two three`` at the command line:: |
| three`` at the command line:: |
| |
| >>> import sys |
| >>> print sys.argv |
| ['demo.py', 'one', 'two', 'three'] |
| |
n | The :mod:`getopt` (XXX reference: ../lib/module-getopt.html) module processes |
n | The :mod:`getopt` module processes *sys.argv* using the conventions of the Unix |
| *sys.argv* using the conventions of the Unix :func:`getopt` function. More |
| :func:`getopt` function. More powerful and flexible command line processing is |
| powerful and flexible command line processing is provided by the :mod:`optparse` |
| provided by the :mod:`optparse` module. |
| (XXX reference: ../lib/module-optparse.html) module. |
| |
| |
| .. _tut-stderr: |
| |
| Error Output Redirection and Program Termination |
| ================================================ |
| |
n | The :mod:`sys` (XXX reference: ../lib/module-sys.html) module also has |
n | The :mod:`sys` module also has attributes for *stdin*, *stdout*, and *stderr*. |
| attributes for *stdin*, *stdout*, and *stderr*. The latter is useful for |
| The latter is useful for emitting warnings and error messages to make them |
| emitting warnings and error messages to make them visible even when *stdout* has |
| visible even when *stdout* has been redirected:: |
| been redirected:: |
| |
| >>> sys.stderr.write('Warning, log file not found starting a new one\n') |
| Warning, log file not found starting a new one |
| |
| The most direct way to terminate a script is to use ``sys.exit()``. |
| |
| |
| .. _tut-string-pattern-matching: |
| |
| String Pattern Matching |
| ======================= |
| |
n | The :mod:`re` (XXX reference: ../lib/module-re.html) module provides regular |
n | The :mod:`re` module provides regular expression tools for advanced string |
| expression tools for advanced string processing. For complex matching and |
| processing. For complex matching and manipulation, regular expressions offer |
| manipulation, regular expressions offer succinct, optimized solutions:: |
| succinct, optimized solutions:: |
| |
| >>> import re |
| >>> re.findall(r'\bf[a-z]*', 'which foot or hand fell fastest') |
| ['foot', 'fell', 'fastest'] |
| >>> re.sub(r'(\b[a-z]+) \1', r'\1', 'cat in the the hat') |
| 'cat in the hat' |
| |
| When only simple capabilities are needed, string methods are preferred because |
| 'tea for two' |
| |
| |
| .. _tut-mathematics: |
| |
| Mathematics |
| =========== |
| |
n | The :mod:`math` (XXX reference: ../lib/module-math.html) module gives access to |
n | The :mod:`math` module gives access to the underlying C library functions for |
| the underlying C library functions for floating point math:: |
| floating point math:: |
| |
| >>> import math |
| >>> math.cos(math.pi / 4.0) |
| 0.70710678118654757 |
| >>> math.log(1024, 2) |
| 10.0 |
| |
n | The :mod:`random` (XXX reference: ../lib/module-random.html) module provides |
n | The :mod:`random` module provides tools for making random selections:: |
| tools for making random selections:: |
| |
| >>> import random |
| >>> random.choice(['apple', 'pear', 'banana']) |
| 'apple' |
| >>> random.sample(xrange(100), 10) # sampling without replacement |
| [30, 83, 16, 4, 8, 81, 41, 50, 18, 33] |
| >>> random.random() # random float |
| 0.17970987693706186 |
| >>> random.randrange(6) # random integer chosen from range(6) |
n | 4 |
n | 4 |
| |
| |
| .. _tut-internet-access: |
| |
| Internet Access |
| =============== |
| |
| There are a number of modules for accessing the internet and processing internet |
n | protocols. Two of the simplest are :mod:`urllib2` (XXX reference: ../lib/module- |
n | protocols. Two of the simplest are :mod:`urllib2` for retrieving data from urls |
| urllib2.html) for retrieving data from urls and :mod:`smtplib` (XXX reference: |
| and :mod:`smtplib` for sending mail:: |
| ../lib/module-smtplib.html) for sending mail:: |
| |
| >>> import urllib2 |
| >>> for line in urllib2.urlopen('http://tycho.usno.navy.mil/cgi-bin/timer.pl'): |
| ... if 'EST' in line or 'EDT' in line: # look for Eastern Time |
| ... print line |
| |
| <BR>Nov. 25, 09:43:32 PM EST |
| |
| >>> import smtplib |
| >>> server = smtplib.SMTP('localhost') |
| >>> server.sendmail('soothsayer@example.org', 'jcaesar@example.org', |
n | """To: jcaesar@example.org |
n | ... """To: jcaesar@example.org |
| From: soothsayer@example.org |
| ... From: soothsayer@example.org |
| |
| ... |
| Beware the Ides of March. |
| ... Beware the Ides of March. |
| """) |
| ... """) |
| >>> server.quit() |
n | |
| (Note that the second example needs a mailserver running on localhost.) |
| |
| |
| .. _tut-dates-and-times: |
| |
| Dates and Times |
| =============== |
| |
n | The :mod:`datetime` (XXX reference: ../lib/module-datetime.html) module supplies |
n | The :mod:`datetime` module supplies classes for manipulating dates and times in |
| classes for manipulating dates and times in both simple and complex ways. While |
| both simple and complex ways. While date and time arithmetic is supported, the |
| date and time arithmetic is supported, the focus of the implementation is on |
| focus of the implementation is on efficient member extraction for output |
| efficient member extraction for output formatting and manipulation. The module |
| formatting and manipulation. The module also supports objects that are timezone |
| also supports objects that are timezone aware. :: |
| aware. :: |
| |
| # dates are easily constructed and formatted |
| >>> from datetime import date |
| >>> now = date.today() |
| >>> now |
| datetime.date(2003, 12, 2) |
| >>> now.strftime("%m-%d-%y. %d %b %Y is a %A on the %d day of %B.") |
| '12-02-03. 02 Dec 2003 is a Tuesday on the 02 day of December.' |
| ======================= |
| |
| Some Python users develop a deep interest in knowing the relative performance of |
| different approaches to the same problem. Python provides a measurement tool |
| that answers those questions immediately. |
| |
| For example, it may be tempting to use the tuple packing and unpacking feature |
| instead of the traditional approach to swapping arguments. The :mod:`timeit` |
n | (XXX reference: ../lib/module-timeit.html) module quickly demonstrates a modest |
n | module quickly demonstrates a modest performance advantage:: |
| performance advantage:: |
| |
| >>> from timeit import Timer |
| >>> Timer('t=a; a=b; b=t', 'a=1; b=2').timeit() |
| 0.57535828626024577 |
| >>> Timer('a,b = b,a', 'a=1; b=2').timeit() |
| 0.54962537085770791 |
| |
n | In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` |
n | In contrast to :mod:`timeit`'s fine level of granularity, the :mod:`profile` and |
| (XXX reference: ../lib/module-profile.html) and :mod:`pstats` modules provide |
| :mod:`pstats` modules provide tools for identifying time critical sections in |
| tools for identifying time critical sections in larger blocks of code. |
| larger blocks of code. |
| |
| |
| .. _tut-quality-control: |
| |
| Quality Control |
| =============== |
| |
| One approach for developing high quality software is to write tests for each |
| function as it is developed and to run those tests frequently during the |
| development process. |
| |
n | The :mod:`doctest` (XXX reference: ../lib/module-doctest.html) module provides a |
n | The :mod:`doctest` module provides a tool for scanning a module and validating |
| tool for scanning a module and validating tests embedded in a program's |
| tests embedded in a program's docstrings. Test construction is as simple as |
| docstrings. Test construction is as simple as cutting-and-pasting a typical |
| cutting-and-pasting a typical call along with its results into the docstring. |
| call along with its results into the docstring. This improves the documentation |
| This improves the documentation by providing the user with an example and it |
| by providing the user with an example and it allows the doctest module to make |
| allows the doctest module to make sure the code remains true to the |
| sure the code remains true to the documentation:: |
| documentation:: |
| |
| def average(values): |
| """Computes the arithmetic mean of a list of numbers. |
| |
| >>> print average([20, 30, 70]) |
| 40.0 |
| """ |
| return sum(values, 0.0) / len(values) |
| |
| import doctest |
| doctest.testmod() # automatically validate the embedded tests |
| |
n | The :mod:`unittest` (XXX reference: ../lib/module-unittest.html) module is not |
n | The :mod:`unittest` module is not as effortless as the :mod:`doctest` module, |
| as effortless as the :mod:`doctest` module, but it allows a more comprehensive |
| but it allows a more comprehensive set of tests to be maintained in a separate |
| set of tests to be maintained in a separate file:: |
| file:: |
| |
| import unittest |
| |
| class TestStatisticalFunctions(unittest.TestCase): |
| |
| def test_average(self): |
| self.assertEqual(average([20, 30, 70]), 40.0) |
| self.assertEqual(round(average([1, 5, 7]), 1), 4.3) |
| .. _tut-batteries-included: |
| |
| Batteries Included |
| ================== |
| |
| Python has a "batteries included" philosophy. This is best seen through the |
| sophisticated and robust capabilities of its larger packages. For example: |
| |
n | * The :mod:`xmlrpclib` (XXX reference: ../lib/module-xmlrpclib.html) and |
n | * The :mod:`xmlrpclib` and :mod:`SimpleXMLRPCServer` modules make implementing |
| :mod:`SimpleXMLRPCServer` (XXX reference: ../lib/module-SimpleXMLRPCServer.html) |
| remote procedure calls into an almost trivial task. Despite the modules |
| modules make implementing remote procedure calls into an almost trivial task. |
| Despite the modules names, no direct knowledge or handling of XML is needed. |
| names, no direct knowledge or handling of XML is needed. |
| |
n | * The :mod:`email` (XXX reference: ../lib/module-email.html) package is a |
n | * The :mod:`email` package is a library for managing email messages, including |
| library for managing email messages, including MIME and other RFC 2822-based |
| MIME and other RFC 2822-based message documents. Unlike :mod:`smtplib` and |
| message documents. Unlike :mod:`smtplib` and :mod:`poplib` which actually send |
| :mod:`poplib` which actually send and receive messages, the email package has |
| and receive messages, the email package has a complete toolset for building or |
| a complete toolset for building or decoding complex message structures |
| decoding complex message structures (including attachments) and for implementing |
| (including attachments) and for implementing internet encoding and header |
| internet encoding and header protocols. |
| protocols. |
| |
n | * The :mod:`xml.dom` (XXX reference: ../lib/module-xml.dom.html) and |
n | * The :mod:`xml.dom` and :mod:`xml.sax` packages provide robust support for |
| :mod:`xml.sax` (XXX reference: ../lib/module-xml.sax.html) packages provide |
| robust support for parsing this popular data interchange format. Likewise, the |
| parsing this popular data interchange format. Likewise, the :mod:`csv` module |
| :mod:`csv` (XXX reference: ../lib/module-csv.html) module supports direct reads |
| supports direct reads and writes in a common database format. Together, these |
| and writes in a common database format. Together, these modules and packages |
| modules and packages greatly simplify data interchange between python |
| greatly simplify data interchange between python applications and other tools. |
| applications and other tools. |
| |
| * Internationalization is supported by a number of modules including |
t | :mod:`gettext` (XXX reference: ../lib/module-gettext.html), :mod:`locale` (XXX |
t | :mod:`gettext`, :mod:`locale`, and the :mod:`codecs` package. |
| reference: ../lib/module-locale.html), and the :mod:`codecs` (XXX reference: |
| ../lib/module-codecs.html) package. |
| |
| |