re: Match Objects always have a boolean value of True

[vrutsky]

BPO	16304
Nosy	@ezio-melotti, @merwok, @stevendaprano, @bitdancer, @serhiy-storchaka
Files	16304.patch

^{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 = 'https://github.com/ezio-melotti'
closed_at = <Date 2012-11-04.05:01:53.337>
created_at = <Date 2012-10-23.11:59:09.464>
labels = ['easy', 'type-feature', 'docs']
title = 're: Match Objects always have a boolean value of  True'
updated_at = <Date 2012-11-04.05:01:53.336>
user = 'https://bugs.python.org/vrutsky'

bugs.python.org fields:

activity = <Date 2012-11-04.05:01:53.336>
actor = 'ezio.melotti'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2012-11-04.05:01:53.337>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2012-10-23.11:59:09.464>
creator = 'vrutsky'
dependencies = []
files = ['27838']
hgrepos = []
issue_num = 16304
keywords = ['patch', 'easy']
message_count = 9.0
messages = ['173595', '173604', '173606', '173641', '173642', '174497', '174703', '174754', '174756']
nosy_count = 9.0
nosy_names = ['ezio.melotti', 'eric.araujo', 'steven.daprano', 'r.david.murray', 'docs@python', 'vrutsky', 'python-dev', 'serhiy.storchaka', 'dhgmgn']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16304'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4']

[vrutsky]

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.

[serhiy-storchaka]

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.

[bitdancer]

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.

[stevendaprano]

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)

[bitdancer]

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).

[dhgmgn]

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.

[merwok]

Thanks for the patch. Note that :const:`True` should be ``True``.

[python-dev]

New changeset dc96df8556d8 by Ezio Melotti in branch '2.7':
bpo-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':
bpo-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':
bpo-16304: merge with 3.2.
http://hg.python.org/cpython/rev/7fde4b4f7e56

New changeset 63b45c959a2a by Ezio Melotti in branch 'default':
bpo-16304: merge with 3.3.
http://hg.python.org/cpython/rev/63b45c959a2a

[ezio-melotti]

Thanks for the patch!
I committed a slightly modified version.