Fix SF bug 419062: building pbs on AIX 4.3.2

Apply patch from "china@thewrittenword.com" to put the correct
location for ld_so_aix in BLDSHARED.

Merged changes from 22a4 branch.

For Python 2.2 and newer, actually support the full NodeList interface by
subclassing list to add the length and item() attributes.

Merge branch changes (coercion, rich comparisons) into trunk.

Add entries for the email and compiler packages.

Markup adjustments.

Added dependencies for the compiler and email packages.
(Migrate to branch, along with new files compiler.tex and asttable.tex.)

Migrate the compiler documentation from the Tools/compiler/doc/ directory.
Changes made to make it work in the new location.

Do not distinguish \refmodule from \module in the generated output;
whether or not a link will be generated will depend on the link database.
Add a couple of explanatory comments for one of the stranger constructs
(giving input an empty name).

Re-write <ulink> elements as described in the conversion spec.

Change the sense of a test in how the profiler interprets exception events.
This should fix a bug in how time is allocated during exception propogation
(esp. in the presence of finally clauses).

Bump Windows build numbers for 2.2a4; installer changes were done earlier.

Turn \input, \include, and \verbatiminput into XInclude elements instead
of something ad-hoc.

Added note about new StringIO/cStringIO feature.

Add support for some more markup that had slipped in.
Fixed a typo in a comment.

Fix comment typo

Fix some markup errors.

Markup adjustment: \[...\] is math markup and does not translate well when
used with text as was done here.  Fixed so that the typeset version wraps
the warning text and the HTML version does not create images of the warning
text.

docroutine() (both instances):  Docstrings for class methods weren't
getting displayed, due to a special case here whose purpose I didn't
understand.  So just disabled the doc suppression here.

Another special case here skips the docs when picking apart a method
and finding that the im_func is also in the class __dict__ under
the same name.  That one I understood.  It has a curious consequence,
though, wrt inherited properties:  a static class copies inherited stuff
into the inheriting class's dict, and that affects whether or not this
special case triggers.  The upshoot is that pydoc doesn't show the
function docstrings of getter/setter/deleter functions of inherited
properties in the property section when the class is static, but does
when the class is dynamic (bring up Lib/test/pydocfodder.py under
GUI pydoc to see this).

List class attrs in MRO order of defining class instead of by alphabetic
order of defining class's name.

Removed no-longer-true comment about pydoc working under all versions of
Python since 1.5 (virtually everything I changed over the last week relies
on "modern" features, particularly nested scopes).

Remove comment that no longer applies.

Updates do email package documentation for markup, style, and
organization.

