Python Library Reference - MIT

[Pages:530]Python Library Reference

Release 2.1.1

Guido van Rossum Fred L. Drake, Jr., editor

July 20, 2001

PythonLabs E-mail: python-docs@

Copyright c 2001 Python Software Foundation. All rights reserved. Copyright c 2000 . All rights reserved. Copyright c 1995-2000 Corporation for National Research Initiatives. All rights reserved. Copyright c 1991-1995 Stichting Mathematisch Centrum. All rights reserved. See the end of this document for complete license and permissions information.

Abstract

Python is an extensible, interpreted, object-oriented programming language. It supports a wide range of applications, from simple text processing scripts to interactive WWW browsers.

While the Python Reference Manual describes the exact syntax and semantics of the language, it does not describe the standard library that is distributed with the language, and which greatly enhances its immediate usability. This library contains built-in modules (written in C) that provide access to system functionality such as file I/O that would otherwise be inaccessible to Python programmers, as well as modules written in Python that provide standardized solutions for many problems that occur in everyday programming. Some of these modules are explicitly designed to encourage and enhance the portability of Python programs.

This library reference manual documents Python's standard library, as well as many optional library modules (which may or may not be available, depending on whether the underlying platform supports them and on the configuration choices made at compile time). It also documents the standard types of the language and its built-in functions and exceptions, many of which are not or incompletely documented in the Reference Manual.

This manual assumes basic knowledge about the Python language. For an informal introduction to Python, see the Python Tutorial; the Python Reference Manual remains the highest authority on syntactic and semantic questions. Finally, the manual entitled Extending and Embedding the Python Interpreter describes how to add new extensions to Python and how to embed it in other applications.

CONTENTS

1 Introduction

1

2 Built-in Types, Exceptions and Functions

3

2.1 Built-in Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 Built-in Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2.3 Built-in Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3 Python Runtime Services

29

3.1 sys -- System-specific parameters and functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

3.2 gc -- Garbage Collector interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

3.3 weakref -- Weak references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.4 fpectl -- Floating point exception control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.5 atexit -- Exit handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.6 types -- Names for all built-in types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

3.7 UserDict -- Class wrapper for dictionary objects . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.8 UserList -- Class wrapper for list objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.9 UserString -- Class wrapper for string objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.10 operator -- Standard operators as functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.11 inspect -- Inspect live objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

3.12 traceback -- Print or retrieve a stack traceback . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

3.13 linecache -- Random access to text lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

3.14 pickle -- Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

3.15 cPickle -- Alternate implementation of pickle . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.16 copy reg -- Register pickle support functions . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.17 shelve -- Python object persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

3.18 copy -- Shallow and deep copy operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

3.19 marshal -- Alternate Python object serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

3.20 warnings -- Warning control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

3.21 imp -- Access the import internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

3.22 code -- Interpreter base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

3.23 codeop -- Compile Python code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

3.24 pprint -- Data pretty printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

3.25 repr -- Alternate repr() implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

3.26 new -- Creation of runtime internal objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.27 site -- Site-specific configuration hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

3.28 user -- User-specific configuration hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

3.29 builtin -- Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

3.30 main -- Top-level script environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

i

4 String Services

77

4.1 string -- Common string operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

4.2 re -- Regular expression operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

4.3 struct -- Interpret strings as packed binary data . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

4.4 difflib -- Helpers for computing deltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

4.5 fpformat -- Floating point conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

4.6 StringIO -- Read and write strings as files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

4.7 cStringIO -- Faster version of StringIO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

4.8 codecs -- Codec registry and base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

4.9 unicodedata -- Unicode Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

5 Miscellaneous Services

101

5.1 doctest -- Test docstrings represent reality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

5.2 unittest -- Unit testing framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

5.3 math -- Mathematical functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

5.4 cmath -- Mathematical functions for complex numbers . . . . . . . . . . . . . . . . . . . . . . . . 119

5.5 random -- Generate pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

5.6 whrandom -- Pseudo-random number generator . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

5.7 bisect -- Array bisection algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

5.8 array -- Efficient arrays of numeric values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

5.9 ConfigParser -- Configuration file parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

5.10 fileinput -- Iterate over lines from multiple input streams . . . . . . . . . . . . . . . . . . . . . 129

5.11 xreadlines -- Efficient iteration over a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

5.12 calendar -- General calendar-related functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

5.13 cmd -- Support for line-oriented command interpreters . . . . . . . . . . . . . . . . . . . . . . . . 132

5.14 shlex -- Simple lexical analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

6 Generic Operating System Services

137

6.1 os -- Miscellaneous OS interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

6.2 os.path -- Common pathname manipulations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

6.3 dircache -- Cached directory listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

6.4 stat -- Interpreting stat() results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

6.5 statcache -- An optimization of os.stat() . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

6.6 statvfs -- Constants used with os.statvfs() . . . . . . . . . . . . . . . . . . . . . . . . . . 154

6.7 filecmp -- File and Directory Comparisons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

6.8 popen2 -- Subprocesses with accessible I/O streams . . . . . . . . . . . . . . . . . . . . . . . . . 156

6.9 time -- Time access and conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

6.10 sched -- Event scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

6.11 mutex -- Mutual exclusion support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

6.12 getpass -- Portable password input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

6.13 curses -- Terminal handling for character-cell displays . . . . . . . . . . . . . . . . . . . . . . . 163

6.14 curses.textpad -- Text input widget for curses programs . . . . . . . . . . . . . . . . . . . . . 178

6.15 curses.wrapper -- Terminal handler for curses programs . . . . . . . . . . . . . . . . . . . . . 179

6.16 curses.ascii -- Utilities for ASCII characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

6.17 curses.panel -- A panel stack extension for curses. . . . . . . . . . . . . . . . . . . . . . . . . 182

6.18 getopt -- Parser for command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

6.19 tempfile -- Generate temporary file names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.20 errno -- Standard errno system symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

6.21 glob -- UNIX style pathname pattern expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

6.22 fnmatch -- UNIX filename pattern matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

6.23 shutil -- High-level file operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

6.24 locale -- Internationalization services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

6.25 gettext -- Multilingual internationalization services . . . . . . . . . . . . . . . . . . . . . . . . 198

ii

7 Optional Operating System Services

207

7.1 signal -- Set handlers for asynchronous events . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

7.2 socket -- Low-level networking interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

7.3 select -- Waiting for I/O completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

7.4 thread -- Multiple threads of control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

7.5 threading -- Higher-level threading interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

7.6 Queue -- A synchronized queue class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

7.7 mmap -- Memory-mapped file support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

7.8 anydbm -- Generic access to DBM-style databases . . . . . . . . . . . . . . . . . . . . . . . . . . 225

7.9 dumbdbm -- Portable DBM implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

7.10 dbhash -- DBM-style interface to the BSD database library . . . . . . . . . . . . . . . . . . . . . 226

7.11 whichdb -- Guess which DBM module created a database . . . . . . . . . . . . . . . . . . . . . . 227

7.12 bsddb -- Interface to Berkeley DB library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

7.13 zlib -- Compression compatible with gzip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

7.14 gzip -- Support for gzip files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

7.15 zipfile -- Work with ZIP archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

7.16 readline -- GNU readline interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

7.17 rlcompleter -- Completion function for GNU readline . . . . . . . . . . . . . . . . . . . . . . 236

8 Unix Specific Services

239

8.1 posix -- The most common POSIX system calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

8.2 pwd -- The password database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

8.3 grp -- The group database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

8.4 crypt -- Function to check UNIX passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

8.5 dl -- Call C functions in shared objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

8.6 dbm -- Simple "database" interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

8.7 gdbm -- GNU's reinterpretation of dbm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

8.8 termios -- POSIX style tty control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

8.9 TERMIOS -- Constants used with the termios module . . . . . . . . . . . . . . . . . . . . . . . 246

8.10 tty -- Terminal control functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

8.11 pty -- Pseudo-terminal utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

8.12 fcntl -- The fcntl() and ioctl() system calls . . . . . . . . . . . . . . . . . . . . . . . . . 247

8.13 pipes -- Interface to shell pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

8.14 posixfile -- File-like objects with locking support . . . . . . . . . . . . . . . . . . . . . . . . . 250

8.15 resource -- Resource usage information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

8.16 nis -- Interface to Sun's NIS (Yellow Pages) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

