Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Issue #18760: Improved cross-references in the xml package.

This commit is contained in:
Serhiy Storchaka 2013-08-29 10:29:30 +03:00
parent afe890923f 15e6590774
commit a8c2a8aa8d
7 changed files with 67 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
Doc/library/xml.dom.pulldom.rst
View File

@ -74,7 +74,8 @@ and switch to DOM-related processing.
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.

9
Doc/library/xml.dom.rst
View File

@ -422,14 +422,15 @@ objects:
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:

5
Doc/library/xml.etree.elementtree.rst
View File

@ -710,8 +710,9 @@ Element Objects
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

11
Doc/library/xml.sax.handler.rst
View File

@ -237,7 +237,8 @@ events in the input document:
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 @@ events in the input document:
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 @@ ErrorHandler Objects
--------------------
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

31
Doc/library/xml.sax.reader.rst
View File

@ -106,47 +106,50 @@ The :class:`XMLReader` interface supports the following methods:
.. 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 @@ InputSource Objects
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:

35
Doc/library/xml.sax.rst
View File

@ -26,7 +26,8 @@ The convenience functions are:
.. 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 @@ The convenience functions are:
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 @@ For these objects, only the interfaces are relevant; they are normally not
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 @@ classes.
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 @@ classes.
.. 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.

17
Doc/library/xml.sax.utils.rst
View File

@ -52,7 +52,8 @@ or as base classes.
.. 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 @@ or as base classes.
.. 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 @@ or as base classes.
.. 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.