Python Reference Manual

Guido van Rossum

Python Software Foundation
Email: docs@python.org

Fred L. Drake, Jr., editor

Release 2.5
19th September, 2006

See About this document... for information on suggesting changes.

Python Library Reference

Guido van Rossum

Python Software Foundation
Email: docs@python.org

Fred L. Drake, Jr., editor

Release 2.5
19th September, 2006

Front Matter
Contents
1. Introduction
2. Built-in Objects
- 2.1 Built-in Functions
- 2.2 Non-essential Built-in Functions
- 2.3 Built-in Exceptions
- 2.4 Built-in Constants
3. Built-in Types
- 3.1 Truth Value Testing
- 3.2 Boolean Operations -- and, or, not
- 3.3 Comparisons
- 3.4 Numeric Types -- int, float, long, complex
  - 3.4.1 Bit-string Operations on Integer Types
- 3.5 Iterator Types
- 3.6 Sequence Types -- str, unicode, list, tuple, buffer, xrange
- 3.7 Set Types -- set, frozenset
- 3.8 Mapping Types -- dict
- 3.9 File Objects
- 3.10 Context Manager Types
- 3.11 Other Built-in Types
- 3.12 Special Attributes
4. String Services
- 4.1 string -- Common string operations
- 4.2 re -- Regular expression operations
- 4.3 struct -- Interpret strings as packed binary data
- 4.4 difflib -- Helpers for computing deltas
- 4.5 StringIO -- Read and write strings as files
- 4.6 cStringIO -- Faster version of StringIO
- 4.7 textwrap -- Text wrapping and filling
- 4.8 codecs -- Codec registry and base classes
- 4.9 unicodedata -- Unicode Database
- 4.10 stringprep -- Internet String Preparation
- 4.11 fpformat -- Floating point conversions
5. Data Types
- 5.1 datetime -- Basic date and time types
- 5.2 calendar -- General calendar-related functions
- 5.3 collections -- High-performance container datatypes
  - 5.3.1 deque objects
  - 5.3.2 defaultdict objects
- 5.4 heapq -- Heap queue algorithm
  - 5.4.1 Theory
- 5.5 bisect -- Array bisection algorithm
  - 5.5.1 Examples
- 5.6 array -- Efficient arrays of numeric values
- 5.7 sets -- Unordered collections of unique elements
- 5.8 sched -- Event scheduler
  - 5.8.1 Scheduler Objects
- 5.9 mutex -- Mutual exclusion support
  - 5.9.1 Mutex Objects
- 5.10 Queue -- A synchronized queue class
  - 5.10.1 Queue Objects
- 5.11 weakref -- Weak references
  - 5.11.1 Weak Reference Objects
  - 5.11.2 Example
- 5.12 UserDict -- Class wrapper for dictionary objects
- 5.13 UserList -- Class wrapper for list objects
- 5.14 UserString -- Class wrapper for string objects
- 5.15 types -- Names for built-in types
- 5.16 new -- Creation of runtime internal objects
- 5.17 copy -- Shallow and deep copy operations
- 5.18 pprint -- Data pretty printer
  - 5.18.1 PrettyPrinter Objects
- 5.19 repr -- Alternate repr() implementation
  - 5.19.1 Repr Objects
  - 5.19.2 Subclassing Repr Objects
6. Numeric and Mathematical Modules
- 6.1 math -- Mathematical functions
- 6.2 cmath -- Mathematical functions for complex numbers
- 6.3 decimal -- Decimal floating point arithmetic
- 6.4 random -- Generate pseudo-random numbers
- 6.5 itertools -- Functions creating iterators for efficient looping
- 6.6 functools -- Higher order functions and operations on callable objects.
  - 6.6.1 partial Objects
- 6.7 operator -- Standard operators as functions.
  - 6.7.1 Mapping Operators to Functions
7. Internet Data Handling
- 7.1 email -- An email and MIME handling package
- 7.2 mailcap -- Mailcap file handling.
- 7.3 mailbox -- Manipulate mailboxes in various formats
- 7.4 mhlib -- Access to MH mailboxes
- 7.5 mimetools -- Tools for parsing MIME messages
  - 7.5.1 Additional Methods of Message Objects
- 7.6 mimetypes -- Map filenames to MIME types
  - 7.6.1 MimeTypes Objects
