diff --git a/boltons/iterutils.py b/boltons/iterutils.py index 65d4da5..f91433c 100644 --- a/boltons/iterutils.py +++ b/boltons/iterutils.py @@ -415,29 +415,27 @@ def one(src, cmp=None): def first(iterable, default=None, key=None): - """Return first element of `iterable` that evaluates true, else return None - (or an optional default value). + """Return first element of *iterable* that evaluates to ``True``, else + return ``None`` or optional *default*. >>> first([0, False, None, [], (), 42]) 42 - >>> first([0, False, None, [], ()]) is None True - >>> first([0, False, None, [], ()], default='ohai') 'ohai' - >>> import re >>> m = first(re.match(regex, 'abc') for regex in ['b.*', 'a(.*)']) >>> m.group(1) 'bc' - The optional `key` argument specifies a one-argument predicate function - like that used for `filter()`. The `key` argument, if supplied, must be - in keyword form. For example: + The optional *key* argument specifies a one-argument predicate function + like that used for *filter()*. The *key* argument, if supplied, should be + in keyword form. For example, finding the first even number in an iterable: >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0) 4 + """ if key is None: for el in iterable: