Repository navigation
backport re.compile flags default value documentation #57084
Description
| BPO | 12875 |
|---|---|
| Nosy | @birkenfeld, @rhettinger, @amauryfa, @pitrou, @ezio-melotti, @merwok |
| Files |
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 = <Date 2011-11-13.22:53:25.733>
created_at = <Date 2011-09-01.05:17:07.853>
labels = ['docs']
title = 'backport re.compile flags default value documentation'
updated_at = <Date 2011-11-14.04:21:47.472>
user = 'https://bugs.python.org/elibendersky'bugs.python.org fields:
activity = <Date 2011-11-14.04:21:47.472>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-11-13.22:53:25.733>
closer = 'eli.bendersky'
components = ['Documentation']
creation = <Date 2011-09-01.05:17:07.853>
creator = 'eli.bendersky'
dependencies = []
files = ['23668']
hgrepos = []
issue_num = 12875
keywords = ['patch']
message_count = 19.0
messages = ['143300', '143301', '143304', '143305', '143306', '143419', '147442', '147445', '147446', '147459', '147461', '147462', '147465', '147467', '147470', '147516', '147543', '147544', '147574']
nosy_count = 9.0
nosy_names = ['georg.brandl', 'rhettinger', 'amaury.forgeotdarc', 'pitrou', 'ezio.melotti', 'eric.araujo', 'eli.bendersky', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue12875'
versions = ['Python 2.7']
Activity
elibendersky commentedon Sep 1, 2011
In the 2.7 docs, re.compile has this signature:
From here it isn't clear what the default value of 'flags' is, to be able to write code like this:
Of course, looking at the source shows immediately that the default flag value is 0 (which is kind-of implied by the flags being a bit-OR of flags, but not mentioned explicitly).
I saw that in the latest 3K docs, it is documented properly:
Naturally this applies to other methods of 're' that take 'flags'.
I hope I'm not missing something and this really is just a documentation issue. If no objections arise, I will commit a fix to the docs of 're' in 2.7
ezio-melotti commentedon Sep 1, 2011
I don't think you are missing anything, but using ints instead of flags is discouraged (see bpo-11957). OTOH there's no re.NOFLAGS flag that can be used instead.
ezio-melotti commentedon Sep 1, 2011
Two more things:
elibendersky commentedon Sep 1, 2011
Ezio,
"but using ints instead of flags is discouraged (see bpo-11957). OTOH there's no re.NOFLAGS flag that can be used instead."
Indeed, there's no re.NOFLAGS, and as I mentioned the 3k docs mention 0 as the default value, thus (in a way) encouraging passing the numeric value.
Perhaps re.NOFLAGS should be added (at least in 3.3)? The docs can then be modified to specify it as the default value of 'flags' instead of 0.
elibendersky commentedon Sep 1, 2011
Regarding backporting 106ee4eb5970 - it's probably a good thing to do but I wouldn't mix it with this issue.
merwok commentedon Sep 2, 2011
+1 to backporting [flags=0].
python-dev commentedon Nov 11, 2011
New changeset 02e4d3ebbb02 by Eli Bendersky in branch '2.7':
Issue bpo-12875: explicitly specify default value of the optional 'flags' argument to re.* functions. Closes bpo-12875
http://hg.python.org/cpython/rev/02e4d3ebbb02
amauryfa commentedon Nov 11, 2011
The documentation now shows::
match(pattern, string[, flags=0])
Is it normal to have the brackets *and* the default value?
birkenfeld commentedon Nov 11, 2011
No, it's not.
elibendersky commentedon Nov 12, 2011
Amaury & Georg,
Grepping through the docs disagrees with your claims ;-) Try to grep for "\=None\]" to see what I mean. There are tons of places where default values are placed inside the brackets. For example in http://docs.python.org/library/csv.html --> look at:
or even:
That said, I have absolutely no objections to following an accepted convention. But what is it?
I looked around, and found the following in the documentation guide:
http://docs.python.org/dev/py3k/documenting/fromlatex.html
This (taken from the 3.3 guide) mentions the 2.x guideline and doesn't mention default values.
So what should I do here? According to Ezio's earlier message, the new style (without brackets) is also being used in Python 2 now. I can do the switch for the 're' module, but can we first get the convention documented somewhere?
ezio-melotti commentedon Nov 12, 2011
+1
This was on my todo list, but feel free to open a new issue about it.
That's because is not documented and not everyone is aware of the conventions and how/where they should be followed.
elibendersky commentedon Nov 12, 2011
Ezio, what do you suggest to do regarding *this* issue?
ezio-melotti commentedon Nov 12, 2011
I suggest removing the [].
elibendersky commentedon Nov 12, 2011
Hmm, I've just notice that this [default=val] pattern already exists in the 're' docs in 2.7, for example:
So my change was consistent within the documentation of this module.
No doubt, the conventions are currently a mess ;-)
I suggest to just convert the whole 're' RST page to the new 3.x convention (i.e. model it after the same RST in the default branch). Is this acceptable? If yes, I will submit a patch for review first.
ezio-melotti commentedon Nov 12, 2011
I created bpo-13386 about the conventions that should be followed in the doc.
Converting the whole page is fine with me.
elibendersky commentedon Nov 12, 2011
I have converted the Doc/library/re.rst doc of 2.7 to follow the new convention of 3.x, patch attached.
rhettinger commentedon Nov 13, 2011
This patch looks fine.
ezio-melotti commentedon Nov 13, 2011
LGTM
python-dev commentedon Nov 13, 2011
New changeset 87ecfd5cd5d1 by Eli Bendersky in branch '2.7':
Normalize the keyword arguments documentation notation in re.rst. Closes issue bpo-12875
http://hg.python.org/cpython/rev/87ecfd5cd5d1