- 7.7 MimeWriter -- Generic MIME file writer
  - 7.7.1 MimeWriter Objects
- 7.8 mimify -- MIME processing of mail messages
- 7.9 multifile -- Support for files containing distinct parts
  - 7.9.1 MultiFile Objects
  - 7.9.2 MultiFile Example
- 7.10 rfc822 -- Parse RFC 2822 mail headers
  - 7.10.1 Message Objects
  - 7.10.2 AddressList Objects
- 7.11 base64 -- RFC 3548: Base16, Base32, Base64 Data Encodings
- 7.12 binhex -- Encode and decode binhex4 files
  - 7.12.1 Notes
- 7.13 binascii -- Convert between binary and ASCII
- 7.14 quopri -- Encode and decode MIME quoted-printable data
- 7.15 uu -- Encode and decode uuencode files
8. Structured Markup Processing Tools
- 8.1 HTMLParser -- Simple HTML and XHTML parser
  - 8.1.1 Example HTML Parser Application
- 8.2 sgmllib -- Simple SGML parser
- 8.3 htmllib -- A parser for HTML documents
  - 8.3.1 HTMLParser Objects
- 8.4 htmlentitydefs -- Definitions of HTML general entities
- 8.5 xml.parsers.expat -- Fast XML parsing using Expat
- 8.6 xml.dom -- The Document Object Model API
- 8.7 xml.dom.minidom -- Lightweight DOM implementation
- 8.8 xml.dom.pulldom -- Support for building partial DOM trees
  - 8.8.1 DOMEventStream Objects
- 8.9 xml.sax -- Support for SAX2 parsers
  - 8.9.1 SAXException Objects
- 8.10 xml.sax.handler -- Base classes for SAX handlers
- 8.11 xml.sax.saxutils -- SAX Utilities
- 8.12 xml.sax.xmlreader -- Interface for XML parsers
- 8.13 xml.etree.ElementTree -- The ElementTree XML API
9. File Formats
- 9.1 csv -- CSV File Reading and Writing
- 9.2 ConfigParser -- Configuration file parser
- 9.3 robotparser -- Parser for robots.txt
- 9.4 netrc -- netrc file processing
  - 9.4.1 netrc Objects
- 9.5 xdrlib -- Encode and decode XDR data
10. Cryptographic Services
- 10.1 hashlib -- Secure hashes and message digests
- 10.2 hmac -- Keyed-Hashing for Message Authentication
- 10.3 md5 -- MD5 message digest algorithm
- 10.4 sha -- SHA-1 message digest algorithm
11. File and Directory Access
- 11.1 os.path -- Common pathname manipulations
- 11.2 fileinput -- Iterate over lines from multiple input streams
- 11.3 stat -- Interpreting stat() results
- 11.4 statvfs -- Constants used with os.statvfs()
- 11.5 filecmp -- File and Directory Comparisons
  - 11.5.1 The dircmp class
- 11.6 tempfile -- Generate temporary files and directories
- 11.7 glob -- Unix style pathname pattern expansion
- 11.8 fnmatch -- Unix filename pattern matching
- 11.9 linecache -- Random access to text lines
- 11.10 shutil -- High-level file operations
  - 11.10.1 Example
- 11.11 dircache -- Cached directory listings
12. Data Compression and Archiving
- 12.1 zlib -- Compression compatible with gzip
- 12.2 gzip -- Support for gzip files
- 12.3 bz2 -- Compression compatible with bzip2
- 12.4 zipfile -- Work with ZIP archives
- 12.5 tarfile -- Read and write tar archive files
13. Data Persistence
- 13.1 pickle -- Python object serialization
- 13.2 cPickle -- A faster pickle
- 13.3 copy_reg -- Register pickle support functions
- 13.4 shelve -- Python object persistence
  - 13.4.1 Restrictions
  - 13.4.2 Example
- 13.5 marshal -- Internal Python object serialization
- 13.6 anydbm -- Generic access to DBM-style databases
- 13.7 whichdb -- Guess which DBM module created a database
- 13.8 dbm -- Simple ``database'' interface
- 13.9 gdbm -- GNU's reinterpretation of dbm
- 13.10 dbhash -- DBM-style interface to the BSD database library
  - 13.10.1 Database Objects
