From 56ad5ed5ad37746228f7482fd501d8469539a2c1 Mon Sep 17 00:00:00 2001 From: Andrew Svetlov Date: Sun, 23 Dec 2012 19:23:07 +0200 Subject: [PATCH] Issue #16443: Add docstrings to regular expression match objects. Patch by Anton Kasyanov. --- Misc/ACKS | 1 + Misc/NEWS | 3 +++ Modules/_sre.c | 70 +++++++++++++++++++++++++++++++++++++++----------- 3 files changed, 59 insertions(+), 15 deletions(-) diff --git a/Misc/ACKS b/Misc/ACKS index 81af9fdd44d..f9c75ab36fb 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -543,6 +543,7 @@ Peter van Kampen Rafe Kaplan Jacob Kaplan-Moss Jan Kaliszewski +Anton Kasyanov Lou Kates Hiroaki Kawai Sebastien Keim diff --git a/Misc/NEWS b/Misc/NEWS index 2b50cbbccef..4ddcd00a858 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -179,6 +179,9 @@ Core and Builtins Library ------- +- Issue #16443: Add docstrings to regular expression match objects. + Patch by Anton Kasyanov. + - Issue #16646: ftplib.FTP.makeport() might lose socket error details. (patch by Serhiy Storchaka) diff --git a/Modules/_sre.c b/Modules/_sre.c index d74bf443a34..99101e7993e 100644 --- a/Modules/_sre.c +++ b/Modules/_sre.c @@ -2559,35 +2559,35 @@ pattern_deepcopy(PatternObject* self, PyObject* memo) } PyDoc_STRVAR(pattern_match_doc, -"match(string[, pos[, endpos]]) --> match object or None.\n\ +"match(string[, pos[, endpos]]) -> match object or None.\n\n\ Matches zero or more characters at the beginning of the string"); PyDoc_STRVAR(pattern_search_doc, -"search(string[, pos[, endpos]]) --> match object or None.\n\ +"search(string[, pos[, endpos]]) -> match object or None.\n\n\ Scan through string looking for a match, and return a corresponding\n\ MatchObject instance. Return None if no position in the string matches."); PyDoc_STRVAR(pattern_split_doc, -"split(string[, maxsplit = 0]) --> list.\n\ +"split(string[, maxsplit = 0]) -> list.\n\n\ Split string by the occurrences of pattern."); PyDoc_STRVAR(pattern_findall_doc, -"findall(string[, pos[, endpos]]) --> list.\n\ +"findall(string[, pos[, endpos]]) -> list.\n\n\ Return a list of all non-overlapping matches of pattern in string."); PyDoc_STRVAR(pattern_finditer_doc, -"finditer(string[, pos[, endpos]]) --> iterator.\n\ +"finditer(string[, pos[, endpos]]) -> iterator.\n\n\ Return an iterator over all non-overlapping matches for the \n\ RE pattern in string. For each match, the iterator returns a\n\ match object."); PyDoc_STRVAR(pattern_sub_doc, -"sub(repl, string[, count = 0]) --> newstring\n\ +"sub(repl, string[, count = 0]) -> newstring.\n\n\ Return the string obtained by replacing the leftmost non-overlapping\n\ occurrences of pattern in string by the replacement repl."); PyDoc_STRVAR(pattern_subn_doc, -"subn(repl, string[, count = 0]) --> (newstring, number of subs)\n\ +"subn(repl, string[, count = 0]) -> (newstring, number of subs)\n\n\ Return the tuple (new_string, number_of_subs_made) found by replacing\n\ the leftmost non-overlapping occurrences of pattern with the\n\ replacement repl."); @@ -3579,14 +3579,54 @@ match_deepcopy(MatchObject* self, PyObject* memo) #endif } +PyDoc_STRVAR(match_doc, +"The result of re.match() and re.search().\n\ +Match objects always have a boolean value of True."); + +PyDoc_STRVAR(match_group_doc, +"group([group1, ...]) -> str or tuple.\n\n\ + Return subgroup(s) of the match by indices or names.\n\ + For 0 returns the entire match."); + +PyDoc_STRVAR(match_start_doc, +"start([group=0]) -> int.\n\n\ + Return index of the start of the substring matched by group."); + +PyDoc_STRVAR(match_end_doc, +"end([group=0]) -> int.\n\n\ + Return index of the end of the substring matched by group."); + +PyDoc_STRVAR(match_span_doc, +"span([group]) -> tuple.\n\n\ + For MatchObject m, return the 2-tuple (m.start(group), m.end(group))."); + +PyDoc_STRVAR(match_groups_doc, +"groups([default=None]) -> tuple.\n\n\ + Return a tuple containing all the subgroups of the match, from 1.\n\ + The default argument is used for groups\n\ + that did not participate in the match"); + +PyDoc_STRVAR(match_groupdict_doc, +"groupdict([default=None]) -> dict.\n\n\ + Return a dictionary containing all the named subgroups of the match,\n\ + keyed by the subgroup name. The default argument is used for groups\n\ + that did not participate in the match"); + +PyDoc_STRVAR(match_expand_doc, +"expand(template) -> str.\n\n\ + Return the string obtained by doing backslash substitution\n\ + on the string template, as done by the sub() method."); + static PyMethodDef match_methods[] = { - {"group", (PyCFunction) match_group, METH_VARARGS}, - {"start", (PyCFunction) match_start, METH_VARARGS}, - {"end", (PyCFunction) match_end, METH_VARARGS}, - {"span", (PyCFunction) match_span, METH_VARARGS}, - {"groups", (PyCFunction) match_groups, METH_VARARGS|METH_KEYWORDS}, - {"groupdict", (PyCFunction) match_groupdict, METH_VARARGS|METH_KEYWORDS}, - {"expand", (PyCFunction) match_expand, METH_O}, + {"group", (PyCFunction) match_group, METH_VARARGS, match_group_doc}, + {"start", (PyCFunction) match_start, METH_VARARGS, match_start_doc}, + {"end", (PyCFunction) match_end, METH_VARARGS, match_end_doc}, + {"span", (PyCFunction) match_span, METH_VARARGS, match_span_doc}, + {"groups", (PyCFunction) match_groups, METH_VARARGS|METH_KEYWORDS, + match_groups_doc}, + {"groupdict", (PyCFunction) match_groupdict, METH_VARARGS|METH_KEYWORDS, + match_groupdict_doc}, + {"expand", (PyCFunction) match_expand, METH_O, match_expand_doc}, {"__copy__", (PyCFunction) match_copy, METH_NOARGS}, {"__deepcopy__", (PyCFunction) match_deepcopy, METH_O}, {NULL, NULL} @@ -3665,7 +3705,7 @@ static PyTypeObject Match_Type = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT, /* tp_flags */ - 0, /* tp_doc */ + match_doc, /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ 0, /* tp_richcompare */