Add raw option to head() and the likes (#173)

* Add raw option to head(), head_option(), first(), last() and last_option()

* Rename raw to no_wrap; improvements

* Make pylint happier

* Fix code formatting

* Increase code coverage

Author: swiergot

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 ## Next Release
 * Allow empty sequence expressions `seq()`, `pseq()` (#159)
+* Add `no_wrap` option to `head()`, `head_option()`, `first()`, `last()` and `last_option()`, as well as to `seq()`, `pseq()` and `Sequence` constructor
 
 ## Release 1.3.0
 * added precompute attribute to reverse transformation (#137)

README.md

@@ -362,10 +362,10 @@ Function | Description | Type
 `sorted(key=None, reverse=False)/order_by(func)` | Returns elements sorted according to python `sorted` | transformation
 `reverse()` | Returns the reversed sequence | transformation
 `slice(start, until)` | Sequence starting at `start` and including elements up to `until` | transformation
-`head()` / `first()` | Returns first element in sequence | action
-`head_option()` | Returns first element in sequence or `None` if its empty | action
-`last()` | Returns last element in sequence | action
-`last_option()` | Returns last element in sequence or `None` if its empty | action
+`head(no_wrap=None)` / `first(no_wrap=None)` | Returns first element in sequence (if `no_wrap=True`, the result will never be wrapped with `Sequence`) | action
+`head_option(no_wrap=None)` | Returns first element in sequence or `None` if its empty (if `no_wrap=True`, the result will never be wrapped with `Sequence`) | action
+`last(no_wrap=None)` | Returns last element in sequence (if `no_wrap=True`, the result will never be wrapped with `Sequence`) | action
+`last_option(no_wrap=None)` | Returns last element in sequence or `None` if its empty (if `no_wrap=True`, the result will never be wrapped with `Sequence`) | action
 `len()` / `size()` | Returns length of sequence | action
 `count(func)` | Returns count of elements in sequence where `func(element)` is True | action
 `empty()` | Returns `True` if the sequence has zero length | action
@@ -443,6 +443,30 @@ Files are given special treatment if opened through the `seq.open` and related A
 multiple iteration over a single file object while correctly handling iteration termination and
 file closing.
 
+### `no_wrap` option
+Even though functions like `first()` are supposed to return a single element, if the element is an iterable,
+then it is wrapped into a `Sequence`. For instance:
+
+```
+>>> s = seq(list(), list())
+>>> type(a.first())
+<class 'functional.pipeline.Sequence'>
+```
+
+That behaviour can be changed with `no_wrap` option:
+
+```
+>>> type(a.first(no_wrap=True))
+<class 'list'>
+```
+
+The option is also accpeted by `seq()`/`pseq()` as well as `Sequence()` constructor, for example:
+
+```
+>>> type(seq([list(), list()], no_wrap=True).last())
+<class 'list'>
+```
+
 ## Road Map Idea
 * SQL based query planner and interpreter
 * `_` lambda operator

functional/pipeline.py

@@ -20,6 +20,7 @@
     is_namedtuple,
     is_tabulatable,
     identity,
+    default_value,
 )
 from functional.io import WRITE_MODE, universal_write_open
 from functional import transformations
@@ -32,7 +33,9 @@ class Sequence(object):
     functional transformations and reductions in a data pipeline style
     """
 
-    def __init__(self, sequence, transform=None, engine=None, max_repr_items=None):
+    def __init__(
+        self, sequence, transform=None, engine=None, max_repr_items=None, no_wrap=None
+    ):
         # pylint: disable=protected-access
         """
         Takes a Sequence, list, tuple. or iterable sequence and wraps it around a Sequence object.
@@ -43,6 +46,7 @@ def __init__(self, sequence, transform=None, engine=None, max_repr_items=None):
         :param transform: transformation to apply
         :param engine: execution engine
         :param max_repr_items: maximum number of items to print with repr
+        :param no_wrap: default value of no_wrap for functions like first() or last()
         :return: sequence wrapped in a Sequence
         """
         self.engine = engine or ExecutionEngine()
@@ -58,6 +62,7 @@ def __init__(self, sequence, transform=None, engine=None, max_repr_items=None):
             raise TypeError("Given sequence must be an iterable value")
         if transform is not None:
             self._lineage.apply(transform)
+        self.no_wrap = no_wrap
 
     def __iter__(self):
         """
@@ -164,9 +169,9 @@ def __add__(self, other):
         :return: concatenated sequence with other
         """
         if isinstance(other, Sequence):
-            return Sequence(self.sequence + other.sequence)
+            return Sequence(self.sequence + other.sequence, no_wrap=self.no_wrap)
         else:
-            return Sequence(self.sequence + other)
+            return Sequence(self.sequence + other, no_wrap=self.no_wrap)
 
     def _evaluate(self):
         """
@@ -185,9 +190,9 @@ def _transform(self, *transforms):
         sequence = None
         for transform in transforms:
             if sequence:
-                sequence = Sequence(sequence, transform=transform)
+                sequence = Sequence(sequence, transform=transform, no_wrap=self.no_wrap)
             else:
-                sequence = Sequence(self, transform=transform)
+                sequence = Sequence(self, transform=transform, no_wrap=self.no_wrap)
         return sequence
 
     @property
@@ -220,7 +225,7 @@ def cache(self, delete_lineage=False):
             self._lineage = Lineage(engine=self.engine)
         return self
 
-    def head(self):
+    def head(self, no_wrap=None):
         """
         Returns the first element of the sequence.
 
@@ -234,11 +239,15 @@ def head(self):
          ...
         IndexError: list index out of range
 
+        :param no_wrap: If set to True, the returned value will never be wrapped with Sequence
         :return: first element of sequence
         """
-        return _wrap(self.take(1)[0])
+        if default_value(no_wrap, self.no_wrap, False):
+            return self.sequence[0]
+        else:
+            return _wrap(self.take(1)[0])
 
-    def first(self):
+    def first(self, no_wrap=None):
         """
         Returns the first element of the sequence.
 
@@ -252,11 +261,12 @@ def first(self):
          ...
         IndexError: list index out of range
 
+        :param no_wrap: If set to True, the returned value will never be wrapped with Sequence
         :return: first element of sequence
         """
-        return self.head()
+        return self.head(no_wrap=no_wrap)
 
-    def head_option(self):
+    def head_option(self, no_wrap=None):
         """
         Returns the first element of the sequence or None, if the sequence is empty.
 
@@ -266,13 +276,14 @@ def head_option(self):
         >>> seq([]).head_option()
         None
 
+        :param no_wrap: If set to True, the returned value will never be wrapped with Sequence
         :return: first element of sequence or None if sequence is empty
         """
         if not self.sequence:
             return None
-        return self.head()
+        return self.head(no_wrap=no_wrap)
 
-    def last(self):
+    def last(self, no_wrap=None):
         """
         Returns the last element of the sequence.
 
@@ -286,11 +297,15 @@ def last(self):
          ...
         IndexError: list index out of range
 
+        :param no_wrap: If set to True, the returned value will never be wrapped with Sequence
         :return: last element of sequence
         """
-        return _wrap(self.sequence[-1])
+        if default_value(no_wrap, self.no_wrap, False):
+            return self.sequence[-1]
+        else:
+            return _wrap(self.sequence[-1])
 
-    def last_option(self):
+    def last_option(self, no_wrap=None):
         """
         Returns the last element of the sequence or None, if the sequence is empty.
 
@@ -300,11 +315,12 @@ def last_option(self):
         >>> seq([]).last_option()
         None
 
+        :param no_wrap: If set to True, the returned value will never be wrapped with Sequence
         :return: last element of sequence or None if sequence is empty
         """
         if not self.sequence:
             return None
-        return self.last()
+        return self.last(no_wrap=no_wrap)
 
     def init(self):
         """

functional/streams.py

@@ -6,7 +6,7 @@
 
 from functional.execution import ExecutionEngine, ParallelExecutionEngine
 from functional.pipeline import Sequence
-from functional.util import is_primitive
+from functional.util import is_primitive, default_value
 from functional.io import get_read_function
 
 
@@ -18,15 +18,17 @@ class Stream(object):
     An instance of Stream is normally accessed as `seq`
     """
 
-    def __init__(self, disable_compression=False, max_repr_items=100):
+    def __init__(self, disable_compression=False, max_repr_items=100, no_wrap=None):
         """
         Default stream constructor.
         :param disable_compression: Disable file compression detection
+        :param no_wrap: default value of no_wrap for functions like first() or last()
         """
         self.disable_compression = disable_compression
         self.max_repr_items = max_repr_items
+        self.no_wrap = no_wrap
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, no_wrap=None, **kwargs):
         """
         Create a Sequence using a sequential ExecutionEngine.
 
@@ -41,11 +43,16 @@ def __call__(self, *args, **kwargs):
         """
         # pylint: disable=no-self-use
         engine = ExecutionEngine()
-        return self._parse_args(args, engine)
+        return self._parse_args(
+            args, engine, no_wrap=default_value(no_wrap, self.no_wrap, False)
+        )
 
-    def _parse_args(self, args, engine):
+    def _parse_args(self, args, engine, no_wrap=None):
+        _no_wrap = default_value(no_wrap, self.no_wrap, False)
         if len(args) == 0:
-            return Sequence([], engine=engine, max_repr_items=self.max_repr_items)
+            return Sequence(
+                [], engine=engine, max_repr_items=self.max_repr_items, no_wrap=_no_wrap
+            )
         if len(args) == 1:
             try:
                 if type(args[0]).__name__ == "DataFrame":
@@ -56,20 +63,32 @@ def _parse_args(self, args, engine):
                             args[0].values,
                             engine=engine,
                             max_repr_items=self.max_repr_items,
+                            no_wrap=_no_wrap,
                         )
             except ImportError:  # pragma: no cover
                 pass
 
         if len(args) > 1:
             return Sequence(
-                list(args), engine=engine, max_repr_items=self.max_repr_items
+                list(args),
+                engine=engine,
+                max_repr_items=self.max_repr_items,
+                no_wrap=_no_wrap,
             )
         elif is_primitive(args[0]):
             return Sequence(
-                [args[0]], engine=engine, max_repr_items=self.max_repr_items
+                [args[0]],
+                engine=engine,
+                max_repr_items=self.max_repr_items,
+                no_wrap=_no_wrap,
             )
         else:
