Merge branch 'master' into master

Author: Drvanon

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)
@@ -72,7 +73,7 @@ Reaching `1.0` primarily means that API stability has been reached so I don't ex
 * Parallel functions: `map`, `select`, `filter`, `filter_not`, `where`, `flatten`, and `flat_map`
 * Compressed file IO support for `gzip`/`lzma`/`bz2` as detailed at https://github.com/EntilZha/PyFunctional/issues/54
 * Cartesian product from `itertools.product` implemented as `Pipeline.cartesian`
-* Website at [pyfunctional.org](http://www.pyfunctional.org) and docs at [docs.pyfunctional.org](http://docs.pyfunctional.org)
+* Website at [pyfunctional.pedro.ai](http://pyfunctional.pedro.ai) and docs at [docs.pyfunctional.pedro.ai](http://docs.pyfunctional.pedro.ai)
 
 ### Bug Fixes
 * No option for encoding in `to_json` https://github.com/EntilZha/PyFunctional/issues/70

DEVELOPER.md

@@ -9,7 +9,7 @@ and that pylint succeeds
 2. Push commit which is the candidate release to Github master
 3. Wait for tests to pass on [TravisCI](https://travis-ci.org/EntilZha/PyFunctional)
 4. Wait for coverage to complete at 100% on [Coveralls](https://coveralls.io/github/EntilZha/PyFunctional)
-5. Wait for docs to complete building successfully at [docs.pyfunctional.org/en/latest](http://docs.pyfunctional.org/en/latest/)
+5. Wait for docs to complete building successfully at [docs.pyfunctional.pedro.ai/en/latest](http://docs.pyfunctional.pedro.ai/en/latest/)
 
 ### Testing Local Release
 1. Run `docker run -it python bash` for clean python installation

README.md

@@ -1,7 +1,7 @@
 # PyFunctional
 ![Build Status](https://github.com/EntilZha/PyFunctional/workflows/Python%20package/badge.svg)
 [![Code Coverage](https://codecov.io/gh/EntilZha/PyFunctional/branch/master/graph/badge.svg)](https://codecov.io/gh/EntilZha/PyFunctional)
-[![ReadTheDocs](https://readthedocs.org/projects/scalafunctional/badge/?version=latest)](http://docs.pyfunctional.org)
+[![ReadTheDocs](https://readthedocs.org/projects/scalafunctional/badge/?version=latest)](http://docs.pyfunctional.pedro.ai)
 [![PyPI version](https://badge.fury.io/py/PyFunctional.svg)](https://badge.fury.io/py/PyFunctional)
 
 ## Features
@@ -268,7 +268,7 @@ all at once rather than in multiple loops using `multiprocessing`
 
 ## Documentation
 Shortform documentation is below and full documentation is at
-[docs.pyfunctional.org](http://docs.pyfunctional.org/en/latest/functional.html).
+[docs.pyfunctional.pedro.ai](http://docs.pyfunctional.pedro.ai/en/latest/functional.html).
 
 ### Streams API
 All of `PyFunctional` streams can be accessed through the `seq` object. The primary way to create
@@ -313,12 +313,12 @@ seq.sqlite3('filepath', 'select * from data')
 ```
 
 For more information on the parameters that these functions can take, reference the
-[streams documentation](http://docs.pyfunctional.org/en/latest/functional.html#module-functional.streams)
+[streams documentation](http://docs.pyfunctional.pedro.ai/en/latest/functional.html#module-functional.streams)
 
 ### Transformations and Actions APIs
 Below is the complete list of functions which can be called on a stream object from `seq`. For
 complete documentation reference
-[transformation and actions API](http://docs.pyfunctional.org/en/latest/functional.html#module-functional.pipeline).
+[transformation and actions API](http://docs.pyfunctional.pedro.ai/en/latest/functional.html#module-functional.pipeline).
 
 Function | Description | Type
  ------- | ----------- | ----
@@ -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
@@ -397,6 +397,7 @@ Function | Description | Type
 `to_pandas(columns=None)` | Converts the sequence to a pandas DataFrame | action
 `cache()` | Forces evaluation of sequence immediately and caches the result | action
 `for_each(func)` | Executes `func` on each element of the sequence | action
+`peek(func)` | Executes `func` on each element of the sequence but returns the element | transformation
 
 ### Lazy Execution
 Whenever possible, `PyFunctional` will compute lazily. This is accomplished by tracking the list
@@ -411,11 +412,17 @@ undesirable to keep recomputing the same value. Below are some examples of inspe
 
 ```python
 def times_2(x):
-    print(x)
     return 2 * x
-elements = seq(1, 1, 2, 3, 4).map(times_2).distinct()
+
+elements = (
+   seq(1, 1, 2, 3, 4)
+      .map(times_2)
+      .peek(print)
+      .distinct()
+)
+
 elements._lineage
-# Lineage: sequence -> map(times_2) -> distinct
+# Lineage: sequence -> map(times_2) -> peek(print) -> distinct
 
 l_elements = elements.to_list()
 # Prints: 1
@@ -425,7 +432,7 @@ l_elements = elements.to_list()
 # Prints: 4
 
 elements._lineage
-# Lineage: sequence -> map(times_2) -> distinct -> cache
+# Lineage: sequence -> map(times_2) -> peek(print) -> distinct -> cache
 
 l_elements = elements.to_list()
 # The cached result is returned so times_2 is not called and nothing is printed
@@ -436,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
@@ -472,7 +503,7 @@ In order to be merged, all pull requests must:
 To learn more about me (the author) visit my webpage at
 [pedro.ai](https://www.pedro.ai).
 
-I created `PyFunctional` while using Python extensivel, and finding that I missed the
+I created `PyFunctional` while using Python extensively, and finding that I missed the
 ease of use for manipulating data that Spark RDDs and Scala collections have. The project takes the
 best ideas from these APIs as well as LINQ to provide an easy way to manipulate data when using
 Scala is not an option or PySpark is overkill.

docs/index.rst

@@ -7,7 +7,7 @@ PyFunctional Documentation
 =============================
 
 Welcome to the `PyFunctional` documentation. For a tutorial of how to use this package you should
-visit `pyfunctional.org <http://www.pyfunctional.org/>`_.
+visit `pyfunctional.pedro.ai <http://pyfunctional.pedro.ai/>`_.
 
 The documentation on this site should primarily be used as an API reference. The Streams
 documentation covers ways to read data into `PyFunctional` while the Transformations and Actions

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):
         """
@@ -546,6 +562,21 @@ def for_each(self, func):
         for e in self:
             func(e)
 
+    def peek(self, func):
+        """
+        Executes func on each element of the sequence and returns the element
+
+        >>> seq([1, 2, 3, 4]).peek(print).map(lambda x: x ** 2).to_list()
+        1
+        2
+        3
+        4
+        [1, 4, 9, 16]
+
+        :param func: function to execute
+        """
+        return self._transform(transformations.peek_t(func))
+
     def filter(self, func):
         """
         Filters sequence to include only elements where func is True.