>> updated examples of Session.__init__/load/save/to_pickle/to_hdf/to_excel/to_csv methods

Author: alixdamman

larray/core/session.py

@@ -46,6 +46,8 @@ class Session(object):
 
     Examples
     --------
+    >>> # scalars
+    >>> i, s = 5, 'string'
     >>> # axes
     >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
     >>> # groups
@@ -55,30 +57,31 @@ class Session(object):
 
     create a Session by passing a list of pairs (name, object)
 
-    >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])
+    >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+    ...                ('arr1', arr1), ('arr2', arr2)])
 
     create a Session using keyword arguments (but you lose order on Python < 3.6)
 
-    >>> s = Session(a=a, b=b, a01=a01, arr1=arr1, arr2=arr2)
+    >>> ses = Session(i=i, s=s, a=a, b=b, a01=a01, arr1=arr1, arr2=arr2)
 
     create a Session by passing a dictionary (but you lose order on Python < 3.6)
 
-    >>> s = Session({'a': a, 'b': b, 'a01': a01, 'arr1': arr1, 'arr2': arr2})
+    >>> ses = Session({'i': i, 's': s, 'a': a, 'b': b, 'a01': a01, 'arr1': arr1, 'arr2': arr2})
 
     load Session from file
 
-    >>> s = Session('my_session.h5')  # doctest: +SKIP
+    >>> ses = Session('my_session.h5')  # doctest: +SKIP
 
     create a session with metadata
 
     >>> # Python <= 3.5
-    >>> s = Session([('arr1', arr1), ('arr2', arr2)], meta=[('title', 'my title'), ('author', 'John Smith')])
-    >>> s.meta
+    >>> ses = Session([('arr1', arr1), ('arr2', arr2)], meta=[('title', 'my title'), ('author', 'John Smith')])
+    >>> ses.meta
     title: my title
     author: John Smith
     >>> # Python 3.6+
-    >>> s = Session(arr1=arr1, arr2=arr2, meta=Metadata(title='my title', author='John Smith'))  # doctest: +SKIP
-    >>> s.meta
+    >>> ses = Session(arr1=arr1, arr2=arr2, meta=Metadata(title='my title', author='John Smith'))  # doctest: +SKIP
+    >>> ses.meta
     title: my title
     author: John Smith
     """
@@ -369,46 +372,57 @@ def load(self, fname, names=None, engine='auto', display=False, **kwargs):
         --------
         In one module:
 
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
         >>> # save the session in an HDF5 file
-        >>> s.save('input.h5')                           # doctest: +SKIP
+        >>> ses.save('input.h5')
 
         In another module: load the whole session
 
         >>> # the load method is automatically called when passing
         >>> # the path of file to the Session constructor
-        >>> s = Session('input.h5')     # doctest: +SKIP
-        >>> s                           # doctest: +SKIP
-        Session(a, b, a01, arr1, arr2)
-        >>> s.meta                      # doctest: +SKIP
+        >>> ses = Session('input.h5')
+        >>> ses
+        Session(i, s, a, b, a01, arr1, arr2)
+        >>> ses.meta
         title: my title
         author: John Smith
 
         Load only some objects
 
-        >>> s = Session()                                   # doctest: +SKIP
-        >>> s.load('input.h5', ['a', 'b', 'arr1', 'arr2'])  # doctest: +SKIP
-        >>> a, b, arr1, arr2 = s['a', 'b', 'arr1', 'arr2']  # doctest: +SKIP
-        >>> # only if you know the order of arrays stored in session
-        >>> a, b, a01, arr1, arr2 = s.values()              # doctest: +SKIP
+        >>> ses = Session()
+        >>> ses.load('input.h5', names=['s', 'a', 'b', 'arr1', 'arr2'], display=True)
+        opening input.h5
+        loading scalar object s ... done
+        loading Axis object a ... done
+        loading Axis object b ... done
+        loading Array object arr1 ... done
+        loading Array object arr2 ... done
 
         Using .csv files (assuming the same session as above)
 
-        >>> s.save('data')                                # doctest: +SKIP
-        >>> s = Session()                                 # doctest: +SKIP
-        >>> # load all .csv files starting with "output" in the data directory
-        >>> s.load('data')                                # doctest: +SKIP
-        >>> # or only arrays (i.e. all CSV files starting with 'arr')
-        >>> s.load('data/arr*.csv')                       # doctest: +SKIP
+        >>> ses.save('data')
+        >>> ses = Session()
+        >>> # load all .csv files from the 'data' directory
+        >>> ses.load('data', display=True)
+        opening data
+        loading Array object arr1 ... done
+        loading Array object arr2 ... done
+        >>> # or only arrays containing the character '1' in their names
+        >>> ses.load('data/*1.csv', display=True)
+        opening data/*1.csv
+        loading Array object arr1 ... done
         """
         if display:
             print("opening", fname)
