Clarify flag case in
re module docstring
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
assignee = 'https://github.com/terryjreedy' closed_at = <Date 2020-03-25.21:59:45.363> created_at = <Date 2020-03-19.17:40:50.780> labels = ['type-feature', '3.9', 'docs'] title = 'Clarify flag case in `re` module docstring' updated_at = <Date 2020-03-25.21:59:45.363> user = 'https://github.com/cool-RR'
activity = <Date 2020-03-25.21:59:45.363> actor = 'terry.reedy' assignee = 'terry.reedy' closed = True closed_date = <Date 2020-03-25.21:59:45.363> closer = 'terry.reedy' components = ['Documentation'] creation = <Date 2020-03-19.17:40:50.780> creator = 'cool-RR' dependencies =  files =  hgrepos =  issue_num = 40016 keywords = ['patch'] message_count = 16.0 messages = ['364617', '364618', '364619', '364620', '364621', '364622', '364625', '364631', '364716', '364734', '364773', '364777', '364778', '365010', '365014', '365015'] nosy_count = 6.0 nosy_names = ['terry.reedy', 'mrabarnett', 'cool-RR', 'docs@python', 'serhiy.storchaka', 'miss-islington'] pr_nums = ['19078', '19161', '19162'] priority = 'normal' resolution = 'fixed' stage = 'resolved' status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue40016' versions = ['Python 3.9']
The text was updated successfully, but these errors were encountered:
Today I was tripped up by an inconsistency in the
The DOTALL flag appears as an uppercase S in 2 places, and as a lowercase s in one place. This is confusing, and I initially tried using the uppercase S only to get an error.
I'm attaching a PR to this ticket.
I'm gonna look past the rudeness, and I'll just say that if I was tripped up by this, after 11 years of working with Python and the re module, then people in a beginner or intermediate level could be tripped up by this as well.
Here's another, simpler suggestion for preventing confusion. Replace this line in the docstring:
With this line:
There's no reason to mention the letters there because they're already mentioned. And it's helpful to add a short explanation, like the other entries in that list.
I apologize if I was rude. It's only because of my bad English. There were many translation options for my words suggested by Google Translator and I obviously picked up the wrong one.
Improving documentation is always a good thing. But I leave the final decision to someone who is fluent in English.
The root confusion is that re compilation has several variations with two sets of indicators, each with an unhelpful exception, and each combined and used in different ways.
The additional issue for docstrings is the extreme compression, including the omission (here) of 're.' prefixes. They are intended as reminders for those who have read and understood the full doc, but we try to make them as clear as possible. I am working on an alternate revision.
The docstring line in question is
This is exceptional in that other syntaxes in the special characters list use lower case only for syntax variables (m, n, name, id/name, yes, no). Here, each letter is a separate and literal special character. (Also exceptional is that the syntax given is illegal, as 'a', 'L', and 'u' are mutually exclusive.)
The corresponding doc entry starts
I suggest the following as the replacement here (followed by more 'below').
I think 'letters' pretty clearly refers to 'a', 'i', ..., and 'x' as given, and that each 'corresponds' to and sets a flag that is a separate entity.
The more complicated inline flags syntax, "(?aiLmsux-imsx:...)", is omitted from the docstring. Perhaps this is intentional.
The flag constants are currently introduced by
My suggested more accurate and expanded replacement: