From 7fbc85c5c541323f78730b051aae8af07a0a25a6 Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Sat, 23 Sep 2000 04:47:56 +0000
Subject: Rename the public interface from "pyexpat" to "xml.parsers.expat".

---
 Doc/lib/libpyexpat.tex   | 50 +++++++++++++++++++++++-------------------------
 Lib/test/test_pyexpat.py | 20 +++++++++----------
 2 files changed, 34 insertions(+), 36 deletions(-)

diff --git a/Doc/lib/libpyexpat.tex b/Doc/lib/libpyexpat.tex
index d663c63..fe2086d 100644
--- a/Doc/lib/libpyexpat.tex
+++ b/Doc/lib/libpyexpat.tex
@@ -1,12 +1,14 @@
-\section{\module{pyexpat} ---
-         Fast XML parsing using the Expat C library}
+\section{\module{xml.parsers.expat} ---
+         Fast XML parsing using the Expat library}
 
-\declaremodule{builtin}{pyexpat}
-\modulesynopsis{An interface to the Expat XML parser.}
+\declaremodule{standard}{xml.parsers.expat}
+\modulesynopsis{An interface to the Expat non-validating XML parser.}
 \moduleauthor{Paul Prescod}{paul@prescod.net}
 \sectionauthor{A.M. Kuchling}{amk1@bigfoot.com}
 
-The \module{pyexpat} module is a Python interface to the Expat
+\versionadded{2.0}
+
+The \module{xml.parsers.expat} module is a Python interface to the Expat
 non-validating XML parser.
 The module provides a single extension type, \class{xmlparser}, that
 represents the current state of an XML parser.  After an
@@ -14,8 +16,12 @@ represents the current state of an XML parser.  After an
 can be set to handler functions.  When an XML document is then fed to
 the parser, the handler functions are called for the character data
 and markup in the XML document.
+
+This module uses the \module{pyexpat}\refbimodindex{pyexpat} module to
+provide access to the Expat parser.  Direct use of the
+\module{pyexpat} module is deprecated.
  
-The \module{pyexpat} module contains two functions:
+The \module{xml.parsers.expat} module contains two functions:
 
 \begin{funcdesc}{ErrorString}{errno}
 Returns an explanatory string for a given error number \var{errno}.
@@ -103,7 +109,7 @@ containing UTF-8 encoded data will be passed to the handlers.
 The following attributes contain values relating to the most recent
 error encountered by an \class{xmlparser} object, and will only have
 correct values once a call to \method{Parse()} or \method{ParseFile()}
-has raised a \exception{pyexpat.error} exception.
+has raised a \exception{xml.parsers.expat.error} exception.
 
 \begin{datadesc}{ErrorByteIndex} 
 Byte index at which an error occurred.
@@ -112,7 +118,7 @@ Byte index at which an error occurred.
 \begin{datadesc}{ErrorCode} 
 Numeric code specifying the problem.  This value can be passed to the
 \function{ErrorString()} function, or compared to one of the constants
-defined in the \module{pyexpat.errors} submodule.
+defined in the \module{errors} object.
 \end{datadesc}
 
 \begin{datadesc}{ErrorColumnNumber} 
@@ -199,14 +205,13 @@ Called for references to external entities.
 \end{methoddesc}
 
 
-\subsection{Example \label{pyexpat-example}}
+\subsection{Example \label{expat-example}}
 
 The following program defines three handlers that just print out their
 arguments.
 
 \begin{verbatim}
-
-import pyexpat
+import xml.parsers.expat
 
 # 3 handler functions
 def start_element(name, attrs):
@@ -216,11 +221,11 @@ def end_element(name):
 def char_data(data):
     print 'Character data:', repr(data)
 
-p=pyexpat.ParserCreate()
+p = xml.parsers.expat.ParserCreate()
 
 p.StartElementHandler = start_element