@@ -434,15 +448,15 @@ def load(self, fname, names=None, engine='auto', display=False, **kwargs):
     def save(self, fname, names=None, engine='auto', overwrite=True, display=False, **kwargs):
         r"""
         Dumps objects from the current session to a file, or several .csv files.
-        The Excel and CSV formats only accepts objects of Array type (plus metadata).
+        The Excel and CSV formats only dumps objects of Array type (plus metadata).
 
         Parameters
         ----------
         fname : str
             Path of the file for the dump.
             If objects are saved in CSV files, the path corresponds to a directory.
         names : list of str or None, optional
-            List of names of Array/Axis/Group objects to dump.
+            List of names of objects to dump.
             If `fname` is None, list of paths to CSV files.
             Defaults to all objects present in the Session.
         engine : {'auto', 'pandas_csv', 'pandas_hdf', 'pandas_excel', 'xlwings_excel', 'pickle'}, optional
@@ -455,31 +469,48 @@ def save(self, fname, names=None, engine='auto', overwrite=True, display=False,
 
         Examples
         --------
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
 
         Save all objects
 
-        >>> s.save('output.h5')                             # doctest: +SKIP
+        >>> ses.save('output.h5', display=True)
+        dumping i ... done
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping a01 ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
 
         Save only some objects
 
-        >>> s.save('output.h5', ['a', 'b', 'arr1'])         # doctest: +SKIP
+        >>> ses.save('output.h5', names=['s', 'a', 'b', 'arr1', 'arr2'], display=True)
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
 
         Update file
 
-        >>> arr1, arr4 = ndtest((3, 3)), ndtest((2, 3))     # doctest: +SKIP
-        >>> s2 = Session([('arr1', arr1), ('arr4', arr4)])  # doctest: +SKIP
+        >>> arr1, arr4 = ndtest((3, 3)), ndtest((2, 3))
+        >>> ses2 = Session([('arr1', arr1), ('arr4', arr4)])
         >>> # replace arr1 and add arr4 in file output.h5
-        >>> s2.save('output.h5', overwrite=False)           # doctest: +SKIP
+        >>> ses2.save('output.h5', overwrite=False, display=True)
+        dumping arr1 ... done
+        dumping arr4 ... done
         """
         if engine == 'auto':
             _, ext = os.path.splitext(fname)
@@ -584,24 +615,39 @@ def to_pickle(self, fname, names=None, overwrite=True, display=False, **kwargs):
 
         Examples
         --------
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
 
-        Save all arrays
+        Save all objects
 
-        >>> s.to_pickle('output.pkl')  # doctest: +SKIP
+        >>> ses.to_pickle('output.pkl', display=True)
+        dumping i ... done
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping a01 ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
 
         Save only some objects
 
