Skip to content

Commit 15e6590

Browse files
serhiy-storchakaserhiy-storchaka
committed
Issue #18760: Improved cross-references in the xml package.
1 parent 3b44a40 commit 15e6590

7 files changed

Lines changed: 67 additions & 44 deletions

File tree

‎Doc/library/xml.dom.pulldom.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,8 @@ and switch to DOM-related processing.
7474

7575
Return a :class:`DOMEventStream` from the given input. *stream_or_string* may be
7676
either a file name, or a file-like object. *parser*, if given, must be a
77-
:class:`XmlReader` object. This function will change the document handler of the
77+
:class:`~xml.sax.xmlreader.XMLReader` object. This function will change the
78+
document handler of the
7879
parser and activate namespace support; other parser configuration (like
7980
setting an entity resolver) must have been done in advance.
8081

‎Doc/library/xml.dom.rst‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -422,14 +422,15 @@ objects:
422422

423423
In addition, the Python DOM interface requires that some additional support is
424424
provided to allow :class:`NodeList` objects to be used as Python sequences. All
425-
:class:`NodeList` implementations must include support for :meth:`__len__` and
426-
:meth:`__getitem__`; this allows iteration over the :class:`NodeList` in
425+
:class:`NodeList` implementations must include support for
426+
:meth:`~object.__len__` and
427+
:meth:`~object.__getitem__`; this allows iteration over the :class:`NodeList` in
427428
:keyword:`for` statements and proper support for the :func:`len` built-in
428429
function.
429430

430431
If a DOM implementation supports modification of the document, the
431-
:class:`NodeList` implementation must also support the :meth:`__setitem__` and
432-
:meth:`__delitem__` methods.
432+
:class:`NodeList` implementation must also support the
433+
:meth:`~object.__setitem__` and :meth:`~object.__delitem__` methods.
433434

434435

435436
.. _dom-documenttype-objects:

‎Doc/library/xml.etree.elementtree.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -664,8 +664,9 @@ Element Objects
664664
or contents.
665665

666666
:class:`Element` objects also support the following sequence type methods
667-
for working with subelements: :meth:`__delitem__`, :meth:`__getitem__`,
668-
:meth:`__setitem__`, :meth:`__len__`.
667+
for working with subelements: :meth:`~object.__delitem__`,
668+
:meth:`~object.__getitem__`, :meth:`~object.__setitem__`,
669+
:meth:`~object.__len__`.
669670

670671
Caution: Elements with no subelements will test as ``False``. This behavior
671672
will change in future versions. Use specific ``len(elem)`` or ``elem is

‎Doc/library/xml.sax.handler.rst‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -237,7 +237,8 @@ events in the input document:
237237
Signals the start of an element in non-namespace mode.
238238

239239
The *name* parameter contains the raw XML 1.0 name of the element type as a
240-
string and the *attrs* parameter holds an object of the :class:`Attributes`
240+
string and the *attrs* parameter holds an object of the
241+
:class:`~xml.sax.xmlreader.Attributes`
241242
interface (see :ref:`attributes-objects`) containing the attributes of
242243
the element. The object passed as *attrs* may be re-used by the parser; holding
243244
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:
260261
The *name* parameter contains the name of the element type as a ``(uri,
261262
localname)`` tuple, the *qname* parameter contains the raw XML 1.0 name used in
262263
the source document, and the *attrs* parameter holds an instance of the
263-
:class:`AttributesNS` interface (see :ref:`attributes-ns-objects`)
264+
:class:`~xml.sax.xmlreader.AttributesNS` interface (see
265+
:ref:`attributes-ns-objects`)
264266
containing the attributes of the element. If no namespace is associated with
265267
the element, the *uri* component of *name* will be ``None``. The object passed
266268
as *attrs* may be re-used by the parser; holding on to a reference to it is not
@@ -376,8 +378,9 @@ ErrorHandler Objects
376378
--------------------
377379

378380
Objects with this interface are used to receive error and warning information
379-
from the :class:`XMLReader`. If you create an object that implements this
380-
interface, then register the object with your :class:`XMLReader`, the parser
381+
from the :class:`~xml.sax.xmlreader.XMLReader`. If you create an object that
382+
implements this interface, then register the object with your
383+
:class:`~xml.sax.xmlreader.XMLReader`, the parser
381384
will call the methods in your object to report all warnings and errors. There
382385
are three levels of errors available: warnings, (possibly) recoverable errors,
383386
and unrecoverable errors. All methods take a :exc:`SAXParseException` as the

‎Doc/library/xml.sax.reader.rst‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -106,47 +106,50 @@ The :class:`XMLReader` interface supports the following methods:
106106

107107
.. method:: XMLReader.getContentHandler()
108108

109-
Return the current :class:`ContentHandler`.
109+
Return the current :class:`~xml.sax.handler.ContentHandler`.
110110

111111

112112
.. method:: XMLReader.setContentHandler(handler)
113113

114-
Set the current :class:`ContentHandler`. If no :class:`ContentHandler` is set,
115-
content events will be discarded.
114+
Set the current :class:`~xml.sax.handler.ContentHandler`. If no
115+
:class:`~xml.sax.handler.ContentHandler` is set, content events will be
116+
discarded.
116117

117118

118119
.. method:: XMLReader.getDTDHandler()
119120

120-
Return the current :class:`DTDHandler`.
121+
Return the current :class:`~xml.sax.handler.DTDHandler`.
121122

122123

123124
.. method:: XMLReader.setDTDHandler(handler)
124125

125-
Set the current :class:`DTDHandler`. If no :class:`DTDHandler` is set, DTD
126+
Set the current :class:`~xml.sax.handler.DTDHandler`. If no
127+
:class:`~xml.sax.handler.DTDHandler` is set, DTD
126128
events will be discarded.
127129

128130

129131
.. method:: XMLReader.getEntityResolver()
130132

131-
Return the current :class:`EntityResolver`.
133+
Return the current :class:`~xml.sax.handler.EntityResolver`.
132134

133135

134136
.. method:: XMLReader.setEntityResolver(handler)
135137

136-
Set the current :class:`EntityResolver`. If no :class:`EntityResolver` is set,
138+
Set the current :class:`~xml.sax.handler.EntityResolver`. If no
139+
:class:`~xml.sax.handler.EntityResolver` is set,
137140
attempts to resolve an external entity will result in opening the system
138141
identifier for the entity, and fail if it is not available.
139142

140143

141144
.. method:: XMLReader.getErrorHandler()
142145

143-
Return the current :class:`ErrorHandler`.
146+
Return the current :class:`~xml.sax.handler.ErrorHandler`.
144147

145148

146149
.. method:: XMLReader.setErrorHandler(handler)
147150

148-
Set the current error handler. If no :class:`ErrorHandler` is set, errors will
149-
be raised as exceptions, and warnings will be printed.
151+
Set the current error handler. If no :class:`~xml.sax.handler.ErrorHandler`
152+
is set, errors will be raised as exceptions, and warnings will be printed.
150153

151154

152155
.. method:: XMLReader.setLocale(locale)
@@ -322,9 +325,11 @@ InputSource Objects
322325
The :class:`Attributes` Interface
323326
---------------------------------
324327

325-
:class:`Attributes` objects implement a portion of the mapping protocol,
326-
including the methods :meth:`copy`, :meth:`get`, :meth:`__contains__`,
327-
:meth:`items`, :meth:`keys`, and :meth:`values`. The following methods
328+
:class:`Attributes` objects implement a portion of the :term:`mapping protocol
329+
<mapping>`, including the methods :meth:`~collections.abc.Mapping.copy`,
330+
:meth:`~collections.abc.Mapping.get`, :meth:`~object.__contains__`,
331+
:meth:`~collections.abc.Mapping.items`, :meth:`~collections.abc.Mapping.keys`,
332+
and :meth:`~collections.abc.Mapping.values`. The following methods
328333
are also provided:
329334

330335

‎Doc/library/xml.sax.rst‎

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,8 @@ The convenience functions are:
2626

2727
.. function:: make_parser(parser_list=[])
2828

29-
Create and return a SAX :class:`XMLReader` object. The first parser found will
29+
Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object. The
30+
first parser found will
3031
be used. If *parser_list* is provided, it must be a sequence of strings which
3132
name modules that have a function named :func:`create_parser`. Modules listed
3233
in *parser_list* will be used before modules in the default list of parsers.
@@ -36,8 +37,9 @@ The convenience functions are:
3637

3738
Create a SAX parser and use it to parse a document. The document, passed in as
3839
*filename_or_stream*, can be a filename or a file object. The *handler*
39-
parameter needs to be a SAX :class:`ContentHandler` instance. If
40-
*error_handler* is given, it must be a SAX :class:`ErrorHandler` instance; if
40+
parameter needs to be a SAX :class:`~handler.ContentHandler` instance. If
41+
*error_handler* is given, it must be a SAX :class:`~handler.ErrorHandler`
42+
instance; if
4143
omitted, :exc:`SAXParseException` will be raised on all errors. There is no
4244
return value; all work must be done by the *handler* passed in.
4345

