Add more links to the "See also" section for the xml.sax package.
Talk about interfaces rather than implementation classes where appropriate.
Add hyperlinks to make the documentation on the Attributes and AttributesNS
interfaces more discoverable.
Closes SF bug #484603.
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{AttributesImpl}, \class{AttributesNSImpl}, and
+\class{Attributes}, \class{AttributesNS}, and
\class{XMLReader} interfaces are defined in the module
\refmodule{xml.sax.xmlreader}. The handler interfaces are defined in
\refmodule{xml.sax.handler}. For convenience, \class{InputSource}
the SAX API. It provides a Java implementation and online
documentation. Links to implementations and historical
information are also available.}
+
+ \seemodule{xml.sax.handler}{Definitions of the interfaces for
+ application-provided objects.}
+
+ \seemodule{xml.sax.saxutils}{Convenience functions for use in SAX
+ applications.}
+
+ \seemodule{xml.sax.xmlreader}{Definitions of the interfaces for
+ parser-provided objects.}
\end{seealso}
There are cases, however, when applications need to use prefixes in
character data or in attribute values, where they cannot safely be
- expanded automatically; the start/endPrefixMapping event supplies
- the information to the application to expand prefixes in those
- contexts itself, if necessary.
+ expanded automatically; the \method{startPrefixMapping()} and
+ \method{endPrefixMapping()} events supply the information to the
+ application to expand prefixes in those contexts itself, if
+ necessary.
- Note that start/endPrefixMapping events are not guaranteed to be
- properly nested relative to each-other: all
- \method{startPrefixMapping()} events will occur before the
- corresponding \method{startElement()} event, and all
- \method{endPrefixMapping()} events will occur after the
- corresponding \method{endElement()} event, but their order is not
- guaranteed.
+ Note that \method{startPrefixMapping()} and
+ \method{endPrefixMapping()} events are not guaranteed to be properly
+ nested relative to each-other: all \method{startPrefixMapping()}
+ events will occur before the corresponding \method{startElement()}
+ event, and all \method{endPrefixMapping()} events will occur after
+ the corresponding \method{endElement()} event, but their order is
+ not guaranteed.
\end{methoddesc}
\begin{methoddesc}[ContentHandler]{endPrefixMapping}{prefix}
End the scope of a prefix-URI mapping.
-
- See \method{startPrefixMapping()} for details. This event will always
- occur after the corresponding endElement event, but the order of
- endPrefixMapping events is not otherwise guaranteed.
+
+ See \method{startPrefixMapping()} for details. This event will
+ always occur after the corresponding \method{endElement()} event,
+ but the order of \method{endPrefixMapping()} events is not otherwise
+ guaranteed.
\end{methoddesc}
\begin{methoddesc}[ContentHandler]{startElement}{name, attrs}
The \var{name} parameter contains the raw XML 1.0 name of the
element type as a string and the \var{attrs} parameter holds an
- instance of the \class{Attributes} class containing the attributes
- of the element. The object passed as \var{attrs} may be re-used by
- the parser; holding on to a reference to it is not a reliable way to
+ object of the \ulink{\class{Attributes}
+ interface}{attributes-objects.html} containing the attributes of the
+ element. The object passed as \var{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. To keep a copy of the attributes,
use the \method{copy()} method of the \var{attrs} object.
\end{methoddesc}
Signals the end of an element in non-namespace mode.
The \var{name} parameter contains the name of the element type, just
- as with the startElement event.
+ as with the \method{startElement()} event.
\end{methoddesc}
\begin{methoddesc}[ContentHandler]{startElementNS}{name, qname, attrs}
The \var{name} parameter contains the name of the element type as a
\code{(\var{uri}, \var{localname})} tuple, the \var{qname} parameter
contains the raw XML 1.0 name used in the source document, and the
- \var{attrs} parameter holds an instance of the \class{AttributesNS}
- class containing the attributes of the element. If no namespace is
+ \var{attrs} parameter holds an instance of the
+ \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
+ containing the attributes of the element. If no namespace is
associated with the element, the \var{uri} component of \var{name}
will be \code{None}. The object passed as \var{attrs} may be
re-used by the parser; holding on to a reference to it is not a
\end{classdesc}
\begin{classdesc}{AttributesImpl}{attrs}
- This is a dictionary-like object which represents the element
- attributes in a \method{startElement()} call. In addition to the
- most useful dictionary operations, it supports a number of other
- methods as described below. Objects of this class should be
+ This is an implementation of the \ulink{\class{Attributes}
+ interface}{attributes-objects.html} (see
+ section~\ref{attributes-objects}). This is a dictionary-like
+ object which represents the element attributes in a
+ \method{startElement()} call. In addition to the most useful
+ dictionary operations, it supports a number of other methods as
+ described by the interface. Objects of this class should be
instantiated by readers; \var{attrs} must be a dictionary-like
- object.
+ object containing a mapping from attribute names to attribute
+ values.
\end{classdesc}
\begin{classdesc}{AttributesNSImpl}{attrs, qnames}
- Namespace-aware variant of attributes, which will be passed to
- \method{startElementNS()}. It is derived from \class{AttributesImpl},
- but understands attribute names as two-tuples of \var{namespaceURI}
- and \var{localname}. In addition, it provides a number of methods
- expecting qualified names as they appear in the original document.
+ Namespace-aware variant of \class{AttributesImpl}, which will be
+ passed to \method{startElementNS()}. It is derived from
+ \class{AttributesImpl}, but understands attribute names as
+ two-tuples of \var{namespaceURI} and \var{localname}. In addition,
+ it provides a number of methods expecting qualified names as they
+ appear in the original document. This class implements the
+ \ulink{\class{AttributesNS} interface}{attributes-ns-objects.html}
+ (see section~\ref{attributes-ns-objects}).
\end{classdesc}
\end{methoddesc}
-\subsection{AttributesImpl Objects \label{attributes-impl-objects}}
+\subsection{The \class{Attributes} Interface \label{attributes-objects}}
-\class{AttributesImpl} objects implement a portion of the mapping
-protocol, and the methods \method{copy()}, \method{get()},
+\class{Attributes} objects implement a portion of the mapping
+protocol, including the methods \method{copy()}, \method{get()},
\method{has_key()}, \method{items()}, \method{keys()}, and
\method{values()}. The following methods are also provided:
-\begin{methoddesc}[AttributesImpl]{getLength}{}
+\begin{methoddesc}[Attributes]{getLength}{}
Return the number of attributes.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getNames}{}
+\begin{methoddesc}[Attributes]{getNames}{}
Return the names of the attributes.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getType}{name}
+\begin{methoddesc}[Attributes]{getType}{name}
Returns the type of the attribute \var{name}, which is normally
\code{'CDATA'}.
\end{methoddesc}
-\begin{methoddesc}[AttributesImpl]{getValue}{name}
+\begin{methoddesc}[Attributes]{getValue}{name}
Return the value of attribute \var{name}.
\end{methoddesc}
% here already, but documented only for derived class.
-\subsection{AttributesNSImpl Objects \label{attributes-ns-impl-objects}}
+\subsection{The \class{AttributesNS} Interface \label{attributes-ns-objects}}
-\begin{methoddesc}[AttributesNSImpl]{getValueByQName}{name}
+This interface is a subtype of the \ulink{\class{Attributes}
+interface}{attributes-objects.html} (see
+section~\ref{attributes-objects}). All methods supported by that
+interface are also available on \class{AttributesNS} objects.
+
+The following methods are also available:
+
+\begin{methoddesc}[AttributesNS]{getValueByQName}{name}
Return the value for a qualified name.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getNameByQName}{name}
+\begin{methoddesc}[AttributesNS]{getNameByQName}{name}
Return the \code{(\var{namespace}, \var{localname})} pair for a
qualified \var{name}.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getQNameByName}{name}
+\begin{methoddesc}[AttributesNS]{getQNameByName}{name}
Return the qualified name for a \code{(\var{namespace},
\var{localname})} pair.
\end{methoddesc}
-\begin{methoddesc}[AttributesNSImpl]{getQNames}{}
+\begin{methoddesc}[AttributesNS]{getQNames}{}
Return the qualified names of all attributes.
\end{methoddesc}
projects / thirdparty / Python / cpython.git / commitdiff
