This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: MatchObject is not a hyperlink in the 're' module documentation
Type: behavior Stage: patch review
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7, Python 2.6
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: Asheesh.Laroia, amaury.forgeotdarc, brian.curtin, christian.heimes, ezio.melotti, georg.brandl, r.david.murray, rarana, serhiy.storchaka, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2009-07-21 22:29 by r.david.murray, last changed 2022-04-11 14:56 by admin. This issue is now closed.

File name Uploaded Description Edit
MatchObjectLinksFix.diff rarana, 2010-03-04 08:16
issue6538_corrections.diff brian.curtin, 2010-07-29 01:40 py3k patch
Messages (19)
msg90776 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2009-07-21 22:29
In the re documentation MatchObject is marked up as a class, but since
there's no declaration of it as a class (it's a section instead) it
doesn't get turned into a hyperlink.  It would be useful if it did link
to the appropriate section.
msg99644 - (view) Author: Ryan Arana (rarana) Date: 2010-02-21 04:53
Changed all occurrences of :class:`MatchObjects` to :ref:`match-objects` in /Doc/library/re.rst

These changes were made to rev 78277.
msg100116 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-02-25 22:27
Hey all,

I think this is ready. Can someone review the patch?
msg100123 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2010-02-25 23:04
It would be simpler to add a ".. class:: MatchObject" directive.
Also, RegexpObject should be handled as well.
msg100133 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-02-26 02:23
Ryan -- would you take a further look at this?
msg100379 - (view) Author: Ryan Arana (rarana) Date: 2010-03-04 08:16
Added .. class:: MatchObject and .. class:: RegexObject directives.
msg100684 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-03-09 00:20
Hey Ryan,

I took a look at the diff you attached here. It looks like you did 

There are some whitespace-only changes -- for example, you remove and then re-insert the line beginning with "The name of the last matched capturing group".

Can you re-submit your most recent patch without the unneeded whitespace-only changes?

There's a light at the end of the tunnel!
msg100688 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-03-09 01:16
I've reviewed the patch and do not see any unnecessary whitespace changes in his patch.
msg100691 - (view) Author: Ryan Arana (rarana) Date: 2010-03-09 01:44
I tried to format the methods of the class(es) as they are formatted in other files, which is why I added the whitespace. 

I can go back and remove that if that's what would be preferred.
msg100722 - (view) Author: Asheesh Laroia (Asheesh.Laroia) * Date: 2010-03-09 14:36
Er, ignore my comment then!

If this is reviewed, can it get committed?
msg101739 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-03-26 02:30
Fixed in trunk (r79430), release26-maint (r79631), py3k (r79434), and release31-maint (r79435). Thanks for the patch.
msg111874 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-28 23:41
I believe these patches are wrong, at least in part, and should be reverted.

1.The re module no longer has either a class RegexObject or a class MatchObject. (They are now _sre.SRE_Pattern and _sre.SRE_Match.) So 
the previous reference to them as anonymous "Compiled regular expression objects" and "Match objects" (lower case 'objects') was correct, certainly more correct that marking the fake names as real code. In other words. 'MatchObject' should be removed, not hyperlinked.

This issue came up today on python-list when someone tried "help(re.MatchObject)" and got a module attribute error. I was about to open a new issue when I discovered this one. I recommend changing the re.match entry from "return a corresponding MatchObject instance." to "return a match object" (which is what the current doc string says) and removing all the misleading RegexObject and MatchObject fake-class method prefixes, The prefixes are present in 2.6 and already removed in 2.7. I think they should also be removed from the 3.x docs. (Unless, of course, re is changed to add/reinstate those names, which could only happen in 3.2.)

2. I believe it is the policy that the 3.x docs 'start fresh' with 3.0. Ancient back-compatibility notes like

"(Incompatibility note: in the original Python 1.5 release, if the tuple was one element long, a string would be returned instead.  In later versions (from 1.5.1 on), a singleton tuple is returned in such cases.)"

were intentionally, not accidentally, removed in 3.0. So I think it a mistake to put revert the removal and that the reversion should be reverted.