- 13.11 bsddb -- Interface to Berkeley DB library
  - 13.11.1 Hash, BTree and Record Objects
- 13.12 dumbdbm -- Portable DBM implementation
  - 13.12.1 Dumbdbm Objects
- 13.13 sqlite3 -- DB-API 2.0 interface for SQLite databases
14. Generic Operating System Services
- 14.1 os -- Miscellaneous operating system interfaces
- 14.2 time -- Time access and conversions
- 14.3 optparse -- More powerful command line option parser
- 14.4 getopt -- Parser for command line options
- 14.5 logging -- Logging facility for Python
- 14.6 getpass -- Portable password input
- 14.7 curses -- Terminal handling for character-cell displays
- 14.8 curses.textpad -- Text input widget for curses programs
  - 14.8.1 Textbox objects
- 14.9 curses.wrapper -- Terminal handler for curses programs
- 14.10 curses.ascii -- Utilities for ASCII characters
- 14.11 curses.panel -- A panel stack extension for curses.
  - 14.11.1 Functions
  - 14.11.2 Panel Objects
- 14.12 platform -- Access to underlying platform's identifying data.
- 14.13 errno -- Standard errno system symbols
- 14.14 ctypes -- A foreign function library for Python.
  - 14.14.1 ctypes tutorial
  - 14.14.2 ctypes reference
15. Optional Operating System Services
- 15.1 select -- Waiting for I/O completion
  - 15.1.1 Polling Objects
- 15.2 thread -- Multiple threads of control
- 15.3 threading -- Higher-level threading interface
- 15.4 dummy_thread -- Drop-in replacement for the thread module
- 15.5 dummy_threading -- Drop-in replacement for the threading module
- 15.6 mmap -- Memory-mapped file support
- 15.7 readline -- GNU readline interface
  - 15.7.1 Example
- 15.8 rlcompleter -- Completion function for GNU readline
  - 15.8.1 Completer Objects
16. Unix Specific Services
- 16.1 posix -- The most common POSIX system calls
  - 16.1.1 Large File Support
  - 16.1.2 Module Contents
- 16.2 pwd -- The password database
- 16.3 spwd -- The shadow password database
- 16.4 grp -- The group database
- 16.5 crypt -- Function to check Unix passwords
- 16.6 dl -- Call C functions in shared objects
  - 16.6.1 Dl Objects
- 16.7 termios -- POSIX style tty control
  - 16.7.1 Example
- 16.8 tty -- Terminal control functions
- 16.9 pty -- Pseudo-terminal utilities
- 16.10 fcntl -- The fcntl() and ioctl() system calls
- 16.11 pipes -- Interface to shell pipelines
  - 16.11.1 Template Objects
- 16.12 posixfile -- File-like objects with locking support
- 16.13 resource -- Resource usage information
  - 16.13.1 Resource Limits
  - 16.13.2 Resource Usage
- 16.14 nis -- Interface to Sun's NIS (Yellow Pages)
- 16.15 syslog -- Unix syslog library routines
- 16.16 commands -- Utilities for running commands
17. Interprocess Communication and Networking
- 17.1 subprocess -- Subprocess management
- 17.2 socket -- Low-level networking interface
- 17.3 signal -- Set handlers for asynchronous events
  - 17.3.1 Example
- 17.4 popen2 -- Subprocesses with accessible I/O streams
  - 17.4.1 Popen3 and Popen4 Objects
  - 17.4.2 Flow Control Issues
- 17.5 asyncore -- Asynchronous socket handler
  - 17.5.1 asyncore Example basic HTTP client
- 17.6 asynchat -- Asynchronous socket command/response handler
  - 17.6.1 asynchat - Auxiliary Classes and Functions
  - 17.6.2 asynchat Example
18. Internet Protocols and Support
- 18.1 webbrowser -- Convenient Web-browser controller
  - 18.1.1 Browser Controller Objects
- 18.2 cgi -- Common Gateway Interface support.
  - 18.2.1 Introduction
  - 18.2.2 Using the cgi module
  - 18.2.3 Higher Level Interface
  - 18.2.4 Old classes
  - 18.2.5 Functions
  - 18.2.6 Caring about security
  - 18.2.7 Installing your CGI script on a Unix system
  - 18.2.8 Testing your CGI script
  - 18.2.9 Debugging CGI scripts
  - 18.2.10 Common problems and solutions
