classification
Title: re: Match Objects always have a boolean value of True
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: dhgmgn, docs@python, eric.araujo, ezio.melotti, python-dev, r.david.murray, serhiy.storchaka, steven.daprano, vrutsky
Priority: normal Keywords: easy, patch

Created on 2012-10-23 11:59 by vrutsky, last changed 2012-11-04 05:01 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
16304.patch dhgmgn, 2012-11-02 09:11 review
Messages (9)
msg173595 - (view) Author: Vladimir Rutsky (vrutsky) * Date: 2012-10-23 11:59
re module documentation says:

 Match Objects always have a boolean value of :const:`True`, so that you can test
   whether e.g. :func:`match` resulted in a match with a simple if statement.

which is confusing - matched objects have boolean value True, doesn't matched - False.
msg173604 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2012-10-23 12:26
The documentation is okay.  :func:`match` returns a Match object (which have a boolean value of True) if match and None (which have a boolean value of False) if doesn't match.
msg173606 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-10-23 12:41
Since the quoted paragraph is distant from where the information about the ``None`` return is documented, the wording of the quoted paragraph can be improved to make this clearer:

Match Objects always have a boolean value of ``True``.  Since ``None`` (which has a boolean value of ``False``) is returned when there is no match, you can test whether there was a match with a simple ``if`` statement.
msg173641 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2012-10-23 22:23
I don't think the relevant information -- that re match and search return None in the case of no match -- is that distant from the paragraph quoted. This fact is already mentioned FOUR times in the page, in each of the re.match, re.search functions and regex.match, regex.search methods, plus implied by the helper function used in the examples.

Personally I think no change is required, but if the docs are going to be changed, I recommend going all the way and showing the usual re idiom with an example:

Match Objects always have a boolean value of ``True``.  Since ``None`` (which has a boolean value of ``False``) is returned when there is no match, you can test whether there was a match with a simple ``if`` statement. For example::

mo = re.search(pattern, string)
if mo:
    process(mo)
msg173642 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-10-23 22:27
Yeah, distant was a poor choice of words.  The issue really comes up if you happen to start reading with that section (say when revisiting the docs with an imperfect memory of what you read before).

So, I agree that no change is *required*.  But adding the example of "the usual idiom" as you suggest seems like it might be worthwhile.  I'm fine with either course of action (or inaction, as the case may be).
msg174497 - (view) Author: Jan Duzinkiewicz (dhgmgn) Date: 2012-11-02 09:11
I agree this is unclear - If Match object always have a boolean value of True, it actually prevents me from using simple if statement - what's the point of "if True:" statement? - so the remark that matching functions do not always return match objects has some value. I've submitted a patch.
msg174703 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-11-03 21:50
Thanks for the patch.  Note that :const:`True` should be ``True``.
msg174754 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-04 05:00
New changeset dc96df8556d8 by Ezio Melotti in branch '2.7':
#16304: clarify match objects docs.  Initial patch by Jan Duzinkiewicz.
http://hg.python.org/cpython/rev/dc96df8556d8

New changeset 1805fc284201 by Ezio Melotti in branch '3.2':
#16304: clarify match objects docs.  Initial patch by Jan Duzinkiewicz.
http://hg.python.org/cpython/rev/1805fc284201

New changeset 7fde4b4f7e56 by Ezio Melotti in branch '3.3':
#16304: merge with 3.2.
http://hg.python.org/cpython/rev/7fde4b4f7e56

New changeset 63b45c959a2a by Ezio Melotti in branch 'default':
#16304: merge with 3.3.
http://hg.python.org/cpython/rev/63b45c959a2a
msg174756 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-04 05:01
Thanks for the patch!
I committed a slightly modified version.
History
Date User Action Args
2012-11-04 05:01:53ezio.melottisetstatus: open -> closed
messages: + msg174756

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: needs patch -> resolved
2012-11-04 05:00:18python-devsetnosy: + python-dev
messages: + msg174754
2012-11-03 21:50:26eric.araujosetnosy: + eric.araujo
messages: + msg174703
2012-11-02 09:11:57dhgmgnsetfiles: + 16304.patch

nosy: + dhgmgn
messages: + msg174497

keywords: + patch
2012-10-26 16:29:55ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

type: enhancement
stage: needs patch
2012-10-23 22:27:38r.david.murraysetmessages: + msg173642
2012-10-23 22:23:26steven.dapranosetnosy: + steven.daprano
messages: + msg173641
2012-10-23 12:41:10r.david.murraysetnosy: + r.david.murray

messages: + msg173606
versions: + Python 3.2, Python 3.3, Python 3.4
2012-10-23 12:26:04serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg173604
2012-10-23 11:59:09vrutskycreate