3. This is more of a question. I have noticed that optional parameters with defaults are sometimes bracketed and sometimes not. Since the brackets are redundant, I prefer without as less cluttered and so I question the addition in the 3.2 patch. But is there a definitive current doc style guide? In any case, removing the default value while changing 'group=0' to '[group]' seems wrong.
msg111876 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-07-28 23:54
I'm guessing assigning to Christian was accidental - taking it back for myself.
msg111883 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-07-29 01:40
How does this patch look? It changes RegexObject to _sre.SRE_Pattern and MatchObject to _sre.SRE_Match. Additionally, references are used to link to those classes generically as "match objects" or "compiled regular expressions" rather than the fake classes used before.
msg111884 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-07-29 02:03
The patch looks good to me, but I'm not sure if it's a good idea to use _sre.SRE_*. I think these are implementation details and even if they should be mentioned somewhere, they "clutter" the doc IMHO.

> 2. I believe it is the policy that the 3.x docs 'start fresh' with 3.0.

Yes, they should be removed.

> 3. [...] In any case, removing the default value while changing 'group=0' to '[group]' seems wrong.

If it's possible to specify a default value the [] should be avoided.
msg111885 - (view) Author: Brian Curtin (brian.curtin) * (Python committer) Date: 2010-07-29 02:24
I didn't actually want to use _sre.SRE_* but I'm not exactly sure how to hide it. It's more correct that way, but it takes this issue the wrong direction by exposing it.

I think it should be denoted as a class but with a generic name, if that's even possible. It would actually be nice if the lines "class _sre.*" were just invisible.
msg111890 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-07-29 03:58
Please note that my original suggestion was to make them *section* links (:ref:s).  As Terry says, they are not real classes and should not be marked up as such.  Nor should the internal class names be exposed.

Terry: [] notation is 2.x, they should all be gone (with the possible exception of a few C functions) in the 3.x docs.
msg111913 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-07-29 11:50
Should be fixed now in r83218. I've removed the "class" directives, and put generic class name substitutes "regex" and "pattern" in the method descriptions, like we do for "contextmanager.__enter__".  I've also removed the compatibility info, and removed [] style arguments where feasible.
msg178037 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-12-24 08:37
I have opened a new issue16760 for regex HOWTO.
Date User Action Args
2022-04-11 14:56:51adminsetgithub: 50787
2012-12-24 08:37:24serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg178037
2010-07-29 11:50:47georg.brandlsetstatus: open -> closed
assignee: brian.curtin -> georg.brandl
resolution: fixed
messages: + msg111913
2010-07-29 03:58:11r.david.murraysetmessages: + msg111890
2010-07-29 02:24:14brian.curtinsetmessages: + msg111885
2010-07-29 02:03:48ezio.melottisetmessages: + msg111884
2010-07-29 01:41:00brian.curtinsetfiles: + issue6538_corrections.diff

messages: + msg111883
stage: patch review
2010-07-28 23:54:48brian.curtinsetpriority: low -> normal
assignee: christian.heimes -> brian.curtin
messages: + msg111876

stage: resolved -> (no value)
2010-07-28 23:41:24terry.reedysetstatus: closed -> open

nosy: + christian.heimes, terry.reedy
messages: + msg111874

assignee: brian.curtin -> christian.heimes
resolution: fixed -> (no value)
2010-03-26 02:30:29brian.curtinsetstatus: open -> closed
type: behavior
messages: + msg101739

assignee: georg.brandl -> brian.curtin
resolution: fixed
stage: needs patch -> resolved
2010-03-09 14:36:00Asheesh.Laroiasetmessages: + msg100722
2010-03-09 02:22:09ezio.melottisetnosy: + ezio.melotti
2010-03-09 01:44:35raranasetmessages: + msg100691
2010-03-09 01:41:19raranasetfiles: - MatchObjectLinksFix.diff
2010-03-09 01:16:22brian.curtinsetnosy: + brian.curtin
messages: + msg100688
2010-03-09 00:20:12Asheesh.Laroiasetmessages: + msg100684
2010-03-04 08:16:52raranasetfiles: + MatchObjectLinksFix.diff

messages: + msg100379
2010-02-26 02:23:39Asheesh.Laroiasetmessages: + msg100133
2010-02-25 23:04:40amaury.forgeotdarcsetnosy: + amaury.forgeotdarc
messages: + msg100123
2010-02-25 22:27:32Asheesh.Laroiasetnosy: + Asheesh.Laroia
messages: + msg100116
2010-02-21 04:53:06raranasetfiles: + MatchObjectLinksFix.diff

nosy: + rarana
messages: + msg99644

keywords: + patch
2009-07-21 22:29:21r.david.murraycreate