py-howto-checkins — Checkins to the Python HOWTOs

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.37,1.38

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv30850

Modified Files:
	python-22.tex 
Log Message:
Fill in remaining XXX spots
        - Describe UnpackTuple()
        - Credit __unicode__ to MAL
Use \pep macro everywhere in body text.
   (Listening to "The Great Gate of Kiev" -- appropriately triumphal
    music for this check-in...)


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.37
retrieving revision 1.38
diff -C2 -r1.37 -r1.38
*** python-22.tex	2001/10/26 20:07:03	1.37
--- python-22.tex	2001/10/26 20:37:55	1.38
***************
*** 115,119 ****
  I'm not going to attempt to cover every single corner case and small
  change that were required to make the new features work.  Instead this
! section will paint only the broad strokes.  See section~\cite{sect-rellinks},
  ``Related Links'', for further sources of information about Python 2.2's new
  object model.
--- 115,119 ----
  I'm not going to attempt to cover every single corner case and small
  change that were required to make the new features work.  Instead this
! section will paint only the broad strokes.  See section~\ref{sect-rellinks},
  ``Related Links'', for further sources of information about Python 2.2's new
  object model.
***************
*** 145,152 ****
  
  This means that \keyword{class} statements that don't have any base
! classes are always classic classes in Python 2.2.  There's actually a
! way to make new-style classes without any base classes, by setting the
! \member{__metaclass__} variable to XXX (What do you set it to?), but
! it's easier to just subclass \keyword{object}.
  
  The type objects for the built-in types are available as built-ins,
--- 145,152 ----
  
  This means that \keyword{class} statements that don't have any base
! classes are always classic classes in Python 2.2.  (Actually you can
! also change this by setting a module-level variable named
! \member{__metaclass__} --- see \pep{253} for the details --- but it's
! easier to just subclass \keyword{object}.)
  
  The type objects for the built-in types are available as built-ins,
***************
*** 430,434 ****
  
  \subsection{Related Links}
! \ref{sect-rellinks}
  
  This section has just been a quick overview of the new features,
--- 430,434 ----
  
  \subsection{Related Links}
! \label{sect-rellinks}
  
  This section has just been a quick overview of the new features,
***************
*** 640,644 ****
  \keyword{yield} statement.  (For complicated reasons, the
  \keyword{yield} statement isn't allowed inside the \keyword{try} block
! of a \code{try...finally} statement; read PEP 255 for a full
  explanation of the interaction between \keyword{yield} and
  exceptions.)
--- 640,644 ----
  \keyword{yield} statement.  (For complicated reasons, the
  \keyword{yield} statement isn't allowed inside the \keyword{try} block
! of a \code{try...finally} statement; read \pep{255} for a full
  explanation of the interaction between \keyword{yield} and
  exceptions.)
***************
*** 804,808 ****
  storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
  won't argue for either side here and will stick to describing what's 
! implemented in 2.2.  Read PEP 238 for a summary of arguments and
  counter-arguments.)  
  
--- 804,808 ----
  storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
  won't argue for either side here and will stick to describing what's 
! implemented in 2.2.  Read \pep{238} for a summary of arguments and
  counter-arguments.)  
  
***************
*** 811,815 ****
  complete until Python 3.0.
  
! First, I'll borrow some terminology from PEP 238.  ``True division'' is the
  division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
  is 0.25, and so forth.  ``Floor division'' is what Python's \code{/}
--- 811,815 ----
  complete until Python 3.0.
  
! First, I'll borrow some terminology from \pep{238}.  ``True division'' is the
  division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
  is 0.25, and so forth.  ``Floor division'' is what Python's \code{/}
***************
*** 844,848 ****
  so extension types can define the two operators.
  
! % XXX a warning someday?
  
  \end{itemize}
--- 844,854 ----
  so extension types can define the two operators.
  
! \item Python 2.2 supports some command-line arguments for testing
! whether code will works with the changed division semantics.  Running
! python with \programopt{-Q warn} will cause a warning to be issued
! whenever division is applied to two integers.  You can use this to
! find code that's affected by the change and fix it.  By default,
! Python 2.2 will simply perform classic division without a warning; the
! warning will be turned on by default in Python 2.3.
  
  \end{itemize}
***************
*** 872,876 ****
  
  % XXX is this still unimplemented?
! All this is the province of the still-unimplemented PEP 261, ``Support
  for `wide' Unicode characters''; consult it for further details, and
  please offer comments on the PEP and on your experiences with the
--- 878,882 ----
  
  % XXX is this still unimplemented?
! All this is the province of the still-unimplemented \pep{261}, ``Support
  for `wide' Unicode characters''; consult it for further details, and
  please offer comments on the PEP and on your experiences with the
***************
*** 911,920 ****
  
  To convert a class instance to Unicode, a \method{__unicode__} method
! can be defined, analogous to \method{__str__}.
! % XXX who implemented that?
  
! \method{encode()} and \method{decode()} were implemented by
! Marc-Andr\'e Lemburg.  The changes to support using UCS-4 internally
! were implemented by Fredrik Lundh and Martin von L\"owis.
  
  \begin{seealso}
--- 917,926 ----
  
  To convert a class instance to Unicode, a \method{__unicode__} method
! can be defined by a class, analogous to \method{__str__}.
  
! \method{encode()}, \method{decode()}, and \method{__unicode__} were
! implemented by Marc-Andr\'e Lemburg.  The changes to support using
! UCS-4 internally were implemented by Fredrik Lundh and Martin von
! L\"owis.
  
  \begin{seealso}
***************
*** 925,928 ****
--- 931,935 ----
  \end{seealso}
  
+ 
  %======================================================================
  \section{PEP 227: Nested Scopes}
***************
*** 1147,1152 ****
  affect you very much.
  
- % XXX PyArg_UnpackTuple()
- 
  \begin{itemize}
  
--- 1154,1157 ----
***************
*** 1181,1185 ****
    (Contributed by M.-A. Lemburg, and used for the MBCS support on
    Windows described in the following section.)
!  
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
     available in method definition tables to simplify implementation of
--- 1186,1197 ----
    (Contributed by M.-A. Lemburg, and used for the MBCS support on
    Windows described in the following section.)
! 
!   \item A different argument parsing function,
!   \cfunction{PyArg_UnpackTuple()}, has been added that's simpler and
!   presumably faster.  Instead of specifying a format string, the
!   caller simply gives the minimum and maximum number of arguments
!   expected, and a set of pointers to \code{PyObject*} variables that
!   will be filled in with argument values.  
! 
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
     available in method definition tables to simplify implementation of

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.36,1.37

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv21846

Modified Files:
	python-22.tex 
Log Message:
Finish off the type/class section; I don't think there's much else 
    to be covered in an overview article like this.


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.36
retrieving revision 1.37
diff -C2 -r1.36 -r1.37
*** python-22.tex	2001/10/23 20:26:16	1.36
--- python-22.tex	2001/10/26 20:07:03	1.37
***************
*** 1,3 ****
- 
  \documentclass{howto}
  
--- 1,2 ----
***************
*** 15,19 ****
  {\large This document is a draft, and is subject to change until the
  final version of Python 2.2 is released.  Currently it's up to date
! for Python 2.2 alpha 4.  Please send any comments, bug reports, or
  questions, no matter how minor, to \email{aku...@me...}.
  }
--- 14,18 ----
  {\large This document is a draft, and is subject to change until the
  final version of Python 2.2 is released.  Currently it's up to date
! for Python 2.2 beta 1.  Please send any comments, bug reports, or
  questions, no matter how minor, to \email{aku...@me...}.
  }
***************
*** 148,152 ****
  classes are always classic classes in Python 2.2.  There's actually a
  way to make new-style classes without any base classes, by setting the
! \member{__metaclass__} variable to XXX.  (What do you set it to?)
  
  The type objects for the built-in types are available as built-ins,
--- 147,152 ----
  classes are always classic classes in Python 2.2.  There's actually a
  way to make new-style classes without any base classes, by setting the
! \member{__metaclass__} variable to XXX (What do you set it to?), but
! it's easier to just subclass \keyword{object}.
  
  The type objects for the built-in types are available as built-ins,
***************
*** 164,225 ****
  
  To make the set of types complete, new type objects such as
! \function{dictionary} and \function{file} have been added.
! 
! Here's a more interesting example.  The following class subclasses
! Python's dictionary implementation in order to automatically fold all
! dictionary keys to lowercase.
! 
! \begin{verbatim}
! class LowerCaseDict(dictionary):
!     def _fold_key (self, key):
!         if not isinstance(key, str):
!             raise TypeError, "All keys must be strings"
!         return key.lower()
!     
!     def __getitem__ (self, key):
!         key = self._fold_key(key)
!         return dictionary.__getitem__(self, key)
! 
!     def __setitem__ (self, key, value):
!         key = self._fold_key(key)
!         dictionary.__setitem__(self, key, value)
! 
!     def __delitem__ (self, key):
!         key = self._fold_key(key)
!         dictionary.__delitem__(self, key, value)
! \end{verbatim}
! 
! Trying out this class, it works as you'd expect:
! 
! \begin{verbatim}
! >>> d = LowerCaseDict()
! >>> d['ABC'] = 1
! >>> d['abc']
! 1
! \end{verbatim}
  
- However, because it's a subclass of Python's dictionary type,
- instances of \class{LowerCaseDict} can be used in most places where a
- regular dictionary is required.
- 
- \begin{verbatim}
- >>> d = LowerCaseDict()
- >>> exec 'Name = 1' in d
- >>> print d.items()
- XXX
- >>> exec 'nAmE = name + 1' in d
- >>> print d.items()
- XXX
- \end{verbatim}
- 
- And now you can have Python with case-insensitive variable names!  One
- of the nice things about Python 2.2 is that it makes Python flexible
- enough to solve many other past problems without hacking Python's C
- code.  If you want a case-insensitive Python environment, using a
- case-folding dictionary and writing a case-insensitive tokenizer using
- the compiler package (now automatically installed in 2.2) will make it
- a straightforward.
  
- 
  \subsection{Descriptors}
  
--- 164,186 ----
  
  To make the set of types complete, new type objects such as
! \function{dictionary} and \function{file} have been added.  Here's a
! more interesting example, adding a \method{lock()} method to file
! objects:
! 
! \begin{verbatim}
! class LockableFile(file):
!     def lock (self, operation, length=0, start=0, whence=0):
!         import fcntl
!         return fcntl.lockf(self.fileno(), operation,
!                            length, start, whence)
! \end{verbatim}
! 
! The now-obsolete \module{posixfile} module contained a class that
! emulated all of a file object's methods and also added a
! \method{lock()} method, but this class couldn't be passed to internal
! functions that expected a built-in file, something which is possible
! with our new \class{LockableFile}.
  
  
  \subsection{Descriptors}
  
***************
*** 372,385 ****
  Following this rule, referring to \method{D.save()} will return
  \method{C.save()}, which is the behaviour we're after.  This lookup
! rule is the same as the one followed by XXX Common Lisp?.
  
  
  \subsection{Attribute Access}
  
! XXX __getattribute__, __getattr__
  
! XXX properties, slots
  
  
  \subsection{Related Links}
  \ref{sect-rellinks}
--- 333,432 ----
  Following this rule, referring to \method{D.save()} will return
  \method{C.save()}, which is the behaviour we're after.  This lookup
! rule is the same as the one followed by Common Lisp.  
  
  
  \subsection{Attribute Access}
  
! A fair number of sophisticated Python classes define hooks for
! attribute access using \method{__getattr__}; most commonly this is
! done for convenience, to make code more readable by automatically
! mapping an attribute access such as \code{obj.parent} into a method
! call such as \code{obj.get_parent()}.  Python 2.2 adds some new ways
! of controlling attribute access.
! 
! First, \method{__getattr__(\var{attr_name})} is still supported by
! new-style classes, and nothing about it has changed.  As before, it
! will be called when an attempt is made to access \code{obj.foo} and no
! attribute named \samp{foo} is found in the instance's dictionary.
! 
! New-style classes also support a new method,
! \method{__getattribute__(\var{attr_name})}.  The difference between
! the two methods is that \method{__getattribute__} is \emph{always}
! called whenever any attribute is accessed, while the old
! \method{__getattr__} is only called if \samp{foo} isn't found in the
! instance's dictionary.
! 
! However, Python 2.2's support for \dfn{properties} will often be a
! simpler way to trap attribute references.  Writing a
! \method{__getattr__} method is complicated because to avoid recursion
! you can't use regular attribute accesses inside them, and instead have
! to mess around with the contents of \member{__dict__}.
! \method{__getattr__} methods also end up being called by Python when
! it checks for other methods such as \method{__repr__} or
! \method{__coerce__}, and so have to be written with this in mind.
! Finally, calling a function on every attribute access results in a
! sizable performance loss.
! 
! \class{property} is a new built-in type that packages up three
! functions that get, set, or delete an attribute, and a docstring.  For
! example, if you want to define a \member{size} attribute that's
! computed, but also settable, you could write:
  
! \begin{verbatim}
! class C:
!     def get_size (self):
!         result = ... computation ...
!         return result
!     def set_size (self, size):
!         ... compute something based on the size
!         and set internal state appropriately ...
! 
!     # Define a property.  The 'delete this attribute'
!     # method is defined as None, so the attribute
!     # can't be deleted.
!     size = property(get_size, set_size,
!                     None,
!                     "Storage size of this instance")
! \end{verbatim}
! 
! That is certainly clearer and easier to write than a pair of
! \method{__getattr__}/\method{__setattr__} methods that check for the
! \member{size} attribute and handle it specially, while retrieving all
! other attributes from the instance's \member{__dict__}.  Accesses to
! \member{size} are also the only ones which have to perform the work of
! calling a function, letting references to other attributes run at
! their usual speed.
! 
! Finally, it's possible to constrain the list of attributes that can be
! referenced on an object using the new \member{__slots__} attribute.
! Python objects are usually very dynamic; at any time it's possible to
! define a new attribute on an instance by just doing
! \code{obj.new_attr=1}.  This is flexible and convenient, but this
! flexibility can also lead to bugs, as when you meant to write
! \code{obj.template = 'a'} but make a typo and wrote
! \code{obj.templtae} by accident.  
! 
! A new-style class can define a class variable named \member{__slots__}
! to constrain the list of legal attribute names.  An example will make
! this clear:
  
+ \begin{verbatim}
+ >>> class C(object):
+ ...     __slots__ = ['template', 'name']
+ ...
+ >>> obj = C()
+ >>> print obj.template
+ None
+ >>> obj.template = 'Test' ; obj.name = 'abc'
+ >>> print obj.template
+ Test
+ >>> obj.templtae
+ Traceback (most recent call last):
+   File "<stdin>", line 1, in ?
+ AttributeError: 'C' object has no attribute 'templtae'
+ \end{verbatim}
+ 
  
+ 
  \subsection{Related Links}
  \ref{sect-rellinks}
***************
*** 390,396 ****
  more complete picture?
  