-        >>> s.to_pickle('output.pkl', ['a', 'b', 'arr1'])  # doctest: +SKIP
+        >>> ses.to_pickle('output.pkl', names=['s', 'a', 'b', 'arr1', 'arr2'], display=True)
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
         """
         self.save(fname, names, ext_default_engine['pkl'], overwrite, display, **kwargs)
 
@@ -626,24 +672,39 @@ def to_hdf(self, fname, names=None, overwrite=True, display=False, **kwargs):
 
         Examples
         --------
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
 
-        Save all arrays
+        Save all objects
 
-        >>> s.to_hdf('output.h5')  # doctest: +SKIP
+        >>> ses.to_hdf('output.h5', display=True)
+        dumping i ... done
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping a01 ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
 
         Save only some objects
 
-        >>> s.to_hdf('output.h5', ['a', 'b', 'arr1'])  # doctest: +SKIP
+        >>> ses.to_hdf('output.h5', names=['s', 'a', 'b', 'arr1', 'arr2'], display=True)
+        dumping s ... done
+        dumping a ... done
+        dumping b ... done
+        dumping arr1 ... done
+        dumping arr2 ... done
         """
         self.save(fname, names, ext_default_engine['hdf'], overwrite, display, **kwargs)
 
@@ -672,24 +733,35 @@ def to_excel(self, fname, names=None, overwrite=True, display=False, **kwargs):
 
         Examples
         --------
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
 
-        Save all arrays
+        Save all arrays (and arrays only)
 
-        >>> s.to_excel('output.xlsx')  # doctest: +SKIP
+        >>> ses.to_excel('output.xlsx', display=True)
+        dumping i ... Cannot dump i. int is not a supported type
+        dumping s ... Cannot dump s. str is not a supported type
+        dumping a ... Cannot dump a. Axis is not a supported type
+        dumping b ... Cannot dump b. Axis is not a supported type
+        dumping a01 ... Cannot dump a01. LGroup is not a supported type
+        dumping arr1 ... done
+        dumping arr2 ... done
 
-        Save only some objects
+        Save only some arrays
 
-        >>> s.to_excel('output.xlsx', ['a', 'b', 'arr1'])  # doctest: +SKIP
+        >>> ses.to_excel('output.xlsx', names=['arr1'], display=True)
+        dumping arr1 ... done
         """
         self.save(fname, names, ext_default_engine['xlsx'], overwrite, display, **kwargs)
 
@@ -716,24 +788,35 @@ def to_csv(self, fname, names=None, display=False, **kwargs):
 
         Examples
         --------
+        >>> # scalars
+        >>> i, s = 5, 'string'
         >>> # axes
-        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")    # doctest: +SKIP
+        >>> a, b = Axis("a=a0..a2"), Axis("b=b0..b2")
         >>> # groups
-        >>> a01 = a['a0,a1'] >> 'a01'                    # doctest: +SKIP
+        >>> a01 = a['a0,a1'] >> 'a01'
         >>> # arrays
-        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)       # doctest: +SKIP
-        >>> s = Session([('a', a), ('b', b), ('a01', a01), ('arr1', arr1), ('arr2', arr2)])  # doctest: +SKIP
+        >>> arr1, arr2 = ndtest((a, b)), ndtest(a)
+        >>> ses = Session([('i', i), ('s', s), ('a', a), ('b', b), ('a01', a01),
+        ...                ('arr1', arr1), ('arr2', arr2)])
         >>> # metadata
-        >>> s.meta.title = 'my title'                    # doctest: +SKIP
-        >>> s.meta.author = 'John Smith'                 # doctest: +SKIP
+        >>> ses.meta.title = 'my title'
+        >>> ses.meta.author = 'John Smith'
 
-        Save all arrays
+        Save all arrays (and arrays only)
 
-        >>> s.to_csv('./Output')  # doctest: +SKIP
+        >>> ses.to_csv('output', display=True)
+        dumping i ... Cannot dump i. int is not a supported type
+        dumping s ... Cannot dump s. str is not a supported type
+        dumping a ... Cannot dump a. Axis is not a supported type
+        dumping b ... Cannot dump b. Axis is not a supported type
+        dumping a01 ... Cannot dump a01. LGroup is not a supported type
+        dumping arr1 ... done
+        dumping arr2 ... done
 
         Save only some arrays
 
-        >>> s.to_csv('./Output', ['a', 'b', 'arr1'])  # doctest: +SKIP
+        >>> ses.to_csv('output', names=['arr1'], display=True)
+        dumping arr1 ... done
         """
         self.save(fname, names, ext_default_engine['csv'], display=display, **kwargs)