Python库参考手册

Python库参考手册(Python Library Reference) Release 2.3.3 Guido van Rossum Fred L. Drake, Jr., editor 翻译团队: 见文末名单 译文最后修改: 2004年3月22日 PythonLabs Email: docs@python.org Copyright c© 2001, 2002, 2003 Python Software Foundation. All rights reserved. Copyright c© 2000 BeOpen.com. 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. 详细版权及使用许可的资料见本文的最后部份. Python is an extensible, interpreted, object-oriented programming language. It supports a wide range of applica- tions, from simple text processing scripts to interactive Web browsers. Python是一种可扩展的,即译式,面向对象规格的编程语言.它能应用在极广泛的地方,从简单的文字处理 工作到交互式的网页浏览器. 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. Python语言参考手册中精确地描述了Python语言的句法及语义.然而语言参考手册中没有提到Python所 附带功能强大的标准库.这个函式库大大地增强了Python的实用性. 其中包括C写的内建模组,提供介面 让程式进行操作系统层次的工作,例如档案的输出输入;同时也有以Python语言本身编写的模组,为实际 编程时常遇的问题提供标准解决 方案 气瓶 现场处置方案 .pdf气瓶 现场处置方案 .doc见习基地管理方案.doc关于群访事件的化解方案建筑工地扬尘治理专项方案下载 .这类模组有的经过特别设计以便Python程式在跨平台的情况下运 行无误. 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. 本参考手册罗列并说明了Python标准库的各种功能,以及许多非核心的模组(按不同的操作系统和编译时 的设置而定,不是每台机上的Python都能用这些模组.) 本手册同时记载了Python语言所有的标准数据类 型,内建函数,异常类,这些在参考手册中被忽略了或只是扼要的提过一下. 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. 本手册的读者要对Python有基本的认识. 初学者应该从Python指南开始. 至于Python语言参考手册则是 该语言的语法和语义问题上的权威阐释. 最后扩展或嵌入Python解释器一文解说了如何在Python中加入 新的扩展模组;以及怎样把Python解释器嵌入到其他的应用程式中. 目录 第第第一一一章章章 内内内建建建对对对象象象Built-In Objects 1 第第第二二二章章章 Python运运运行行行时时时服服服务务务Python Runtime Services 3 2.1 main —顶层脚本的运行环境Top-level script environment . . . . . . . . . . . . . . . . 3 第第第三三三章章章 其其其他他他各各各类类类服服服务务务Miscellaneous Services 5 第第第四四四章章章 普普普遍遍遍的的的操操操作作作系系系统统统服服服务务务Generic Operating System Services 7 第第第五五五章章章 可可可选选选配配配的的的操操操作作作系系系统统统服服服务务务Optional Operating System Services 9 第第第六六六章章章 互互互联联联网网网通通通讯讯讯协协协议议议及及及其其其支支支援援援Internet Protocols and Support 11 第第第七七七章章章 互互互联联联网网网资资资料料料处处处理理理Internet Data Handling 13 7.1 base64 —编码和解码MIME Base64数据Encode and decode MIME base64 data . . . . . . . 13 7.2 xml.dom — The Document Object Model文档对象模式API . . . . . . . . . . . . . . . . . . 14 第第第八八八章章章 多多多媒媒媒体体体服服服务务务Multimedia Services 25 第第第九九九章章章 加加加密密密服服服务务务Cryptographic Services 27 第第第十十十章章章 Python语语语言言言服服服务务务Python Language Services 29 第第第十十十一一一章章章SGI IRIX特特特定定定服服服务务务SGI IRIX Specific Services 31 11.1 al — SGI的音讯功能Audio functions on the SGI . . . . . . . . . . . . . . . . . . . . . . . . . 31 11.2 AL — al模组中用到的常数。Constants used with the al module . . . . . . . . . . . . . . . . 33 第第第十十十二二二章章章SunOS特特特定定定服服服务务务SunOS Specific Services 35 第第第十十十三三三章章章MS Windows有有有关关关的的的服服服务务务MS Windows Services 37 附附附录录录 A 翻翻翻译译译团团团队队队 39 i ii 第第第一一一章章章 内内内建建建对对对象象象Built-In Objects Names for built-in exceptions and functions and a number of constants are found in a separate symbol table. This table is searched last when the interpreter looks up the meaning of a name, so local and global user-defined names can override built-in names. Built-in types are described together here for easy reference.1 内建的异常、函数和一组常量的名字都能在一个独立的符号表中找到。当解释器在查找一个名字的意义 的时候，这个表格是被最后查找的，所以局部的和全局的用户定义的名字可以覆盖内建的名字。所有的 内建类型都统一在本章描述，作为一个简单的参考。2 The tables in this chapter document the priorities of operators by listing them in order of ascending priority (within a table) and grouping operators that have the same priority in the same box. Binary operators of the same priority group from left to right. (Unary operators group from right to left, but there you have no real choice.) See chapter 5 of the Python Reference Manual for the complete picture on operator priorities. 在本章的表格中，对于操作符的优先级，以它们在表格中列出的顺序，升序排列，(在同一个表格中) 并且把相同优先级的操作符组织在同一格当中。同一优先级的二元操作符已从左到右的顺序结合。(一 元操作符从右到左结合，但事实上，你并没有选择的余地。) 对于操作符优先级的一个整体印象参 见Python参考手册第5章。 1Most descriptions sorely lack explanations of the exceptions that may be raised — this will be fixed in a future version of this manual. 2这儿的绝大多数描述都非常缺乏对它们所能抛出的异常的解释—这将会在本手册的未来版本得到修正。 1 2 第第第二二二章章章 Python运运运行行行时时时服服服务务务Python Runtime Services The modules described in this chapter provide a wide range of services related to the Python interpreter and its interaction with its environment. Here’s an overview: 本章所讲到的这些模块，对于与Python解释器相关的，以及解释器和它运行环境之间的交互，提供了丰 富的服务。以下是一个综述： main 顶层脚本运行所在的环境The environment where the top-level script is run. 2.1 main —顶层脚本的运行环境Top-level script environment This module represents the (otherwise anonymous) scope in which the interpreter’s main program executes — commands read either from standard input, from a script file, or from an interactive prompt. It is this environment in which the idiomatic “conditional script” stanza causes a script to run: 这个模块描述了(否则就是匿名的)解释器主程序运行命令的作用域– 这些命令包括读取自标准输入的, 脚本文件的,或者交互模式提示符的. 一般我们会用以下的“条件脚本”块来使一个脚本运行,这个环境就 是 main . if __name__ == "__main__": main() 3 4 第第第三三三章章章 其其其他他他各各各类类类服服服务务务Miscellaneous Services The modules described in this chapter provide miscellaneous services that are available in all Python versions. Here’s an overview: 本章所包含的为所有版本上的Python皆有的各杂类模组. 以下为概览: 5 6 第第第四四四章章章 普普普遍遍遍的的的操操操作作作系系系统统统服服服务务务Generic Operating System Services The modules described in this chapter provide interfaces to operating system features that are available on (al- most) all operating systems, such as files and a clock. The interfaces are generally modeled after the UNIX or C interfaces, but they are available on most other systems as well. Here’s an overview: 本章描述的模组及为存取操作系统提供服务介面。此类服务多为（基本上）所有操作平台所共有的，如 档案的读写及时钟值。介面的格式是仿照UNIX 或C的风格来建立的，但同时能使用在多数其他的系统 上。 7 8 第第第五五五章章章 可可可选选选配配配的的的操操操作作作系系系统统统服服服务务务Optional Operating System Services The modules described in this chapter provide interfaces to operating system features that are available on selected operating systems only. The interfaces are generally modeled after the UNIX or C interfaces but they are available on some other systems as well (e.g. Windows or NT). Here’s an overview: 本章描述的模组提供介面以存取只有某些特定操作系统才有的功能。介面设计以UNIX或C风格为蓝本, 但它们也能在其他如Windows, NT等平台上使用。以下是概述: 9 10 第第第六六六章章章 互互互联联联网网网通通通讯讯讯协协协议议议及及及其其其支支支援援援Internet Protocols and Support The modules described in this chapter implement Internet protocols and support for related technology. They are all implemented in Python. Most of these modules require the presence of the system-dependent module socket, which is currently supported on most popular platforms. Here is an overview: 本课描述的模组是对互联网通讯协议的实现,以及和其相关技术的支援。所有这些模组都是以Python来 实现的。大部份此类模组要用到一个依赖於操作系统的socket模组，此模组在基本存在於大多数流行 的平台中。以下是本章的概述： 11 12 第第第七七七章章章 互互互联联联网网网资资资料料料处处处理理理Internet Data Handling This chapter describes modules which support handling data formats commonly used on the Internet. 本章描述的模组帮助我们处理在互联网上通常会遇到的资料格式。 base64 使用MIME Base64来编码和解码文件Encode and decode files using the MIME base64 data. xml.dom Document Object Model API for Python文档对象模式. 7.1 base64 — 编码和解码MIME Base64数据Encode and decode MIME base64 data This module performs base64 encoding and decoding of arbitrary binary strings into text strings that can be safely sent by email or included as part of an HTTP POST request. The encoding scheme is defined in RFC 1521 (MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies, section 5.2, “Base64 Content-Transfer-Encoding”) and is used for MIME email and various other Internet-related applications; it is not the same as the output produced by the uuencode program. For example, the string ’www.python.org’ is encoded as the string ’d3d3LnB5dGhvbi5vcmc=\n’. 这个模块执行任意二进制串到文本串的Base64编码和解码，从而该数据能够被安全的由email传 输或者包含并且作为HTTP POST请求的一部分。编码的模式在RFC 1521 (MIME(Multipurpose In- ternet Mail Extensions) 第一部分：Mechanisms for Specifying and Describing the Format of Internet Mes- sage Bodies，5.2节，”Base64 Base64 Content-Transfer-Encoding”) 中定义，并且在MIME邮件以及各种其 它Internet相关的应用程序中使用；它不同于uuencode程序的输出。例如，字符串’www.python.org’ 编码为字符串’d3d3LnB5dGhvbi5vcmc=\n’。 decode(input, output) Decode the contents of the input file and write the resulting binary data to the output file. input and out- put must either be file objects or objects that mimic the file object interface. input will be read until in- put.read() returns an empty string. decode(input, output) 解码input文件的内容，输出结果二进制数据到output文件。input和output必须都为文件对象或模 拟文件对象接口的对象。input将一直读取，直至input.read()返回一个空串。 decodestring(s) Decode the string s, which must contain one or more lines of base64 encoded data, and return a string containing the resulting binary data. decodestring(s) 解码字符串s，必须包含一行或多行Base64编码数据，返回一个包含结果二进制数据的字符串。 encode(input, output) Encode the contents of the input file and write the resulting base64 encoded data to the output file. input and output must either be file objects or objects that mimic the file object interface. input will be read until input.read() returns an empty string. encode() returns the encoded data plus a trailing newline 13 character (’\n’). encode(input, output) 编码input文件的内容，输出结果Base64编码数据到output文件。input和output必须都为文件对象 或模拟文件对象接口的对象。input 将一直读取，直至input.read() 返回一个空串。encode() 返回编码后的数据外加一个结尾换行符(’\n’)。 encodestring(s) Encode the string s, which can contain arbitrary binary data, and return a string containing one or more lines of base64-encoded data. encodestring() returns a string containing one or more lines of base64- encoded data always including an extra trailing newline (’\n’). encodestring(s) 编码字符串s，能够包含任意的二进制数据，返回一个包含一行或多行Base64编码数 据。encodestring() 返回一个包含一行或多行Base64编码数据的字符串，而且总是包含一 个额外的结尾换行符(’\n’). See Also: Module binascii (section ??): Support module containing ASCII-to-binary and binary-to-ASCII conversions. RFC 1521, “MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies” Section 5.2, “Base64 Content-Transfer-Encoding,” provides the definition of the base64 encoding. 7.2 xml.dom — The Document Object Model文档对象模式API New in version 2.0. The Document Object Model, or “DOM,” is a cross-language API from the World Wide Web Consortium (W3C) for accessing and modifying XML documents. A DOM implementation presents an XML document as a tree structure, or allows client code to build such a structure from scratch. It then gives access to the structure through a set of objects which provided well-known interfaces. 文档对象模式,或称”DOM”是来自互联网协会(W3C)的一种交叉语言,用以访问和修改XML文档. DOM可 以将XML文档处理成为一种树状的数据结构，或是从客户代码生成这种数据结构. 并且提供了一套易读 的对象来访问这种数据结构. 1 The DOM is extremely useful for random-access applications. SAX only allows you a view of one bit of the document at a time. If you are looking at one SAX element, you have no access to another. If you are looking at a text node, you have no access to a containing element. When you write a SAX application, you need to keep track of your program’s position in the document somewhere in your own code. SAX does not do it for you. Also, if you need to look ahead in the XML document, you are just out of luck. DOM对于随机访问的应用非常有用. 而对于SAX,则只允许你同一时刻只能访问一小片XML文档,这意味 着: 如果你正在关注一个SAX元素,则你无法访问另一个.如果你正在访问一个文本结点,则你无法访问其 容器元素. 当你写SAX应用时,你得在代码中跟踪你程序在XML文档中的作用位置. SAX不能替你进行位 置的记录. 所以,如果你需要随时回到前面处理,SAX将无能为力! Some applications are simply impossible in an event driven model with no access to a tree. Of course you could build some sort of tree yourself in SAX events, but the DOM allows you to avoid writing that code. The DOM is a standard tree representation for XML data. 事务驱动模式的应用使你几乎不可能访问树形结构. 当然你可以自个儿架构某种结构在SAX的事务过程 中来存放树结构,但是DOM省却了你的这种代码. DOM是XML数据的标准树表达方式! The Document Object Model is being defined by the W3C in stages, or “levels” in their terminology. The Python mapping of the API is substantially based on the DOM Level 2 recommendation. The mapping of the Level 3 specification, currently only available in draft form, is being developed by the Python XML Special Interest Group as part of the PyXML package. Refer to the documentation bundled with that package for information on 1译按：（cross-language?交叉语言;） 14 第七章 7. 互联网资料处理Internet Data Handling the current state of DOM Level 3 support. 文档对象模式在W3C 的术语体系中被划分为“阶段”(stages)或是“阶层”(levels). Python 充分的映射 了DOM阶层2推荐的所有特性. 阶层3的 规范 编程规范下载gsp规范下载钢格栅规范下载警徽规范下载建设厅规范下载 当前Python的支持仅仅在草案阶段Python XML特殊兴趣组 也成为PyXML包的一部分. 2 DOM applications typically start by parsing some XML into a DOM. How this is accomplished is not covered at all by DOM Level 1, and Level 2 provides only limited improvements: There is a DOMImplementation object class which provides access to Document creation methods, but no way to access an XML reader/parser/Document builder in an implementation-independent way. There is also no well-defined way to access these methods without an existing Document object. In Python, each DOM implementation will provide a function getDOMImplementation(). DOM Level 3 adds a Load/Store specification, which defines an interface to the reader, but this is not yet available in the Python standard library. 典型的DOM应用由解析一些XML成为DOM 开始. 这在Python 已经完全封装了DOM 阶层1 至 阶层2的规范,仅仅除了一点限制: DOMImplementation 对象类提供Document 创建方法, 但是 没有独立执行的XML 读取/解析/文档结构创建的方法. Python中,每次DOM 的执行都需使用函 式getDOMImplementation(). DOM阶层3增加了Load/Store规范, 可以定义一个实例来进行XML的 读取,但是,这还没有在Python标准库中实现. Once you have a DOM document object, you can access the parts of your XML document through its properties and methods. These properties are defined in the DOM specification; this portion of the reference manual describes the interpretation of the specification in Python. 一但你获得了DOM文档对象,你便可以通过其提供的属性和方法来访问XML的各个部分. 这些属性 在DOM规范中进行了定义;手册的这一部分描述Python的DOM规范. The specification provided by the W3C defines the DOM API for Java, ECMAScript, and OMG IDL. The Python mapping defined here is based in large part on the IDL version of the specification, but strict compliance is not required (though implementations are free to support the strict mapping from IDL). See section 7.2.3, “Confor- mance,” for a detailed discussion of mapping requirements. W3C定义的DOM API规范有Java,ECMAScript,和OMG IDL版本的实现. Python的映射主要基于IDL版本, 但是并没有严密的匹配(尽管允许从IDL精确映射执行). 参考7.2.3一节,一致性“Conformance,”讨论详细的 映射必要条件. See Also: Document Object Model (DOM) Level 2 Specification DOM阶层2规范 (http://www.w3.org/TR/DOM-Level-2-Core/) The W3C recommendation upon which the Python DOM API is based. W3C推荐!Python DOM API完 全符合. Document Object Model (DOM) Level 1 Specification DOM阶层1规范 (http://www.w3.org/TR/REC-DOM-Level-1/) The W3C recommendation for the DOM supported by W3C 建 议 至 少 要 支 持 的,Python 由xml.dom.minidom提供映射. PyXML (http://pyxml.sourceforge.net) Users that require a full-featured implementation of DOM should use the PyXML package. 需要全部可执 行特性的用户,可以使用PyXML包. CORBA Scripting with Python CORBA分布式对象系统脚本与Python (http://cgi.omg.org/cgi-bin/doc?orbos/99-08-02.pdf) This specifies the mapping from OMG IDL to Python. 论述Python对于OMG IDL的映射 7.2.1 Module Contents模块s The xml.dom contains the following functions: 2译按：（levels?级别,阶层;） 7.2. xml.dom — The Document Object Model文档对象模式API 15 xml.dom包含以下函式: registerDOMImplementation(name, factory) Register the factory function with the name name. The factory function should return an object which implements the DOMImplementation interface. The factory function can return the same object every time, or a new one for each call, as appropriate for the specific implementation (e.g. if that implementation supports some customization). 3 以name注册”工厂(factory)函式”. ”工厂函式”应该返回一个DOMImplementation对象实例. 所 谓”工厂函式”,就是每次调用总能返回适当的对象实例,依据特定的实现. (例如:支持某些定制的实 现) (译按:行文有待斟酌!) getDOMImplementation([name[, features ] ] ) Return a suitable DOM implementation. The name is either well-known, the module name of a DOM implementation, or None. If it is not None, imports the corresponding module and returns a DOMImplementation object if the import succeeds. If no name is given, and if the environment variable PYTHON DOM is set, this variable is used to find the implementation. If name is not given, this examines the available implementations to find one with the required feature set. If no implementation can be found, raise an ImportError. The features list must be a sequence of (feature, version) pairs which are passed to the hasFeature() method on available DOMImplementation objects. Some convenience constants are also provided: EMPTY NAMESPACE The value used to indicate that no namespace is associated with a node in the DOM. This is typically found as the namespaceURI of a node, or used as the namespaceURI parameter to a namespaces-specific method. New in version 2.2. XML NAMESPACE The namespace URI associated with the reserved prefix xml, as defined by Namespaces in XML (section 4). New in version 2.2. XMLNS NAMESPACE The namespace URI for namespace declarations, as defined by Document Object Model (DOM) Level 2 Core Specification (section 1.1.8). New in version 2.2. XHTML NAMESPACE The URI of the XHTML namespace as defined by XHTML 1.0: The Extensible HyperText Markup Language (section 3.1.1). New in version 2.2. In addition, xml.dom contains a base Node class and the DOM exception classes. The Node class provided by this module does not implement any of the methods or attributes defined by the DOM specification; concrete DOM implementations must provide those. The Node class provided as part of this module does provide the constants used for the nodeType attribute on concrete Node objects; they are located within the class rather than at the module level to conform with the DOM specifications. 7.2.2 Objects in the DOM The definitive documentation for the DOM is the DOM specification from the W3C. Note that DOM attributes may also be manipulated as nodes instead of as simple strings. It is fairly rare that you must do this, however, so this usage is not yet documented. 3译按：（factory function?工厂函式,范式的一种模式;） 16 第七章 7. 互联网资料处理Internet Data Handling Interface Section Purpose DOMImplementation 7.2.2 Interface to the underlying implementation. Node 7.2.2 Base interface for most objects in a document. NodeList 7.2.2 Interface for a sequence of nodes. DocumentType 7.2.2 Information about the declarations needed to process a document. Document 7.2.2 Object which represents an entire document. Element 7.2.2 Element nodes in the document hierarchy. Attr 7.2.2 Attribute value nodes on element nodes. Comment 7.2.2 Representation of comments in the source document. Text 7.2.2 Nodes containing textual content from the document. ProcessingInstruction 7.2.2 Processing instruction representation. An additional section describes the exceptions defined for working with the DOM in Python. DOMImplementation Objects The DOMImplementation interface provides a way for applications to determine the availability of par- ticular features in the DOM they are using. DOM Level 2 added the ability to create new Document and Doc