! \url{http://www.python.org/2.2/descrintro.html} is a tutorial
  introduction to the descriptor features, written by Guido van Rossum.
! % XXX read it and comment on it
  
  Next, there are two relevant PEPs, \pep{252} and \pep{253}.  \pep{252}
--- 437,445 ----
  more complete picture?
  
! \url{http://www.python.org/2.2/descrintro.html} is a lengthy tutorial
  introduction to the descriptor features, written by Guido van Rossum.
! If my description has whetted your appetite, go read this tutorial
! next, because it goes into much more detail about the new features
! while still remaining quite easy to read.
  
  Next, there are two relevant PEPs, \pep{252} and \pep{253}.  \pep{252}
***************
*** 398,410 ****
  descriptor API.  \pep{253} is titled "Subtyping Built-in Types", and
  describes the changes to type objects that make it possible to subtype
! built-in objects.  This is the more complicated PEP of the two, and at
! a few points the necessary explanations of types and meta-types may
! cause your head to explode.  Both PEPs were written and implemented by
! Guido van Rossum, with substantial assistance from the rest of the
! Zope Corp. team.
! 
! Finally, there's the ultimate authority: the source code.
! typeobject.c, others?
! % XXX point people at the right files
  
  
--- 447,460 ----
  descriptor API.  \pep{253} is titled "Subtyping Built-in Types", and
  describes the changes to type objects that make it possible to subtype
! built-in objects.  \pep{253} is the more complicated PEP of the two,
! and at a few points the necessary explanations of types and meta-types
! may cause your head to explode.  Both PEPs were written and
! implemented by Guido van Rossum, with substantial assistance from the
! rest of the Zope Corp. team.
! 
! Finally, there's the ultimate authority: the source code.  Most of the
! machinery for the type handling is in \file{Objects/typeobject.c}, but
! you should only resort to it after all other avenues have been
! exhausted (including posting a question to python-list or python-dev.)
  
  
***************
*** 1097,1100 ****
--- 1147,1152 ----
  affect you very much.
  
+ % XXX PyArg_UnpackTuple()
+ 
  \begin{itemize}
  
***************
*** 1296,1304 ****
  
  The author would like to thank the following people for offering
! suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr., Carel
! Fellinger, Mark Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e
! Lemburg, Fredrik Lundh, Tim Peters, Neil Schemenauer, Guido van
! Rossum.
  
  \end{document}
--- 1348,1356 ----
  
  The author would like to thank the following people for offering
! suggestions, corrections and assistance with various drafts of this
! article: Fred Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr.,
! Carel Fellinger, Mark Hammond, Stephen Hansen, Jack Jansen,
! Marc-Andr\'e Lemburg, Fredrik Lundh, Tim Peters, Tom Reinhardt, Neil
! Schemenauer, Guido van Rossum.
  
  \end{document}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.35,1.36

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv32195

Modified Files:
	python-22.tex 
Log Message:
Fill out section on how to write a new-style class


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.35
retrieving revision 1.36
diff -C2 -r1.35 -r1.36
*** python-22.tex	2001/10/22 15:32:05	1.35
--- python-22.tex	2001/10/23 20:26:16	1.36
***************
*** 1,2 ****
--- 1,3 ----
+ 
  \documentclass{howto}
  
***************
*** 129,135 ****
  intended to last forever; eventually old-style classes will be
  dropped, possibly in Python 3.0.
  
! So how do you define a new-style class?  XXX
! Subclass object -- subclass a built-in type.
  
  
--- 130,223 ----
  intended to last forever; eventually old-style classes will be
  dropped, possibly in Python 3.0.
+ 
+ So how do you define a new-style class?  You do it by subclassing an
+ existing new-style class.  Most of Python's built-in types, such as
+ integers, lists, dictionaries, and even files, are new-style classes
+ now.  A new-style class named \class{object}, the base class for all
+ built-in types, has been also been added so if no built-in type is
+ suitable, you can just subclass \class{object}:
+ 
+ \begin{verbatim}
+ class C(object):
+     def __init__ (self):
+         ...
+     ...
+ \end{verbatim}
+ 
+ This means that \keyword{class} statements that don't have any base
+ classes are always classic classes in Python 2.2.  There's actually a
+ way to make new-style classes without any base classes, by setting the
+ \member{__metaclass__} variable to XXX.  (What do you set it to?)
+ 
+ The type objects for the built-in types are available as built-ins,
+ named using a clever trick.  Python has always had built-in functions
+ named \function{int()}, \function{float()}, and \function{str()}.  In
+ 2.2, they aren't functions any more, but type objects that behave as
+ factories when called.
+ 
+ \begin{verbatim}
+ >>> int
+ <type 'int'>
+ >>> int('123')
+ 123
+ \end{verbatim}
+ 
+ To make the set of types complete, new type objects such as
+ \function{dictionary} and \function{file} have been added.
+ 
+ Here's a more interesting example.  The following class subclasses
+ Python's dictionary implementation in order to automatically fold all
+ dictionary keys to lowercase.
+ 
+ \begin{verbatim}
+ class LowerCaseDict(dictionary):
+     def _fold_key (self, key):
+         if not isinstance(key, str):
+             raise TypeError, "All keys must be strings"
+         return key.lower()
+     
+     def __getitem__ (self, key):
+         key = self._fold_key(key)
+         return dictionary.__getitem__(self, key)
+ 
+     def __setitem__ (self, key, value):
+         key = self._fold_key(key)
+         dictionary.__setitem__(self, key, value)
+ 
+     def __delitem__ (self, key):
+         key = self._fold_key(key)
+         dictionary.__delitem__(self, key, value)
+ \end{verbatim}
+ 
+ Trying out this class, it works as you'd expect:
+ 
+ \begin{verbatim}
+ >>> d = LowerCaseDict()
+ >>> d['ABC'] = 1
+ >>> d['abc']
+ 1
+ \end{verbatim}
+ 
+ However, because it's a subclass of Python's dictionary type,
+ instances of \class{LowerCaseDict} can be used in most places where a
+ regular dictionary is required.
+ 
+ \begin{verbatim}
+ >>> d = LowerCaseDict()
+ >>> exec 'Name = 1' in d
+ >>> print d.items()
+ XXX
+ >>> exec 'nAmE = name + 1' in d
+ >>> print d.items()
+ XXX
+ \end{verbatim}
  
! And now you can have Python with case-insensitive variable names!  One
! of the nice things about Python 2.2 is that it makes Python flexible
! enough to solve many other past problems without hacking Python's C
! code.  If you want a case-insensitive Python environment, using a
! case-folding dictionary and writing a case-insensitive tokenizer using
! the compiler package (now automatically installed in 2.2) will make it
! a straightforward.
  
  
***************
*** 234,245 ****
  ignore the implementation details.
  
! \subsection{Inheritance Lookup: The Diamond Rule}
  
! XXX
  
  \subsection{Attribute Access}
  
  XXX __getattribute__, __getattr__
  
  \subsection{Related Links}
  \ref{sect-rellinks}
--- 322,385 ----
  ignore the implementation details.
  
! \subsection{Multiple Inheritance: The Diamond Rule}
  
! Multiple inheritance has also been made more useful through changing
! the rules under which names are resolved.  Consider this set of classes
! (diagram taken from \pep{253} by Guido van Rossum):
! 
! \begin{verbatim}
!                 class A:
!                   ^ ^  def save(self): ...
!                  /   \
!                 /     \
!                /       \
!               /         \
!           class B     class C:
!               ^         ^  def save(self): ...
!                \       /
!                 \     /
!                  \   /
!                   \ /
!                 class D
! \end{verbatim}
  
+ The lookup rule for classic classes is simple but not very smart; the
+ base classes are searched depth-first, going from left to right.  A
+ reference to \method{D.save} will search the classes \class{D},
+ \class{B}, and then \class{A}, where \method{save()} would be found
+ and returned.  \method{C.save()} would never be found at all.  This is
+ bad, because if \class{C}'s \method{save()} method is saving some
+ internal state specific to \class{C}, not calling it will result in
+ that state never getting saved.
+ 
+ New-style classes follow a different algorithm that's a bit more
+ complicated to explain, but does the right thing in this situation.
+ 
+ \begin{enumerate}
+ 
+ \item List all the base classes, following the classic lookup rule and
+ include a class multiple times if it's visited repeatedly.  In the
+ above example, the list of visited classes is [\class{D}, \class{B},
+ \class{A}, \class{C}, class{A}].
+ 
+ \item Scan the list for duplicated classes.  If any are found, remove
+ all but one occurrence, leaving the \emph{last} one in the list.  In
+ the above example, the list becomes [\class{D}, \class{B}, \class{C},
+ class{A}] after dropping duplicates.
+ 
+ \end{enumerate}
+ 
+ Following this rule, referring to \method{D.save()} will return
+ \method{C.save()}, which is the behaviour we're after.  This lookup
+ rule is the same as the one followed by XXX Common Lisp?.
+ 
+ 
  \subsection{Attribute Access}
  
  XXX __getattribute__, __getattr__
  
+ XXX properties, slots
+ 
+ 
  \subsection{Related Links}
  \ref{sect-rellinks}
***************
*** 265,268 ****
--- 405,409 ----
  
  Finally, there's the ultimate authority: the source code.
+ typeobject.c, others?
  % XXX point people at the right files
  
***************
*** 350,354 ****
  >>> a,b,c
  (1, 2, 3)
- >>>
  \end{verbatim}
  
--- 491,494 ----
***************
*** 374,378 ****
  Dec 12
  Oct 10
- >>>
  \end{verbatim}          
  
--- 514,517 ----
***************
*** 472,476 ****
    File "<stdin>", line 2, in generate_ints
  StopIteration
- >>>
  \end{verbatim}
  
--- 611,614 ----

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.34,1.35

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv9044

Modified Files:
	python-22.tex 
Log Message:
Update bug/patch counts


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.34
retrieving revision 1.35
diff -C2 -r1.34 -r1.35
*** python-22.tex	2001/10/22 14:11:06	1.34
--- python-22.tex	2001/10/22 15:32:05	1.35
***************
*** 1019,1023 ****
  As usual there were a bunch of other improvements and bugfixes
  scattered throughout the source tree.  A search through the CVS change
! logs finds there were 119 patches applied, and 179 bugs fixed; both
  figures are likely to be underestimates.  Some of the more notable
  changes are:
--- 1019,1023 ----
  As usual there were a bunch of other improvements and bugfixes
  scattered throughout the source tree.  A search through the CVS change
! logs finds there were 312 patches applied, and 391 bugs fixed; both
  figures are likely to be underestimates.  Some of the more notable
  changes are:

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.33,1.34

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv12162

Modified Files:
	python-22.tex 
Log Message:
Add correction from /F about SRE
\filename{} should be \file{}


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.33
retrieving revision 1.34
diff -C2 -r1.33 -r1.34
*** python-22.tex	2001/10/22 02:03:40	1.33
--- python-22.tex	2001/10/22 14:11:06	1.34
***************
*** 905,914 ****
    \item Various bugfixes and performance improvements have been made
    to the SRE engine underlying the \module{re} module.  For example,
!   \function{re.sub()} will now use \function{string.replace()}
!   automatically when the pattern and its replacement are both just
!   literal strings without regex metacharacters.  Another contributed
!   patch speeds up certain Unicode character ranges by a factor of
!   two. (SRE is maintained by Fredrik Lundh.  The BIGCHARSET patch was
!   contributed by Martin von L\"owis.)
  
    \item The \module{smtplib} module now supports \rfc{2487}, ``Secure
--- 905,913 ----
    \item Various bugfixes and performance improvements have been made
    to the SRE engine underlying the \module{re} module.  For example,
!   the \function{re.sub()} and \function{re.split()} functions have
!   been rewritten in C.  Another contributed patch speeds up certain
!   Unicode character ranges by a factor of two. (SRE is maintained by
!   Fredrik Lundh.  The BIGCHARSET patch was contributed by Martin von
!   L\"owis.)
  
    \item The \module{smtplib} module now supports \rfc{2487}, ``Secure
***************
*** 1044,1048 ****
  Most of the MacPython toolbox modules, which interface to MacOS APIs
  such as windowing, QuickTime, scripting, etc. have been ported to OS~X,
! but they've been left commented out in \filename{setup.py}.  People who want
  to experiment with these modules can uncomment them manually.
  
--- 1043,1047 ----
  Most of the MacPython toolbox modules, which interface to MacOS APIs
  such as windowing, QuickTime, scripting, etc. have been ported to OS~X,
! but they've been left commented out in \file{setup.py}.  People who want
  to experiment with these modules can uncomment them manually.
  
***************
*** 1160,1166 ****
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
! Schemenauer, Guido van Rossum.
  
  \end{document}
--- 1159,1166 ----
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr., Carel
! Fellinger, Mark Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e
! Lemburg, Fredrik Lundh, Tim Peters, Neil Schemenauer, Guido van
! Rossum.
  
  \end{document}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.32,1.33

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv1828

Modified Files:
	python-22.tex 
Log Message:
Partly fill out the PEP 252 section


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.32
retrieving revision 1.33
diff -C2 -r1.32 -r1.33
*** python-22.tex	2001/10/22 02:00:11	1.32
--- python-22.tex	2001/10/22 02:03:40	1.33
***************
*** 53,67 ****
  \section{PEP 252: Type and Class Changes}
  
! XXX I need to read and digest the relevant PEPs.
  
! \begin{seealso}
  
! \seepep{252}{Making Types Look More Like Classes}{Written and implemented 
! by Guido van Rossum.}
  
! \seeurl{http://www.python.org/2.2/descrintro.html}{A tutorial
! on the type/class changes in 2.2.}
  
! \end{seealso}
  
  
--- 53,269 ----
  \section{PEP 252: Type and Class Changes}
  
! The largest and most far-reaching changes in Python 2.2 are to
! Python's model of objects and classes.  The changes should be backward
! compatible, so it's likely that your code will continue to run
! unchanged, but the changes provide some amazing new capabilities.
! Before beginning this, the longest and most complicated section of
! this article, I'll provide an overview of the changes and offer some
! comments.
! 
! A long time ago I wrote a Web page
! (\url{http://www.amk.ca/python/writing/warts.html}) listing flaws in
! Python's design.  One of the most significant flaws was that it's
! impossible to subclass Python types implemented in C.  In particular,
! it's not possible to subclass built-in types, so you can't just
! subclass, say, lists in order to add a single useful method to them.
! The \module{UserList} module provides a class that supports all of the
! methods of lists and that can be subclassed further, but there's lots
! of C code that expects a regular Python list and won't accept a
! \class{UserList} instance.
  
! Python 2.2 fixes this, and in the process adds some exciting new
! capabilities.  A brief summary:
  
! \begin{itemize}
  
! \item You can subclass built-in types such as lists and even integers,
! and your subclasses should work in every place that requires the
! original type.
! 
! \item It's now possible to define static and class methods, in addition
! to the instance methods available in previous versions of Python.
! 
! \item It's also possible to automatically call methods on accessing or
! setting an instance attribute by using a new mechanism called
! \dfn{properties}.  Many uses of \method{__getattr__} can be rewritten
! to use properties instead, making the resulting code simpler and
! faster.  As a small side benefit, attributes can now have docstrings,
! too.
! 
! \item The list of legal attributes for an instance can be limited to a
! particular set using \dfn{slots}, making it possible to safeguard
! against typos and perhaps make more optimizations possible in future
! versions of Python.
  
! \end{itemize}
! 
! Some users have voiced concern about all these changes.  Sure, they
! say, the new features are neat and lend themselves to all sorts of
! tricks that weren't possible in previous versions of Python, but
! they also make the language more complicated.  Some people have said
! that they've always recommended Python for its simplicity, and feel
! that its simplicity is being lost.
! 
! Personally, I think there's no need to worry.  Many of the new
! features are quite esoteric, and you can write a lot of Python code
! without ever needed to be aware of them.  Writing a simple class is no
! more difficult than it ever was, so you don't need to bother learning
! or teaching them unless they're actually needed.  Some very
! complicated tasks that were previously only possible from C will now
! be possible in pure Python, and to my mind that's all for the better.
! 
! I'm not going to attempt to cover every single corner case and small
! change that were required to make the new features work.  Instead this
! section will paint only the broad strokes.  See section~\cite{sect-rellinks},
! ``Related Links'', for further sources of information about Python 2.2's new
! object model.
! 
! 
! \subsection{Old and New Classes}
! 
! First, you should know that Python 2.2 really has two kinds of
! classes: classic or old-style classes, and new-style classes.  The
! old-style class model is exactly the same as the class model in
! earlier versions of Python.  All the new features described in this
! section apply only to new-style classes. This divergence isn't
! intended to last forever; eventually old-style classes will be
! dropped, possibly in Python 3.0.
! 
! So how do you define a new-style class?  XXX
! Subclass object -- subclass a built-in type.
! 
! 
! \subsection{Descriptors}
! 
! In previous versions of Python, there was no consistent way to
! discover what attributes and methods were supported by an object.
! There were some informal conventions, such as defining
! \member{__members__} and \member{__methods__} attributes that were
! lists of names, but often the author of an extension type or a class
! wouldn't bother to define them.  You could fall back on inspecting the
! \member{__dict__} of an object, but when class inheritance or an
! arbitrary \method{__getattr__} hook were in use this could still be
! inaccurate.
! 
! The one big idea underlying the new class model is that an API for
! describing the attributes of an object using \dfn{descriptors} has
! been formalized.  Descriptors specify the value of an attribute,
! stating whether it's a method or a field.  With the descriptor API,
! static methods and class methods become possible, as well as more
! exotic constructs.
! 
! Attribute descriptors are objects that live inside class objects, and
! have a few attributes of their own:
! 
! \begin{itemize}
! 
! \item \member{__name__} is the attribute's name.
! 
! \item \member{__doc__} is the attribute's docstring.
! 
! \item \method{__get__(\var{object})} is a method that retrieves the attribute value from \var{object}.
! 
! \item \method{__get__(\var{object}, \var{value})} sets the attribute
! on \var{object} to \var{value}.
! 
! \end{itemize}
! 
! For example, when you write \code{obj.x}, the steps that Python
! actually performs are:
! 
! \begin{verbatim}
! descriptor = obj.__class__.x
! descriptor.get(obj)
! \end{verbatim}
! 
! For methods, \method{descriptor.get} returns a temporary object that's
! callable, and wraps up the instance and the method to be called on it.
! This is also why static methods and class methods are now possible;
! they have descriptors that wrap up just the method, or the method and
! the class.  As a brief explanation of these new kinds of methods,
! static methods aren't passed the instance, and therefore resemble
! regular functions.  Class methods are passed the class of the object,
! but not the object itself.  Static and class methods is defined like
! this:
! 
! \begin{verbatim}
! class C:
!     def f(arg1, arg2):
!         ...
!     f = staticmethod(f)
! 
!     def g(cls, arg1, arg2):
!         ...
!     g = classmethod(g)
! \end{verbatim}
! 
! The \function{staticmethod()} function takes the function
! \function{f}, and returns it wrapped up in a descriptor so it can be
! stored in the class object.  You might expect there to be special
! syntax for creating such methods (\code{def static f()},
! \code{defstatic f()}, or something like that) but no such syntax has
! been defined yet; that's been left for future versions.
! 
! More new features, such as slots and properties, are also implemented
! as new kinds of descriptors, and it's not difficult to write a
! descriptor class that does something novel.  For example, it would be
! possible to write a descriptor class that made it possible to write
! Eiffel-style preconditions and postconditions for a method.  A class
! that used this feature might be defined like this:
! 
! \begin{verbatim}
! from eiffel import eiffelmethod
! 
! class C:
!     def f(self, arg1, arg2):
!         # The actual function
!     def pre_f(self):
!         # Check preconditions
!     def post_f(self):
!         # Check postconditions
! 
!     f = eiffelmethod(f, pre_f, post_f)
! \end{verbatim}
! 
! Note that a person using the new \function{eiffelmethod()} doesn't
! have to understand anything about descriptors.  This is why I think
! the new features don't increase the basic complexity of the language.
! There will be a few wizards who need to know about it in order to
! write \function{eiffelmethod()} or the ZODB or whatever, but most
! users will just write code on top of the resulting libraries and
! ignore the implementation details.
! 
! \subsection{Inheritance Lookup: The Diamond Rule}
! 
! XXX
! 
! \subsection{Attribute Access}
! 
! XXX __getattribute__, __getattr__
! 
! \subsection{Related Links}
! \ref{sect-rellinks}
! 
! This section has just been a quick overview of the new features,
! giving enough of an explanation to start you programming, but many
! details have been simplified or ignored.  Where should you go to get a
! more complete picture?
! 
! \url{http://www.python.org/2.2/descrintro.html} is a tutorial
! introduction to the descriptor features, written by Guido van Rossum.
! % XXX read it and comment on it
! 
! Next, there are two relevant PEPs, \pep{252} and \pep{253}.  \pep{252}
! is titled "Making Types Look More Like Classes", and covers the
! descriptor API.  \pep{253} is titled "Subtyping Built-in Types", and
! describes the changes to type objects that make it possible to subtype
! built-in objects.  This is the more complicated PEP of the two, and at
! a few points the necessary explanations of types and meta-types may
! cause your head to explode.  Both PEPs were written and implemented by
! Guido van Rossum, with substantial assistance from the rest of the
! Zope Corp. team.
! 
! Finally, there's the ultimate authority: the source code.
! % XXX point people at the right files
  
  
***************
*** 486,490 ****
  please offer comments on the PEP and on your experiences with the
  2.2 beta releases.
! % XXX update previous line once 2.2 reaches beta.
  
  Another change is much simpler to explain. Since their introduction,
--- 688,692 ----
  please offer comments on the PEP and on your experiences with the
  2.2 beta releases.
! % XXX update previous line once 2.2 reaches beta or final.
  
  Another change is much simpler to explain. Since their introduction,
***************
*** 826,830 ****
    \item The code for the MacOS port for Python, maintained by Jack
    Jansen, is now kept in the main Python CVS tree, and many changes
!   have been made to support MacOS X.
  
  The most significant change is the ability to build Python as a
--- 1028,1032 ----
    \item The code for the MacOS port for Python, maintained by Jack
    Jansen, is now kept in the main Python CVS tree, and many changes
!   have been made to support MacOS~X.
  
  The most significant change is the ability to build Python as a
***************
*** 832,836 ****
  option to the configure script when compiling Python.  According to
  Jack Jansen, ``This installs a self-contained Python installation plus
! the OSX framework "glue" into
  \file{/Library/Frameworks/Python.framework} (or another location of
  choice).  For now there is little immediate added benefit to this
--- 1034,1038 ----
  option to the configure script when compiling Python.  According to
  Jack Jansen, ``This installs a self-contained Python installation plus
! the OS~X framework "glue" into
  \file{/Library/Frameworks/Python.framework} (or another location of
  choice).  For now there is little immediate added benefit to this
***************
*** 841,846 ****
  
  Most of the MacPython toolbox modules, which interface to MacOS APIs
! such as windowing, QuickTime, scripting, etc. have been ported to OS
! X, but they've been left commented out in \filename{setup.py}.  People who want
  to experiment with these modules can uncomment them manually.
  
--- 1043,1048 ----
  
  Most of the MacPython toolbox modules, which interface to MacOS APIs
! such as windowing, QuickTime, scripting, etc. have been ported to OS~X,
! but they've been left commented out in \filename{setup.py}.  People who want
  to experiment with these modules can uncomment them manually.
  

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.31,1.32

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv1314

Modified Files:
	python-22.tex 
Log Message:
A bunch of minor rewordings


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.31
retrieving revision 1.32
diff -C2 -r1.31 -r1.32
*** python-22.tex	2001/09/28 20:46:46	1.31
--- python-22.tex	2001/10/22 02:00:11	1.32
***************
*** 39,45 ****
  rationale for a change, refer to the PEP for a particular new feature.
  
  
- The final release of Python 2.2 is planned for October 2001.
- 
  \begin{seealso}
  
--- 39,44 ----
  rationale for a change, refer to the PEP for a particular new feature.
  
+ The final release of Python 2.2 is planned for December 2001.
  
  \begin{seealso}
  
***************
*** 91,105 ****
  \method{__getitem__()} calls will be made, with \var{index}
  incrementing by one each time.  In other words, the presence of the
! \method{__getitem__()} method doesn't mean that \code{file[5]} will
! work, though it really should.
  
  In Python 2.2, iteration can be implemented separately, and
  \method{__getitem__()} methods can be limited to classes that really
  do support random access.  The basic idea of iterators is quite
! simple.  A new built-in function, \function{iter(obj)}, returns an
! iterator for the object \var{obj}.  (It can also take two arguments:
! \code{iter(\var{C}, \var{sentinel})} will call the callable \var{C},
! until it returns \var{sentinel}, which will signal that the iterator
! is done.  This form probably won't be used very often.)
  
  Python classes can define an \method{__iter__()} method, which should
--- 90,105 ----
  \method{__getitem__()} calls will be made, with \var{index}
  incrementing by one each time.  In other words, the presence of the
! \method{__getitem__()} method doesn't mean that using \code{file[5]} 
! to randomly access the sixth element will work, though it really should.
  
  In Python 2.2, iteration can be implemented separately, and
  \method{__getitem__()} methods can be limited to classes that really
  do support random access.  The basic idea of iterators is quite
! simple.  A new built-in function, \function{iter(obj)} or
! \code{iter(\var{C}, \var{sentinel})}, is used to get an iterator.
! \function{iter(obj)} returns an iterator for the object \var{obj},
! while \code{iter(\var{C}, \var{sentinel})} returns an iterator that
! will invoke the callable object \var{C} until it returns
! \var{sentinel} to signal that the iterator is done.  
  
  Python classes can define an \method{__iter__()} method, which should
***************
*** 136,140 ****
  In 2.2, Python's \keyword{for} statement no longer expects a sequence;
  it expects something for which \function{iter()} will return something.
! For backward compatibility, and convenience, an iterator is
  automatically constructed for sequences that don't implement
  \method{__iter__()} or a \code{tp_iter} slot, so \code{for i in
--- 136,140 ----
  In 2.2, Python's \keyword{for} statement no longer expects a sequence;
  it expects something for which \function{iter()} will return something.
! For backward compatibility and convenience, an iterator is
  automatically constructed for sequences that don't implement
  \method{__iter__()} or a \code{tp_iter} slot, so \code{for i in
***************
*** 183,187 ****
  \code{dict.has_key(\var{key})}.
  
- 
  Files also provide an iterator, which calls the \method{readline()}
  method until there are no more lines in the file.  This means you can
--- 183,186 ----
***************
*** 213,217 ****
  
  You're doubtless familiar with how function calls work in Python or
! C.  When you call a function, it gets a private area where its local
  variables are created.  When the function reaches a \keyword{return}
  statement, the local variables are destroyed and the resulting value
--- 212,216 ----
  
  You're doubtless familiar with how function calls work in Python or
! C.  When you call a function, it gets a private namespace where its local
  variables are created.  When the function reaches a \keyword{return}
  statement, the local variables are destroyed and the resulting value
***************
*** 233,237 ****
  function containing a \keyword{yield} statement is a generator
  function; this is detected by Python's bytecode compiler which
! compiles the function specially.  Because a new keyword was
  introduced, generators must be explicitly enabled in a module by
  including a \code{from __future__ import generators} statement near
--- 232,236 ----
  function containing a \keyword{yield} statement is a generator
  function; this is detected by Python's bytecode compiler which
! compiles the function specially as a result.  Because a new keyword was
  introduced, generators must be explicitly enabled in a module by
  including a \code{from __future__ import generators} statement near
***************
*** 241,248 ****
  When you call a generator function, it doesn't return a single value;
  instead it returns a generator object that supports the iterator
! interface.  On executing the \keyword{yield} statement, the generator
  outputs the value of \code{i}, similar to a \keyword{return}
  statement.  The big difference between \keyword{yield} and a
! \keyword{return} statement is that, on reaching a \keyword{yield} the
  generator's state of execution is suspended and local variables are
  preserved.  On the next call to the generator's \code{.next()} method,
--- 240,247 ----
  When you call a generator function, it doesn't return a single value;
  instead it returns a generator object that supports the iterator
! protocol.  On executing the \keyword{yield} statement, the generator
  outputs the value of \code{i}, similar to a \keyword{return}
  statement.  The big difference between \keyword{yield} and a
! \keyword{return} statement is that on reaching a \keyword{yield} the
  generator's state of execution is suspended and local variables are
  preserved.  On the next call to the generator's \code{.next()} method,
***************
*** 316,320 ****
  The idea of generators comes from other programming languages,
  especially Icon (\url{http://www.cs.arizona.edu/icon/}), where the
! idea of generators is central to the language.  In Icon, every
  expression and function call behaves like a generator.  One example
  from ``An Overview of the Icon Programming Language'' at
--- 315,319 ----
  The idea of generators comes from other programming languages,
  especially Icon (\url{http://www.cs.arizona.edu/icon/}), where the
! idea of generators is central.  In Icon, every
  expression and function call behaves like a generator.  One example
  from ``An Overview of the Icon Programming Language'' at
***************
*** 338,343 ****
  Python language, but learning or using them isn't compulsory; if they
  don't solve any problems that you have, feel free to ignore them.
! This is different from Icon where the idea of generators is a basic
! concept.  One novel feature of Python's interface as compared to
  Icon's is that a generator's state is represented as a concrete object
  that can be passed around to other functions or stored in a data
--- 337,341 ----
  Python language, but learning or using them isn't compulsory; if they
  don't solve any problems that you have, feel free to ignore them.
! One novel feature of Python's interface as compared to
  Icon's is that a generator's state is represented as a concrete object
  that can be passed around to other functions or stored in a data
***************
*** 359,363 ****
  are 32-bit values on most machines, and long integers, which can be of
  arbitrary size, was becoming an annoyance.  For example, on platforms
! that support large files (files larger than \code{2**32} bytes), the
  \method{tell()} method of file objects has to return a long integer.
  However, there were various bits of Python that expected plain
--- 357,361 ----
  are 32-bit values on most machines, and long integers, which can be of
  arbitrary size, was becoming an annoyance.  For example, on platforms
! that support files larger than \code{2**32} bytes, the
  \method{tell()} method of file objects has to return a long integer.
  However, there were various bits of Python that expected plain
***************
*** 386,390 ****
  identically.  You can still distinguish them with the
  \function{type()} built-in function, but that's rarely needed.  The
! \function{int()} function will now return a long integer if the value
  is large enough.  
  
--- 384,388 ----
  identically.  You can still distinguish them with the
  \function{type()} built-in function, but that's rarely needed.  The
! \function{int()} constructor will now return a long integer if the value
  is large enough.  
  
***************
*** 403,409 ****
  to fix an old design flaw that's been in Python from the beginning.
  Currently Python's division operator, \code{/}, behaves like C's
! division operator when presented with two integer arguments.  It
  returns an integer result that's truncated down when there would be
! fractional part.  For example, \code{3/2} is 1, not 1.5, and
  \code{(-1)/2} is -1, not -0.5.  This means that the results of divison
  can vary unexpectedly depending on the type of the two operands and
--- 401,407 ----
  to fix an old design flaw that's been in Python from the beginning.
  Currently Python's division operator, \code{/}, behaves like C's
! division operator when presented with two integer arguments: it
  returns an integer result that's truncated down when there would be
! a fractional part.  For example, \code{3/2} is 1, not 1.5, and
  \code{(-1)/2} is -1, not -0.5.  This means that the results of divison
  can vary unexpectedly depending on the type of the two operands and
***************
*** 415,420 ****
  caused endless discussions on python-dev and in July erupted into an
  storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
! won't argue for either side here; read PEP 238 for a summary of
! arguments and counter-arguments.)
  
  Because this change might break code, it's being introduced very
--- 413,419 ----
  caused endless discussions on python-dev and in July erupted into an
  storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
! won't argue for either side here and will stick to describing what's 
! implemented in 2.2.  Read PEP 238 for a summary of arguments and
! counter-arguments.)  
  
  Because this change might break code, it's being introduced very
***************
*** 422,426 ****
  complete until Python 3.0.
  
! First, some terminology from PEP 238.  ``True division'' is the
  division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
  is 0.25, and so forth.  ``Floor division'' is what Python's \code{/}
--- 421,425 ----
  complete until Python 3.0.
  
! First, I'll borrow some terminology from PEP 238.  ``True division'' is the
  division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
  is 0.25, and so forth.  ``Floor division'' is what Python's \code{/}
***************
*** 482,489 ****
  \function{unichr()} to raise a \exception{ValueError} exception.
  
  All this is the province of the still-unimplemented PEP 261, ``Support
  for `wide' Unicode characters''; consult it for further details, and
  please offer comments on the PEP and on your experiences with the
! 2.2 alpha releases.
  % XXX update previous line once 2.2 reaches beta.
  
--- 481,489 ----
  \function{unichr()} to raise a \exception{ValueError} exception.
  
+ % XXX is this still unimplemented?
  All this is the province of the still-unimplemented PEP 261, ``Support
  for `wide' Unicode characters''; consult it for further details, and
  please offer comments on the PEP and on your experiences with the
! 2.2 beta releases.
  % XXX update previous line once 2.2 reaches beta.
  
***************
*** 520,523 ****
--- 520,527 ----
  \end{verbatim}
  
+ To convert a class instance to Unicode, a \method{__unicode__} method
+ can be defined, analogous to \method{__str__}.
+ % XXX who implemented that?
+ 
  \method{encode()} and \method{decode()} were implemented by
  Marc-Andr\'e Lemburg.  The changes to support using UCS-4 internally
***************
*** 537,541 ****
  feature, to be enabled by a \code{from __future__ import
  nested_scopes} directive.  In 2.2 nested scopes no longer need to be
! specially enabled, but are always enabled.  The rest of this section
  is a copy of the description of nested scopes from my ``What's New in
  Python 2.1'' document; if you read it when 2.1 came out, you can skip
--- 541,545 ----
  feature, to be enabled by a \code{from __future__ import
  nested_scopes} directive.  In 2.2 nested scopes no longer need to be
! specially enabled, and are now always present.  The rest of this section
  is a copy of the description of nested scopes from my ``What's New in
  Python 2.1'' document; if you read it when 2.1 came out, you can skip
***************
*** 642,650 ****
  
    \item The \module{xmlrpclib} module was contributed to the standard
!   library by Fredrik Lundh.  It provides support for writing XML-RPC
!   clients; XML-RPC is a simple remote procedure call protocol built on
    top of HTTP and XML. For example, the following snippet retrieves a
!   list of RSS channels from the O'Reilly Network, and then retrieves a
!   list of the recent headlines for one channel:
  
  \begin{verbatim}
--- 646,654 ----
  
    \item The \module{xmlrpclib} module was contributed to the standard
!   library by Fredrik Lundh, provding support for writing XML-RPC
!   clients.  XML-RPC is a simple remote procedure call protocol built on
    top of HTTP and XML. For example, the following snippet retrieves a
!   list of RSS channels from the O'Reilly Network, and then 
!   lists the recent headlines for one channel:
  
  \begin{verbatim}
***************
*** 674,677 ****
--- 678,685 ----
    algorithm described by \rfc{2104}.
  
+   \item The Python profiler has been extensively reworked and various
+   errors in its output have been corrected.  (Contributed by Fred
+   Fred~L. Drake, Jr. and Tim Peters.)
+  
    \item The \module{socket} module can be compiled to support IPv6;
    specify the \longprogramopt{enable-ipv6} option to Python's configure
***************
*** 685,690 ****
  
    \item In the interpreter's interactive mode, there's a new built-in
!   function \function{help()}, that uses the \module{pydoc} module
!   introduced in Python 2.1 to provide interactive.
    \code{help(\var{object})} displays any available help text about
    \var{object}.  \code{help()} with no argument puts you in an online
--- 693,698 ----
  
    \item In the interpreter's interactive mode, there's a new built-in
!   function \function{help()} that uses the \module{pydoc} module
!   introduced in Python 2.1 to provide interactive help.
    \code{help(\var{object})} displays any available help text about
    \var{object}.  \code{help()} with no argument puts you in an online
***************
*** 727,736 ****
    of legal characters defined by the current locale.  The buggy
    modules have all been fixed to use \constant{ascii_letters} instead.
!   (Reported by an unknown person; fixed by Fred L. Drake, Jr.)
  
    \item The \module{mimetypes} module now makes it easier to use
    alternative MIME-type databases by the addition of a
    \class{MimeTypes} class, which takes a list of filenames to be
!   parsed.  (Contributed by Fred L. Drake, Jr.)
  
    \item A \class{Timer} class was added to the \module{threading}
--- 735,744 ----
    of legal characters defined by the current locale.  The buggy
    modules have all been fixed to use \constant{ascii_letters} instead.
!   (Reported by an unknown person; fixed by Fred~L. Drake, Jr.)
  
    \item The \module{mimetypes} module now makes it easier to use
    alternative MIME-type databases by the addition of a
    \class{MimeTypes} class, which takes a list of filenames to be
!   parsed.  (Contributed by Fred~L. Drake, Jr.)
  
    \item A \class{Timer} class was added to the \module{threading}
***************
*** 745,749 ****
  
  Some of the changes only affect people who deal with the Python
! interpreter at the C level, writing Python extension modules,
  embedding the interpreter, or just hacking on the interpreter itself.
  If you only write Python code, none of the changes described here will
--- 753,757 ----
  
  Some of the changes only affect people who deal with the Python
! interpreter at the C level because they're writing Python extension modules,
  embedding the interpreter, or just hacking on the interpreter itself.
  If you only write Python code, none of the changes described here will
***************
*** 754,759 ****
    \item Profiling and tracing functions can now be implemented in C,
    which can operate at much higher speeds than Python-based functions
!   and should reduce the overhead of enabling profiling and tracing, so
!   it will be of interest to authors of development environments for
    Python.  Two new C functions were added to Python's API,
    \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
--- 762,767 ----
    \item Profiling and tracing functions can now be implemented in C,
    which can operate at much higher speeds than Python-based functions
!   and should reduce the overhead of profiling and tracing.  This 
!   will be of interest to authors of development environments for
    Python.  Two new C functions were added to Python's API,
    \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
***************
*** 780,784 ****
    which assumes that 8-bit strings are in Python's default ASCII
    encoding and converts them to the specified new encoding.
!   (Contributed by M.-A. Lemburg.)
   
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
--- 788,793 ----
    which assumes that 8-bit strings are in Python's default ASCII
    encoding and converts them to the specified new encoding.
!   (Contributed by M.-A. Lemburg, and used for the MBCS support on
!   Windows described in the following section.)
   
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
***************
*** 792,796 ****
  \item
     Two new wrapper functions, \cfunction{PyOS_snprintf()} and
!    \cfunction{PyOS_vsnprintf()} were added.  which provide a
     cross-platform implementations for the relatively new
     \cfunction{snprintf()} and \cfunction{vsnprintf()} C lib APIs. In
--- 801,805 ----
  \item
     Two new wrapper functions, \cfunction{PyOS_snprintf()} and
!    \cfunction{PyOS_vsnprintf()} were added to provide 
     cross-platform implementations for the relatively new
     \cfunction{snprintf()} and \cfunction{vsnprintf()} C lib APIs. In
***************
*** 833,837 ****
  Most of the MacPython toolbox modules, which interface to MacOS APIs
  such as windowing, QuickTime, scripting, etc. have been ported to OS
! X, but they've been left commented out in setup.py.  People who want
  to experiment with these modules can uncomment them manually.
  
--- 842,846 ----
  Most of the MacPython toolbox modules, which interface to MacOS APIs
  such as windowing, QuickTime, scripting, etc. have been ported to OS
! X, but they've been left commented out in \filename{setup.py}.  People who want
  to experiment with these modules can uncomment them manually.
  
***************
*** 854,858 ****
  %can uncomment them. Gestalt and Internet Config modules are enabled by
  %default.
- 
    
    \item Keyword arguments passed to builtin functions that don't take them
--- 863,866 ----
***************
*** 860,863 ****
--- 868,877 ----
    message "\var{function} takes no keyword arguments".
    
+   \item Weak references, added in Python 2.1 as an extension module,
+   are now part of the core because they're used in the implementation
+   of new-style classes.  The \exception{ReferenceError} exception has
+   therefore moved from the \module{weakref} module to become a
+   built-in exception.
+ 
    \item A new script, \file{Tools/scripts/cleanfuture.py} by Tim
    Peters, automatically removes obsolete \code{__future__} statements
***************
*** 866,872 ****
    \item The new license introduced with Python 1.6 wasn't
    GPL-compatible.  This is fixed by some minor textual changes to the
!   2.2 license, so Python can now be embedded inside a GPLed program
!   again.  The license changes were also applied to the Python 2.0.1
!   and 2.1.1 releases.
  
    \item When presented with a Unicode filename on Windows, Python will
--- 880,888 ----
    \item The new license introduced with Python 1.6 wasn't
    GPL-compatible.  This is fixed by some minor textual changes to the
!   2.2 license, so it's now legal to embed Python inside a GPLed
!   program again.  Note that Python itself is not GPLed, but instead is
!   under a license that's essentially equivalent to the BSD license,
!   same as it always was.  The license changes were also applied to the
!   Python 2.0.1 and 2.1.1 releases.
  
    \item When presented with a Unicode filename on Windows, Python will
***************
*** 901,906 ****
    contains objects that sneakily changed their hash value, or mutated
    the dictionary they were contained in. For a while python-dev fell
!   into a gentle rhythm of Michael Hudson finding a case that dump
!   core, Tim Peters fixing it, Michael finding another case, and round
    and round it went.   
  
--- 917,922 ----
    contains objects that sneakily changed their hash value, or mutated
    the dictionary they were contained in. For a while python-dev fell
!   into a gentle rhythm of Michael Hudson finding a case that dumped
!   core, Tim Peters fixing the bug, Michael finding another case, and round
    and round it went.   
  
***************
*** 942,946 ****
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
  Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
  Schemenauer, Guido van Rossum.
--- 958,962 ----
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Andrew Dalke, Fred~L. Drake, Jr., Carel Fellinger, Mark
  Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
  Schemenauer, Guido van Rossum.

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.30,1.31

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv887

Modified Files:
	python-22.tex 
Log Message:
Minor additions and rewrites.
Bump version number.


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.30
retrieving revision 1.31
diff -C2 -r1.30 -r1.31
*** python-22.tex	2001/09/24 14:51:16	1.30
--- python-22.tex	2001/09/28 20:46:46	1.31
***************
*** 4,8 ****
  
  \title{What's New in Python 2.2}
! \release{0.05}
  \author{A.M. Kuchling}
  \authoraddress{\email{aku...@me...}}
--- 4,8 ----
  
  \title{What's New in Python 2.2}
! \release{0.06}
  \author{A.M. Kuchling}
  \authoraddress{\email{aku...@me...}}
***************
*** 14,18 ****
  {\large This document is a draft, and is subject to change until the
  final version of Python 2.2 is released.  Currently it's up to date
! for Python 2.2 alpha 1.  Please send any comments, bug reports, or
  questions, no matter how minor, to \email{aku...@me...}.
  }
--- 14,18 ----
  {\large This document is a draft, and is subject to change until the
  final version of Python 2.2 is released.  Currently it's up to date
! for Python 2.2 alpha 4.  Please send any comments, bug reports, or
  questions, no matter how minor, to \email{aku...@me...}.
  }
***************
*** 389,394 ****
  is large enough.  
  
- % XXX is there a warning-enabling command-line option for this?
- 
  \begin{seealso}
  
--- 389,392 ----
***************
*** 398,401 ****
--- 396,400 ----
  \end{seealso}
  
+ 
  %======================================================================
  \section{PEP 238: Changing the Division Operator}
***************
*** 667,672 ****
  #   'title': 'html2fo 0.3 (Default)'}, ... ]
  \end{verbatim}
  
! See \url{http://www.xmlrpc.com/} for more information about XML-RPC.
  
    \item The \module{socket} module can be compiled to support IPv6;
--- 666,676 ----
  #   'title': 'html2fo 0.3 (Default)'}, ... ]
  \end{verbatim}
+ 
+ The \module{SimpleXMLRPCServer} module makes it easy to create
+ straightforward XML-RPC servers.  See \url{http://www.xmlrpc.com/} for
+ more information about XML-RPC.
  
!   \item The new \module{hmac} module implements implements the HMAC
!   algorithm described by \rfc{2104}.
  
    \item The \module{socket} module can be compiled to support IPv6;
***************
*** 708,715 ****
    Baxter and Michel Pelletier.)
  
!   \item The \module{rfc822} module's parsing of email addresses is
!   now compliant with \rfc{2822}, an update to \rfc{822}.  The module's
!   name is \emph{not} going to be changed to \samp{rfc2822}.
!   (Contributed by Barry Warsaw.)
  
    \item New constants \constant{ascii_letters},
--- 712,721 ----
    Baxter and Michel Pelletier.)
  
!   \item The \module{rfc822} module's parsing of email addresses is now
!   compliant with \rfc{2822}, an update to \rfc{822}.  (The module's
!   name is \emph{not} going to be changed to \samp{rfc2822}.)  A new
!   package, \module{email}, has also been added for parsing and
!   generating e-mail messages.  (Contributed by Barry Warsaw, and
!   arising out of his work on Mailman.)
  
    \item New constants \constant{ascii_letters},

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.29,1.30

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv1934

Modified Files:
	python-22.tex 
Log Message:
Add link to Unix Review's 2.2 article
Fix two errors


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.29
retrieving revision 1.30
diff -C2 -r1.29 -r1.30
*** python-22.tex	2001/09/14 16:19:27	1.29
--- python-22.tex	2001/09/24 14:51:16	1.30
***************
*** 26,30 ****
  language design.
  
! This article doesn't attempt to provide a complete specification for
  the new features, but instead provides a convenient overview.  For
  full details, you should refer to the documentation for Python 2.2,
--- 26,30 ----
  language design.
  
! This article doesn't attempt to provide a complete specification of
  the new features, but instead provides a convenient overview.  For
  full details, you should refer to the documentation for Python 2.2,
***************
*** 39,44 ****
--- 39,53 ----
  rationale for a change, refer to the PEP for a particular new feature.
  
+ 
  The final release of Python 2.2 is planned for October 2001.
  
+ \begin{seealso}
+ 
+ \url{http://www.unixreview.com/documents/s=1356/urm0109h/0109h.htm}
+ {``What's So Special About Python 2.2?'' is also about the new 2.2
+ features, and was written by Cameron Laird and Kathryn Soraiz.}
+ 
+ \end{seealso}
+ 
  
  %======================================================================
***************
*** 913,917 ****
    \item The \function{pow()} built-in function no longer supports 3
    arguments when floating-point numbers are supplied.
!   \code{pow(\var{x}, \var{y}, \var{z})} returns \code{(x**y) % z}, but
    this is never useful for floating point numbers, and the final
    result varies unpredictably depending on the platform.  A call such
--- 922,926 ----
    \item The \function{pow()} built-in function no longer supports 3
    arguments when floating-point numbers are supplied.
!   \code{pow(\var{x}, \var{y}, \var{z})} returns \code{(x**y) \% z}, but
    this is never useful for floating point numbers, and the final
    result varies unpredictably depending on the platform.  A call such

[Py-howto-checkins] CVS: pyhowto xml-howto.tex,1.13,1.14

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv5046

Modified Files:
	xml-howto.tex 
Log Message:
Massive rewriting and expansion of the introductory section


Index: xml-howto.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/xml-howto.tex,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -r1.13 -r1.14
*** xml-howto.tex	2001/09/20 21:19:05	1.13
--- xml-howto.tex	2001/09/20 21:43:03	1.14
***************
*** 38,159 ****
  reasonably simple to implement and use, and is already being used for
  specifying markup languages for various new standards: MathML for
! expressing mathematical equations, Synchronized Multimedia
!    Integration Language for
! multimedia presentations, and so forth.
  
  SGML and XML represent a document by tagging the document's various
! components with their function, or meaning.  For example, an academic
! paper contains several parts: it has a title, one or more authors, an
! abstract, the actual text of the paper, a list of references, and so
! forth.  A markup languge for writing such papers would therefore have
! tags for indicating what the contents of the abstract are, what the
! title is, and so forth.  This should not be confused with the physical
! details of how the document is actually printed on paper.  The
! abstract might be printed with narrow margins in a smaller font than
! the rest of the document, but the markup usually won't be concerned
! with details such as this; other software will translate from the
! markup language to a typesetting language such as \TeX, and will
! handle the details.
  
  A markup language specified using XML looks a lot like HTML; a
  document consists of a single \dfn{element}, which contains
  sub-elements, which can have further sub-elements inside them.
  Elements are indicated by \dfn{tags} in the text.  Tags are always
! inside angle brackets \code{<}~\code{>}.  There are two forms of
! elements.  An element can contain content between opening and closing
  tags, as in \code{<name>Euryale</name>}, which is a \element{name}
  element containing the data \samp{Euryale}. This content may be text
! data, other XML elements, or a mixture of both.  Elements can also be
! empty, in which case they contain nothing, and are represented as a
! single tag ended with a slash, as in \code{<stop/>}, which is an empty
! \element{stop} element.  Unlike HTML, XML element names are
! case-sensitive; \element{stop} and \element{Stop} are two different
! element types.
  
  Opening and empty tags can also contain attributes, which specify
! values associated with an element.  For example, text such as
  \code{<name lang='greek'>Herakles</name>}, the \element{name} element
  has a \attribute{lang} attribute which has a value of \samp{greek}.
! This would contrast with \code{<name lang='latin'>Hercules</name>},
! where the attribute's value is \samp{latin}.
  
! A given XML language is specified with a Document Type Definition, or
! \dfn{DTD}.  The DTD declares the element names that are allowed, and
! how elements can be nested inside each other.  The DTD also specifies
! the attributes that can be provided for each element, their default
! values, and if they can be omitted.  For example, to take an example
! from HTML, the \element{LI} element, representing an entry in a list,
! can only occur inside certain elements which represent lists, such as
! \element{OL} or \element{UL}.  A \dfn{validating parser} can be given
! a DTD and a document, and verify whether a given document is legal
! according to the DTD's rules, or determine that one or more rules have
! been violated.
! 
! Applications that process XML can be classed into two types.  The
! simplest class is an application that only handles one particular
! markup language.  For example, a chemistry program may only need to
! process Chemical Markup Language, but not MathML.  This
! application can therefore be written specifically for a single DTD,
! and doesn't need to be capable of handling multiple markup
! languages.  This type is simpler to write, and can easily be
! implemented with the available Python software.
! 
! The second type of application is less common, and has to be able to
! handle any markup language you throw at it.  An example might be a
! smart XML editor that helps you to write XML that conforms to a
! selected DTD; it might do so by not letting you enter an element where
! it would be illegal, or by suggesting elements that can be placed at
! the current cursor location.  Such an application needs to handle any
! possible XML-defined markup, and therefore must be able to obtain a
! data structure embodying the DTD in use.  XXX This type of application
! can't currently be implemented in Python without difficulty (XXX but
! wait and see if a DTD module is included...)
  
! For the full details of XML's syntax, the one definitive source is the
! XML 1.0 specification, available on the Web at
  \url{http://www.w3.org/TR/xml-spec.html}.  However, like all
! specifications, it's quite formal and isn't intended to be a friendly
  introduction or a tutorial.  The annotated version of the standard, at
! \url{http://www.xml.com/xml/pub/axml/axmlintro.html}, is quite helpful
! in clarifying the specification's intent.  There are also various
! informal tutorials and books available to introduce you to XML.
! 
! The rest of this HOWTO will assume that you're familiar with the
! relevant terminology.  Most sections will use XML terms such as
! \emph{element} and \emph{attribute}; section~\ref{DOM} on the Document
! Object Model will assume that you've read the relevant Working Draft,
! and are familiar with things like Iterators and Nodes.
! Section~\ref{SAX} does not require that you have experience with the
! Java SAX implentations.
  
! \subsection{Related Links}
  
! \begin{seealso}
!   \seetitle[http://www.w3.org/XML/]{Extensible Markup Language (XML)}
!            {The World Wide Web Consortium's main page leading to
!             documents relating to XML.  Start here for background
!             information and specifications.}
!   \seetitle[http://www.oasis-open.org/cover/sgml-xml.html]{The XML
!             Cover Pages}{Perhaps the leading index of information on
!             XML and SGML.}
! \end{seealso}
  
  
  \section{Installing the XML Toolkit}
  
! Windows users should get the precompiled version at
! \url{http://sourceforge.net/projects/pyxml}; Mac users will use the
! corresponding precompiled version at \url{XXX}.  Linux users may wish
! to use either the Debian package from \url{XXX}, or the RPM from
! \url{http://sourceforge.net/projects/pyxml}.  To compile from source
! on a \UNIX{} platform, simply perform the following steps.
  
  \begin{enumerate}
- \item If you have are using Python 1.5, you need to install the
- distutils first, which are available from
- \url{http://www.python.org/sigs/distutils-sig}. Python 1.6 and later
- already includes the distutils, so you can skip this step.
  
! \item Get a copy of the source distribution from
  \url{http://sourceforge.net/projects/pyxml}.  Unpack it with the
  following command.
--- 38,318 ----
  reasonably simple to implement and use, and is already being used for
  specifying markup languages for various new standards: MathML for
! expressing mathematical equations, Synchronized Multimedia Integration
! Language for multimedia presentations, and so forth.
  
  SGML and XML represent a document by tagging the document's various
! components with their function or meaning.  For example, a book
! contains several parts: it has a title, one or more authors, the text
! of the book, perhaps a preface or an index, and so forth.  A markup
! languge for writing books would therefore have elements indicating
! what the contents of the preface are, what the title is, and so forth.
! This should not be confused with the physical details of how the
! document is actually printed on paper.  The index might be printed
! with narrow margins in a smaller font than the rest of the book, but
! markup usually isn't (or shouldn't be, anyway) concerned with details
! such as this.  Instead, other software will translate from the markup
! language to a typesetting language such as \TeX, handling the
! presentation details.
! 
! This section will provide a brief overview of XML and a few related
! standards, but it's far from being complete because making it complete
! would require a full-length book and not a short HOWTO. There's no
! better way to get a completely accurate description than to read the
! original W3C Recommendations; you can find links to them in
! section~\ref{xml-links}, ``Related Links''.  If you already know what
! XML is, you can skip the rest of this section.
! 
! Later sections of this HOWTO assume that you're familiar with XML
! terminology.  Most sections will use XML terms such as \emph{element}
! and \emph{attribute}.  Section~\ref{SAX} does not require that you
! have experience with the Java SAX implentations.
  
+ 
+ \subsection{Elements, Attributes and Entities}
+ 
  A markup language specified using XML looks a lot like HTML; a
  document consists of a single \dfn{element}, which contains
  sub-elements, which can have further sub-elements inside them.
  Elements are indicated by \dfn{tags} in the text.  Tags are always
! inside angle brackets \code{<}~\code{>}.  Elements can either contain content, or they can be empty:
! 
! \begin{itemize}
! 
! \item   An element can contain content between opening and closing
  tags, as in \code{<name>Euryale</name>}, which is a \element{name}
  element containing the data \samp{Euryale}. This content may be text
! data, other XML elements, or a mixture of both. 
! 
! \item Elements can also be empty, containing nothing, and are
! represented as a single tag ended with a slash.  For example,
! \code{<stop/>} is an empty \element{stop} element.  Unlike HTML, XML
! element names are case-sensitive; \element{stop} and \element{Stop}
! are two different elements.
! 
! \end{itemize}
  
  Opening and empty tags can also contain attributes, which specify
! values associated with an element.  For example, in the XML text
  \code{<name lang='greek'>Herakles</name>}, the \element{name} element
  has a \attribute{lang} attribute which has a value of \samp{greek}.
! Contrast this with \code{<name lang='latin'>Hercules</name>}, where
! the attribute's value is \samp{latin}.
! 
! XML also includes \dfn{entities} as a shorthand for including a
! particular character or a longer string.  Entity references always
! begin with a \samp{\&} and end with a \samp{;}.  For example, a
! particular Unicode character can be written as \code{\&\#4660;} using
! its character code in decimal, or as \code{\&\#x1234;} using
! hexadecimal.  It's also possible to define your own entities, making
! \code{\&title;} expand to ``The Odyssey'', for example.  If you want to
! include the \samp{\&} character in XML content, it must be written as
! \code{\&amp;}.
! 
! \subsection{Well-Formed XML}
! 
! A legal XML document must, as a minimum, be \dfn{well-formed}: each
! open tag must have a corresponding closing tag, and tags must nest
! properly.  For example, \code{<b><i>text</b></i>} is not well-formed
! because the \element{i} element should be enclosed inside the
! \element{b} element, but instead the closing \code{</b>} tag is
! encountered first.  This example can be made well-formed by swapping
! the order of the closing tags, resulting in \code{<b><i>text</i></b>}.
! 
! If you've ever written HTML by hand, you may have acquired the habit
! of being a bit sloppy about this.  Strictly speaking, HTML has exactly
! the same rules about nesting tags as XML, but most Web browsers are
! very forgiving of errors in HTML.  This is convenient for HTML
! authors, but it makes it difficult to write programs to parse HTML
! input, because the programs have to cope with all sorts of malformed
! input.
! 
! The authors of the XML specification didn't want XML to fall into the
! same trap, because it would make XML processing software much harder
! to write.  Therefore, all XML parsers have to be strict and must
! report an error if their input isn't well-formed.  The Expat parser
! includes an executable program named \program{xmlwf} that parses the
! contents of files and reports any well-formedness violations; it's
! very handy for checking XML data that's been output from a program or
! written by hand.
! 
! 
! \subsection{DTDs}
! 
! Well-formedness just says that all tags nest properly and that every
! opening tag is matched by a closing tag.  It says nothing about the
! order of elements or about which elements can be contained inside other
! elements.
! 
! The following XML, apparently representing a book, is well-formed but
! it makes no logical sense:
! 
! \begin{verbatim}
! <book>
!   <index>  ... </index>
!   <chapter> ... </chapter>
!   <chapter> ... </chapter>
!   <abstract>  ... </abstract>
!   <chapter> ... </chapter>
!   <preface> .... </preface>
! </book>
! \end{verbatim}
  
! Prefaces don't come at the end of books, the index doesn't belong at
! the front, and the abstract doesn't belong in the middle.
! Well-formedness alone doesn't provide any way of enforcing that order.
! You could write a Python program that took an XML file like this and
! checked whether all the parts are in order, but then someone wanting
! to understand what documents are legal would have to read your program.
! 
! Document Type Definitions, or \dfn{DTDs} for short, are a more concise
! way of enforcing ordering and nesting rules. A DTD declares the
! element names that are allowed, and how elements can be nested inside
! each other.  To take an example from HTML, the \element{LI} element,
! representing an entry in a list, can only occur inside certain
! elements which represent lists, such as \element{OL} or \element{UL}.
! 
! The DTD also specifies the attributes that can be provided for each
! element, the default value for each attribute, and whether the
! attribute can be omitted.  A \dfn{validating parser} can take a
! document and a DTD, and check whether the document is legal according
! to the DTD's rules.
! 
! Note that it's quite possible to get useful work done without using a
! validating parser and writing a DTD.  You might decide that just
! writing well-formed XML and checking it with a Python program is all
! you need.  
! 
! A DTD lists the supported elements, the order in which elements must
! occur, and the possible attributes for each element.  Here's a
! fragment from an imaginary DTD for writing books:
  
! \begin{verbatim}
! <!ELEMENT book (abstract?, preface, chapter*, appendix?)>
! <!ELEMENT abstract ...>
! <!ELEMENT chapter ...>
! <!ATTLIST chapter id    ID    #REQUIRED 
!                   title CDATA #IMPLIED>
! \end{verbatim}
! 
! The first line declares the \element{book} element, and specifies the
! elements that can occur inside it and the order in which the
! subelements must be provided.  DTDs borrow from regular expression
! notation in order to express how elements can be repeated; \samp{?}
! means an element must occur 0 or 1 times, \samp{*} is 0 or more times,
! and \samp{+} means the element must occur 1 or more times.  For
! example, the \element{abstract} and \element{appendix} elements are
! optional inside a \element{book} element.  Exactly one
! \element{preface} element has to be present, and it can be followed by
! any number of \element{chapter} elements; having no chapters at all
! would be legal.
! 
! The \code{ATTLIST} declaration specifies attributes for the
! \element{chapter} element.  Chapters can have two attributes,
! \attribute{id} and \attribute{title}.  \attribute{title} contains
! character data (CDATA) and is optional (that's what \samp{\#IMPLIED}
! means, for obscure historical reasons).  \attribute{id} must contain
! an ID value, and it's required and not optional.  
! 
! A validating parser could take this DTD and a sample document, and
! report whether the document is \dfn{valid} according to the rules of
! the DTD.  A document is valid if all the elements occur in the right
! order, and in the right number of repetitions.
! 
! \subsection{Related Links}
! \label{xml-links}
! 
! For the full details of XML's syntax, the definitive source is the XML
! 1.0 specification, available on the Web at
  \url{http://www.w3.org/TR/xml-spec.html}.  However, like all
! specifications it's quite formal and isn't intended to be a friendly
  introduction or a tutorial.  The annotated version of the standard, at
! \url{http://www.xml.com/xml/pub/a/axml/axmlintro.html}, is quite helpful
! in clarifying the specification's intent.  There are also many more
! informal tutorials and books available to introduce you to XML at
! greater length.
  
! The XML Cover Pages, at \url{http://xml.coverpages.org}, are an
! extensive collection of links to XML and SGML resources, including a
! news page that's updated every few days.  If you can only remember one
! XML-related URL, remember this one.  Cafe con Leche, 
! at \url{http://www.ibiblio.org/xml/}, is another good resource.
! 
! The xml-dev mailing list is a high-traffic list for implementation and
! development; see \url{http://www.xml.org/xml/xmldev.shtml} for
! archives and subscription information.  Be warned: Some people might
! find the discussion too focused on inventing new standards and tools,
! not on applying existing standards.  
! 
! 
! \section{Related Standards}
  
! XML 1.0 is the basic standard, but people have built many, \emph{many}
! additional standards and tools on top of XML or to be used with XML.
! This section will quickly introduce some of these related
! technologies, paying particular attention to those that are supported
! by the Python/XML package.
  
+ %\subsection{XPath and XPointer}
  
+ %XXX write section on XPath and XPointer
+ 
+ \subsection{XSLT}
+ 
+ XML documents are often transformed from one format to another.  These
+ transformations can be minor, such as changing all \element{OL}
+ elements into \element{UL} elements, or major, such as translating a
+ DocBook document into HTML so it can be displayed in a Web browser.
+ You can write a separate Python program to do each transformation as
+ you need it, and at times that will be the most appropriate option,
+ but an alternative approach is to use XSL, the Extensible Stylesheet
+ Language.
+ 
+ XSL is really two standards: XSLT, XSL Transformations; and XSL-FO,
+ XSL Formatting Objects.  XSLT is used much more often than XSL-FO,
+ because XSL-FO is intended primarily for rendering XML for printing
+ onto paper.  XSLT is a general tool for transforming one XML document
+ into another document, and therefore can be used for more diverse
+ tasks.
+ 
+ To use XSLT, you have to write a \dfn{stylesheet}, which is itself an
+ XML document written in the XSLT DTD.  The source document is turned
+ into a tree structure, and the stylesheet specifies the transformation
+ you want to perform by selecting some elements from the tree and
+ rearranging them.  
+ 
+ The Python/XML package includes 4XSLT, an XSLT processor written by
+ Fourthought, Inc., letting you write Python programs that apply an
+ XSLT stylesheet to a document.
+ 
+ \subsubsection{Related Links}
+ 
+ The W3C's XSL page is at \url{http://www.w3.org/Style/XSL/}, and links
+ to the XSLT specifications and to friendlier tutorials.
+ 
+ 
+ %\subsection{XML Schemas}
+ 
+ % XXX write a section on XSchema
+ 
+ 
+ %\subsection{RDF}
+ 
+ % XXX write a section on RDF; point users toward Redfoot.
+ 
+ 
  \section{Installing the XML Toolkit}
+ 
+ Releases are available from
+ \url{http://sourceforge.net/projects/pyxml/}.
+ Windows users should download the appropriate precompiled version.
+ Linux users can either download an RPM, or install from source.  Users
+ on other platfoms have no choice but to install from source.
  
! To compile from source on a \UNIX{} platform, simply perform the
! following steps.
  
  \begin{enumerate}
  
! \item Download the latest version of the source distribution from
  \url{http://sourceforge.net/projects/pyxml}.  Unpack it with the
  following command.
***************
*** 163,200 ****
  \end{verbatim}
  
! \item
!  Run:
! \begin{verbatim}
! python setup.py install
! \end{verbatim}
! 
! To properly execute this operation, a C compiler is required - the
! same that was used to build Python itself. On a Unix system, this
! operation may require superuser permissions. \code{setup.py} supports
! a number of different commands and options, invoke \code{setup.py}
! without any arguments to obtain help.
  
  \end{enumerate}
  
  If you have difficulty installing this software, send a problem report
! to <xm...@py...> describing the problem, or submit a bug report
  at \url{http://sourceforget.net/projects/pyxml}.
  
  There are various demonstration programs in the \file{demo/} directory
! of the source distribution.  You may wish to look at them next to get
! an impression of what's possible with the XML tools, and as a source
  of example code.
  
- % package layout
  
  \subsection{Related Links}
- 
- \begin{seealso}
-   \seetitle[http://www.python.org/topics/xml/]{Python and XML
-             Processing}{This is the starting point for Python-related
-             XML topics; it is updated to refer to all software,
-             mailing lists, documentation, etc.}
- \end{seealso}
  
  
  \section{SAX: The Simple API for XML}
--- 322,359 ----
  \end{verbatim}
  
! \item Run \code{python setup.py install}.  In order to run this,
! you'll need to have a C compiler installed, and it should be the same
! one that was used to build your Python installation. On a Unix system,
! this operation may require superuser permissions. \code{setup.py}
! supports a number of different commands and options; invoke
! \code{setup.py} without any arguments to see a help message.
  
  \end{enumerate}
  
+ If you're using Python 1.5, you'll have to install the Distutils
+ first, available from
+ \url{http://www.python.org/sigs/distutils-sig}. The PyXML package
+ still works with Python 1.5.2, but the Unicode support is much less
+ powerful.  Versions of Python after 1.5.2 added very complete Unicode
+ support, so if you're going to be doing serious XML work you should
+ use the latest version of Python 2.x.  At this writing, the latest
+ released version is Python 2.1.
+ 
  If you have difficulty installing this software, send a problem report
! to the XML-SIG mailing list describing the problem, or submit a bug report
  at \url{http://sourceforget.net/projects/pyxml}.
  
  There are various demonstration programs in the \file{demo/} directory
! of the Python/XML source distribution.  You may wish to look at them
! to get an idea of what's possible with the XML tools, and as a source
  of example code.
  
  
  \subsection{Related Links}
  
+ The Python/XML Topic Guide, at
+ \url{http://pyxml.sourceforge.net/topics/} is the starting point for
+ Python-related XML topics; it links to software, mailing lists,
+ documentation, etc.
  
  \section{SAX: The Simple API for XML}

[Py-howto-checkins] CVS: pyhowto xml-howto.tex,1.12,1.13

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv32602

Modified Files:
	xml-howto.tex 
Log Message:
Note things that need to be written
Revise abstract
Change author & e-mail address
Rewrite the DOM section somewhat (it still needs a lot of work)
Delete glossary


Index: xml-howto.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/xml-howto.tex,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -r1.12 -r1.13
*** xml-howto.tex	2001/09/20 03:04:32	1.12
--- xml-howto.tex	2001/09/20 21:19:05	1.13
***************
*** 1,4 ****
--- 1,10 ----
  \documentclass{howto}
  
+ % $Id$
+ 
+ % XXX not covered: c14n.py, xml.marshal, scripts, namespaces, TREX/schemas,
+ % XSLT, XPath
+ % XXX overview of parsers
+ 
  \newcommand{\element}[1]{\code{#1}}
  \newcommand{\attribute}[1]{\code{#1}}
***************
*** 8,13 ****
  \release{0.6.1}
  
! \author{The Python/XML Special Interest Group}
! \authoraddress{\email{xm...@py...}\break (edited by \email{am...@bi...})}
  
  \begin{document}
--- 14,19 ----
  \release{0.6.1}
  
! \author{A.M. Kuchling}
! \authoraddress{\email{aku...@me...}}
  
  \begin{document}
***************
*** 16,20 ****
  \begin{abstract}
  \noindent
! XML is the eXtensible Markup Language, a subset of SGML, intended to
  allow the creation and processing of application-specific markup
  languages.  Python makes an excellent language for processing XML
--- 22,26 ----
  \begin{abstract}
  \noindent
! XML is the eXtensible Markup Language, a subset of SGML intended to
  allow the creation and processing of application-specific markup
  languages.  Python makes an excellent language for processing XML
***************
*** 22,28 ****
  assumes you're already familiar with the structure and terminology of
  XML.
- 
- This is a draft document; 'XXX' in the text indicates that something
- has to be filled in later, or rewritten, or verified, or something.  
  \end{abstract}
  
--- 28,31 ----
***************
*** 613,640 ****
  
  The Document Object Model specifies a tree-based representation for an
! XML document.  A top-level \class{Document} instance is the root of
! the tree, and has a single child which is the top-level
! \class{Element} instance; this \class{Element} has children nodes
! representing the content and any sub-elements, which may have further
! children, and so forth.  Functions are defined which let you traverse
! the resulting tree any way you like, access element and attribute
! values, insert and delete nodes, and convert the tree back into XML.
! 
! The DOM is useful for modifying XML documents, because you can create
! a DOM tree, modify it by adding new nodes and moving subtrees around,
! and then produce a new XML document as output.  You can also construct
! a DOM tree yourself, and convert it to XML; this is often a more
! flexible way of producing XML output than simply writing
! \code{<tag1>}...\code{</tag1>} to a file.
! 
! While the DOM doesn't require that the entire tree be resident in
! memory at one time, the Python DOM implementation currently does keep
! the whole tree in RAM.  It's possible to write an implementation that
! stores most of the tree on disk or in a database, and reads in new
! sections as they're accessed, but this hasn't been done yet.
! This means you may not have enough memory to process very large
! documents as a DOM tree.  A SAX handler, on the other hand, can
! potentially churn through amounts of data far larger than the
! available RAM.
  
  \subsection{Getting A DOM Tree}
--- 616,642 ----
  
  The Document Object Model specifies a tree-based representation for an
! XML document, as opposed to the event-driven processing provided by
! SAX.  Both approaches have their uses.
! 
! A top-level \class{Document} instance is the root of the tree, and has
! a single child which is the top-level \class{Element} instance; this
! \class{Element} has child nodes representing the content and any
! sub-elements, which may in turn have further children and so forth.
! There are different classes for everything that can be found in an XML
! document, so in addition to the \class{Element} class, there are also
! classes such as \class{Text}, \class{Comment}, \class{CDATASection},
! \class{EntityReference}, and so on.  Tree nodes provide methods for
! accessing the parent and child nodes, accessing element and attribute
! values, insert and delete nodes, and converting the tree back into XML.
! 
! The DOM is often useful for modifying XML documents, because you can
! create a DOM tree, modify it by adding new nodes and moving subtrees
! around, and then produce a new XML document as output.  On the other
! hand, while the DOM doesn't require that the entire tree be resident
! in memory at one time, the Python DOM implementation currently keeps
! the whole tree in RAM.  This means you may not have enough memory to
! process very large documents as a DOM tree.  A SAX handler, on the
! other hand, can potentially churn through amounts of data far larger
! than the available RAM.
  
  \subsection{Getting A DOM Tree}
***************
*** 643,649 ****
  offers two alternative implementations of the DOM,
  \module{xml.dom.minidom} and \code{4DOM}. \module{xml.dom.minidom} is
! included in Python 2. It is a minimalistic implementation, which means
! it does not provide all interfaces and operations required by the DOM
! standard. \code{4DOM} (XXX reference) is a complete implementation of
  DOM Level 2 (which is currently work in progress), so we will use that
  in the examples.
--- 645,651 ----
  offers two alternative implementations of the DOM,
  \module{xml.dom.minidom} and \code{4DOM}. \module{xml.dom.minidom} is
! included in Python 2. It is a minimal implementation, which means it
! does not provide all interfaces and operations required by the DOM
! standard.  \code{4DOM} (XXX reference) is a complete implementation of
  DOM Level 2 (which is currently work in progress), so we will use that
  in the examples.
***************
*** 655,663 ****
  input (a file-like object, a string, a file name, and a URL,
  respectively). They all return a DOM \class{Document} object.
  
  \begin{verbatim}
  import sys
! from xml.dom.ext.reader.Sax import FromXmlStream
! from xml.dom.ext import PrettyPrint
  
  # parse the document
--- 657,665 ----
  input (a file-like object, a string, a file name, and a URL,
  respectively). They all return a DOM \class{Document} object.
+ % XXX these functions seem to be deprecated!  why?
  
  \begin{verbatim}
  import sys
! from xml.dom.ext.reader.Sax2 import FromXmlStream
  
  # parse the document
***************
*** 669,675 ****
  This HOWTO can't be a complete introduction to the Document Object
  Model, because there are lots of interfaces and lots of
! methods. Luckily, the DOM Recommendation is quite a readable document,
! so I'd recommend that you read it to get a complete picture of the
! available interfaces; this will only be a partial overview.
  
  The Document Object Model represents a XML document as a tree of
--- 671,678 ----
  This HOWTO can't be a complete introduction to the Document Object
  Model, because there are lots of interfaces and lots of
! methods. Luckily, the DOM Recommendation is quite readable as
! specifications go, so I'd recommend that you read it to get a complete
! picture of the available interfaces.  This section will only be a
! partial overview.
  
  The Document Object Model represents a XML document as a tree of
***************
*** 678,682 ****
  \class{Text}, and \class{Comment}.  
  
! We'll use a single example document throughout this section.  Here's the sample:
  
  \begin{verbatim}
--- 681,686 ----
  \class{Text}, and \class{Comment}.  
  
! We'll use a single example document throughout this section.  Here's
! the sample:
  
  \begin{verbatim}
***************
*** 720,730 ****
  This isn't the only possible tree, because different parsers may
  differ in how they generate \class{Text} nodes; any of the
! \class{Text} nodes in the above tree might be split into multiple nodes.)
  
  \subsubsection{The \class{Node} class}
  
! We'll start by considering the basic \class{Node} class.  All the
! other DOM nodes --- \class{Document}, \class{Element}, \class{Text},
! and so forth --- are subclasses of \class{Node}.  It's possible to
  perform many tasks using just the interface provided by \class{Node}.
  
--- 724,735 ----
  This isn't the only possible tree, because different parsers may
  differ in how they generate \class{Text} nodes; any of the
! \class{Text} nodes in the above tree might be split into multiple
! nodes.)
  
  \subsubsection{The \class{Node} class}
  
! e'll start by considering the basic \class{Node} class.  All the
! other DOM nodes---\class{Document}, \class{Element}, \class{Text},
! and so forth---are subclasses of \class{Node}.  It's possible to
  perform many tasks using just the interface provided by \class{Node}.
  
***************
*** 763,767 ****
  \member{documentElement} attribute contains the \class{Element} node
  for the root element.  The \class{Document} node may have additional
! children, such as \class{ProcessingInstruction} nodes; the complete list of children XXX.
  
  
--- 768,773 ----
  \member{documentElement} attribute contains the \class{Element} node
  for the root element.  The \class{Document} node may have additional
! children, such as \class{ProcessingInstruction} nodes; the complete
! list of children XXX.
  
  
***************
*** 775,854 ****
  Introduction to the walker class
  
- \subsection{Building A Document}
- 
- Intro to builder
- 
- \subsection{Processing HTML}
- 
- Intro to HTML builder
- 
- %Explanations, sample code, ...
- 
  \subsection{Related Links}
- 
- \begin{seealso}
-   \seetitle[http://www.w3.org/DOM/]{Document Object Model (DOM)}{The
-             World Wide Web Consortium's DOM page.}
-   \seetitle[http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/]
-            {Document Object Model (DOM) Level 1 Specification}{The DOM
-             Level 1 Recommendation.  Unlike most standards, this one
-             is actually pretty readable, particularly if you're only
-             interested in the Core XML interfaces.}
- \end{seealso}
- 
- 
- \section{Glossary \label{glossary}}
- 
- XML has given rise to a sea of acronyms and terms.  This section will
- list the most significant terms, and sketch their relevance.
- 
- Many of the following definitions are taken from Lars Marius Garshol's
- SGML glossary, at \url{http://www.stud.ifi.uio.no/\~larsga/download/diverse/sgmlglos.html}.
  
! \begin{definitions}
! \term{DOM (Document Object Model)}
! %
! The Document Object Model is intended to be a platform- and
! language-neutral interface that will allow programs and scripts to
! dynamically access and update the content, structure and style of
! documents. Documents will be represented as tree structures which can
! be traversed and modified.
! 
! \term{DTD (Document Type Definition)}
! %
! A Document Type Definition (nearly always called DTD) defines
! an XML document type, complete with element types, entities
! and an XML declaration.
!        
! In other words: a DTD completely describes one particular kind
! of XML document, such as, for instance, HTML 3.2.
!         
! \term{SAX (Simple API for XML)}
! %
! SAX is a simple standardized API for XML parsers developed by the
! contributors to the xml-dev mailing list. The interface is mostly
! language-independent, as long as the language is object-oriented; the
! first implementation was written for Java, but a Python implementation
! is also available.  SAX is supported by many XML parsers.
!           
! \term{XML (eXtensible Markup Language)}
! %
! XML is an SGML application profile specialized for use on the
! web and has its own standards for linking and stylesheets under development.
!           
! %XML-Data
! 
! \term{XSL (eXtensible Style Language)}
! %
! XSL is a proposal for a stylesheet language for XML, which
! enables browsers to lay out XML documents in an attractive
! manner, and also provides a way to convert XML documents to
! HTML.
! \end{definitions}
!           
! %\section{Related Links}
! %
! %This section collects all
! %the links from the preceding sections.
  
  \end{document}
--- 781,797 ----
  Introduction to the walker class
  
  \subsection{Related Links}
  
! The DOM Level 1 Recommendation is at
! \url{http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/}.  Unlike
! most standards, this one is actually pretty readable, particularly if
! you're only interested in the Core XML interfaces.
! 
! Level 2 of the DOM has also been defined, adding more specialized
! features such as support for XML namespaces, events, and ranges.  DOM
! Level 3 is still being worked on, and will add yet more features.  The
! World Wide Web Consortium's DOM page at \url{http://www.w3.org/DOM/}
! has pointers to the specifications and current drafts for these higher
! DOM levels.
  
  \end{document}

[Py-howto-checkins] CVS: pyhowto xml-howto.tex,1.11,1.12

[Fred L. D. <fd...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv5148

Modified Files:
	xml-howto.tex 
Log Message:

Fix a typo.
Add some additional references.
Convert the use of definition lists for references to "See also" sections.


Index: xml-howto.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/xml-howto.tex,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -r1.11 -r1.12
*** xml-howto.tex	2001/09/20 02:34:28	1.11
--- xml-howto.tex	2001/09/20 03:04:32	1.12
***************
*** 117,121 ****
  
  The rest of this HOWTO will assume that you're familiar with the
! relevant terminology.  Most section will use XML terms such as
  \emph{element} and \emph{attribute}; section~\ref{DOM} on the Document
  Object Model will assume that you've read the relevant Working Draft,
--- 117,121 ----
  
  The rest of this HOWTO will assume that you're familiar with the
! relevant terminology.  Most sections will use XML terms such as
  \emph{element} and \emph{attribute}; section~\ref{DOM} on the Document
  Object Model will assume that you've read the relevant Working Draft,
***************
*** 126,129 ****
--- 126,140 ----
  \subsection{Related Links}
  
+ \begin{seealso}
+   \seetitle[http://www.w3.org/XML/]{Extensible Markup Language (XML)}
+            {The World Wide Web Consortium's main page leading to
+             documents relating to XML.  Start here for background
+             information and specifications.}
+   \seetitle[http://www.oasis-open.org/cover/sgml-xml.html]{The XML
+             Cover Pages}{Perhaps the leading index of information on
+             XML and SGML.}
+ \end{seealso}
+ 
+ 
  \section{Installing the XML Toolkit}
  
***************
*** 176,186 ****
  \subsection{Related Links}
  
! \begin{definitions}
! \term{\url{http://www.python.org/topics/xml/}}
! %
! This is the starting point for Python-related XML topics; it is
! updated to refer to all software, mailing lists, documentation, etc. 
  
- \end{definitions}
  
  \section{SAX: The Simple API for XML}
--- 187,197 ----
  \subsection{Related Links}
  
! \begin{seealso}
!   \seetitle[http://www.python.org/topics/xml/]{Python and XML
!             Processing}{This is the starting point for Python-related
!             XML topics; it is updated to refer to all software,
!             mailing lists, documentation, etc.}
! \end{seealso}
  
  
  \section{SAX: The Simple API for XML}
***************
*** 775,795 ****
  
  \subsection{Related Links}
- 
- \begin{definitions}
- \term{\url{http://www.w3.org/DOM/}}
- %
- The World Wide Web Consortium's DOM page.
- 
- \term{\url{http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/}}
- %
- The DOM Level 1 Recommendation.  Unlike most standards, this one is
- actually pretty readable, particularly if you're only interested in
- the Core XML interfaces.  
- 
- \end{definitions}
  
  
  
! \section{Glossary}
  
  XML has given rise to a sea of acronyms and terms.  This section will
--- 786,802 ----
  
  \subsection{Related Links}
  
+ \begin{seealso}
+   \seetitle[http://www.w3.org/DOM/]{Document Object Model (DOM)}{The
+             World Wide Web Consortium's DOM page.}
+   \seetitle[http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001/]
+            {Document Object Model (DOM) Level 1 Specification}{The DOM
+             Level 1 Recommendation.  Unlike most standards, this one
+             is actually pretty readable, particularly if you're only
+             interested in the Core XML interfaces.}
+ \end{seealso}
  
  
! \section{Glossary \label{glossary}}
  
  XML has given rise to a sea of acronyms and terms.  This section will

[Py-howto-checkins] CVS: pyhowto python-dev.tex,1.9,1.10

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv2434

Modified Files:
	python-dev.tex 
Log Message:
Add link to Apache voting rules
Change a sentence a bit


Index: python-dev.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-dev.tex,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -r1.9 -r1.10
*** python-dev.tex	2001/07/16 01:26:07	1.9
--- python-dev.tex	2001/09/20 02:47:26	1.10
***************
*** 441,445 ****
  favor of the suggestion, -1 indicates they're against it, +0 indicates
  ``I don't care, but go ahead'', while -0 means ``I don't care, so why
! bother?''.  In the Apache project, this voting is formalized and is
  actually how project decisions are made, but in Python, it's just a
  concise way to express opinions in a straw poll, and the result isn't
--- 441,446 ----
  favor of the suggestion, -1 indicates they're against it, +0 indicates
  ``I don't care, but go ahead'', while -0 means ``I don't care, so why
! bother?''.  In the Apache project, this voting is formalized (see
! \url{http://dev.apache.org/guidelines.html} for the rules) and is
  actually how project decisions are made, but in Python, it's just a
  concise way to express opinions in a straw poll, and the result isn't
***************
*** 452,457 ****
  it.  Guido exercised his right to decide, and the feature was added to
  the language in Python 2.0.  Some people still hate it; some people
! who argued against it, such as this author, have now grown sneakily
! fond of it.  
  
  %======================================================================
--- 453,458 ----
  it.  Guido exercised his right to decide, and the feature was added to
  the language in Python 2.0.  Some people still hate it; some people
! who first argued against it, such as this author, have now grown
! sneakily fond of it.
  
  %======================================================================

[Py-howto-checkins] CVS: pyhowto xml-howto.tex,1.10,1.11

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv875

Modified Files:
	xml-howto.tex 
Log Message:
Rewrite pass over SAX section


Index: xml-howto.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/xml-howto.tex,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -r1.10 -r1.11
*** xml-howto.tex	2001/03/21 01:17:00	1.10
--- xml-howto.tex	2001/09/20 02:34:28	1.11
***************
*** 187,213 ****
  \label{SAX}
  
! The Simple API for XML isn't a standard in the formal sense, but an
! informal specification designed by David Megginson, with input from
! many people on the xml-dev mailing list.  SAX defines an event-driven
! interface for parsing XML.  To use SAX, you must create Python class
! instances which implement a specified interface, and the parser will
! then call various methods of those objects.
! 
! This howto describes version 2 of SAX (also referred to as
! SAX2). Earlier versions of this text did explain SAX1, which is
! primarily of historical interest only.
  
  SAX is most suitable for purposes where you want to read through an
  entire XML document from beginning to end, and perform some
! computation, such as building a data structure representating a
! document, or summarizing information in a document (computing an
! average value of a certain element, for example).  It's not very
! useful if you want to modify the document structure in some
! complicated way that involves changing how elements are nested, though
! it could be used if you simply wish to change element contents or
! attributes.  For example, you would not want to re-order chapters in a
! book using SAX, but you might want to change the contents of any
! \element{name} elements with the attribute \attribute{lang} equal to
! 'greek' into Greek letters.
  
  One advantage of SAX is speed and simplicity.  Let's say
--- 187,213 ----
  \label{SAX}
  
! The Simple API for XML isn't a standard in the formal sense that XML
! or ANSI C are.  Rather, SAX is an informal specification originally
! designed by David Megginson with input from many people on the xml-dev
! mailing list.  SAX defines an event-driven interface for parsing XML.
! To use SAX, you must create Python class instances which implement a
! specified interface, and the parser will then call various methods on
! those objects.
! 
! This HOWTO describes version 2 of SAX (also referred to as
! SAX2). Earlier versions of this text explained SAX1, which is now only
! of historical interest.
  
  SAX is most suitable for purposes where you want to read through an
  entire XML document from beginning to end, and perform some
! computation such as building a data structure or summarizing the
! contained information (computing an average value of a certain
! element, for example).  SAX is not very convenient if you want to
! modify the document structure by changing how elements are nested,
! though it would be straightforward to write a SAX program that simply
! changed element contents or attributes.  For example, you wouldn't
! want to re-order chapters in a book using SAX, but you might want to
! extract the contents of all \element{name} elements with the attribute
! \attribute{lang} set to 'greek'.
  
  One advantage of SAX is speed and simplicity.  Let's say
***************
*** 219,227 ****
  instance which ignores all elements that aren't \element{writer}.
  
! Another advantage is that you don't have the whole document resident
! in memory at any one time, which matters if you are processing really
! huge documents.
  
! SAX defines 4 basic interfaces; an SAX-compliant XML parser can be
  passed any objects that support these interfaces, and will call
  various methods as data is processed.  Your task, therefore, is to
--- 219,227 ----
  instance which ignores all elements that aren't \element{writer}.
  
! Another advantage of SAX is that you don't have the whole document
! resident in memory at any one time, which matters if you are
! processing really huge documents.  
  
! SAX defines 4 basic interfaces. A SAX-compliant XML parser can be
  passed any objects that support these interfaces, and will call
  various methods as data is processed.  Your task, therefore, is to
***************
*** 245,249 ****
  \lineii{EntityResolver}{Called to resolve references to external
  entities.  If your documents will have no external entity references,
! you won't need to implement this interface. }
  
  \lineii{ErrorHandler}{Called for error handling.  The parser will call
--- 245,249 ----
  \lineii{EntityResolver}{Called to resolve references to external
  entities.  If your documents will have no external entity references,
! you don't need to implement this interface.}
  
  \lineii{ErrorHandler}{Called for error handling.  The parser will call
***************
*** 255,259 ****
  listed above are implemented as Python classes.  The default method
  implementations are defined to do nothing---the method body is just a
! Python \code{pass} statement--so usually you can simply ignore methods
  that aren't relevant to your application. 
  
--- 255,259 ----
  listed above are implemented as Python classes.  The default method
  implementations are defined to do nothing---the method body is just a
! Python \code{pass} statement---so usually you can simply ignore methods
  that aren't relevant to your application. 
  
***************
*** 261,265 ****
  \begin{verbatim}
  # Define your specialized handler classes
! from xml.sax import Contenthandler, ...
  class docHandler(ContentHandler):
      ...
--- 261,265 ----
  \begin{verbatim}
  # Define your specialized handler classes
! from xml.sax import ContentHandler, ...
  class docHandler(ContentHandler):
      ...
***************
*** 274,287 ****
  parser.setContentHandler(dh)
  
! # Parse the file; your handler's method will get called
  parser.parse(sys.stdin)
- 
  \end{verbatim}
  
  \subsection{Starting Out}
  
! Following the earlier example, let's consider a simple XML format for
! storing information about a comic book collection.  Here's a sample
! document for a collection consisting of a single issue:
  
  \begin{verbatim}
--- 274,286 ----
  parser.setContentHandler(dh)
  
! # Parse the file; your handler's methods will get called
  parser.parse(sys.stdin)
  \end{verbatim}
  
  \subsection{Starting Out}
  
! Let's follow the earlier example of a comic book collection, using a
! simple DTD-less format. Here's a sample document for a collection
! consisting of a single issue:
  
  \begin{verbatim}
***************
*** 298,304 ****
  \samp{collection} element.  It has one child \element{comic} element
  for each issue; the book's title and number are given as attributes of
! the \element{comic} element, which can have one or more children
! containing the issue's writer and artists.  There may be several
! artists or writers for a single issue.
  
  Let's start off with something simple: a document handler named
--- 297,304 ----
  \samp{collection} element.  It has one child \element{comic} element
  for each issue; the book's title and number are given as attributes of
! the \element{comic} element.  The \element{comic} element can in turn
! contain several other elements such as \element{writer} and
! \element{penciller} listing the writer and artists responsible for the
! issue.  There may be several artists or writers for a single issue.
  
  Let's start off with something simple: a document handler named
***************
*** 317,332 ****
  \class{ContentHandler}, \class{DTDHandler}, \class{EntityResolver},
  and \class{ErrorHandler}.  This is what you should use if you want to
! use one class for everything.  When you want separate classes for each
! purpose, or if you want to implement only a single interface, you can
! just subclass each interface individually.  Neither of the two
! approaches is always ``better'' than the other; their suitability
! depends on what you're trying to do, and on what you prefer.
  
! Since this class is doing a search, an instance needs to know what to
! search for.  The desired title and issue number are passed to the
  \class{FindIssue} constructor, and stored as part of the instance.
  
! Now let's look at the function which actually does all the work.
! This simple task only requires looking at the attributes of a given
  element, so only the \method{startElement} method is relevant.
  
--- 317,331 ----
  \class{ContentHandler}, \class{DTDHandler}, \class{EntityResolver},
  and \class{ErrorHandler}.  This is what you should use if you want to
! just write a single class that wraps up all the logic for your
! parsing.  You could also subclass each interface individually and
! implement separate classes for each purpose.  Neither of the two
! approaches is always ``better'' than the other; mostly it's a matter
! of taste.
  
! Since this class is doing a search, an instance needs to know what it's searching for.  The desired title and issue number are passed to the
  \class{FindIssue} constructor, and stored as part of the instance.
  
! Now let's override some of the parsing methods.
! This simple search only requires looking at the attributes of a given
  element, so only the \method{startElement} method is relevant.
  
***************
*** 339,353 ****
          title = attrs.get('title', None)
          number = attrs.get('number', None)
!         if title == self.search_title and number == self.search_number:
!             print title, '#'+str(number), 'found'
  \end{verbatim}
  
  The \method{startElement()} method is passed a string giving the name
  of the element, and an instance containing the element's attributes.
! The latter implements the \class{AttributeList} interface, which
! includes most of the semantics of Python dictionaries.  Therefore, the 
! function looks for \element{comic} elements, and compares the
! specified \attribute{title} and \attribute{number} attributes to the
! search values.  If they match, a message is printed out.
  
  \method{startElement()} is called for every single element in the
--- 338,356 ----
          title = attrs.get('title', None)
          number = attrs.get('number', None)
!         if (title == self.search_title and 
! 	    number == self.search_number):
!             print title, '#' + str(number), 'found'
  \end{verbatim}
  
  The \method{startElement()} method is passed a string giving the name
  of the element, and an instance containing the element's attributes.
! Attributes are accessed using 
! methods from the \class{AttributeList} interface, which
! includes most of the semantics of Python dictionaries.  
! 
! To summarize, \method{startElement()} function looks for
! \element{comic} elements, and compares the specified \attribute{title}
! and \attribute{number} attributes to the search values.  If they
! match, a message is printed out.
  
  \method{startElement()} is called for every single element in the
***************
*** 363,369 ****
  \end{verbatim}
  
! To actually use the class, we need top-level code that creates 
! instances of a parser and of \class{FindIssue}, associates them, and
! then calls a parser method to process the input.
  
  \begin{verbatim}
--- 366,372 ----
  \end{verbatim}
  
! To actually use the class, we need top-level code that creates
! instances of a parser and of \class{FindIssue}, associates the parser
! and the handler, and then calls a parser method to process the input.
  
  \begin{verbatim}
***************
*** 374,377 ****
--- 377,381 ----
      # Create a parser
      parser = make_parser()
+ 
      # Tell the parser we are not interested in XML namespaces
      parser.setFeature(feature_namespaces, 0)
***************
*** 389,416 ****
  The \function{make_parser} class can automate the job of creating
  parsers.  There are already several XML parsers available to Python,
! and more might be added in future.  \file{xmllib.py} is included with
! Python 1.5, so it's always available, but it's also not particularly
! fast.  A faster version of \file{xmllib.py} is included in
! \module{xml.parsers}.  The \module{xml.parsers.expat} module is faster
! still, so it's obviously a preferred choice if it's available.
! \function{make_parser} determines which parsers are available and
! chooses the fastest one, so you don't have to know what the different
! parsers are, or how they differ. (You can also tell
  \function{make_parser} to try a list of parsers, if you want to use a
  specific one).
  
! In SAX2, XML namespace are supported. Parsers will not call
! \method{startElement}, but \method{startElementNS} if namespace
! processing is active. Since our content handler does not implement the
! namespace-aware methods, we request that namespace processing is
! deactivated. The default of this setting varies from parser to parser,
! so you should always set it to a safe value -- unless your handlers
! support either method.
! 
! Once you've created a parser instance, calling
! \method{setContentHandler} tells the parser what to use as the
! handler.
  
! If you run the above code with the sample XML document, it'll output
  \code{Sandman \#62 found.}  
  
--- 393,423 ----
  The \function{make_parser} class can automate the job of creating
  parsers.  There are already several XML parsers available to Python,
! and more might be added in future.  \file{xmllib.py} is included as
! part of the Python standard library, so it's always available, but
! it's also not particularly fast.  A faster version of \file{xmllib.py}
! is included in \module{xml.parsers}.  The \module{xml.parsers.expat}
! module is faster still, so it's obviously a preferred choice if it's
! available.  \function{make_parser} determines which parsers are
! available and chooses the fastest one, so you don't have to know what
! the different parsers are, or how they differ. (You can also tell
  \function{make_parser} to try a list of parsers, if you want to use a
  specific one).
  
! SAX2 supports XML namespaces.  If namespace processing is active,
! parsers won't call \method{startElement()}, but instead will call a
! method named \method{startElementNS()}. Since our \class{FindIssue}
! content handler doesn't implement the namespace-aware methods, we
! request that namespace processing is deactivated.  The default of this
! setting varies from parser to parser, so you should always set it to a
! safe value (unless your handler supports both namespace-aware and
! -unaware processing).
! 
! Once you've created a parser instance, calling the
! \method{setContentHandler()} method tells the parser what to use as
! the content handler.  There are similar methods for setting the other
! handlers: \method{setDTDHandler()}, \method{setEntityResolver()}, and
! \method{setErrorHandler()}.
  
! If you run the above code with the sample XML document, it'll print
  \code{Sandman \#62 found.}  
  
***************
*** 427,431 ****
  The \code{\&foo;} entity is unknown, and the \element{comic} element
  isn't closed (if it was empty, there would be a \samp{/} before the
! closing \samp{>}. As a result, you get a SAXParseException, e.g.
  
  \begin{verbatim}
--- 434,439 ----
  The \code{\&foo;} entity is unknown, and the \element{comic} element
  isn't closed (if it was empty, there would be a \samp{/} before the
! closing \samp{>}. As a result, you get a
! \exception{SAXParseException}, e.g.
  
  \begin{verbatim}
***************
*** 434,451 ****
  
  The default code for the \class{ErrorHandler} interface automatically
! raises an exception for any error; if that is what you want in case of
! an error, you don't need to change the error handler.  Otherwise, you
! should provide your own version of the \class{ErrorHandler} interface,
! and at minimum override the \method{error()} and \method{fatalError()}
  methods.  The minimal implementation for each method can be a single
  line.  The methods in the \class{ErrorHandler}
! interface--\method{warning}, \method{error}, and
! \method{fatalError}--are all passed a single argument, an exception
  instance.  The exception will always be a subclass of
  \exception{SAXException}, and calling \code{str()} on it will produce
  a readable error message explaining the problem.
  
! So, to re-implement a variant of \class{ErrorRaiser}, simply define
! one of the three methods to print the exception they're passed:
  
  \begin{verbatim}
--- 442,460 ----
  
  The default code for the \class{ErrorHandler} interface automatically
! raises an exception for any error; if that is what you want, you don't
! need to implement an error handler class at all.  Otherwise, you can
! provide your own version of the \class{ErrorHandler} interface, at
! minimum overriding the \method{error()} and \method{fatalError()}
  methods.  The minimal implementation for each method can be a single
  line.  The methods in the \class{ErrorHandler}
! interface---\method{warning()}, \method{error()}, and
! \method{fatalError()}---are all passed a single argument, an exception
  instance.  The exception will always be a subclass of
  \exception{SAXException}, and calling \code{str()} on it will produce
  a readable error message explaining the problem.
  
! For example, if you just want to continue running if a recoverable
! error occurs, simply define the \method{error()} method to print the
! exception it's passed:
  
  \begin{verbatim}
***************
*** 460,464 ****
  \subsection{Searching Element Content}
  
! Let's tackle a slightly more complicated task, printing out all issues
  written by a certain author.  This now requires looking at element
  content, because the writer's name is inside a \element{writer}
--- 469,473 ----
  \subsection{Searching Element Content}
  
! Let's tackle a slightly more complicated task: printing out all issues
  written by a certain author.  This now requires looking at element
  content, because the writer's name is inside a \element{writer}
***************
*** 526,531 ****
  flexibly; you can include extra spaces or newlines wherever you like.
  This means that you must normalize the whitespace before comparing
! attribute values or element content; otherwise the comparision might
! produce a wrong result due to the content of two elements having
  different amounts of whitespace.
  
--- 535,540 ----
  flexibly; you can include extra spaces or newlines wherever you like.
  This means that you must normalize the whitespace before comparing
! attribute values or element content; otherwise the comparison might
! produce an incorrect result due to the content of two elements having
  different amounts of whitespace.
  
***************
*** 545,556 ****
  single function call.  In the example above, there might be only one
  call to \method{characters()} for the string \samp{Peter Milligan}, or
! it might call \method{characters()} once for each character.  More
! realistically, if the content contains an entity reference, as in
! \samp{Wagner
! \& Seagle}, the parser might call the method three times; once for 
! \samp{Wagner\ }, once for \samp{\&}, represented by the entity
! reference, and again for \samp{\ Seagle}.
  
! For step 2 of \class{FindWriter}, \method{characters()} only has to
  check \code{inWriterContent}, and if it's true, add the characters to
  the string being built up.
--- 554,564 ----
  single function call.  In the example above, there might be only one
  call to \method{characters()} for the string \samp{Peter Milligan}, or
! it might call \method{characters()} once for each character.  Another,
! more realistic example: if the content contains an entity reference,
! as in \samp{Wagner \& Seagle}, the parser might call the method
! three times; once for \samp{Wagner\ }, once for \samp{\&}, represented
! by the entity reference, and again for \samp{\ Seagle}.
  
! For step 2 of the algorithm, \method{characters()} only has to
  check \code{inWriterContent}, and if it's true, add the characters to
  the string being built up.
***************
*** 571,580 ****
  \function{normalize_whitespace()} function is called.  This can be
  done because we know that leading and trailing whitespace are
! insignificant for this element, in this DTD.  
  
  End tags can't have attributes on them, so there's no \var{attrs}
! parameter.  Empty elements with attributes, such as \samp{<arc
! name="Season of Mists"/>}, will result in a call to
! \method{startElement()}, followed immediately by a call to \method{endElement()}.
  
  XXX how are external entities handled?  Anything special need to be
--- 579,589 ----
  \function{normalize_whitespace()} function is called.  This can be
  done because we know that leading and trailing whitespace are
! insignificant for this application.  
  
  End tags can't have attributes on them, so there's no \var{attrs}
! parameter to the \method{endElement()} method.  Empty elements with
! attributes, such as \samp{<arc name="Season of Mists"/>}, will result
! in a call to \method{startElement()}, followed immediately by a call
! to \method{endElement()}.
  
  XXX how are external entities handled?  Anything special need to be
***************
*** 583,594 ****
  \subsection{Related Links}
  
! \begin{definitions}
! \term{\url{http://www.megginson.com/SAX/}}
! %
! The SAX home page.  This has the most recent copy of the
  specification, and lists SAX implementations for various languages and
! platforms.  At the moment it's somewhat Java-centric.
  
- \end{definitions}
  
  \section{DOM: The Document Object Model}
--- 592,600 ----
  \subsection{Related Links}
  
! The SAX home page is \url{http://www.megginson.com/SAX/}.
! This has the most recent copy of the
  specification, and lists SAX implementations for various languages and
! platforms.  At the moment it's somewhat Java-centric, though.
  
  
  \section{DOM: The Document Object Model}

[Py-howto-checkins] CVS: pyhowto advocacy.tex,1.4,1.5

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv30524

Modified Files:
	advocacy.tex 
Log Message:
Update link to Ousterhout's scripting paper


Index: advocacy.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/advocacy.tex,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** advocacy.tex	1999/12/09 12:58:18	1.4
--- advocacy.tex	2001/09/17 06:01:28	1.5
***************
*** 341,345 ****
  the Web.
  
! \term{\url{http://www.scriptics.com/people/john.ousterhout/scripting.html}}
   
  John Ousterhout's white paper on scripting is a good argument for the
--- 341,345 ----
  the Web.
  
! \term{\url{http://home.pacbell.net/ouster/scripting.html}}
   
  John Ousterhout's white paper on scripting is a good argument for the

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.28,1.29

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv10254

Modified Files:
	python-22.tex 
Log Message:
Add support for SMTP TLS


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -r1.28 -r1.29
*** python-22.tex	2001/09/10 16:18:50	1.28
--- python-22.tex	2001/09/14 16:19:27	1.29
***************
*** 689,692 ****
--- 689,697 ----
    contributed by Martin von L\"owis.)
  
+   \item The \module{smtplib} module now supports \rfc{2487}, ``Secure
+   SMTP over TLS'', so it's now possible to encrypt the SMTP traffic
+   between a Python program and the mail transport agent being handed a
+   message.  (Contributed by Gerhard H\"aring.)
+ 
    \item The \module{imaplib} module, maintained by Piers Lauder, has
    support for several new extensions: the NAMESPACE extension defined

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.27,1.28

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv12519

Modified Files:
	python-22.tex 
Log Message:
Remove some XXX markers
Update the patch and bug counts


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.27
retrieving revision 1.28
diff -C2 -r1.27 -r1.28
*** python-22.tex	2001/09/10 03:20:53	1.27
--- python-22.tex	2001/09/10 16:18:50	1.28
***************
*** 45,54 ****
  \section{PEP 252: Type and Class Changes}
  
! XXX
  
- I need to read and digest the relevant PEPs.
- 
- GvR's description at http://www.python.org/2.2/descrintro.html
- 
  \begin{seealso}
  
--- 45,50 ----
  \section{PEP 252: Type and Class Changes}
  
! XXX I need to read and digest the relevant PEPs.
  
  \begin{seealso}
  
***************
*** 56,59 ****
--- 52,58 ----
  by Guido van Rossum.}
  
+ \seeurl{http://www.python.org/2.2/descrintro.html}{A tutorial
+ on the type/class changes in 2.2.}
+ 
  \end{seealso}
  
***************
*** 355,359 ****
  However, there were various bits of Python that expected plain
  integers and would raise an error if a long integer was provided
! instead.  For example, in version XXX of Python, only regular integers
  could be used as a slice index, and \code{'abc'[1L:]} would raise a
  \exception{TypeError} exception with the message 'slice index must be
--- 354,358 ----
  However, there were various bits of Python that expected plain
  integers and would raise an error if a long integer was provided
! instead.  For example, in Python 1.5, only regular integers
  could be used as a slice index, and \code{'abc'[1L:]} would raise a
  \exception{TypeError} exception with the message 'slice index must be
***************
*** 370,376 ****
  \begin{verbatim}
  >>> 1234567890123
! XXX
! >>> 2 ** 32
! XXX put output here
  \end{verbatim}
  
--- 369,375 ----
  \begin{verbatim}
  >>> 1234567890123
! 1234567890123L
! >>> 2 ** 64
! 18446744073709551616L
  \end{verbatim}
  
***************
*** 715,719 ****
    parsed.  (Contributed by Fred L. Drake, Jr.)
  
!   \item XXX threading.Timer class
  
  \end{itemize}
--- 714,720 ----
    parsed.  (Contributed by Fred L. Drake, Jr.)
  
!   \item A \class{Timer} class was added to the \module{threading}
!   module that allows scheduling an activity to happen at some future
!   time.  (Contributed by Itamar Shtull-Trauring.)
  
  \end{itemize}
***************
*** 759,764 ****
    which assumes that 8-bit strings are in Python's default ASCII
    encoding and converts them to the specified new encoding.
!   (Contributed by M.-A. Lemburg, and used for the MBCS support on
!   Windows described in the previous section.)
   
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
--- 760,764 ----
    which assumes that 8-bit strings are in Python's default ASCII
    encoding and converts them to the specified new encoding.
!   (Contributed by M.-A. Lemburg.)
   
    \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
***************
*** 789,793 ****
  As usual there were a bunch of other improvements and bugfixes
  scattered throughout the source tree.  A search through the CVS change
! logs finds there were 43 patches applied, and 77 bugs fixed; both
  figures are likely to be underestimates.  Some of the more notable
  changes are:
--- 789,793 ----
  As usual there were a bunch of other improvements and bugfixes
  scattered throughout the source tree.  A search through the CVS change
! logs finds there were 119 patches applied, and 179 bugs fixed; both
  figures are likely to be underestimates.  Some of the more notable
  changes are:
***************
*** 855,862 ****
    choice of ASCII as the default encoding turns out to be an
    annoyance.
- 
    (Contributed by Mark Hammond with assistance from Marc-Andr\'e
    Lemburg.)
  
    \item The \file{Tools/scripts/ftpmirror.py} script
    now parses a \file{.netrc} file, if you have one.
--- 855,864 ----
    choice of ASCII as the default encoding turns out to be an
    annoyance.
    (Contributed by Mark Hammond with assistance from Marc-Andr\'e
    Lemburg.)
  
+   \item Large file support is now enabled on Windows.  (Contributed by
+   Tim Peters.)
+ 
    \item The \file{Tools/scripts/ftpmirror.py} script
    now parses a \file{.netrc} file, if you have one.
***************
*** 909,913 ****
    this is never useful for floating point numbers, and the final
    result varies unpredictably depending on the platform.  A call such
!   as \code{pow(2.0, 8.0, 7.0)} will now raise a \exception{XXX}
    exception.
    
--- 911,915 ----
    this is never useful for floating point numbers, and the final
    result varies unpredictably depending on the platform.  A call such
!   as \code{pow(2.0, 8.0, 7.0)} will now raise a \exception{TypeError}
    exception.
    

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.26,1.27

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv9267

Modified Files:
	python-22.tex 
Log Message:
Add section on long integer changes
Add removal of 3-arg pow() for floats
Rewrite introduction a bit


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.26
retrieving revision 1.27
diff -C2 -r1.26 -r1.27
*** python-22.tex	2001/09/05 14:53:31	1.26
--- python-22.tex	2001/09/10 03:20:53	1.27
***************
*** 18,35 ****
  }
  
! This article explains the new features in Python 2.2.  Python 2.2
! includes some significant changes that go far toward cleaning up the
! language's darkest corners, and some exciting new features.
  
  This article doesn't attempt to provide a complete specification for
! the new features, but instead provides a convenient overview of the
! new features.  For full details, you should refer to 2.2 documentation
  such as the
  \citetitle[http://python.sourceforge.net/devel-docs/lib/lib.html]{Python
  Library Reference} and the
  \citetitle[http://python.sourceforge.net/devel-docs/ref/ref.html]{Python
! Reference Manual}, or to the PEP for a particular new feature.
! % These \citetitle marks should get the python.org URLs for the final
  % release, just as soon as the docs are published there.
  
  The final release of Python 2.2 is planned for October 2001.
--- 18,41 ----
  }
  
! This article explains the new features in Python 2.2.
  
+ Python 2.2 can be thought of as the "cleanup release".  There are some
+ features such as generators and iterators that are completely new, but
+ most of the changes, significant and far-reaching though they may be,
+ are aimed at cleaning up irregularities and dark corners of the
+ language design.
+ 
  This article doesn't attempt to provide a complete specification for
! the new features, but instead provides a convenient overview.  For
! full details, you should refer to the documentation for Python 2.2,
  such as the
  \citetitle[http://python.sourceforge.net/devel-docs/lib/lib.html]{Python
  Library Reference} and the
  \citetitle[http://python.sourceforge.net/devel-docs/ref/ref.html]{Python
! Reference Manual}.   
! % XXX These \citetitle marks should get the python.org URLs for the final
  % release, just as soon as the docs are published there.
+ If you want to understand the complete implementation and design
+ rationale for a change, refer to the PEP for a particular new feature.
  
  The final release of Python 2.2 is planned for October 2001.
***************
*** 37,56 ****
  
  %======================================================================
! % It looks like this set of changes will likely get into 2.2,
! % so I need to read and digest the relevant PEPs.
! %\section{PEP 252: Type and Class Changes}
  
! %XXX
  
! % GvR's description at http://www.python.org/2.2/descrintro.html
  
! %\begin{seealso}
  
! %\seepep{252}{Making Types Look More Like Classes}{Written and implemented 
! %by GvR.}
  
! %\end{seealso}
  
  
  %======================================================================
  \section{PEP 234: Iterators}
--- 43,62 ----
  
  %======================================================================
! \section{PEP 252: Type and Class Changes}
  
! XXX
  
! I need to read and digest the relevant PEPs.
  
! GvR's description at http://www.python.org/2.2/descrintro.html
  
! \begin{seealso}
  
! \seepep{252}{Making Types Look More Like Classes}{Written and implemented 
! by Guido van Rossum.}
  
+ \end{seealso}
  
+ 
  %======================================================================
  \section{PEP 234: Iterators}
***************
*** 341,347 ****
  %======================================================================
  \section{PEP 237: Unifying Long Integers and Integers}
  
! XXX write this section
  
  
  %======================================================================
--- 347,392 ----
  %======================================================================
  \section{PEP 237: Unifying Long Integers and Integers}
+ 
+ In recent versions, the distinction between regular integers, which
+ are 32-bit values on most machines, and long integers, which can be of
+ arbitrary size, was becoming an annoyance.  For example, on platforms
+ that support large files (files larger than \code{2**32} bytes), the
+ \method{tell()} method of file objects has to return a long integer.
+ However, there were various bits of Python that expected plain
+ integers and would raise an error if a long integer was provided
+ instead.  For example, in version XXX of Python, only regular integers
+ could be used as a slice index, and \code{'abc'[1L:]} would raise a
+ \exception{TypeError} exception with the message 'slice index must be
+ int'.
+ 
+ Python 2.2 will shift values from short to long integers as required.
+ The 'L' suffix is no longer needed to indicate a long integer literal,
+ as now the compiler will choose the appropriate type.  (Using the 'L'
+ suffix will be discouraged in future 2.x versions of Python,
+ triggering a warning in Python 2.4, and probably dropped in Python
+ 3.0.)  Many operations that used to raise an \exception{OverflowError}
+ will now return a long integer as their result.  For example:
+ 
+ \begin{verbatim}
+ >>> 1234567890123
+ XXX
+ >>> 2 ** 32
+ XXX put output here
+ \end{verbatim}
+ 
+ In most cases, integers and long integers will now be treated
+ identically.  You can still distinguish them with the
+ \function{type()} built-in function, but that's rarely needed.  The
+ \function{int()} function will now return a long integer if the value
+ is large enough.  
  
! % XXX is there a warning-enabling command-line option for this?
  
+ \begin{seealso}
+ 
+ \seepep{237}{Unifying Long Integers and Integers}{Written by
+ Moshe Zadka and Guido van Rossum.  Implemented mostly by Guido van Rossum.}
+ 
+ \end{seealso}
  
  %======================================================================
***************
*** 859,863 ****
    \function{sys.setdlopenflags()} functions.    (Contributed by Bram Stolk.)
  
!   \item XXX 3-argument float pow() is gone
    
  \end{itemize}
--- 904,914 ----
    \function{sys.setdlopenflags()} functions.    (Contributed by Bram Stolk.)
  
!   \item The \function{pow()} built-in function no longer supports 3
!   arguments when floating-point numbers are supplied.
!   \code{pow(\var{x}, \var{y}, \var{z})} returns \code{(x**y) % z}, but
!   this is never useful for floating point numbers, and the final
!   result varies unpredictably depending on the platform.  A call such
!   as \code{pow(2.0, 8.0, 7.0)} will now raise a \exception{XXX}
!   exception.
    
  \end{itemize}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.25,1.26

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv15439

Modified Files:
	python-22.tex 
Log Message:
Note some changes that I need to write about


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.25
retrieving revision 1.26
diff -C2 -r1.25 -r1.26
*** python-22.tex	2001/09/04 21:25:58	1.25
--- python-22.tex	2001/09/05 14:53:31	1.26
***************
*** 340,343 ****
--- 340,349 ----
  
  %======================================================================
+ \section{PEP 237: Unifying Long Integers and Integers}
+ 
+ XXX write this section
+ 
+ 
+ %======================================================================
  \section{PEP 238: Changing the Division Operator}
  
***************
*** 664,667 ****
--- 670,675 ----
    parsed.  (Contributed by Fred L. Drake, Jr.)
  
+   \item XXX threading.Timer class
+ 
  \end{itemize}
  
***************
*** 850,853 ****
--- 858,863 ----
    by \cfunction{dlopen()} using the \function{sys.getdlopenflags()} and
    \function{sys.setdlopenflags()} functions.    (Contributed by Bram Stolk.)
+ 
+   \item XXX 3-argument float pow() is gone
    
  \end{itemize}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.24,1.25

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv1608

Modified Files:
	python-22.tex 
Log Message:
Correction: the Borland C port isn't fully operational yet


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.24
retrieving revision 1.25
diff -C2 -r1.24 -r1.25
*** python-22.tex	2001/08/30 21:30:16	1.24
--- python-22.tex	2001/09/04 21:25:58	1.25
***************
*** 830,835 ****
    and round it went.   
  
!   \item On Windows, Python can now be compiled with Borland C thanks 
!   to a number of patches contributed by Stephen Hansen.
    
    \item Another Windows enhancement: Wise Solutions generously offered
--- 830,836 ----
    and round it went.   
  
!   \item On Windows, Python can now be compiled with Borland C thanks
!   to a number of patches contributed by Stephen Hansen, though the
!   result isn't fully functional yet.  (But this \emph{is} progress...)
    
    \item Another Windows enhancement: Wise Solutions generously offered
***************
*** 859,863 ****
  suggestions and corrections to various drafts of this article: Fred
  Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
  Schemenauer, Guido van Rossum.
  
--- 860,864 ----
  suggestions and corrections to various drafts of this article: Fred
  Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Stephen Hansen, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
  Schemenauer, Guido van Rossum.
  

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.23,1.24

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv18813

Modified Files:
	python-22.tex 
Log Message:
Add Jack Jansen's explanation of the MacOS X changes


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.23
retrieving revision 1.24
diff -C2 -r1.23 -r1.24
*** python-22.tex	2001/08/29 01:16:54	1.23
--- python-22.tex	2001/08/30 21:30:16	1.24
***************
*** 742,754 ****
  \begin{itemize}
  
    \item Keyword arguments passed to builtin functions that don't take them
    now cause a \exception{TypeError} exception to be raised, with the
    message "\var{function} takes no keyword arguments".
    
-   \item The code for the Mac OS port for Python, maintained by Jack
-   Jansen, is now kept in the main Python CVS tree.
-   % XXX should expand this with all of Jack's recent changes (ask him for 
-   % a summary)        
-   
    \item A new script, \file{Tools/scripts/cleanfuture.py} by Tim
    Peters, automatically removes obsolete \code{__future__} statements
--- 742,790 ----
  \begin{itemize}
  
+   \item The code for the MacOS port for Python, maintained by Jack
+   Jansen, is now kept in the main Python CVS tree, and many changes
+   have been made to support MacOS X.
+ 
+ The most significant change is the ability to build Python as a
+ framework, enabled by supplying the \longprogramopt{enable-framework}
+ option to the configure script when compiling Python.  According to
+ Jack Jansen, ``This installs a self-contained Python installation plus
+ the OSX framework "glue" into
+ \file{/Library/Frameworks/Python.framework} (or another location of
+ choice).  For now there is little immediate added benefit to this
+ (actually, there is the disadvantage that you have to change your PATH
+ to be able to find Python), but it is the basis for creating a
+ full-blown Python application, porting the MacPython IDE, possibly
+ using Python as a standard OSA scripting language and much more.''
+ 
+ Most of the MacPython toolbox modules, which interface to MacOS APIs
+ such as windowing, QuickTime, scripting, etc. have been ported to OS
+ X, but they've been left commented out in setup.py.  People who want
+ to experiment with these modules can uncomment them manually.
+ 
+ % Jack's original comments:
+ %The main change is the possibility to build Python as a
+ %framework. This installs a self-contained Python installation plus the
+ %OSX framework "glue" into /Library/Frameworks/Python.framework (or
+ %another location of choice). For now there is little immedeate added
+ %benefit to this (actually, there is the disadvantage that you have to
+ %change your PATH to be able to find Python), but it is the basis for
+ %creating a fullblown Python application, porting the MacPython IDE,
+ %possibly using Python as a standard OSA scripting language and much
+ %more. You enable this with "configure --enable-framework".
+  
+ %The other change is that most MacPython toolbox modules, which
+ %interface to all the MacOS APIs such as windowing, quicktime,
+ %scripting, etc. have been ported. Again, most of these are not of
+ %immedeate use, as they need a full application to be really useful, so
+ %they have been commented out in setup.py. People wanting to experiment
+ %can uncomment them. Gestalt and Internet Config modules are enabled by
+ %default.
+ 
+   
    \item Keyword arguments passed to builtin functions that don't take them
    now cause a \exception{TypeError} exception to be raised, with the
    message "\var{function} takes no keyword arguments".
    
    \item A new script, \file{Tools/scripts/cleanfuture.py} by Tim
    Peters, automatically removes obsolete \code{__future__} statements
***************
*** 823,828 ****
  suggestions and corrections to various drafts of this article: Fred
  Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Marc-Andr\'e Lemburg, Tim Peters, Neil Schemenauer, Guido van
! Rossum.
  
  \end{document}
--- 859,864 ----
  suggestions and corrections to various drafts of this article: Fred
  Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Jack Jansen, Marc-Andr\'e Lemburg, Tim Peters, Neil
! Schemenauer, Guido van Rossum.
  
  \end{document}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.22,1.23

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv15768

Modified Files:
	python-22.tex 
Log Message:
Add METH_O and METH_NOARGS change
Rewrite snprintf() item a bit
Bump version number


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.22
retrieving revision 1.23
diff -C2 -r1.22 -r1.23
*** python-22.tex	2001/08/15 15:55:48	1.22
--- python-22.tex	2001/08/29 01:16:54	1.23
***************
*** 4,8 ****
  
  \title{What's New in Python 2.2}
! \release{0.04}
  \author{A.M. Kuchling}
  \authoraddress{\email{aku...@me...}}
--- 4,8 ----
  
  \title{What's New in Python 2.2}
! \release{0.05}
  \author{A.M. Kuchling}
  \authoraddress{\email{aku...@me...}}
***************
*** 708,719 ****
    (Contributed by M.-A. Lemburg, and used for the MBCS support on
    Windows described in the previous section.)
!    
!   \item Two new wrapper functions, \cfunction{PyOS_snprintf()} and
!   \cfunction{PyOS_vsnprintf()} were added.   which provide a cross-platform
!   implementations for the relatively new snprintf()/vsnprintf() C lib
!   APIs. In contrast to the standard sprintf() and vsprintf() C lib
!   APIs, these versions apply bounds checking on the used buffer which
!   enhances protection against buffer overruns.
!   (Contributed by M.-A. Lemburg.)
  
  \end{itemize}
--- 708,729 ----
    (Contributed by M.-A. Lemburg, and used for the MBCS support on
    Windows described in the previous section.)
!  
!   \item Two new flags \constant{METH_NOARGS} and \constant{METH_O} are
!    available in method definition tables to simplify implementation of
!    methods with no arguments or a single untyped argument. Calling
!    such methods is more efficient than calling a corresponding method
!    that uses \constant{METH_VARARGS}. 
!    Also, the old \constant{METH_OLDARGS} style of writing C methods is 
!    now officially deprecated.  
! 
! \item
!    Two new wrapper functions, \cfunction{PyOS_snprintf()} and
!    \cfunction{PyOS_vsnprintf()} were added.  which provide a
!    cross-platform implementations for the relatively new
!    \cfunction{snprintf()} and \cfunction{vsnprintf()} C lib APIs. In
!    contrast to the standard \cfunction{sprintf()} and
!    \cfunction{vsprintf()} functions, the Python versions check the
!    bounds of the buffer used to protect against buffer overruns.
!    (Contributed by M.-A. Lemburg.)
  
  \end{itemize}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.21,1.22

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv8985

Modified Files:
	python-22.tex 
Log Message:
Note addition of cleanfuture.py


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.21
retrieving revision 1.22
diff -C2 -r1.21 -r1.22
*** python-22.tex	2001/08/11 03:06:50	1.21
--- python-22.tex	2001/08/15 15:55:48	1.22
***************
*** 738,741 ****
--- 738,747 ----
    \item The code for the Mac OS port for Python, maintained by Jack
    Jansen, is now kept in the main Python CVS tree.
+   % XXX should expand this with all of Jack's recent changes (ask him for 
+   % a summary)        
+   
+   \item A new script, \file{Tools/scripts/cleanfuture.py} by Tim
+   Peters, automatically removes obsolete \code{__future__} statements
+   from Python source code.
  
    \item The new license introduced with Python 1.6 wasn't

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.20,1.21

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv10592

Modified Files:
	python-22.tex 
Log Message:
Add section on PEP 238 changes
Minor grammatical changes, reformattings, and an error fix from Keith Briggs


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.20
retrieving revision 1.21
diff -C2 -r1.20 -r1.21
*** python-22.tex	2001/08/07 14:28:58	1.20
--- python-22.tex	2001/08/11 03:06:50	1.21
***************
*** 13,19 ****
  
  {\large This document is a draft, and is subject to change until the
! final version of Python 2.2 is released.  Currently it's not up to
! date at all.  Please send any comments, bug reports, or questions, no
! matter how minor, to \email{aku...@me...}.  }
  
  This article explains the new features in Python 2.2.  Python 2.2
--- 13,20 ----
  
  {\large This document is a draft, and is subject to change until the
! final version of Python 2.2 is released.  Currently it's up to date
! for Python 2.2 alpha 1.  Please send any comments, bug reports, or
! questions, no matter how minor, to \email{aku...@me...}.
! }
  
  This article explains the new features in Python 2.2.  Python 2.2
***************
*** 136,142 ****
  \end{verbatim}
  
! Iterator support has been added to some of Python's basic types.  The
! \keyword{in} operator now works on dictionaries, so \code{\var{key} in
! dict} is now equivalent to \code{dict.has_key(\var{key})}.
  Calling \function{iter()} on a dictionary will return an iterator
  which loops over its keys:
--- 137,141 ----
  \end{verbatim}
  
! Iterator support has been added to some of Python's basic types.  
  Calling \function{iter()} on a dictionary will return an iterator
  which loops over its keys:
***************
*** 165,171 ****
  values, or key/value pairs, you can explicitly call the
  \method{iterkeys()}, \method{itervalues()}, or \method{iteritems()}
! methods to get an appropriate iterator.  
  
! Files also provide an iterator, which calls its \method{readline()}
  method until there are no more lines in the file.  This means you can
  now read each line of a file using code like this:
--- 164,174 ----
  values, or key/value pairs, you can explicitly call the
  \method{iterkeys()}, \method{itervalues()}, or \method{iteritems()}
! methods to get an appropriate iterator.  In a minor related change,
! the \keyword{in} operator now works on dictionaries, so
! \code{\var{key} in dict} is now equivalent to
! \code{dict.has_key(\var{key})}.
  
! 
! Files also provide an iterator, which calls the \method{readline()}
  method until there are no more lines in the file.  This means you can
  now read each line of a file using code like this:
***************
*** 337,340 ****
--- 340,413 ----
  
  %======================================================================
+ \section{PEP 238: Changing the Division Operator}
+ 
+ The most controversial change in Python 2.2 is the start of an effort
+ to fix an old design flaw that's been in Python from the beginning.
+ Currently Python's division operator, \code{/}, behaves like C's
+ division operator when presented with two integer arguments.  It
+ returns an integer result that's truncated down when there would be
+ fractional part.  For example, \code{3/2} is 1, not 1.5, and
+ \code{(-1)/2} is -1, not -0.5.  This means that the results of divison
+ can vary unexpectedly depending on the type of the two operands and
+ because Python is dynamically typed, it can be difficult to determine
+ the possible types of the operands.
+ 
+ (The controversy is over whether this is \emph{really} a design flaw,
+ and whether it's worth breaking existing code to fix this.  It's
+ caused endless discussions on python-dev and in July erupted into an
+ storm of acidly sarcastic postings on \newsgroup{comp.lang.python}. I
+ won't argue for either side here; read PEP 238 for a summary of
+ arguments and counter-arguments.)
+ 
+ Because this change might break code, it's being introduced very
+ gradually.  Python 2.2 begins the transition, but the switch won't be
+ complete until Python 3.0.
+ 
+ First, some terminology from PEP 238.  ``True division'' is the
+ division that most non-programmers are familiar with: 3/2 is 1.5, 1/4
+ is 0.25, and so forth.  ``Floor division'' is what Python's \code{/}
+ operator currently does when given integer operands; the result is the
+ floor of the value returned by true division.  ``Classic division'' is
+ the current mixed behaviour of \code{/}; it returns the result of
+ floor division when the operands are integers, and returns the result
+ of true division when one of the operands is a floating-point number.
+ 
+ Here are the changes 2.2 introduces:
+ 
+ \begin{itemize}
+ 
+ \item A new operator, \code{//}, is the floor division operator.
+ (Yes, we know it looks like \Cpp's comment symbol.)  \code{//}
+ \emph{always} returns the floor divison no matter what the types of
+ its operands are, so \code{1 // 2} is 0 and \code{1.0 // 2.0} is also
+ 0.0.
+ 
+ \code{//} is always available in Python 2.2; you don't need to enable
+ it using a \code{__future__} statement.  
+ 
+ \item By including a \code{from __future__ import true_division} in a
+ module, the \code{/} operator will be changed to return the result of
+ true division, so \code{1/2} is 0.5.  Without the \code{__future__}
+ statement, \code{/} still means classic division.  The default meaning
+ of \code{/} will not change until Python 3.0.  
+ 
+ \item Classes can define methods called \method{__truediv__} and
+ \method{__floordiv__} to overload the two division operators.  At the
+ C level, there are also slots in the \code{PyNumberMethods} structure
+ so extension types can define the two operators.
+ 
+ % XXX a warning someday?
+ 
+ \end{itemize}
+ 
+ \begin{seealso}
+ 
+ \seepep{238}{Changing the Division Operator}{Written by Moshe Zadka and 
+ Guido van Rossum.  Implemented by Guido van Rossum..}
+ 
+ \end{seealso}
+ 
+ 
+ %======================================================================
  \section{Unicode Changes}
  
***************
*** 733,738 ****
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Fred L. Drake, Jr., Mark Hammond, Marc-Andr\'e
! Lemburg, Tim Peters, Neil Schemenauer, Guido van Rossum.
  
  \end{document}
--- 806,812 ----
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Fred L. Drake, Jr., Carel Fellinger, Mark
! Hammond, Marc-Andr\'e Lemburg, Tim Peters, Neil Schemenauer, Guido van
! Rossum.
  
  \end{document}

[Py-howto-checkins] CVS: pyhowto python-22.tex,1.19,1.20

[A.M. K. <aku...@us...>]

Update of /cvsroot/py-howto/pyhowto
In directory usw-pr-cvs1:/tmp/cvs-serv31033

Modified Files:
	python-22.tex 
Log Message:
Document two new items
Correct error noticed by Keith Briggs
Re-indent a paragraph


Index: python-22.tex
===================================================================
RCS file: /cvsroot/py-howto/pyhowto/python-22.tex,v
retrieving revision 1.19
retrieving revision 1.20
diff -C2 -r1.19 -r1.20
*** python-22.tex	2001/07/31 15:51:16	1.19
--- python-22.tex	2001/08/07 14:28:58	1.20
***************
*** 70,74 ****
  \method{__getitem__()} is more properly used to define an indexing
  operation on an object so that you can write \code{obj[5]} to retrieve
! the fifth element.  It's a bit misleading when you're using this only
  to support \keyword{for} loops.  Consider some file-like object that
  wants to be looped over; the \var{index} parameter is essentially
--- 70,74 ----
  \method{__getitem__()} is more properly used to define an indexing
  operation on an object so that you can write \code{obj[5]} to retrieve
! the sixth element.  It's a bit misleading when you're using this only
  to support \keyword{for} loops.  Consider some file-like object that
  wants to be looped over; the \var{index} parameter is essentially
***************
*** 511,519 ****
  
    \item The \module{xmlrpclib} module was contributed to the standard
! library by Fredrik Lundh.  It provides support for writing XML-RPC
! clients; XML-RPC is a simple remote procedure call protocol built on
! top of HTTP and XML. For example, the following snippet retrieves a
! list of RSS channels from the O'Reilly Network, and then retrieves a
! list of the recent headlines for one channel:
  
  \begin{verbatim}
--- 511,519 ----
  
    \item The \module{xmlrpclib} module was contributed to the standard
!   library by Fredrik Lundh.  It provides support for writing XML-RPC
!   clients; XML-RPC is a simple remote procedure call protocol built on
!   top of HTTP and XML. For example, the following snippet retrieves a
!   list of RSS channels from the O'Reilly Network, and then retrieves a
!   list of the recent headlines for one channel:
  
  \begin{verbatim}
***************
*** 586,589 ****
--- 586,594 ----
    (Reported by an unknown person; fixed by Fred L. Drake, Jr.)
  
+   \item The \module{mimetypes} module now makes it easier to use
+   alternative MIME-type databases by the addition of a
+   \class{MimeTypes} class, which takes a list of filenames to be
+   parsed.  (Contributed by Fred L. Drake, Jr.)
+ 
  \end{itemize}
  
***************
*** 702,706 ****
    \item On Windows, Python can now be compiled with Borland C thanks 
    to a number of patches contributed by Stephen Hansen.
! 
    \item Another Windows enhancement: Wise Solutions generously offered
    PythonLabs use of their InstallerMaster 8.1 system.  Earlier
--- 707,711 ----
    \item On Windows, Python can now be compiled with Borland C thanks 
    to a number of patches contributed by Stephen Hansen.
!   
    \item Another Windows enhancement: Wise Solutions generously offered
    PythonLabs use of their InstallerMaster 8.1 system.  Earlier
***************
*** 708,711 ****
--- 713,723 ----
    show its age.  (Packaged up by Tim Peters.)
  
+   \item Files ending in \samp{.pyw} can now be imported on Windows.
+   \samp{.pyw} is a Windows-only thing, used to indicate that a script
+   needs to be run using PYTHONW.EXE instead of PYTHON.EXE in order to
+   prevent a DOS console from popping up to display the output.  This
+   patch makes it possible to import such scripts, in case they're also
+   usable as modules.  (Implemented by David Bolen.)
+ 
    \item On platforms where Python uses the C \cfunction{dlopen()} function 
    to load extension modules, it's now possible to set the flags used 
***************
*** 721,726 ****
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Fred L. Drake, Jr., Mark Hammond, Marc-Andr\'e Lemburg,
! Tim Peters, Neil Schemenauer, Guido van Rossum.  
  
  \end{document}
--- 733,738 ----
  The author would like to thank the following people for offering
  suggestions and corrections to various drafts of this article: Fred
! Bremmer, Keith Briggs, Fred L. Drake, Jr., Mark Hammond, Marc-Andr\'e
! Lemburg, Tim Peters, Neil Schemenauer, Guido van Rossum.
  
  \end{document}