@@ -62,10 +64,12 @@ For these objects, only the interfaces are relevant; they are normally not
6264
instantiated by the application itself. Since Python does not have an explicit
6365
notion of interface, they are formally introduced as classes, but applications
6466
may use implementations which do not inherit from the provided classes. The
65-
:class:`InputSource`, :class:`Locator`, :class:`Attributes`,
66-
:class:`AttributesNS`, and :class:`XMLReader` interfaces are defined in the
67+
:class:`~xml.sax.xmlreader.InputSource`, :class:`~xml.sax.xmlreader.Locator`,
68+
:class:`~xml.sax.xmlreader.Attributes`, :class:`~xml.sax.xmlreader.AttributesNS`,
69+
and :class:`~xml.sax.xmlreader.XMLReader` interfaces are defined in the
6770
module :mod:`xml.sax.xmlreader`. The handler interfaces are defined in
68-
:mod:`xml.sax.handler`. For convenience, :class:`InputSource` (which is often
71+
:mod:`xml.sax.handler`. For convenience,
72+
:class:`~xml.sax.xmlreader.InputSource` (which is often
6973
instantiated directly) and the handler classes are also available from
7074
:mod:`xml.sax`. These interfaces are described below.
7175

@@ -78,7 +82,8 @@ classes.
7882
Encapsulate an XML error or warning. This class can contain basic error or
7983
warning information from either the XML parser or the application: it can be
8084
subclassed to provide additional functionality or to add localization. Note
81-
that although the handlers defined in the :class:`ErrorHandler` interface
85+
that although the handlers defined in the
86+
:class:`~xml.sax.handler.ErrorHandler` interface
8287
receive instances of this exception, it is not required to actually raise the
8388
exception --- it is also useful as a container for information.
8489

@@ -91,22 +96,26 @@ classes.
9196

9297
.. exception:: SAXParseException(msg, exception, locator)
9398

94-
Subclass of :exc:`SAXException` raised on parse errors. Instances of this class
95-
are passed to the methods of the SAX :class:`ErrorHandler` interface to provide
96-
information about the parse error. This class supports the SAX :class:`Locator`
97-
interface as well as the :class:`SAXException` interface.
99+
Subclass of :exc:`SAXException` raised on parse errors. Instances of this
100+
class are passed to the methods of the SAX
101+
:class:`~xml.sax.handler.ErrorHandler` interface to provide information
102+
about the parse error. This class supports the SAX
103+
:class:`~xml.sax.xmlreader.Locator` interface as well as the
104+
:class:`SAXException` interface.
98105

99106

100107
.. exception:: SAXNotRecognizedException(msg, exception=None)
101108

102-
Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is
109+
Subclass of :exc:`SAXException` raised when a SAX
110+
:class:`~xml.sax.xmlreader.XMLReader` is
103111
confronted with an unrecognized feature or property. SAX applications and
104112
extensions may use this class for similar purposes.
105113

106114

107115
.. exception:: SAXNotSupportedException(msg, exception=None)
108116

109-
Subclass of :exc:`SAXException` raised when a SAX :class:`XMLReader` is asked to
117+
Subclass of :exc:`SAXException` raised when a SAX
118+
:class:`~xml.sax.xmlreader.XMLReader` is asked to
110119
enable a feature that is not supported, or to set a property to a value that the
111120
implementation does not support. SAX applications and extensions may use this
112121
class for similar purposes.

‎Doc/library/xml.sax.utils.rst‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,8 @@ or as base classes.
5252

5353
.. class:: XMLGenerator(out=None, encoding='iso-8859-1', short_empty_elements=False)
5454

55-
This class implements the :class:`ContentHandler` interface by writing SAX
55+
This class implements the :class:`~xml.sax.handler.ContentHandler` interface
56+
by writing SAX
5657
events back into an XML document. In other words, using an :class:`XMLGenerator`
5758
as the content handler will reproduce the original document being parsed. *out*
5859
should be a file-like object which will default to *sys.stdout*. *encoding* is
@@ -67,7 +68,8 @@ or as base classes.
6768

6869
.. class:: XMLFilterBase(base)
6970

70-
This class is designed to sit between an :class:`XMLReader` and the client
71+
This class is designed to sit between an
72+
:class:`~xml.sax.xmlreader.XMLReader` and the client
7173
application's event handlers. By default, it does nothing but pass requests up
7274
to the reader and events on to the handlers unmodified, but subclasses can
7375
override specific methods to modify the event stream or the configuration
@@ -76,9 +78,10 @@ or as base classes.
7678

7779
.. function:: prepare_input_source(source, base='')
7880

79-
This function takes an input source and an optional base URL and returns a fully
80-
resolved :class:`InputSource` object ready for reading. The input source can be
81-
given as a string, a file-like object, or an :class:`InputSource` object;
82-
parsers will use this function to implement the polymorphic *source* argument to
83-
their :meth:`parse` method.
81+
This function takes an input source and an optional base URL and returns a
82+
fully resolved :class:`~xml.sax.xmlreader.InputSource` object ready for
83+
reading. The input source can be given as a string, a file-like object, or
84+
an :class:`~xml.sax.xmlreader.InputSource` object; parsers will use this
85+
function to implement the polymorphic *source* argument to their
86+
:meth:`parse` method.
8487

0 commit comments

Comments
 (0)