re.flags not documented in Module Contents as promised.

[4Dummies]

BPO	28951
Nosy	@ezio-melotti, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-12-12.18:57:28.437>
labels = ['expert-regex', 'easy', '3.9', '3.10', '3.11', 'type-feature', 'docs']
title = 're.flags not documented in Module Contents as promised.'
updated_at = <Date 2022-04-05.08:42:26.298>
user = 'https://bugs.python.org/4Dummies'

bugs.python.org fields:

activity = <Date 2022-04-05.08:42:26.298>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Regular Expressions']
creation = <Date 2016-12-12.18:57:28.437>
creator = '4Dummies'
dependencies = []
files = []
hgrepos = []
issue_num = 28951
keywords = ['easy']
message_count = 7.0
messages = ['283034', '283037', '283462', '283487', '283493', '283494', '283503']
nosy_count = 5.0
nosy_names = ['ezio.melotti', 'mrabarnett', 'r.david.murray', 'docs@python', '4Dummies']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28951'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

[4Dummies]

In the online documentation of module re
(https://docs.python.org/3.5/library/re.html)
under
6.2.1. Regular Expression Syntax
for item
(?aiLmsux)
we are promised "The flags are described in Module Contents"
but no description is found there. In fact a number of other references are found to flags, but no description of the individual flags. AFAICT the closest thing to a description is found at the original reference -- at least it gives a code and name for each one.

[bitdancer]

When I follow the link to module contents, I find a list of the flags with their descriptions. (re.A, re.I, etc, etc). Perhaps you are confusing the letters used in the regular expression to represent the flags with the flags themselves? I'm not sure how we could make that clearer.

[4Dummies]

Ordinarily when I see a cross-reference like that "the flags are described
in foo" I expect foo to have a heading "FLAGS" so I can tell I'm looking at
what was promised. Not knowing much about flags, it was not clear to me
that those scattered lines re.A through re.X were the promised
descriptions. I didn't even notice them until now, partly because it's
made more confusing by all the stuff that's out of alphabetic order. Or I
think it is -- it's hard to tell because of things like re.S and re.DOTALL
being together. My current guess is that the uppercase things come before
lowercase, but those odd pairings are definitely messing with my mind.

All of which is just to say it probably makes perfect sense to someone
who's used to it, but it's hard on someone new to these docs, and I'm not
even new to Python, just to the re module.

On Mon, Dec 12, 2016 at 11:03 AM, R. David Murray <report@bugs.python.org>
wrote:

R. David Murray added the comment:

When I follow the link to module contents, I find a list of the flags with
their descriptions. (re.A, re.I, etc, etc). Perhaps you are confusing the
letters used in the regular expression to represent the flags with the
flags themselves? I'm not sure how we could make that clearer.

----------
nosy: +r.david.murray

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue28951\>

---

-- 
Kevin O'Gorman
#define QUESTION ((bb) || (!bb))   /* Shakespeare */

Please consider the environment before printing this email.

[bitdancer]

Making a 'flags' subheading in module contents would be reasonable. Alternatively we could just drop that parenthetical, since the descriptions for each flag are themselves cross-linked.

[4Dummies]

Well, my original problem is that I wanted to find out what the flags did
and could not find any pointer in the table of contents. I think they
deserve either really good cross-references, or a heading in the contents.
And a non-confusing alphabetized list, if they're going to be mixed in with
other module contents.

On Sat, Dec 17, 2016 at 6:13 AM, R. David Murray <report@bugs.python.org>
wrote:

R. David Murray added the comment:

Making a 'flags' subheading in module contents would be reasonable.
Alternatively we could just drop that parenthetical, since the descriptions
for each flag are themselves cross-linked.

----------

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue28951\>

---

-- 
Kevin O'Gorman
#define QUESTION ((bb) || (!bb))   /* Shakespeare */

Please consider the environment before printing this email.

[4Dummies]

Oh, and on the alphabetized list, I suggest NOT listing synonyms together,
but just mark some as "synonym for X" and listing them all alphabetically
(according to "en" collation, not "C" so upper- and lower-case sort
together, not separately).

On Sat, Dec 17, 2016 at 6:13 AM, R. David Murray <report@bugs.python.org>
wrote:

R. David Murray added the comment:

Making a 'flags' subheading in module contents would be reasonable.
Alternatively we could just drop that parenthetical, since the descriptions
for each flag are themselves cross-linked.

----------

---

Python tracker <report@bugs.python.org>
<http://bugs.python.org/issue28951\>

---

-- 
Kevin O'Gorman
#define QUESTION ((bb) || (!bb))   /* Shakespeare */

Please consider the environment before printing this email.

[bitdancer]

(Please delete the message you are replying to when responding to bug tracker emails.)

I think a section heading would be good (three subheads under module contents: functions, flags, and exceptions). I'm less in favor of alphabetical entries for synonyms. We'll see what others think.