- 18.3 cgitb -- Traceback manager for CGI scripts
- 18.4 wsgiref -- WSGI Utilities and Reference Implementation
  - 18.4.1 wsgiref.util - WSGI environment utilities
  - 18.4.2 wsgiref.headers - WSGI response header tools
  - 18.4.3 wsgiref.simple_server - a simple WSGI HTTP server
  - 18.4.4 wsgiref.validate - WSGI conformance checker
  - 18.4.5 wsgiref.handlers - server/gateway base classes
- 18.5 urllib -- Open arbitrary resources by URL
  - 18.5.1 URLopener Objects
  - 18.5.2 Examples
- 18.6 urllib2 -- extensible library for opening URLs
  - 18.6.1 Request Objects
  - 18.6.2 OpenerDirector Objects
  - 18.6.3 BaseHandler Objects
  - 18.6.4 HTTPRedirectHandler Objects
  - 18.6.5 HTTPCookieProcessor Objects
  - 18.6.6 ProxyHandler Objects
  - 18.6.7 HTTPPasswordMgr Objects
  - 18.6.8 AbstractBasicAuthHandler Objects
  - 18.6.9 HTTPBasicAuthHandler Objects
  - 18.6.10 ProxyBasicAuthHandler Objects
  - 18.6.11 AbstractDigestAuthHandler Objects
  - 18.6.12 HTTPDigestAuthHandler Objects
  - 18.6.13 ProxyDigestAuthHandler Objects
  - 18.6.14 HTTPHandler Objects
  - 18.6.15 HTTPSHandler Objects
  - 18.6.16 FileHandler Objects
  - 18.6.17 FTPHandler Objects
  - 18.6.18 CacheFTPHandler Objects
  - 18.6.19 GopherHandler Objects
  - 18.6.20 UnknownHandler Objects
  - 18.6.21 HTTPErrorProcessor Objects
  - 18.6.22 Examples
- 18.7 httplib -- HTTP protocol client
  - 18.7.1 HTTPConnection Objects
  - 18.7.2 HTTPResponse Objects
  - 18.7.3 Examples
- 18.8 ftplib -- FTP protocol client
  - 18.8.1 FTP Objects
- 18.9 gopherlib -- Gopher protocol client
- 18.10 poplib -- POP3 protocol client
  - 18.10.1 POP3 Objects
  - 18.10.2 POP3 Example
- 18.11 imaplib -- IMAP4 protocol client
  - 18.11.1 IMAP4 Objects
  - 18.11.2 IMAP4 Example
- 18.12 nntplib -- NNTP protocol client
  - 18.12.1 NNTP Objects
- 18.13 smtplib -- SMTP protocol client
  - 18.13.1 SMTP Objects
  - 18.13.2 SMTP Example
- 18.14 smtpd -- SMTP Server
  - 18.14.1 SMTPServer Objects
  - 18.14.2 DebuggingServer Objects
  - 18.14.3 PureProxy Objects
  - 18.14.4 MailmanProxy Objects
- 18.15 telnetlib -- Telnet client
  - 18.15.1 Telnet Objects
  - 18.15.2 Telnet Example
- 18.16 uuid -- UUID objects according to RFC 4122
  - 18.16.1 Example
- 18.17 urlparse -- Parse URLs into components
  - 18.17.1 Results of urlparse() and urlsplit()
- 18.18 SocketServer -- A framework for network servers
  - 18.18.1 Server Creation Notes
  - 18.18.2 Server Objects
  - 18.18.3 RequestHandler Objects
- 18.19 BaseHTTPServer -- Basic HTTP server
- 18.20 SimpleHTTPServer -- Simple HTTP request handler
- 18.21 CGIHTTPServer -- CGI-capable HTTP request handler
- 18.22 cookielib -- Cookie handling for HTTP clients
  - 18.22.1 CookieJar and FileCookieJar Objects
  - 18.22.2 FileCookieJar subclasses and co-operation with web browsers
  - 18.22.3 CookiePolicy Objects
  - 18.22.4 DefaultCookiePolicy Objects
  - 18.22.5 Cookie Objects
  - 18.22.6 Examples
