bit of iter import and docs cleanup

glom/streaming.py

@@ -7,7 +7,6 @@
 from __future__ import unicode_literals
 
 from itertools import islice, dropwhile, takewhile, chain
-import inspect
 from functools import partial
 try:
     from itertools import imap, ifilter
@@ -122,7 +121,7 @@ def _add_op(self, opname, args, callback):
 
     def map(self, subspec):
         """Return a new :class:`Iter()` spec which will apply the provided
-        subspec to each element of the iterable.
+        *subspec* to each element of the iterable.
 
         >>> glom(range(5), Iter().map(lambda x: x * 2).all())
         [0, 2, 4, 6, 8]
@@ -144,7 +143,7 @@ def map(self, subspec):
 
     def filter(self, key=T):
         """Return a new :class:`Iter()` spec which will include only elements matching the
-        given subspec.
+        given *key*.
 
         >>> glom(range(6), Iter().filter(lambda x: x % 2).all())
         [1, 3, 5]
@@ -154,8 +153,7 @@ def filter(self, key=T):
         power of glom specs. For even more power, combine,
         :meth:`Iter.filter()` with :class:`Check()`.
 
-        # Python's built-in integers know how many binary digits they
-        # require, using the bit_length method
+        >>> # PROTIP: Python's ints know how many binary digits they require, using the bit_length method
         >>> glom(range(9), Iter().filter(Check(T.bit_length(), one_of=(2, 4), default=SKIP)).all())
         [2, 3, 8]
 
@@ -265,16 +263,16 @@ def unique(self, key=T):
 
 
     def slice(self, *args):
-        """
-        Returns a new :class:`Iter()` spec which trims iterables.
+        """Returns a new :class:`Iter()` spec which trims iterables in the
+        same manner as :func:`itertools.islice`.
 
         >>> target = [0, 1, 2, 3, 4, 5]
         >>> glom(target, Iter().slice(3).all())
         [0, 1, 2]
         >>> glom(target, Iter().slice(2, 4).all())
         [2, 3]
 
-        For more info, see :func:`itertools.islice`.
+        This method accepts only positional arguments.
         """
         # TODO: make a kwarg-compatible version of this (islice takes no kwargs)
         try:
@@ -339,14 +337,18 @@ def all(self):
 
     def first(self, key=T, default=None):
         """A convenience method for lazily yielding a single truthy item from
-        an iterable. As this spec yields at most one item, and not an
-        iterable, the return value of this method is not a new Iter()
-        instance.
+        an iterable.
 
         >>> target = [False, 1, 2, 3]
         >>> glom(target, Iter().first())
         1
 
+        This method takes a condition, *key*, which can also be a
+        glomspec, as well as a *default*, in case nothing matches the
+        condition.
+
+        As this spec yields at most one item, and not an iterable, the
+        return value of this method is not a new Iter() instance.
         """
         return (self, First(key=key, default=default))