classification
Title: backport re.compile flags default value documentation
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: amaury.forgeotdarc, docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl, pitrou, python-dev, rhettinger
Priority: normal Keywords: patch

Created on 2011-09-01 05:17 by eli.bendersky, last changed 2011-11-14 04:21 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue12875.1.patch eli.bendersky, 2011-11-12 18:28
Messages (19)
msg143300 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-09-01 05:17
In the 2.7 docs, re.compile has this signature:

  re.compile(pattern[, flags])

From here it isn't clear what the default value of 'flags' is, to be able to write code like this:

  re.compile(pattern, re.I if options['ignore_case'] else <WHAT??>)

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:

  re.compile(pattern, flags=0)

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
msg143301 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-09-01 05:24
I don't think you are missing anything, but using ints instead of flags is discouraged (see #11957).  OTOH there's no re.NOFLAGS flag that can be used instead.
msg143304 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-09-01 05:40
Two more things:
 1) Python 2 doc used to use the func(arg[, optional1[, optional2]]) notation, and with Python 3 we switched to func(arg, optional1=default1, optional2=default2).  The latter is also used in Python 2 now, and the [] are still there in Python 3 in some places;
 2) If you are going to fix it, you can probably backport the fix from py3k with "hg diff Doc/library/re.rst -c 106ee4eb5970";
msg143305 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-09-01 06:17
Ezio,

"but using ints instead of flags is discouraged (see #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.
msg143306 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-09-01 06:17
Regarding backporting 106ee4eb5970 - it's probably a good thing to do but I wouldn't mix it with this issue.
msg143419 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-09-02 17:08
+1 to backporting [flags=0].
msg147442 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-11-11 19:16
New changeset 02e4d3ebbb02 by Eli Bendersky in branch '2.7':
Issue #12875: explicitly specify default value of the optional 'flags' argument to re.* functions. Closes #12875
http://hg.python.org/cpython/rev/02e4d3ebbb02
msg147445 - (view) Author: Amaury Forgeot d'Arc (amaury.forgeotdarc) * (Python committer) Date: 2011-11-11 20:47
The documentation now shows::
    match(pattern, string[, flags=0])
Is it normal to have the brackets *and* the default value?
msg147446 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-11-11 21:09
No, it's not.
msg147459 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-12 03:32
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:

    sniff(sample[, delimiters=None])

or even:

    class csv.DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])

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

    There is no optional command. Just give function signatures 
    like they should appear in the output:

    .. function:: open(filename[, mode[, buffering]])

       Description.

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?
msg147461 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-12 03:54
> but can we first get the convention documented somewhere?

+1
This was on my todo list, but feel free to open a new issue about it.

> Grepping through the docs disagrees with your claims 

That's because is not documented and not everyone is aware of the conventions and how/where they should be followed.
msg147462 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-12 04:20
Ezio, what do you suggest to do regarding *this* issue?
msg147465 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-12 05:43
I suggest removing the [].
msg147467 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-12 05:51
Hmm, I've just notice that this [default=val] pattern already exists in the 're' docs in 2.7, for example:

  subn(repl, string[, count=0])

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.
msg147470 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-12 06:13
I created #13386 about the conventions that should be followed in the doc.

Converting the whole page is fine with me.
msg147516 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-12 18:28
I have converted the Doc/library/re.rst doc of 2.7 to follow the new convention of 3.x, patch attached.
msg147543 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-11-13 03:07
This patch looks fine.
msg147544 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-11-13 03:08
LGTM
msg147574 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-11-13 22:52
New changeset 87ecfd5cd5d1 by Eli Bendersky in branch '2.7':
Normalize the keyword arguments documentation notation in re.rst. Closes issue #12875
http://hg.python.org/cpython/rev/87ecfd5cd5d1
History
Date User Action Args
2011-11-14 04:21:47ezio.melottisetresolution: fixed
stage: commit review -> resolved
2011-11-13 22:53:25eli.benderskysetstatus: open -> closed
2011-11-13 22:52:12python-devsetmessages: + msg147574
2011-11-13 03:08:33ezio.melottisetmessages: + msg147544
stage: commit review
2011-11-13 03:07:04rhettingersetnosy: + rhettinger
messages: + msg147543
2011-11-12 18:28:19eli.benderskysetfiles: + issue12875.1.patch
keywords: + patch
messages: + msg147516
2011-11-12 06:13:43ezio.melottisetmessages: + msg147470
2011-11-12 05:51:19eli.benderskysetmessages: + msg147467
2011-11-12 05:43:03ezio.melottisetmessages: + msg147465
2011-11-12 04:20:27eli.benderskysetmessages: + msg147462
2011-11-12 03:54:56ezio.melottisetmessages: + msg147461
2011-11-12 03:32:43eli.benderskysetmessages: + msg147459
2011-11-11 21:09:23georg.brandlsetnosy: + georg.brandl
messages: + msg147446
2011-11-11 20:47:46amaury.forgeotdarcsetstatus: closed -> open
nosy: + amaury.forgeotdarc
messages: + msg147445

2011-11-11 19:19:53eli.benderskysetstatus: open -> closed
2011-11-11 19:16:17python-devsetnosy: + python-dev
messages: + msg147442
2011-09-02 17:08:32eric.araujosetnosy: + eric.araujo
messages: + msg143419
2011-09-01 06:17:58eli.benderskysetmessages: + msg143306
2011-09-01 06:17:11eli.benderskysetmessages: + msg143305
2011-09-01 05:40:30ezio.melottisetmessages: + msg143304
2011-09-01 05:24:31ezio.melottisetmessages: + msg143301
2011-09-01 05:17:07eli.benderskycreate