8.17 syslog -- UNIX syslog library routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

8.18 commands -- Utilities for running commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

9 The Python Debugger

257

9.1 Debugger Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

9.2 How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

10 The Python Profiler

263

10.1 Introduction to the profiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

10.2 How Is This Profiler Different From The Old Profiler? . . . . . . . . . . . . . . . . . . . . . . . . . 263

10.3 Instant Users Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

10.4 What Is Deterministic Profiling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

10.5 Reference Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

10.6 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

10.7 Calibration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

10.8 Extensions -- Deriving Better Profilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

11 Internet Protocols and Support

275

11.1 webbrowser -- Convenient Web-browser controller . . . . . . . . . . . . . . . . . . . . . . . . . 275

iii

11.2 cgi -- Common Gateway Interface support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 11.3 urllib -- Open arbitrary resources by URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 11.4 urllib2 -- extensible library for opening URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 11.5 httplib -- HTTP protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 11.6 ftplib -- FTP protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 11.7 gopherlib -- Gopher protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 11.8 poplib -- POP3 protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 11.9 imaplib -- IMAP4 protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 11.10 nntplib -- NNTP protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 11.11 smtplib -- SMTP protocol client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 11.12 telnetlib -- Telnet client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 11.13 urlparse -- Parse URLs into components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 11.14 SocketServer -- A framework for network servers . . . . . . . . . . . . . . . . . . . . . . . . . 313 11.15 BaseHTTPServer -- Basic HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 11.16 SimpleHTTPServer -- Simple HTTP request handler . . . . . . . . . . . . . . . . . . . . . . . 317 11.17 CGIHTTPServer -- CGI-capable HTTP request handler . . . . . . . . . . . . . . . . . . . . . . . 318 11.18 Cookie -- HTTP state management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 11.19 asyncore -- Asynchronous socket handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

12 Internet Data Handling

327

12.1 formatter -- Generic output formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

12.2 rfc822 -- Parse RFC 822 mail headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

12.3 mimetools -- Tools for parsing MIME messages . . . . . . . . . . . . . . . . . . . . . . . . . . 334

12.4 MimeWriter -- Generic MIME file writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

12.5 multifile -- Support for files containing distinct parts . . . . . . . . . . . . . . . . . . . . . . . 336

12.6 binhex -- Encode and decode binhex4 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

12.7 uu -- Encode and decode uuencode files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

12.8 binascii -- Convert between binary and ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

12.9 xdrlib -- Encode and decode XDR data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

12.10 mailcap -- Mailcap file handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

12.11 mimetypes -- Map filenames to MIME types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

12.12 base64 -- Encode and decode MIME base64 data . . . . . . . . . . . . . . . . . . . . . . . . . . 345

12.13 quopri -- Encode and decode MIME quoted-printable data . . . . . . . . . . . . . . . . . . . . . 346

12.14 mailbox -- Read various mailbox formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

12.15 mhlib -- Access to MH mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

12.16 mimify -- MIME processing of mail messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

12.17 netrc -- netrc file processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350

12.18 robotparser -- Parser for robots.txt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

13 Structured Markup Processing Tools

353

13.1 sgmllib -- Simple SGML parser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

13.2 htmllib -- A parser for HTML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

13.3 htmlentitydefs -- Definitions of HTML general entities . . . . . . . . . . . . . . . . . . . . . 357

13.4 xml.parsers.expat -- Fast XML parsing using Expat . . . . . . . . . . . . . . . . . . . . . . 357

13.5 xml.dom -- The Document Object Model API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

13.6 xml.dom.minidom -- Lightweight DOM implementation . . . . . . . . . . . . . . . . . . . . . 373

13.7 xml.dom.pulldom -- Support for building partial DOM trees . . . . . . . . . . . . . . . . . . . 377

13.8 xml.sax -- Support for SAX2 parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

13.9 xml.sax.handler -- Base classes for SAX handlers . . . . . . . . . . . . . . . . . . . . . . . . 379

13.10 xml.sax.saxutils -- SAX Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

13.11 xml.sax.xmlreader -- Interface for XML parsers . . . . . . . . . . . . . . . . . . . . . . . . 383

13.12 xmllib -- A parser for XML documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

14 Multimedia Services

391

iv

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download