[Python-checkins] CVS: python/dist/src/Doc/lib xmldom.tex,1.4,1.5

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv15429/lib

Modified Files:
	xmldom.tex 
Log Message:

Added descriptions of the defined exceptions and their mapping to the
DOM recommendation.


Index: xmldom.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/xmldom.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** xmldom.tex	2000/12/08 06:54:51	1.4
--- xmldom.tex	2000/12/13 17:38:02	1.5
***************
*** 120,124 ****
--- 120,127 ----
  \end{tableiii}
  
+ An additional section describes the exceptions defined for working
+ with the DOM in Python.
  
+ 
  \subsubsection{DOMImplementation Objects
                 \label{dom-implementation-objects}}
***************
*** 593,596 ****
--- 596,725 ----
  whitespace character.
  \end{memberdesc}
+ 
+ 
+ \subsubsection{Exceptions \label{dom-exceptions}}
+ 
+ \versionadded{2.1}
+ 
+ The DOM Level 2 recommendation defines a single exception,
+ \exception{DOMException}, and a number of constants that allow
+ applications to determine what sort of error occurred.
+ \exception{DOMException} instances carry a \member{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 exception 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 \member{code} attribute.
+ 
+ \begin{excdesc}{DOMException}
+   Base exception class used for all specific DOM exceptions.  This
+   exception class cannot be directly instantiated.
+ \end{excdesc}
+ 
+ \begin{excdesc}{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.
+ \end{excdesc}
+ 
+ \begin{excdesc}{HierarchyRequestErr}
+   Raised when an attempt is made to insert a node where the node type
+   is not allowed.
+ \end{excdesc}
+ 
+ \begin{excdesc}{IndexSizeErr}
+   Raised when an index or size parameter to a method is negative or
+   exceeds the allowed values.
+ \end{excdesc}
+ 
+ \begin{excdesc}{InuseAttributeErr}
+   Raised when an attempt is made to insert an \class{Attr} node that
+   is already present elsewhere in the document.
+ \end{excdesc}
+ 
+ \begin{excdesc}{InvalidAccessErr}
+   Raised if a parameter or an operation is not supported on the
+   underlying object.
+ \end{excdesc}
+ 
+ \begin{excdesc}{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
+   \class{Element} node with a space in the element type name will
+   cause this error to be raised.
+ \end{excdesc}
+ 
+ \begin{excdesc}{InvalidModificationErr}
+   Raised when an attempt is made to modify the type of a node.
+ \end{excdesc}
+ 
+ \begin{excdesc}{InvalidStateErr}
+   Raised when an attempt is made to use an object that is not or is no
+   longer usable.
+ \end{excdesc}
+ 
+ \begin{excdesc}{NamespaceErr}
+   If an attempt is made to change any object in a way that is not
+   permitted with regard to the
+   \citetitle[http://www.w3.org/TR/REC-xml-names/]{Namespaces in XML}
+   recommendation, this exception is raised.
+ \end{excdesc}
+ 
+ \begin{excdesc}{NotFoundErr}
+   Exception when a node does not exist in the referenced context.  For
+   example, \method{NamedNodeMap.removeNamedItem()} will raise this if
+   the node passed in does not exist in the map.
+ \end{excdesc}
+ 
+ \begin{excdesc}{NotSupportedErr}
+   Raised when the implementation does not support the requested type
+   of object or operation.
+ \end{excdesc}
+ 
+ \begin{excdesc}{NoDataAllowedErr}
+   This is raised if data is specified for a node which does not
+   support data.
+   % XXX  a better explanation is needed!
+ \end{excdesc}
+ 
+ \begin{excdesc}{NoModificationAllowedErr}
+   Raised on attempts to modify an object where modifications are not
+   allowed (such as for read-only nodes).
+ \end{excdesc}
+ 
+ \begin{excdesc}{SyntaxErr}
+   Raised when an invalid or illegal string is specified.
+   % XXX  how is this different from InvalidCharacterErr ???
+ \end{excdesc}
+ 
+ \begin{excdesc}{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.
+ \end{excdesc}
+ 
+ The exception codes defined in the DOM recommendation map to the
+ exceptions described above according to this table:
+ 
+ \begin{tableii}{l|l}{constant}{Constant}{Exception}
+   \lineii{DOMSTRING_SIZE_ERR}{\exception{DomstringSizeErr}}
+   \lineii{HIERARCHY_REQUEST_ERR}{\exception{HierarchyRequestErr}}
+   \lineii{INDEX_SIZE_ERR}{\exception{IndexSizeErr}}
+   \lineii{INUSE_ATTRIBUTE_ERR}{\exception{InuseAttributeErr}}
+   \lineii{INVALID_ACCESS_ERR}{\exception{InvalidAccessErr}}
+   \lineii{INVALID_CHARACTER_ERR}{\exception{InvalidCharacterErr}}
+   \lineii{INVALID_MODIFICATION_ERR}{\exception{InvalidModificationErr}}
+   \lineii{INVALID_STATE_ERR}{\exception{InvalidStateErr}}
+   \lineii{NAMESPACE_ERR}{\exception{NamespaceErr}}
+   \lineii{NOT_FOUND_ERR}{\exception{NotFoundErr}}
+   \lineii{NOT_SUPPORTED_ERR}{\exception{NotSupportedErr}}
+   \lineii{NO_DATA_ALLOWED_ERR}{\exception{NoDataAllowedErr}}
+   \lineii{NO_MODIFICATION_ALLOWED_ERR}{\exception{NoModificationAllowedErr}}
+   \lineii{SYNTAX_ERR}{\exception{SyntaxErr}}
+   \lineii{WRONG_DOCUMENT_ERR}{\exception{WrongDocumentErr}}
+ \end{tableii}