-            return Sequence(args[0], engine=engine, max_repr_items=self.max_repr_items)
+            return Sequence(
+                args[0],
+                engine=engine,
+                max_repr_items=self.max_repr_items,
+                no_wrap=_no_wrap,
+            )
 
     def open(
         self,
@@ -274,17 +293,26 @@ class ParallelStream(Stream):
     Parallelized version of functional.streams.Stream normally accessible as `pseq`
     """
 
-    def __init__(self, processes=None, partition_size=None, disable_compression=False):
+    def __init__(
+        self,
+        processes=None,
+        partition_size=None,
+        disable_compression=False,
+        no_wrap=None,
+    ):
         """
         Configure Stream for parallel processing and file compression detection
         :param processes: Number of parallel processes
         :param disable_compression: Disable file compression detection
+        :param no_wrap: default value of no_wrap for functions like first() or last()
         """
-        super(ParallelStream, self).__init__(disable_compression=disable_compression)
+        super(ParallelStream, self).__init__(
+            disable_compression=disable_compression, no_wrap=no_wrap
+        )
         self.processes = processes
         self.partition_size = partition_size
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, no_wrap=None, **kwargs):
         """
         Create a Sequence using a parallel ExecutionEngine.
 
@@ -302,7 +330,9 @@ def __call__(self, *args, **kwargs):
         engine = ParallelExecutionEngine(
             processes=processes, partition_size=partition_size
         )
-        return self._parse_args(args, engine)
+        return self._parse_args(
+            args, engine, no_wrap=default_value(no_wrap, self.no_wrap, False)
+        )
 
 
 # pylint: disable=invalid-name