- 18.23 Cookie -- HTTP state management
  - 18.23.1 Cookie Objects
  - 18.23.2 Morsel Objects
  - 18.23.3 Example
- 18.24 xmlrpclib -- XML-RPC client access
  - 18.24.1 ServerProxy Objects
  - 18.24.2 Boolean Objects
  - 18.24.3 DateTime Objects
  - 18.24.4 Binary Objects
  - 18.24.5 Fault Objects
  - 18.24.6 ProtocolError Objects
  - 18.24.7 MultiCall Objects
  - 18.24.8 Convenience Functions
  - 18.24.9 Example of Client Usage
- 18.25 SimpleXMLRPCServer -- Basic XML-RPC server
  - 18.25.1 SimpleXMLRPCServer Objects
  - 18.25.2 CGIXMLRPCRequestHandler
- 18.26 DocXMLRPCServer -- Self-documenting XML-RPC server
  - 18.26.1 DocXMLRPCServer Objects
  - 18.26.2 DocCGIXMLRPCRequestHandler
19. Multimedia Services
- 19.1 audioop -- Manipulate raw audio data
- 19.2 imageop -- Manipulate raw image data
- 19.3 aifc -- Read and write AIFF and AIFC files
- 19.4 sunau -- Read and write Sun AU files
  - 19.4.1 AU_read Objects
  - 19.4.2 AU_write Objects
- 19.5 wave -- Read and write WAV files
  - 19.5.1 Wave_read Objects
  - 19.5.2 Wave_write Objects
- 19.6 chunk -- Read IFF chunked data
- 19.7 colorsys -- Conversions between color systems
- 19.8 rgbimg -- Read and write ``SGI RGB'' files
- 19.9 imghdr -- Determine the type of an image
- 19.10 sndhdr -- Determine type of sound file
- 19.11 ossaudiodev -- Access to OSS-compatible audio devices
  - 19.11.1 Audio Device Objects
  - 19.11.2 Mixer Device Objects
20. Graphical User Interfaces with Tk
- 20.1 Tkinter -- Python interface to Tcl/Tk
- 20.2 Tix -- Extension widgets for Tk
- 20.3 ScrolledText -- Scrolled Text Widget
- 20.4 turtle -- Turtle graphics for Tk
  - 20.4.1 Turtle, Pen and RawPen Objects
- 20.5 Idle
- 20.6 Other Graphical User Interface Packages
21. Internationalization
- 21.1 gettext -- Multilingual internationalization services
- 21.2 locale -- Internationalization services
22. Program Frameworks
- 22.1 cmd -- Support for line-oriented command interpreters
  - 22.1.1 Cmd Objects
- 22.2 shlex -- Simple lexical analysis
  - 22.2.1 shlex Objects
  - 22.2.2 Parsing Rules
23. Development Tools
- 23.1 pydoc -- Documentation generator and online help system
- 23.2 doctest -- Test interactive Python examples
- 23.3 unittest -- Unit testing framework
- 23.4 test -- Regression tests package for Python
  - 23.4.1 Writing Unit Tests for the test package
  - 23.4.2 Running tests using test.regrtest
- 23.5 test.test_support -- Utility functions for tests
24. The Python Debugger
- 24.1 Debugger Commands
- 24.2 How It Works
25. The Python Profilers
- 25.1 Introduction to the profilers
- 25.2 Instant User's Manual
- 25.3 What Is Deterministic Profiling?
- 25.4 Reference Manual - profile and cProfile
  - 25.4.1 The Stats Class
- 25.5 Limitations
- 25.6 Calibration
- 25.7 Extensions -- Deriving Better Profilers
- 25.8 hotshot -- High performance logging profiler
- 25.9 timeit -- Measure execution time of small code snippets
  - 25.9.1 Command Line Interface
  - 25.9.2 Examples
- 25.10 trace -- Trace or track Python statement execution
  - 25.10.1 Command Line Usage
  - 25.10.2 Programming Interface
26. Python Runtime Services
- 26.1 sys -- System-specific parameters and functions
- 26.2 __builtin__ -- Built-in objects
- 26.3 __main__ -- Top-level script environment
- 26.4 warnings -- Warning control
- 26.5 contextlib -- Utilities for with-statement contexts.
- 26.6 atexit -- Exit handlers
  - 26.6.1 atexit Example
