[Python-Dev] Revising RE docs (was: partition() (was: Remove str.find in 3.0?))

[Michael Chermside]

Barry Warsaw writes:
> Although it's mildly annoying that the docs describe the compiled method
> names in terms of the uncompiled functions.  I always find myself
> looking up the regexp object's API only to be shuffled off to the
> module's API and then having to do the argument remapping myself.

An excellent point. Obviously, EITHER (1) the module functions ought to
be documented by reference to the RE object methods, or vice versa:
(2) document the RE object methods by reference to the module functions.

(2) is what we have today, but I would prefer (1) to gently encourage
people to use the precompiled objects (which are distinctly faster when
re-used).

Does anyone else think we ought to swap that around in the documentation?
I'm not trying to assign more work to Fred... but if there were a
python-dev consensus that this would be desirable, then perhaps someone
would be encouraged to supply a patch.

-- Michael Chermside