Display a class's method resolution order, if it's non-trivial.  "Trivial"
here means it has no more than one base class to rummage through (in which
cases there's no potential confusion about resolution order).

More test cases, including something that simulates what the profiler
probably *should* be doing.

A file just to look at (using pydoc).

Add tests for new PyErr_NormalizeException() behavior

Add raise_exception() to the _testcapi module.  It isn't a test, but
the C API exists only to support test_exceptions.  raise_exception()
takes two arguments -- an exception class and an integer specifying
how many arguments it should be called with.

test_exceptions uses BadException() to test the interpreter's behavior
when there is a problem instantiating the exception.  test_capi1()
calls it with too many arguments.  test_capi2() causes an exception to
be raised in the Python code of the constructor.

PyErr_NormalizeException()

If a new exception occurs while an exception instance is being
created, try harder to make sure there is a traceback.  If the
original exception had a traceback associated with it and the new
exception does not, keep the old exception.

Of course, callers to PyErr_NormalizeException() must still be
prepared to have tb set to NULL.

XXX This isn't an ideal solution, but it's better than no traceback at
all.  It occurs if, for example, the exception occurs when the call to
the constructor fails before any Python code is executed.  Guido
suggests that it there is Python code that was about to be executed
-- but wasn't, say, because it was called with the wrong number of
arguments -- then we should point at the first line of the code object
anyway.

Don't export generators future info

Prevent a NULL pointer from being pushed onto the stack.

It's possible for PyErr_NormalizeException() to set the traceback
pointer to NULL.  I'm not sure how to provoke this directly from
Python, although it may be possible.  The error occurs when an
exception is set using PyErr_SetObject() and another exception occurs
while PyErr_NormalizeException() is creating the exception instance.

XXX As a result of this change, it's possible for an exception to
occur but sys.last_traceback to be left undefined.  Not sure if this
is a problem.

Move the styling for the HTML version of \mailheader into the CSS file.
In both the HTML and typeset versions of the documentation, add a colon
after the name of a mail header so that it is more easily distinguished
from other text.

Note that the colon following a mail header name should not be included
when using the \mailheader markup.
Change a couple of inline examples to show the markup rather than the
result.

Typo fix.

Move the \mailheader description to the right place.
Clarify the \mimetype description; it can be used to refer to a part of a
MIME type name, so \mimetype{text} or \mimetype{plain} can be used, not
just \mimetype{text/plain}.

Start making some markup adjustments; Barry has indicated he will work on
this before we finish the integration, along with some restructuring.

Test case for SF bugs #463359 and #462937, added to test_grammar for lack of
a better place. Excessively fragile code, but at least it breaks when
something in this area changes!

Update the tests for the current incarnation of the email package, and
added some new tests of message/delivery-status content type messages.

More test messages for test_email.py

_parsebody(): Use get_boundary() and get_type().

    Also, add a clause to the big-if to handle message/delivery-status
    content types.  These create a message with subparts that are
    Message instances, which best represent the header blocks of this
    content type.

has_key(): Implement in terms of get().

get_type(): Use a compiled regular expression, which can be shared.

_get_params_preserve(): A helper method which extracts the header's
    parameter list preserving value quoting.  I'm not sure that this
    needs to be a public method.  It's necessary because we want
    get_param() and friends to return the unquoted parameter value,
    however we want the quote-preserved form for set_boundary().

get_params(), get_param(), set_boundary(): Implement in terms of
    _get_params_preserve().

walk(): Yield ourself first, then recurse over our subparts (if any).

__init__(): Arguments major renamed to maintype and minor renamed to
    subtype for consistency with the rest of the package.

Updated docstrings.  Also,

typed_subpart_iterator(): Arguments major renamed to maintype and
    minor renamed to subtype for consistency with the rest of the
    package.

Image.py and class Image => MIMEImage.py and MIMEImage

Text.py and class Text => MIMEText.py and MIMEText

MessageRFC822.py and class MessageRFC822 => MIMEMessage.py and MIMEMessage

These are renamed so as to be more consistent; these are MIME specific
derived classes for when creating the object model out of whole cloth.

In class Generator:

    _handle_text(): If the payload is None, then just return (i.e. don't
write anything).  Subparts of message/delivery-status types
will have this property since they are just blocks of headers.

Also, when raising the TypeError, include the type of the
payload in the error message.

    _handle_multipart(), _handle_message(): When creating a clone of self,
pass in our _mangle_from_ and maxheaderlen flags so the clone
has the same behavior.

    _handle_message_delivery_status(): New method to do the proper
printing of message/delivery-status type messages.  These have
to be handled differently than other message/* types because
their payloads are subparts containing just blocks of headers.

In class DecodedGenerator:

    _dispatch(): Skip over multipart/* messages since we don't care
        about them, and don't want the non-text format to appear in
        the printed results.

cosmetic

The email package documentation, currently organized the way I think
Fred prefers.  I'm not sure I like this organization, so it may change.

SF [#463737] Add types.CallableIterType
Rather than add umpteen new obscure internal Iter types, got rid of all of
them.  See the new comment.

test_iterator(): Don't do a type comparison to see if it's an
iterator, just test to make sure it has the two required iterator
protocol methods __iter__() and next() -- actually just test
hasattr-ness.

add_operators(): the __floordiv__ and __truediv__ descriptors (and
their 'i' and 'r' variants) were not being generated if the
corresponding nb_ slots were present in the type object.  I bet this
is because floor and true division were introduced after I last
looked at that part of the code.

Update to support \mailheader and 5-column tables.

Simplify a helper by returning fewer values.

Factor out the protect-from-exceptions helpers and make capture_events()
use it.  This simplifies the individual tests a little.

Added some new tests related to exception handling.

Guido points out that sys.__stdout__ is a bit bucket under IDLE.  So keep
the local save/modify/restore of sys.stdout, but add machinery so that
regrtest can tell test_support the value of sys.stdout at the time
regrtest.main() started, and test_support can pass that out later to anyone
who needs a "visible" stdout.

_reconstructor(): there's no need for tricks with assignment to
__class__.  The __new__ protocol is up to this.  (Thanks to Tim for
pointing this out.)

test_support should be imported directly, not via test.test_support.

Get rid of the increasingly convoluted global tricks w/ sys.stdout, in
favor of local save/modify/restore.  The test suite should run fine again.

Clarified some points about the interface to the mmap() function.
This closes SF bug #448918.

Minor changes.

Revise the example to be more resiliant in the face of continued use after
the object has been pickled; don't mutate the instance dict in the
__getstate__() method.  Other minor changes for style.  Broke up the
displayed interactive session to get better page-breaking behavior for
typeset versions, and to point out an important aspect of the example.

This closes SF bug #453914.

- Provisional support for pickling new-style objects. (*)

- Made cls.__module__ writable.

- Ensure that obj.__dict__ is returned as {}, not None, even upon first
  reference; it simply springs into life when you ask for it.

(*) The pickling support is provisional for the following reasons:

- It doesn't support classes with __slots__.

- It relies on additional support in copy_reg.py: the C method
  __reduce__, defined in the object class, really calls calling
  copy_reg._reduce(obj).  Eventually the Python code in copy_reg.py
  needs to be migrated to C, but I'd like to experiment with the
  Python implementation first.  The _reduce() code also relies on an
  additional helper function, _reconstructor(), defined in
  copy_reg.py; this should also be reimplemented in C.

Set sys.save_stdout (to sys.stdout), so doctest-using tests can be run
standalone.

Added documentation for the SSL interface, contributed by Gerhard Häring.
This closes SF patch #461337.

Fix a URL (closing SF patch #462195).
Cleaned up a bunch of XXX comments containing links to additional
information, replacing them with proper references.
Replaced "MacOS" with "Mac OS", since that's what the style guide says.

SF patch #459385 (Norman Vine): time.timezone fix for Cygwin.

Also did some whitespace normalization.

+ Display property functions in the same order they're specified to
  property() (get, set, del; not set, get, del).

+ Change "Data defined/inherited in ..." header lines to
  "Data and non-method functions defined/inherited in ...".  Things like
  the value of __class__, and __new__, and class vrbls like the i in
      class C:
          i = int
  show up in this section too.  I don't think it's worth a separate
  section to distinguish them from non-callable attrs, and there's no
  obvious reliable way to distinguish callable from non-callable attrs
  anyway.

Note a few tasks that are done now.

Separate out the type/class-related news and reword some items.

Add news items about comparisons, repr(), __class__ assignment.

Change repr() of a new-style class to say <class 'ClassName'> rather
than <type 'ClassName'>.  Exception: if it's a built-in type or an
extension type, continue to call it <type 'ClassName>.  Call me a
wimp, but I don't want to break more user code than necessary.

Make __class__ assignment possible, when the object structures are the
same.  I hope the test for structural equivalence is stringent enough.
It only allows the assignment if the old and new types:

- have the same basic size
- have the same item size
- have the same dict offset
- have the same weaklist offset
- have the same GC flag bit
- have a common base that is the same except for maybe the dict and
  weaklist (which may have been added separately at the same offsets
  in both types)

+ Got rid of all instances of <small>.  Under IE5, GUI-mode pydoc has
  always been close to useless, because the <small>-ified docstrings
  were too small to read, even after cranking up my default font size
  just for pydoc.  Now it reads fine under my defaults (as does most
  of the web <0.5 wink>).  If it's thought important to play tricks
  with font size, tough, then someone should rework pydoc to use style
  sheets, and (more) predictable percentage-of-default size controls.

+ Tried to ensure that all <dt> and <dd> tags are closed.  I've read (but
  don't know) that some browsers get confused if they're not, and esp.
  when style sheets are in use too.

GUI mode now displays useful stuff for properties.  This is usually better
than text mode, since here we can hyperlink from the getter etc methods
back to their definitions.

+ Text-mode (but not yet GUI mode) pydoc now produces useful stuff for
  properties:  the docstring (if any) is displayed, and the getter, setter
  and deleter (if any) functions are named.  All that is shown indented
  after the property name.

+ Text-mode pydoc class display now draws a horizontal line between
  class attribute groups (similar to GUI mode -- while visually more
  intrusive in text mode, it's still an improvement).

Make properties discoverable from Python:

- property() now takes 4 keyword arguments:  fget, fset, fdel, doc.
  Note that the real purpose of the 'f' prefix is to make fdel fit in
  ('del' is a keyword, so can't used as a keyword argument name).

- These map to visible readonly attributes 'fget', 'fset', 'fdel',
  and '__doc__' in the property object.

- fget/fset/fdel weren't discoverable from Python before.

- __doc__ is new, and allows to associate a docstring with a property.

Added several new tests to check the behavior with respect to doctype
declarations and weird markup that we used to accept & ignore that recent
versions raised an exception for; the original behavior has been restored
and augmented (the user can decide what to do if they care; the default is
to ignore it as done in early versions).

Adapt to use the test_main() approach.

Re-factor the SGMLParser class to use the new markupbase.ParserBase class.
Use a new internal method, error(), consistently to raise parse errors;
the new base class also uses this.
Adjust the parse_comment() method to return the new offset into the buffer
instead of the number of characters scanned; this was the only helper
method that did it this way, so we have better consistency now.  Required
to share the new base class.
This fixes SF bug #448482 and #453706.

Re-factor the HTMLParser class to use the new markupbase.ParserBase class.
Use a new internal method, error(), consistently to raise parse errors;
the new base class also uses this.

Be consistent about the string module.

New base class for the SGMLParser and HTMLParser classes from the sgmllib
and HTMLParser modules (and indirectly for the htmllib.HTMLParser class).

This has all the support for scanning over DOCTYPE declarations; it warrants
having a base class since this is a fair amount of tedious code (since it's
fairly strict), and should be in a separate module to avoid compiling many
REs that are not used (which would happen if this were placed in either then
sgmllib or HTMLParser module).

Don't swap the arguments to PyFrame_BlockSetup when recreating the recently
popped frame-block. What an embarrassing bug! Especially for Jeremy, since
he accepted the patch :-)

This fixes SF bugs #463359 and #462937, and possibly other, *very* obscure
bugs with very deeply nested loops that continue the loop and then break out
of it or raise an exception.

Another comparison patch-up: comparing a type with a dynamic metatype
to one with a static metatype raised an obscure error.

Add more tests showing the relationship between exceptions raised & caught
and the information provided to the profiler.  This stuff is a mess!

Do the same thing to complex that I did to str: the rich comparison
function returns NotImplemented when comparing objects whose
tp_richcompare slot is not itself.

StringIO patch #462596: let's [c]StringIO accept read buffers on
input to .write() too.

Fixed old bug (caused by careless Carbonizing) that noone noticed until
this week (apparently me and Bob Heeter at more or less the same time).

Patch #463421: speed up md5 module with real memcpy/set.

Change string comparison so that it applies even when one (or both)
arguments are subclasses of str, as long as they don't override rich
comparison.

Fix the baffler that Tim reported: sometimes the repr() of an object
looks like <X object at ...>, sometimes it says <X instance at ...>.
Make this uniformly say <X object at ...>.

Add more signature information and some descriptions for the new APIs
introduced in Python 2.2.
Add documentation for the slice object interface (not complete).
Added version annotations for several of the Python 2.2 APIs already
documented.

Add more reference count information.

Add link to Unix Review's 2.2 article
Fix two errors

start of new config handling stuff

More work on class display:

+ Minor code cleanup, generalization and simplification.

+ "Do something" to make the attribute aggregation more apparent:
    - In text mode, stick a "* " at the front of subgroup header lines.
    - In GUI mode, display a horizontal rule between subgroups.
   For GUI mode, this is a huge improvement, at least under IE.

Try to do for pydoc's GUI mode what the earlier checkin did for text
mode (identify the source class for class attrs; segregate attrs according
to source class, and whether class method, static method, property, plain
method, or data; display data attrs; display docstrings for data attrs
when possible).

Alas, this is mondo ugly, and I'm no HTML guy.  Part of the problem is
that pydoc's GUI mode has always been ugly under IE, largely because
<small> under IE renders docstrings unreadably small (while sometimes
non-docstring text is painfully large).  Another part is that these
segregated listings of attrs would *probably* look much better as bulleted
lists.  Alas, when I tried that, the bullets all ended up on lines by
themselves, before the method names; this is apparently because pydoc
(ab?)uses definition lists for format effects, and at least under IE
if a definition list is the first chunk of a list item, it gets rendered
on a line after the <li> bullet.

An HTML wizard would certainly be welcomed here.

Added a note about the new email package.

Part of a partial solution to SF bugs 463378, 463381, 463383, 463384.
This almost entirely replaces how pydoc pumps out class docs, but only
in text mode (like help(whatever) from a Python shell), not in GUI mode.

A class C's attrs are now grouped by the class in which they're defined,
attrs defined by C first, then inherited attrs grouped by alphabetic order
of the defining classes' names.

Within each of those groups, the attrs are subgrouped according to whether
they're plain methods, class methods, static methods, properties, or data.
Note that pydoc never dumped class data attrs before.  If a class data
attr is implemented via a data descriptor, the data docstring (if any)
is also displayed (e.g., file.softspace).

Within a subgroup, the attrs are listed alphabetically.

This is a friggin' mess, and there are bound to be glitches.  Please
beat on it and complain!  Here are three glitches:

1. __new__ gets classifed as 'data', for some reason.  This will
   have to get fixed in inspect.py, but since the latter is already
   looking for any clue that something is a method, pydoc will
   almost certainly not know what to do with it when its classification
   changes.

2. properties are special-cased to death.  Unlike any other kind of
   function or method, they don't have a __name__ attr, so none of
   pydoc's usual code can deal with them.  Worse, the getter and
   setter and del'er methods associated with a property don't appear
   to be discoverable from Python, so there's really nothing I can
   think of to do here beyond just listing their names.

   Note that a property can't be given a docstring, either (or at least
   I've been unable to sneak one in) -- perhaps the property()
   constructor could take an optional doc argument?

3. In a nested-scopes world, pydoc still doesn't know anything about
   nesting, so e.g. classes nested in functions are effectively invisible.

Reactivate participation of expat parsers in GC. Fixes bug #462710.

Install the new Lib/email pkg.
Create & populate the new Lib/test/data directory.

Generalize file.writelines() to allow iterable objects.

The test data (mostly example messages) for the email package test
suite.  Note that other tests can put input data in this directory.