[Python-checkins] cpython (3.3): Issue #18760: Improved cross-references in the xml package.
serhiy.storchaka
python-checkins at python.org
Thu Aug 29 09:36:12 CEST 2013
http://hg.python.org/cpython/rev/a426e5c03d6e
changeset: 85438:a426e5c03d6e
branch: 3.3
parent: 85428:84debb4abd50
user: Serhiy Storchaka <storchaka at gmail.com>
date: Thu Aug 29 10:28:44 2013 +0300
summary:
Issue #18760: Improved cross-references in the xml package.
files:
Doc/library/xml.dom.pulldom.rst | 3 +-
Doc/library/xml.dom.rst | 9 ++-
Doc/library/xml.etree.elementtree.rst | 5 +-
Doc/library/xml.sax.handler.rst | 11 +++-
Doc/library/xml.sax.reader.rst | 31 +++++++-----
Doc/library/xml.sax.rst | 35 +++++++++-----
Doc/library/xml.sax.utils.rst | 17 ++++---
7 files changed, 67 insertions(+), 44 deletions(-)
diff --git a/Doc/library/xml.dom.pulldom.rst b/Doc/library/xml.dom.pulldom.rst
--- a/Doc/library/xml.dom.pulldom.rst
+++ b/Doc/library/xml.dom.pulldom.rst
@@ -74,7 +74,8 @@
Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be
either a file name, or a file-like object. *parser*, if given, must be a
- :class:`XmlReader` object. This function will change the document handler of the
+ :class:`~xml.sax.xmlreader.XMLReader` object. This function will change the
+ document handler of the
parser and activate namespace support; other parser configuration (like
setting an entity resolver) must have been done in advance.
diff --git a/Doc/library/xml.dom.rst b/Doc/library/xml.dom.rst
--- a/Doc/library/xml.dom.rst
+++ b/Doc/library/xml.dom.rst
@@ -422,14 +422,15 @@
In addition, the Python DOM interface requires that some additional support is
provided to allow :class:`NodeList` objects to be used as Python sequences. All
-:class:`NodeList` implementations must include support for :meth:`__len__` and
-:meth:`__getitem__`; this allows iteration over the :class:`NodeList` in
+:class:`NodeList` implementations must include support for
+:meth:`~object.__len__` and
+:meth:`~object.__getitem__`; this allows iteration over the :class:`NodeList` in
:keyword:`for` statements and proper support for the :func:`len` built-in
function.
If a DOM implementation supports modification of the document, the
-:class:`NodeList` implementation must also support the :meth:`__setitem__` and
-:meth:`__delitem__` methods.
+:class:`NodeList` implementation must also support the
+:meth:`~object.__setitem__` and :meth:`~object.__delitem__` methods.
.. _dom-documenttype-objects:
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -664,8 +664,9 @@
or contents.
:class:`Element` objects also support the following sequence type methods
- for working with subelements: :meth:`__delitem__`, :meth:`__getitem__`,
- :meth:`__setitem__`, :meth:`__len__`.
+ for working with subelements: :meth:`~object.__delitem__`,
+ :meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
+ :meth:`~object.__len__`.
Caution: Elements with no subelements will test as ``False``. This behavior
will change in future versions. Use specific ``len(elem)`` or ``elem is
diff --git a/Doc/library/xml.sax.handler.rst b/Doc/library/xml.sax.handler.rst
--- a/Doc/library/xml.sax.handler.rst
+++ b/Doc/library/xml.sax.handler.rst
@@ -237,7 +237,8 @@
Signals the start of an element in non-namespace mode.
The *name* parameter contains the raw XML 1.0 name of the element type as a
- string and the *attrs* parameter holds an object of the :class:`Attributes`
+ string and the *attrs* parameter holds an object of the
+ :class:`~xml.sax.xmlreader.Attributes`
interface (see :ref:`attributes-objects`) containing the attributes of
the element. The object passed as *attrs* may be re-used by the parser; holding
on to a reference to it is not a reliable way to keep a copy of the attributes.
@@ -260,7 +261,8 @@
The *name* parameter contains the name of the element type as a ``(uri,
localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in
the source document, and the *attrs* parameter holds an instance of the
- :class:`AttributesNS` interface (see :ref:`attributes-ns-objects`)
+ :class:`~xml.sax.xmlreader.AttributesNS` interface (see
+ :ref:`attributes-ns-objects`)
containing the attributes of the element. If no namespace is associated with
the element, the *uri* component of *name* will be ``None``. The object passed
as *attrs* may be re-used by the parser; holding on to a reference to it is not
@@ -376,8 +378,9 @@
--------------------
Objects with this interface are used to receive error and warning information
-from the :class:`XMLReader`. If you create an object that implements this
-interface, then register the object with your :class:`XMLReader`, the parser
+from the :class:`~xml.sax.xmlreader.XMLReader`. If you create an object that
+implements this interface, then register the object with your
+:class:`~xml.sax.xmlreader.XMLReader`, the parser
will call the methods in your object to report all warnings and errors. There
are three levels of errors available: warnings, (possibly) recoverable errors,
and unrecoverable errors. All methods take a :exc:`SAXParseException` as the
diff --git a/Doc/library/xml.sax.reader.rst b/Doc/library/xml.sax.reader.rst
--- a/Doc/library/xml.sax.reader.rst
+++ b/Doc/library/xml.sax.reader.rst
@@ -106,47 +106,50 @@
.. method:: XMLReader.getContentHandler()
- Return the current :class:`ContentHandler`.
+ Return the current :class:`~xml.sax.handler.ContentHandler`.
.. method:: XMLReader.setContentHandler(handler)
- Set the current :class:`ContentHandler`. If no :class:`ContentHandler` is set,
- content events will be discarded.
+ Set the current :class:`~xml.sax.handler.ContentHandler`. If no
+ :class:`~xml.sax.handler.ContentHandler` is set, content events will be
+ discarded.
.. method:: XMLReader.getDTDHandler()
- Return the current :class:`DTDHandler`.
+ Return the current :class:`~xml.sax.handler.DTDHandler`.
.. method:: XMLReader.setDTDHandler(handler)
- Set the current :class:`DTDHandler`. If no :class:`DTDHandler` is set, DTD
+ Set the current :class:`~xml.sax.handler.DTDHandler`. If no
+ :class:`~xml.sax.handler.DTDHandler` is set, DTD
events will be discarded.
.. method:: XMLReader.getEntityResolver()
- Return the current :class:`EntityResolver`.
+ Return the current :class:`~xml.sax.handler.EntityResolver`.
.. method:: XMLReader.setEntityResolver(handler)
- Set the current :class:`EntityResolver`. If no :class:`EntityResolver` is set,
+ Set the current :class:`~xml.sax.handler.EntityResolver`. If no
+ :class:`~xml.sax.handler.EntityResolver` is set,
attempts to resolve an external entity will result in opening the system
identifier for the entity, and fail if it is not available.
.. method:: XMLReader.getErrorHandler()
- Return the current :class:`ErrorHandler`.
+ Return the current :class:`~xml.sax.handler.ErrorHandler`.
.. method:: XMLReader.setErrorHandler(handler)
- Set the current error handler. If no :class:`ErrorHandler` is set, errors will
- be raised as exceptions, and warnings will be printed.
+ Set the current error handler. If no :class:`~xml.sax.handler.ErrorHandler`
+ is set, errors will be raised as exceptions, and warnings will be printed.
.. method:: XMLReader.setLocale(locale)
@@ -322,9 +325,11 @@
The :class:`Attributes` Interface
---------------------------------
-:class:`Attributes` objects implement a portion of the mapping protocol,
-including the methods :meth:`copy`, :meth:`get`, :meth:`__contains__`,
-:meth:`items`, :meth:`keys`, and :meth:`values`. The following methods
+:class:`Attributes` objects implement a portion of the :term:`mapping protocol
+<mapping>`, including the methods :meth:`~collections.abc.Mapping.copy`,
+:meth:`~collections.abc.Mapping.get`, :meth:`~object.__contains__`,
+:meth:`~collections.abc.Mapping.items`, :meth:`~collections.abc.Mapping.keys`,
+and :meth:`~collections.abc.Mapping.values`. The following methods
are also provided:
diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst
--- a/Doc/library/xml.sax.rst
+++ b/Doc/library/xml.sax.rst
@@ -26,7 +26,8 @@
.. function:: make_parser(parser_list=[])
- Create and return a SAX :class:`XMLReader` object. The first parser found will
+ Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object. The
+ first parser found will
be used. If *parser_list* is provided, it must be a sequence of strings which
name modules that have a function named :func:`create_parser`. Modules listed
in *parser_list* will be used before modules in the default list of parsers.
@@ -36,8 +37,9 @@
Create a SAX parser and use it to parse a document. The document, passed in as
*filename_or_stream*, can be a filename or a file object. The *handler*
- parameter needs to be a SAX :class:`ContentHandler` instance. If
- *error_handler* is given, it must be a SAX :class:`ErrorHandler` instance; if
+ parameter needs to be a SAX :class:`~handler.ContentHandler` instance. If
+ *error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler`
+ instance; if
omitted, :exc:`SAXParseException` will be raised on all errors. There is no
return value; all work must be done by the *handler* passed in.
@@ -62,10 +64,12 @@
instantiated by the application itself. Since Python does not have an explicit
notion of interface, they are formally introduced as classes, but applications
may use implementations which do not inherit from the provided classes. The
-:class:`InputSource`, :class:`Locator`, :class:`Attributes`,
-:class:`AttributesNS`, and :class:`XMLReader` interfaces are defined in the
+:class:`~xml.sax.xmlreader.InputSource`, :class:`~xml.sax.xmlreader.Locator`,
+:class:`~xml.sax.xmlreader.Attributes`, :class:`~xml.sax.xmlreader.AttributesNS`,
+and :class:`~xml.sax.xmlreader.XMLReader` interfaces are defined in the
module :mod:`xml.sax.xmlreader`. The handler interfaces are defined in
-:mod:`xml.sax.handler`. For convenience, :class:`InputSource` (which is often
+:mod:`xml.sax.handler`. For convenience,
+:class:`~xml.sax.xmlreader.InputSource` (which is often
instantiated directly) and the handler classes are also available from
:mod:`xml.sax`. These interfaces are described below.
@@ -78,7 +82,8 @@
Encapsulate an XML error or warning. This class can contain basic error or
warning information from either the XML parser or the application: it can be
subclassed to provide additional functionality or to add localization. Note
- that although the handlers defined in the :class:`ErrorHandler` interface
+ that although the handlers defined in the
+ :class:`~xml.sax.handler.ErrorHandler` interface
receive instances of this exception, it is not required to actually raise the
exception --- it is also useful as a container for information.
@@ -91,22 +96,26 @@
.. exception:: SAXParseException(msg, exception, locator)
- Subclass of :exc:`SAXException` raised on parse errors. Instances of this class
- are passed to the methods of the SAX :class:`ErrorHandler` interface to provide
- information about the parse error. This class supports the SAX :class:`Locator`
- interface as well as the :class:`SAXException` interface.
+ Subclass of :exc:`SAXException` raised on parse errors. Instances of this
+ class are passed to the methods of the SAX
+ :class:`~xml.sax.handler.ErrorHandler` interface to provide information
+ about the parse error. This class supports the SAX
+ :class:`~xml.sax.xmlreader.Locator` interface as well as the
+ :class:`SAXException` interface.
.. exception:: SAXNotRecognizedException(msg, exception=None)
- Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is
+ Subclass of :exc:`SAXException` raised when a SAX
+ :class:`~xml.sax.xmlreader.XMLReader` is
confronted with an unrecognized feature or property. SAX applications and
extensions may use this class for similar purposes.
.. exception:: SAXNotSupportedException(msg, exception=None)
- Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is asked to
+ Subclass of :exc:`SAXException` raised when a SAX
+ :class:`~xml.sax.xmlreader.XMLReader` is asked to
enable a feature that is not supported, or to set a property to a value that the
implementation does not support. SAX applications and extensions may use this
class for similar purposes.
diff --git a/Doc/library/xml.sax.utils.rst b/Doc/library/xml.sax.utils.rst
--- a/Doc/library/xml.sax.utils.rst
+++ b/Doc/library/xml.sax.utils.rst
@@ -52,7 +52,8 @@
.. class:: XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)
- This class implements the :class:`ContentHandler` interface by writing SAX
+ This class implements the :class:`~xml.sax.handler.ContentHandler` interface
+ by writing SAX
events back into an XML document. In other words, using an :class:`XMLGenerator`
as the content handler will reproduce the original document being parsed. *out*
should be a file-like object which will default to *sys.stdout*. *encoding* is
@@ -67,7 +68,8 @@
.. class:: XMLFilterBase(base)
- This class is designed to sit between an :class:`XMLReader` and the client
+ This class is designed to sit between an
+ :class:`~xml.sax.xmlreader.XMLReader` and the client
application's event handlers. By default, it does nothing but pass requests up
to the reader and events on to the handlers unmodified, but subclasses can
override specific methods to modify the event stream or the configuration
@@ -76,9 +78,10 @@
.. function:: prepare_input_source(source, base='')
- This function takes an input source and an optional base URL and returns a fully
- resolved :class:`InputSource` object ready for reading. The input source can be
- given as a string, a file-like object, or an :class:`InputSource` object;
- parsers will use this function to implement the polymorphic *source* argument to
- their :meth:`parse` method.
+ This function takes an input source and an optional base URL and returns a
+ fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for
+ reading. The input source can be given as a string, a file-like object, or
+ an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this
+ function to implement the polymorphic *source* argument to their
+ :meth:`parse` method.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list