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 语言本身编写的模组, 为实际 编程时常遇的问题提供标准解决方案. 这类模组有的经过特别设计以便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 的规范当前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 DocumentType objects using the DOMImplementation as well. hasFeature(feature, version) Node Objects All of the components of an XML document are subclasses of Node. nodeType An integer representing the node type. Symbolic constants for the types are on the Node object: ELEMENT NODE, ATTRIBUTE NODE, TEXT NODE, CDATA SECTION NODE, ENTITY NODE, PROCESSING INSTRUCTION NODE, COMMENT NODE, DOCUMENT NODE, DOCUMENT TYPE NODE, NOTATION NODE. This is a read-only attribute. parentNode The parent of the current node, or None for the document node. The value is always a Node object or None. For Element nodes, this will be the parent element, except for the root element, in which case it will be the Document object. For Attr nodes, this is always None. This is a read-only attribute. attributes A NamedNodeMap of attribute objects. Only elements have actual values for this; others provide None for this attribute. This is a read-only attribute. previousSibling The node that immediately precedes this one with the same parent. For instance the element with an end-tag that comes just before the self element’s start-tag. Of course, XML documents are made up of more than just elements so the previous sibling could be text, a comment, or something else. If this node is the first child of the parent, this attribute will be None. This is a read-only attribute. nextSibling The node that immediately follows this one with the same parent. See also previousSibling. If this is the last child of the parent, this attribute will be None. This is a read-only attribute. childNodes A list of nodes contained within this node. This is a read-only attribute. firstChild The first child of the node, if there are any, or None. This is a read-only attribute. lastChild The last child of the node, if there are any, or None. This is a read-only attribute. localName The part of the tagName following the colon if there is one, else the entire tagName. The value is a string. 7.2. xml.dom — The Document Object Model 文档对象模式API 17 prefix The part of the tagName preceding the colon if there is one, else the empty string. The value is a string, or None namespaceURI The namespace associated with the element name. This will be a string or None. This is a read-only attribute. nodeName This has a different meaning for each node type; see the DOM specification for details. You can always get the information you would get here from another property such as the tagName property for elements or the name property for attributes. For all node types, the value of this attribute will be either a string or None. This is a read-only attribute. nodeValue This has a different meaning for each node type; see the DOM specification for details. The situation is similar to that with nodeName. The value is a string or None. hasAttributes() Returns true if the node has any attributes. hasChildNodes() Returns true if the node has any child nodes. isSameNode(other) Returns true if other refers to the same node as this node. This is especially useful for DOM implementations which use any sort of proxy architecture (because more than one object can refer to the same node). Note: This is based on a proposed DOM Level 3 API which is still in the “working draft” stage, but this particular interface appears uncontroversial. Changes from the W3C will not necessarily affect this method in the Python DOM interface (though any new W3C API for this would also be supported). appendChild(newChild) Add a new child node to this node at the end of the list of children, returning newChild. insertBefore(newChild, refChild) Insert a new child node before an existing child. It must be the case that refChild is a child of this node; if not, ValueError is raised. newChild is returned. removeChild(oldChild) Remove a child node. oldChild must be a child of this node; if not, ValueError is raised. oldChild is returned on success. If oldChild will not be used further, its unlink() method should be called. replaceChild(newChild, oldChild) Replace an existing node with a new node. It must be the case that oldChild is a child of this node; if not, ValueError is raised. normalize() Join adjacent text nodes so that all stretches of text are stored as single Text instances. This simplifies processing text from a DOM tree for many applications. New in version 2.1. cloneNode(deep) Clone this node. Setting deep means to clone all child nodes as well. This returns the clone. NodeList Objects A NodeList represents a sequence of nodes. These objects are used in two ways in the DOM Core recommen- dation: the Element objects provides one as its list of child nodes, and the getElementsByTagName() and getElementsByTagNameNS() methods of Node return objects with this interface to represent query results. The DOM Level 2 recommendation defines one method and one attribute for these objects: item(i) Return the i’th item from the sequence, if there is one, or None. The index i is not allowed to be less then zero or greater than or equal to the length of the sequence. 18 第七章 7. 互联网资料处理Internet Data Handling length The number of nodes in the sequence. In addition, the Python DOM interface requires that some additional support is provided to allow NodeList objects to be used as Python sequences. All NodeList implementations must include support for len () and getitem (); this allows iteration over the NodeList in for statements and proper support for the len() built-in function. If a DOM implementation supports modification of the document, the NodeList implementation must also support the setitem () and delitem () methods. DocumentType Objects Information about the notations and entities declared by a document (including the external subset if the parser uses it and can provide the information) is available from a DocumentType object. The DocumentType for a document is available from the Document object’s doctype attribute; if there is no DOCTYPE declaration for the document, the document’s doctype attribute will be set to None instead of an instance of this interface. DocumentType is a specialization of Node, and adds the following attributes: publicId The public identifier for the external subset of the document type definition. This will be a string or None. systemId The system identifier for the external subset of the document type definition. This will be a URI as a string, or None. internalSubset A string giving the complete internal subset from the document. This does not include the brackets which enclose the subset. If the document has no internal subset, this should be None. name The name of the root element as given in the DOCTYPE declaration, if present. entities This is a NamedNodeMap giving the definitions of external entities. For entity names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no entities are defined. notations This is a NamedNodeMap giving the definitions of notations. For notation names defined more than once, only the first definition is provided (others are ignored as required by the XML recommendation). This may be None if the information is not provided by the parser, or if no notations are defined. Document Objects A Document represents an entire XML document, including its constituent elements, attributes, processing in- structions, comments etc. Remeber that it inherits properties from Node. documentElement The one and only root element of the document. createElement(tagName) Create and return a new element node. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild(). createElementNS(namespaceURI, tagName) Create and return a new element with a namespace. The tagName may have a prefix. The element is not inserted into the document when it is created. You need to explicitly insert it with one of the other methods such as insertBefore() or appendChild(). createTextNode(data) Create and return a text node containing the data passed as a parameter. As with the other creation methods, this one does not insert the node into the tree. 7.2. xml.dom — The Document Object Model 文档对象模式API 19 createComment(data) Create and return a comment node containing the data passed as a parameter. As with the other creation methods, this one does not insert the node into the tree. createProcessingInstruction(target, data) Create and return a processing instruction node containing the target and data passed as parameters. As with the other creation methods, this one does not insert the node into the tree. createAttribute(name) Create and return an attribute node. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance. createAttributeNS(namespaceURI, qualifiedName) Create and return an attribute node with a namespace. The tagName may have a prefix. This method does not associate the attribute node with any particular element. You must use setAttributeNode() on the appropriate Element object to use the newly created attribute instance. getElementsByTagName(tagName) Search for all descendants (direct children, children’s children, etc.) with a particular element type name. getElementsByTagNameNS(namespaceURI, localName) Search for all descendants (direct children, children’s children, etc.) with a particular namespace URI and localname. The localname is the part of the namespace after the prefix. Element Objects Element is a subclass of Node, so inherits all the attributes of that class. tagName The element type name. In a namespace-using document it may have colons in it. The value is a string. getElementsByTagName(tagName) Same as equivalent method in the Document class. getElementsByTagNameNS(tagName) Same as equivalent method in the Document class. getAttribute(attname) Return an attribute value as a string. getAttributeNode(attrname) Return the Attr node for the attribute named by attrname. getAttributeNS(namespaceURI, localName) Return an attribute value as a string, given a namespaceURI and localName. getAttributeNodeNS(namespaceURI, localName) Return an attribute value as a node, given a namespaceURI and localName. removeAttribute(attname) Remove an attribute by name. No exception is raised if there is no matching attribute. removeAttributeNode(oldAttr) Remove and return oldAttr from the attribute list, if present. If oldAttr is not present, NotFoundErr is raised. removeAttributeNS(namespaceURI, localName) Remove an attribute by name. Note that it uses a localName, not a qname. No exception is raised if there is no matching attribute. setAttribute(attname, value) Set an attribute value from a string. setAttributeNode(newAttr) Add a new attibute node to the element, replacing an existing attribute if necessary if the name attribute 20 第七章 7. 互联网资料处理Internet Data Handling matches. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised. setAttributeNodeNS(newAttr) Add a new attibute node to the element, replacing an existing attribute if necessary if the namespaceURI and localName attributes match. If a replacement occurs, the old attribute node will be returned. If newAttr is already in use, InuseAttributeErr will be raised. setAttributeNS(namespaceURI, qname, value) Set an attribute value from a string, given a namespaceURI and a qname. Note that a qname is the whole attribute name. This is different than above. Attr Objects Attr inherits from Node, so inherits all its attributes. name The attribute name. In a namespace-using document it may have colons in it. localName The part of the name following the colon if there is one, else the entire name. This is a read-only attribute. prefix The part of the name preceding the colon if there is one, else the empty string. NamedNodeMap Objects NamedNodeMap does not inherit from Node. length The length of the attribute list. item(index) Return an attribute with a particular index. The order you get the attributes in is arbitrary but will be consistent for the life of a DOM. Each item is an attribute node. Get its value with the value attribbute. There are also experimental methods that give this class more mapping behavior. You can use them or you can use the standardized getAttribute*() family of methods on the Element objects. Comment Objects Comment represents a comment in the XML document. It is a subclass of Node, but cannot have child nodes. data The content of the comment as a string. The attribute contains all characters between the leading , but does not include them. Text and CDATASection Objects The Text interface represents text in the XML document. If the parser and DOM implementation support the DOM’s XML extension, portions of the text enclosed in CDATA marked sections are stored in CDATASection objects. These two interfaces are identical, but provide different values for the nodeType attribute. These interfaces extend the Node interface. They cannot have child nodes. data The content of the text node as a string. Note: The use of a CDATASection node does not indicate that the node represents a complete CDATA marked section, only that the content of the node was part of a CDATA section. A single CDATA section may be represented by more than one node in the document tree. There is no way to determine whether two adjacent CDATASection nodes represent different CDATA marked sections. 7.2. xml.dom — The Document Object Model 文档对象模式API 21 ProcessingInstruction Objects Represents a processing instruction in the XML document; this inherits from the Node interface and cannot have child nodes. target The content of the processing instruction up to the first whitespace character. This is a read-only attribute. data The content of the processing instruction following the first whitespace character. Exceptions New in version 2.1. The DOM Level 2 recommendation defines a single exception, DOMException, and a number of constants that allow applications to determine what sort of error occurred. DOMException instances carry a code attribute that provides the appropriate value for the specific exception. The Python DOM interface provides the constants, but also expands the set of exceptions so that a specific excep- tion exists for each of the exception codes defined by the DOM. The implementations must raise the appropriate specific exception, each of which carries the appropriate value for the code attribute. exception DOMException Base exception class used for all specific DOM exceptions. This exception class cannot be directly instan- tiated. exception DomstringSizeErr Raised when a specified range of text does not fit into a string. This is not known to be used in the Python DOM implementations, but may be received from DOM implementations not written in Python. exception HierarchyRequestErr Raised when an attempt is made to insert a node where the node type is not allowed. exception IndexSizeErr Raised when an index or size parameter to a method is negative or exceeds the allowed values. exception InuseAttributeErr Raised when an attempt is made to insert an Attr node that is already present elsewhere in the document. exception InvalidAccessErr Raised if a parameter or an operation is not supported on the underlying object. exception InvalidCharacterErr This exception is raised when a string parameter contains a character that is not permitted in the context it’s being used in by the XML 1.0 recommendation. For example, attempting to create an Element node with a space in the element type name will cause this error to be raised. exception InvalidModificationErr Raised when an attempt is made to modify the type of a node. exception InvalidStateErr Raised when an attempt is made to use an object that is not or is no longer usable. exception NamespaceErr If an attempt is made to change any object in a way that is not permitted with regard to the Namespaces in XML recommendation, this exception is raised. exception NotFoundErr Exception when a node does not exist in the referenced context. For example, NamedNodeMap.removeNamedItem() will raise this if the node passed in does not exist in the map. exception NotSupportedErr Raised when the implementation does not support the requested type of object or operation. 22 第七章 7. 互联网资料处理Internet Data Handling exception NoDataAllowedErr This is raised if data is specified for a node which does not support data. exception NoModificationAllowedErr Raised on attempts to modify an object where modifications are not allowed (such as for read-only nodes). exception SyntaxErr Raised when an invalid or illegal string is specified. exception WrongDocumentErr Raised when a node is inserted in a different document than it currently belongs to, and the implementation does not support migrating the node from one document to the other. The exception codes defined in the DOM recommendation map to the exceptions described above according to this table: Constant Exception DOMSTRING SIZE ERR DomstringSizeErr HIERARCHY REQUEST ERR HierarchyRequestErr INDEX SIZE ERR IndexSizeErr INUSE ATTRIBUTE ERR InuseAttributeErr INVALID ACCESS ERR InvalidAccessErr INVALID CHARACTER ERR InvalidCharacterErr INVALID MODIFICATION ERR InvalidModificationErr INVALID STATE ERR InvalidStateErr NAMESPACE ERR NamespaceErr NOT FOUND ERR NotFoundErr NOT SUPPORTED ERR NotSupportedErr NO DATA ALLOWED ERR NoDataAllowedErr NO MODIFICATION ALLOWED ERR NoModificationAllowedErr SYNTAX ERR SyntaxErr WRONG DOCUMENT ERR WrongDocumentErr 7.2.3 Conformance This section describes the conformance requirements and relationships between the Python DOM API, the W3C DOM recommendations, and the OMG IDL mapping for Python. Type Mapping The primitive IDL types used in the DOM specification are mapped to Python types according to the following table. IDL Type Python Type boolean IntegerType (with a value of 0 or 1) int IntegerType long int IntegerType unsigned int IntegerType Additionally, the DOMString defined in the recommendation is mapped to a Python string or Unicode string. Applications should be able to handle Unicode whenever a string is returned from the DOM. The IDL null value is mapped to None, which may be accepted or provided by the implementation whenever null is allowed by the API. Accessor Methods The mapping from OMG IDL to Python defines accessor functions for IDL attribute declarations in much the way the Java mapping does. Mapping the IDL declarations 7.2. xml.dom — The Document Object Model 文档对象模式API 23 readonly attribute string someValue; attribute string anotherValue; yields three accessor functions: a “get” method for someValue ( get someValue()), and “get” and “set” methods for anotherValue ( get anotherValue() and set anotherValue()). The mapping, in particular, does not require that the IDL attributes are accessible as normal Python attributes: object.someValue is not required to work, and may raise an AttributeError. The Python DOM API, however, does require that normal attribute access work. This means that the typical surrogates generated by Python IDL compilers are not likely to work, and wrapper objects may be needed on the client if the DOM objects are accessed via CORBA. While this does require some additional consideration for CORBA DOM clients, the implementers with experience using DOM over CORBA from Python do not consider this a problem. Attributes that are declared readonly may not restrict write access in all DOM implementations. Additionally, the accessor functions are not required. If provided, they should take the form defined by the Python IDL mapping, but these methods are considered unnecessary since the attributes are accessible directly from Python. “Set” accessors should never be provided for readonly attributes. 24 第七章 7. 互联网资料处理Internet Data Handling 第第第八八八章章章 多多多媒媒媒体体体服服服务务务 Multimedia Services The modules described in this chapter implement various algorithms or interfaces that are mainly useful for mul- timedia applications. They are available at the discretion of the installation. Here’s an overview: 本章所描述的模组实现了只要用在多媒体应用中遇到的介面及算法。能否调用它们视乎安装Python 时的 选项而定。以下是概述: 25 26 第第第九九九章章章 加加加密密密服服服务务务 Cryptographic Services The modules described in this chapter implement various algorithms of a cryptographic nature. They are available at the discretion of the installation. Here’s an overview: 本章描述的模组实现了具加密性质的不同算法。它们能不能用视安装时的选项而定。以下是概述。 Hardcore cypherpunks will probably find the cryptographic modules written by A.M. Kuchling of further interest; the package adds built-in modules for DES and IDEA encryption, provides a Python module for reading and decrypting PGP files, and then some. These modules are not distributed with Python but available separately. See the URL http://www.amk.ca/python/code/crypto.html for more information. 对加密十分狂热者可以找一找A.M. Kuchling 写的加密模组; 它提供了DES 及IDEA 加密法的内建模组, 提 供了一个Python 模组来读取及解读PGP 档案, 以及别的东西. 这些模组并不包括在Python 的发布中, 但可 以从别处取得到。详情请看http://www.amk.ca/python/code/crypto.html 。 27 28 第第第十十十章章章 Python 语语语言言言服服服务务务 Python Language Services Python provides a number of modules to assist in working with the Python language. These module support tokenizing, parsing, syntax analysis, bytecode disassembly, and various other facilities. Python 有一系列模组,对分析Python 语言本身的工作提供了帮助。这些模组包括标记符的辨识,分词, 字元码的的反编译以及其他的一些辅助工具。 These modules include: 此类模组包括: 29 30 第第第十十十一一一章章章 SGI IRIX 特特特定定定服服服务务务 SGI IRIX Specific Services The modules described in this chapter provide interfaces to features that are unique to SGI’s IRIX operating system (versions 4 and 5). 本章描述的模组为SGI 的IRIX 操作系统(版本4 及5) 提供介面, 存取该系统所独有的一些功能。 al SGI 的音讯功能Audio functions on the SGI. AL al 模组中用到的常数。Constants used with the al module. 11.1 al — SGI 的音讯功能Audio functions on the SGI This module provides access to the audio facilities of the SGI Indy and Indigo workstations. See section 3A of the IRIX man pages for details. You’ll need to read those man pages to understand what these functions do! Some of the functions are not available in IRIX releases before 4.0.5. Again, see the manual to check whether a specific function is available on your platform. 本模组可用来存取SGI Indy 及Indigo 工作站的音讯设备。详细情况可参考IRIX 帮助页的第3A 节。你要 看过了那些帮助页才能明白这几个函数是干什么用的。以下有的函数不能在IRIX 4.0.5 版以前使用。再 说一遍,看相关的手册来检查某个指定的函数是否能用在你的平台上。 All functions and methods defined in this module are equivalent to the C functions with ‘AL’ prefixed to their name. 本模组所定义的所有函数及方法和C 中以‘AL’ 前缀的同名函数是等价的。 Symbolic constants from the C header file are defined in the standard module AL, see below. 在C 标头档 中定义的符号常数定义则被放置到了AL, 看下面。 Warning: The current version of the audio library may dump core when bad argument values are passed rather than returning an error status. Unfortunately, since the precise circumstances under which this may happen are undocumented and hard to check, the Python interface can provide no protection against this kind of problems. (One example is specifying an excessive queue size — there is no documented upper limit.) Warning: 音讯函数库目的的版本当调用时收到不合法的引数时会产生core 档而不会传回错误态。很可 惜的是,因为到底哪种情况才会产生这些错无法在现有的文献中找到而且也很难试出来,所以Python 无 法对这些问题提供保护。(例如:提交一个额外的队列的大小时,没有任何文献提到它的最大上限是多 少。) The module defines the following functions: 本模组提供以下的函数: openport(name, direction[, config]) The name and direction arguments are strings. The optional config argument is a configuration object as 31 returned by newconfig(). The return value is an audio port object; methods of audio port objects are described below. name 及direction 引数皆是字串。可选引数config 则是一个透过调用newconfig() 而得到的配置对 象。函数传回音讯端口对象audio port object: 这个对象包含下面描述的方法。 newconfig() The return value is a new audio configuration object; methods of audio configuration objects are described below. 传回一个新的音讯配置对象audio configuration object: 该对象包含下面描述的方法。 queryparams(device) The device argument is an integer. The return value is a list of integers containing the data returned by ALqueryparams(). device 引数是一个整数。传回一个整数列表,其中包含由ALqueryparams() 传回的数据。 getparams(device, list) The device argument is an integer. The list argument is a list such as returned by queryparams(); it is modified in place (!). device 引数是一个整数。list 引数则是由queryparam() 传回的列表;这个列表会被即场修改 的(!) setparams(device, list) The device argument is an integer. The list argument is a list such as returned by queryparams(). device 引数是一个整数。list 引数则是由queryparam() 传回的列表. 11.1.1 配置对象Configuration Objects Configuration objects returned by newconfig() have the following methods: 配置对象由newconfig() 传回, 它有以下方对: getqueuesize() Return the queue size. 传回队列的大小。 setqueuesize(size) Set the queue size. 设定队列大小。 getwidth() Get the sample width. 获得取样本的宽度。 setwidth(width) Set the sample width. 设定取样的宽度。 getchannels() Get the channel count. 取得频道的数目。 setchannels(nchannels) Set the channel count. 设定频道数目。 getsampfmt() Get the sample format. 取得样本的格式。 setsampfmt(sampfmt) Set the sample format. 设定样本的格式。 getfloatmax() Get the maximum value for floating sample formats. 取得浮点样本格式的最大值。 setfloatmax(floatmax) Set the maximum value for floating sample formats. 设定浮点样本格式的最大值。 32 第十一章 11. SGI IRIX 特定服务SGI IRIX Specific Services 11.1.2 端口对象Port Objects Port objects, as returned by openport(), have the following methods: 端口对象由调用openport() 得到,它有以下方法: closeport() Close the port. 关闭端口。 getfd() Return the file descriptor as an int. 传回描述档案的整数值。 getfilled() Return the number of filled samples. 传回已取得值的样本的数目。 getfillable() Return the number of fillable samples. 传回可以取值的样本的数目。 readsamps(nsamples) Read a number of samples from the queue, blocking if necessary. Return the data as a string containing the raw data, (e.g., 2 bytes per sample in big-endian byte order (high byte, low byte) if you have set the sample width to 2 bytes). 从队列中读取一定数目的样本,以等候态直至读取完毕。传回代表原始数据的字符串,(例如, 如 你设定取样宽度为两个位元的话, 则每个样本以双字元大顺位次序存放(高字元, 低字元)). writesamps(samples) Write samples into the queue, blocking if necessary. The samples are encoded as described for the readsamps() return value. 把样本写到队列中去, 以等候态直至写完。样本的编码方式以readsamps() 函数的传回值所描述 的一样。 getfillpoint() Return the ‘fill point’. 传回”填入点fill point”. setfillpoint(fillpoint) Set the ‘fill point’. 设置“填入点fill point”. getconfig() Return a configuration object containing the current configuration of the port. 传回一个配置对象,其中包含了目前端口的配置。 setconfig(config) Set the configuration from the argument, a configuration object. 用引数,一个配置对象来设置端口。 getstatus(list) Get status information on last error. 取得最近一次错误的状态资料。 11.2 AL — al 模组中用到的常数。Constants used with the al module This module defines symbolic constants needed to use the built-in module al (see above); they are equivalent to those defined in the C header file except that the name prefix ‘AL ’ is omitted. Read the module source for a complete list of the defined names. Suggested use: 此模组定义了使用内建模组al (看上面)时要用到的常量,它们和C 标头档 中所定义的是一 样的,只不过忽略掉了所有的‘AL ’ 前缀。全部常量的定义可以参看源码。建议用法如下: import al from AL import * 11.2. AL — al 模组中用到的常数。Constants used with the al module 33 34 第第第十十十二二二章章章 SunOS 特特特定定定服服服务务务 SunOS Specific Services The modules described in this chapter provide interfaces to features that are unique to the SunOS operating system (versions 4 and 5; the latter is also known as Solaris version 2). 本章所描述的模组提供介面存取SunOX 操作系统所独有的功能。(版本4, 及5; 后者也被称为Solaris Version 2) 35 36 第第第十十十三三三章章章 MS Windows 有有有关关关的的的服服服务务务 MS Windows Services This chapter describes modules that are only available on MS Windows platforms. 本章描述了只存在于MS Windows 平台上的模组. 37 38 附附附录录录 A 翻翻翻译译译团团团队队队 • 杜文山:... • 刘鑫:... • 余颖:... • glace : 后勤 • Leira : . . . • Hackgou : . . . • Zoom.Quiet : . . . 39
还剩44页未读

继续阅读

下载pdf到电脑,查找使用更方便

pdf的实际排版效果,会与网站的显示效果略有不同!!

需要 20 金币 [ 分享pdf获得金币 ] 1 人已下载

下载pdf

pdf贡献者

chenguangwei

贡献于2010-09-10

下载需要 20 金币 [金币充值 ]
亲,您也可以通过 分享原创pdf 来获得金币奖励!
下载pdf