Allow first to supply a default value returned when iterable is empty.

jaraco · Mar 25, 2018 · e773284 · e773284
1 parent f527c3d
commit e773284
Show file tree

Hide file tree

Showing 2 changed files with 18 additions and 2 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,3 +1,8 @@
+2.2
+===
+
+* ``first`` now accepts a default value, same as ``next``.
+
 2.1.1
 =====
 

diff --git a/jaraco/itertools.py b/jaraco/itertools.py
@@ -712,7 +712,7 @@ def takewhile_peek(predicate, iterable):
 		yield next(iterable)
 
 
-def first(iterable):
+def first(iterable, *args):
 	"""
 	Return the first item from the iterable.
 
@@ -724,9 +724,20 @@ def first(iterable):
 	>>> first(iter)
 	0
 
+	Raises StopIteration if no value is present.
+
+	>>> first([])
+	Traceback (most recent call last):
+	...
+	StopIteration
+
+	Pass a default to be used when iterable is empty.
+
+	>>> first([], None)
+
 	"""
 	iterable = iter(iterable)
-	return next(iterable)
+	return next(iterable, *args)
 
 
 def last(iterable):