[docs] Bug in RE module documentation

[Gene Wood]

Sandro,
   Thanks very much for your response.

Regarding the difference between the 2.6 and 2.7 documentation, indeed
you're correct. I should have sent this link instead :

http://docs.python.org/release/2.6/library/re.html#re.compile

However the text that I'm referring to is identical in the 2.7 and 2.6 docs.

If the intent of this part of the doc is "to give a clue, mentioning the
most commonly used
methods" I would recommend changing the language from :

"Compile a regular expression pattern into a regular expression object,
which can be used for matching using its match() and search() methods,
described below."

which is very specific to something like :

"Compile a regular expression pattern into a regular expression object,
which can be used for matching using methods such as match() and search(),
described below."

which conveys that "match" and "search" are merely the most commonly used
methods and that all methods apply. The existing method implies those 2
methods specifically.

-Gene



On Wed, Aug 24, 2011 at 3:19 PM, Sandro Tosi <sandro.tosi at gmail.com> wrote:

> Hello Gene,
> thanks for your email.
>
> On Wed, Aug 24, 2011 at 07:19, Gene Wood <gene_wood at cementhorizon.com>
> wrote:
> > http://docs.python.org/library/re.html#re.compile
> > The doc says : "Compile a regular expression pattern into a regular
> > expression object, which can be used for matching using its match() and
> > search() methods, described below."
> > However if you do a dir of the resulting object under python 2.6 the
> object
> > actually supports all of the methods listed in the doc.
> > I went around trying to figure out how I was going to upgrade to python
> 2.7
> > in order to do a multiline "subn" regex and then found a
> stackoverflow.com
> > answer that indicated you could call "subn" from this object. I then did
> a
> > dir on the object and found it supported all the methods.
>
> Just let me clarify one thing first: the link you mentioned at the
> beginning of the email is referring to python 2.7, so trying to match
> that documentation against 2.6 can results in some incongruences and
> ambiguities. If you're working on 2.6 (even thought we suggest to
> upgrade to the latest supported version, 2.7 in this case) you may
> want to refer to the 2.6-specific documentation:
> http://docs.python.org/release/2.6/
>
> > I suggest you change the doc to either say :
> > "Compile a regular expression pattern into a regular expression object,
> > which can be used for matching using its match(), search(), split(),
> > findall(), finditer(), sub() and subn() methods, described below."
> > or
> > "Compile a regular expression pattern into a regular expression object,
> > which can be used for matching using any of the methods described below."
>
> With that said above, I don't think the documentation should list all
> the available methods form the resulting object. What I think the doc
> is trying to do is to give a clue, mentioning the most commonly used
> methods.
>
> Regards,
> --
> Sandro Tosi (aka morph, morpheus, matrixhasu)
> My website: http://matrixhasu.altervista.org/
> Me at Debian: http://wiki.debian.org/SandroTosi
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110824/78b433c5/attachment.html>