- 26.7 traceback -- Print or retrieve a stack traceback
  - 26.7.1 Traceback Example
- 26.8 __future__ -- Future statement definitions
- 26.9 gc -- Garbage Collector interface
- 26.10 inspect -- Inspect live objects
- 26.11 site -- Site-specific configuration hook
- 26.12 user -- User-specific configuration hook
- 26.13 fpectl -- Floating point exception control
  - 26.13.1 Example
  - 26.13.2 Limitations and other considerations
27. Custom Python Interpreters
- 27.1 code -- Interpreter base classes
  - 27.1.1 Interactive Interpreter Objects
  - 27.1.2 Interactive Console Objects
- 27.2 codeop -- Compile Python code
28. Restricted Execution
- 28.1 rexec -- Restricted execution framework
- 28.2 Bastion -- Restricting access to objects
29. Importing Modules
- 29.1 imp -- Access the import internals
  - 29.1.1 Examples
- 29.2 zipimport -- Import modules from Zip archives
  - 29.2.1 zipimporter Objects
  - 29.2.2 Examples
- 29.3 pkgutil -- Package extension utility
- 29.4 modulefinder -- Find modules used by a script
- 29.5 runpy -- Locating and executing Python modules.
30. Python Language Services
- 30.1 parser -- Access Python parse trees
- 30.2 symbol -- Constants used with Python parse trees
- 30.3 token -- Constants used with Python parse trees
- 30.4 keyword -- Testing for Python keywords
- 30.5 tokenize -- Tokenizer for Python source
- 30.6 tabnanny -- Detection of ambiguous indentation
- 30.7 pyclbr -- Python class browser support
  - 30.7.1 Class Descriptor Objects
  - 30.7.2 Function Descriptor Objects
- 30.8 py_compile -- Compile Python source files
- 30.9 compileall -- Byte-compile Python libraries
- 30.10 dis -- Disassembler for Python byte code
  - 30.10.1 Python Byte Code Instructions
- 30.11 pickletools -- Tools for pickle developers.
- 30.12 distutils -- Building and installing Python modules
31. Python compiler package
- 31.1 The basic interface
- 31.2 Limitations
- 31.3 Python Abstract Syntax
- 31.4 Using Visitors to Walk ASTs
- 31.5 Bytecode Generation
32. Abstract Syntax Trees
- 32.1 Abstract Grammar
33. Miscellaneous Services
- 33.1 formatter -- Generic output formatting
34. SGI IRIX Specific Services
- 34.1 al -- Audio functions on the SGI
  - 34.1.1 Configuration Objects
  - 34.1.2 Port Objects
- 34.2 AL -- Constants used with the al module
- 34.3 cd -- CD-ROM access on SGI systems
  - 34.3.1 Player Objects
  - 34.3.2 Parser Objects
- 34.4 fl -- FORMS library for graphical user interfaces
- 34.5 FL -- Constants used with the fl module
- 34.6 flp -- Functions for loading stored FORMS designs
- 34.7 fm -- Font Manager interface
- 34.8 gl -- Graphics Library interface
- 34.9 DEVICE -- Constants used with the gl module
- 34.10 GL -- Constants used with the gl module
- 34.11 imgfile -- Support for SGI imglib files
- 34.12 jpeg -- Read and write JPEG files
35. SunOS Specific Services
- 35.1 sunaudiodev -- Access to Sun audio hardware
  - 35.1.1 Audio Device Objects
- 35.2 SUNAUDIODEV -- Constants used with sunaudiodev
36. MS Windows Specific Services
- 36.1 msilib -- Read and write Microsoft Installer files
- 36.2 msvcrt - Useful routines from the MS VC++ runtime
- 36.3 _winreg - Windows registry access
  - 36.3.1 Registry Handle Objects
- 36.4 winsound -- Sound-playing interface for Windows
A. Undocumented Modules
- A.1 Frameworks
- A.2 Miscellaneous useful utilities
- A.3 Platform specific modules
- A.4 Multimedia
- A.5 Obsolete
- A.6 SGI-specific Extension modules
B. Reporting Bugs
C. History and License
- C.1 History of the software
- C.2 Terms and conditions for accessing or otherwise using Python
- C.3 Licenses and Acknowledgements for Incorporated Software
Module Index
Index
About this document ...

See About this document... for information on suggesting changes.