-p.EndElementHandler   = end_element
-p.CharacterDataHandler= char_data
+p.EndElementHandler = end_element
+p.CharacterDataHandler = char_data
 
 p.Parse("""<?xml version="1.0"?>
 <parent id="top"><child1 name="paul">Text goes here</child1>
@@ -244,21 +249,15 @@ End element: parent
 \end{verbatim}
 
 
-\section{\module{pyexpat.errors} --- Error constants}
-
-\declaremodule{builtin}{pyexpat.errors}
-\modulesynopsis{Error constants defined for the Expat parser}
-\moduleauthor{Paul Prescod}{paul@prescod.net}
+\subsection{Expat error constants \label{expat-errors}}
 \sectionauthor{A.M. Kuchling}{amk1@bigfoot.com}
 
 The following table lists the error constants in the
-\module{pyexpat.errors} submodule, available once the
-\refmodule{pyexpat} module has been imported.
-
-Note that this module cannot be imported directly until
-\refmodule{pyexpat} has been imported.
+\code{errors} object of the \module{xml.parsers.expat} module.  These
+constants are useful in interpreting some of the attributes of the
+parser object after an error has occurred.
 
-The following constants are defined:
+The \code{errors} object has the following attributes:
 
 \begin{datadesc}{XML_ERROR_ASYNC_ENTITY}
 \end{datadesc}
@@ -323,4 +322,3 @@ A reference was made to a entity which was not defined.
 \begin{datadesc}{XML_ERROR_UNKNOWN_ENCODING}
 The document encoding is not supported by Expat.
 \end{datadesc}
-
diff --git a/Lib/test/test_pyexpat.py b/Lib/test/test_pyexpat.py
index 9c31671..a119987 100644
--- a/Lib/test/test_pyexpat.py
+++ b/Lib/test/test_pyexpat.py
@@ -3,7 +3,7 @@
 # XXX TypeErrors on calling handlers, or on bad return values from a
 # handler, are obscure and unhelpful.
         
-import pyexpat
+from xml.parsers import expat
                 
 class Outputter:
     def StartElementHandler(self, name, attrs):
@@ -67,7 +67,7 @@ def confirm(ok):
         print "Not OK."
 
 out = Outputter()
-parser = pyexpat.ParserCreate(namespace_separator='!')
+parser = expat.ParserCreate(namespace_separator='!')
 
 # Test getting/setting returns_unicode
 parser.returns_unicode = 0; confirm(parser.returns_unicode == 0)
@@ -115,28 +115,28 @@ data = '''\
 parser.returns_unicode = 0
 try:
     parser.Parse(data, 1)
-except pyexpat.error:
-    print '** Error', parser.ErrorCode, pyexpat.ErrorString(parser.ErrorCode)
+except expat.error:
+    print '** Error', parser.ErrorCode, expat.ErrorString(parser.ErrorCode)
     print '** Line', parser.ErrorLineNumber
     print '** Column', parser.ErrorColumnNumber
     print '** Byte', parser.ErrorByteIndex
 
 # Try the parse again, this time producing Unicode output
-parser = pyexpat.ParserCreate(namespace_separator='!')
+parser = expat.ParserCreate(namespace_separator='!')
 parser.returns_unicode = 1
 
 for name in HANDLER_NAMES:
     setattr(parser, name, getattr(out, name))
 try:
     parser.Parse(data, 1)
-except pyexpat.error:
-    print '** Error', parser.ErrorCode, pyexpat.ErrorString(parser.ErrorCode)
+except expat.error:
+    print '** Error', parser.ErrorCode, expat.ErrorString(parser.ErrorCode)
     print '** Line', parser.ErrorLineNumber
     print '** Column', parser.ErrorColumnNumber
     print '** Byte', parser.ErrorByteIndex
 
 # Try parsing a file
-parser = pyexpat.ParserCreate(namespace_separator='!')
+parser = expat.ParserCreate(namespace_separator='!')
 parser.returns_unicode = 1
 
 for name in HANDLER_NAMES:
@@ -145,8 +145,8 @@ import StringIO
 file = StringIO.StringIO(data)
 try:
     parser.ParseFile(file)
-except pyexpat.error:
-    print '** Error', parser.ErrorCode, pyexpat.ErrorString(parser.ErrorCode)
+except expat.error:
+    print '** Error', parser.ErrorCode, expat.ErrorString(parser.ErrorCode)
     print '** Line', parser.ErrorLineNumber
     print '** Column', parser.ErrorColumnNumber
     print '** Byte', parser.ErrorByteIndex
-- 
cgit v0.12

