fix #274 : implemented get_options() and set_options() to set global printing options for arrays

Author: alixdamman

doc/source/api.rst

@@ -664,6 +664,8 @@ Miscellaneous
    from_frame
    from_series
    get_example_filepath
+   set_options
+   get_options
    labels_array
    union
    stack

doc/source/changes/version_0_30.rst.inc

@@ -224,6 +224,55 @@ Miscellaneous improvements
 * implemented :py:obj:`LArray.reverse()` method to reverse one or several axes of an array (closes :issue:`631`).
 
 
+* added :py:obj:`set_options` allowing to set options for larray within a ``with`` block or globally:
+
+    >>> from larray import *
+    >>> arr = ndtest((500, 100), dtype=float) + 0.123456
+
+    You can use ``set_options`` either as a context manager:
+
+    >>> # display_width defines the maximum display width when printing an array
+    >>> # display_edgeitems defines the number of lines of the header and tail to display
+    >>> with set_options(display_width=100, display_edgeitems=2):
+    ...     print(arr)
+     a\b            b0            b1            b2  ...           b97           b98           b99
+      a0      0.123456      1.123456      2.123456  ...     97.123456     98.123456     99.123456
+      a1    100.123456    101.123456    102.123456  ...    197.123456    198.123456    199.123456
+     ...           ...           ...           ...  ...           ...           ...           ...
+    a498  49800.123456  49801.123456  49802.123456  ...  49897.123456  49898.123456  49899.123456
+    a499  49900.123456  49901.123456  49902.123456  ...  49997.123456  49998.123456  49999.123456
+
+    Or to set global options:
+
+    >>> # display_maxlines defines the maximum number of lines to show
+    >>> # display_precision defines the number of digits of precision for floating point output
+    >>> set_options(display_maxlines=10, display_precision=2)
+    >>> print(arr)
+     a\b        b0        b1        b2  ...       b97       b98       b99
+      a0      0.12      1.12      2.12  ...     97.12     98.12     99.12
+      a1    100.12    101.12    102.12  ...    197.12    198.12    199.12
+      a2    200.12    201.12    202.12  ...    297.12    298.12    299.12
+      a3    300.12    301.12    302.12  ...    397.12    398.12    399.12
+      a4    400.12    401.12    402.12  ...    497.12    498.12    499.12
+     ...       ...       ...       ...  ...       ...       ...       ...
+    a495  49500.12  49501.12  49502.12  ...  49597.12  49598.12  49599.12
+    a496  49600.12  49601.12  49602.12  ...  49697.12  49698.12  49699.12
+    a497  49700.12  49701.12  49702.12  ...  49797.12  49798.12  49799.12
+    a498  49800.12  49801.12  49802.12  ...  49897.12  49898.12  49899.12
+    a499  49900.12  49901.12  49902.12  ...  49997.12  49998.12  49999.12
+
+    To put back the default options, you can use:
+
+    >>> set_options(display_precision=None, display_width=80, display_maxlines=200, display_edgeitems=5)
+
+  The :py:obj:`get_options` function returns a view of the current options as a dictionary:
+
+    >>> get_options()
+    {'display_precision': None, 'display_width': 80, 'display_maxlines': 200, 'display_edgeitems': 5}
+
+  Closes :issue:`274`.
+
+
 Fixes
 -----
 

larray/__init__.py

@@ -30,6 +30,8 @@
 from larray.inout.sas import read_sas
 from larray.inout.xw_excel import open_excel, Workbook
 
+from larray.util.options import get_options, set_options
+
 from larray.viewer import view, edit, compare
 
 from larray.extra.ipfp import ipfp
@@ -68,6 +70,8 @@
     # inout
     'from_lists', 'from_string', 'from_frame', 'from_series', 'read_csv', 'read_tsv',
     'read_eurostat', 'read_excel', 'read_hdf', 'read_sas', 'open_excel', 'Workbook',
+    # utils
+    'get_options', 'set_options',
     # viewer
     'view', 'edit', 'compare',
     # ipfp

larray/core/array.py

@@ -65,6 +65,7 @@
 from larray.util.misc import (table2str, size2str, basestring, izip, rproduct, ReprString, duplicates,
                               float_error_handler_factory, _isnoneslice, light_product, unique_list, common_type,
                               renamed_to, deprecate_kwarg, LHDFStore, lazy_attribute)
+from larray.util.options import _OPTIONS, DISPLAY_MAXLINES, DISPLAY_EDGEITEMS, DISPLAY_WIDTH, DISPLAY_PRECISION
 
 
 def all(values, axis=None):
@@ -2277,8 +2278,9 @@ def __str__(self):
         elif not len(self):
             return 'LArray([])'
         else:
-            table = list(self.as_table(maxlines=200, edgeitems=5))
-            return table2str(table, 'nan', fullinfo=True, maxwidth=200, keepcols=self.ndim - 1)
+            table = list(self.as_table(_OPTIONS[DISPLAY_MAXLINES], _OPTIONS[DISPLAY_EDGEITEMS]))
+            return table2str(table, 'nan', maxwidth=_OPTIONS[DISPLAY_WIDTH], keepcols=self.ndim - 1,
+                             precision=_OPTIONS[DISPLAY_PRECISION])
     __repr__ = __str__
 
     def __iter__(self):
@@ -2287,19 +2289,22 @@ def __iter__(self):
     def __contains__(self, key):
         return any(key in axis for axis in self.axes)
 
-    def as_table(self, maxlines=None, edgeitems=5, light=False, wide=True, value_name='value'):
-        """
+    def as_table(self, maxlines=-1, edgeitems=5, light=False, wide=True, value_name='value'):
+        r"""
         Generator. Returns next line of the table representing an array.
 
         Parameters
         ----------
         maxlines : int, optional
-            Maximum number of lines to show.
+            Maximum number of lines to show. Defaults to -1 (all lines are shown).
         edgeitems : int, optional
             If number of lines to display is greater than `maxlines`,
             only the first and last `edgeitems` lines are displayed.
-            Only active if `maxlines` is not None.
-            Equals to 5 by default.
+            Only active if `maxlines` is not -1.
+            Defaults to 5.
+        light : bool, optional
+            Whether or not to hide repeated labels. In other words, only show a label if it is different from the
+            previous one. Defaults to False.
         wide : boolean, optional
             Whether or not to write arrays in "wide" format. If True, arrays are exported with the last axis
             represented horizontally. If False, arrays are exported in "narrow" format: one column per axis plus one
@@ -2317,13 +2322,13 @@ def as_table(self, maxlines=None, edgeitems=5, light=False, wide=True, value_nam
         --------
         >>> arr = ndtest((2, 2, 3))
         >>> list(arr.as_table())  # doctest: +NORMALIZE_WHITESPACE
-        [['a', 'b\\\\c', 'c0', 'c1', 'c2'],
+        [['a', 'b\\c', 'c0', 'c1', 'c2'],
          ['a0', 'b0', 0, 1, 2],
          ['a0', 'b1', 3, 4, 5],
          ['a1', 'b0', 6, 7, 8],
          ['a1', 'b1', 9, 10, 11]]
         >>> list(arr.as_table(light=True))  # doctest: +NORMALIZE_WHITESPACE
-        [['a', 'b\\\\c', 'c0', 'c1', 'c2'],
+        [['a', 'b\\c', 'c0', 'c1', 'c2'],
          ['a0', 'b0', 0, 1, 2],
          ['', 'b1', 3, 4, 5],
          ['a1', 'b0', 6, 7, 8],
@@ -2379,7 +2384,7 @@ def as_table(self, maxlines=None, edgeitems=5, light=False, wide=True, value_nam
         other_colnames = self.axes[-1].labels.tolist() if wide else [value_name]
         yield axes_names + other_colnames
         # summary if needed
-        if maxlines is not None and height > maxlines:
+        if maxlines >= 0 and height > maxlines:
             # replace middle lines of the table by '...'.
             # We show only the first and last edgeitems lines.
             startticks = islice(ticks, edgeitems)
@@ -2398,7 +2403,8 @@ def as_table(self, maxlines=None, edgeitems=5, light=False, wide=True, value_nam
                 yield list(tick) + dataline.tolist()
 
     def dump(self, header=True, wide=True, value_name='value'):
-        """Dump array as a 2D nested list
+        """
+        Dump array as a 2D nested list
 
         Parameters
         ----------
@@ -2420,7 +2426,7 @@ def dump(self, header=True, wide=True, value_name='value'):
             # flatten all dimensions except the last one
             return self.data.reshape(-1, self.shape[-1]).tolist()
         else:
-            return list(self.as_table(wide=wide, value_name=value_name))
+            return list(self.as_table(maxlines=-1, wide=wide, value_name=value_name))
 
     # XXX: should filter(geo=['W']) return a view by default? (collapse=True)
     # I think it would be dangerous to make it the default

larray/tests/test_array.py

@@ -309,10 +309,8 @@ def test_str(small_array, array):
 115  A21          F  153105.0  153106.0  153107.0"""
     # too many columns
     assert str(array['P01', 'A11', 'M']) == """\
-age    0       1       2       3       4       5       6       7        8  ...  \
-     106       107       108       109       110       111       112       113       114       115
-     0.0  1320.0  2640.0  3960.0  5280.0  6600.0  7920.0  9240.0  10560.0  ...  \
-139920.0  141240.0  142560.0  143880.0  145200.0  146520.0  147840.0  149160.0  150480.0  151800.0"""
+age    0       1       2  ...       112       113       114       115
+     0.0  1320.0  2640.0  ...  147840.0  149160.0  150480.0  151800.0"""
 
     arr = LArray([0, ''], Axis(['a0', ''], 'a'))
     assert str(arr) == "a  a0  \n    0  "

larray/tests/test_options.py

@@ -0,0 +1,29 @@
+from __future__ import absolute_import, division, print_function
+import pytest
+import larray
+
+
+def test_invalid_option_raises():
+    with pytest.raises(ValueError):
+        larray.set_options(not_a_valid_options=True)
+
+
+def test_set_options_as_global():
+    original_ops = larray.get_options()
+    arr = larray.ndtest((500, 100))
+    larray.set_options(display_width=40, display_maxlines=10)
+    expected = """\
+ a\\b     b0     b1  ...    b98    b99
+  a0      0      1  ...     98     99
+  a1    100    101  ...    198    199
+  a2    200    201  ...    298    299
+  a3    300    301  ...    398    399
+  a4    400    401  ...    498    499
+ ...    ...    ...  ...    ...    ...
+a495  49500  49501  ...  49598  49599
+a496  49600  49601  ...  49698  49699
+a497  49700  49701  ...  49798  49799
+a498  49800  49801  ...  49898  49899
+a499  49900  49901  ...  49998  49999"""
+    assert str(arr) == expected
+    larray.set_options(**original_ops)

larray/util/__init__.py

@@ -1 +0,0 @@
-from __future__ import absolute_import, division, print_function

larray/util/misc.py

@@ -81,13 +81,15 @@ def prod(values):
     return reduce(operator.mul, values, 1)
 
 
-def format_value(value, missing, fullinfo=False):
-    if isinstance(value, float) and not fullinfo:
+def format_value(value, missing, precision=None):
+    if isinstance(value, float):
         # nans print as "-1.#J", let's use something nicer
         if value != value:
             return missing
+        elif precision is not None:
+            return '{:.{precision}f}'.format(value, precision=precision)
         else:
-            return '%2.f' % value
+            return str(value)
     elif isinstance(value, np.ndarray) and value.shape:
         # prevent numpy's default wrapping
         return str(list(value)).replace(',', '')
@@ -131,8 +133,8 @@ def get_min_width(table, index):
     return max(longest_word(row[index]) for row in table)
 
 
-def table2str(table, missing, fullinfo=False, summarize=True, maxwidth=80, numedges='auto', sep='  ', cont='...',
-              keepcols=0):
+def table2str(table, missing, summarize=True, maxwidth=200, numedges='auto', sep='  ', cont='...',
+              keepcols=0, precision=None):
     """
     table is a list of lists
     :type table: list of list
@@ -144,7 +146,7 @@ def table2str(table, missing, fullinfo=False, summarize=True, maxwidth=80, numed
     for row in table:
         if len(row) < numcol:
             row.extend([''] * (numcol - len(row)))
-    formatted = [[format_value(value, missing, fullinfo) for value in row]
+    formatted = [[format_value(value, missing, precision) for value in row]
                  for row in table]
     maxwidths = [get_col_width(formatted, i) for i in range(numcol)]
 

larray/util/options.py

@@ -0,0 +1,138 @@
+from __future__ import absolute_import, division, print_function
+
+
+DISPLAY_PRECISION = 'display_precision'
+DISPLAY_WIDTH = 'display_width'
+DISPLAY_MAXLINES = 'display_maxlines'
+DISPLAY_EDGEITEMS = 'display_edgeitems'
+
+
+_OPTIONS = {
+    DISPLAY_PRECISION: None,
+    DISPLAY_WIDTH: 80,
+    DISPLAY_MAXLINES: 200,
+    DISPLAY_EDGEITEMS: 5,
+}
+
+
+def _positive_integer(value):
+    if not (isinstance(value, int) and value > 0):
+        raise ValueError("Expected positive integer")
+
+
+def _integer_maxlines(value):
+    if not isinstance(value, int) and value >= -1:
+        raise ValueError("Expected integer")
+
+
+def _positive_integer_or_none(value):
+    if value is None:
+        return
+    else:
+        _positive_integer(value)
+
+
+_VALIDATORS = {
+    DISPLAY_PRECISION: _positive_integer_or_none,
+    DISPLAY_WIDTH: _positive_integer,
+    DISPLAY_MAXLINES: _integer_maxlines,
+    DISPLAY_EDGEITEMS: _positive_integer,
+}
+
+
+# idea taken from xarray. See xarray/core/options.py module for original implementation.
+class set_options(object):
+    r"""Set options for larray in a controlled context.
+
+    Currently supported options:
+
+    - ``display_precision``: number of digits of precision for floating point output.
+      Print as many digits as necessary to uniquely specify the value by default (None).
+    - ``display_width``: maximum display width for ``repr`` on larray objects. Defaults to 80.
+    - ``display_maxlines``: Maximum number of lines to show. All lines are shown if -1.
+      Defaults to 200.
+    - ``display_edgeitems`` : if number of lines to display is greater than ``display_maxlines``,
+      only the first and last ``display_edgeitems`` lines are displayed.
+      Only active if ``display_maxlines`` is not -1. Defaults to 5.
+
+    Examples
+    --------
+    >>> from larray import *
+    >>> arr = ndtest((500, 100), dtype=float) + 0.123456
+
+    You can use ``set_options`` either as a context manager:
+
+    >>> with set_options(display_width=100, display_edgeitems=2):
+    ...     print(arr)
+     a\b            b0            b1            b2  ...           b97           b98           b99
+      a0      0.123456      1.123456      2.123456  ...     97.123456     98.123456     99.123456
+      a1    100.123456    101.123456    102.123456  ...    197.123456    198.123456    199.123456
+     ...           ...           ...           ...  ...           ...           ...           ...
+    a498  49800.123456  49801.123456  49802.123456  ...  49897.123456  49898.123456  49899.123456
+    a499  49900.123456  49901.123456  49902.123456  ...  49997.123456  49998.123456  49999.123456
+
+    Or to set global options:
+
+    >>> set_options(display_maxlines=10, display_precision=2) # doctest: +SKIP
+    >>> print(arr) # doctest: +SKIP
+     a\b        b0        b1        b2  ...       b97       b98       b99
+      a0      0.12      1.12      2.12  ...     97.12     98.12     99.12
+      a1    100.12    101.12    102.12  ...    197.12    198.12    199.12
+      a2    200.12    201.12    202.12  ...    297.12    298.12    299.12
+      a3    300.12    301.12    302.12  ...    397.12    398.12    399.12
+      a4    400.12    401.12    402.12  ...    497.12    498.12    499.12
+     ...       ...       ...       ...  ...       ...       ...       ...
+    a495  49500.12  49501.12  49502.12  ...  49597.12  49598.12  49599.12
+    a496  49600.12  49601.12  49602.12  ...  49697.12  49698.12  49699.12
+    a497  49700.12  49701.12  49702.12  ...  49797.12  49798.12  49799.12
+    a498  49800.12  49801.12  49802.12  ...  49897.12  49898.12  49899.12
+    a499  49900.12  49901.12  49902.12  ...  49997.12  49998.12  49999.12
+
+    To put back the default options, you can use:
+
+    >>> set_options(display_precision=None, display_width=80, display_maxlines=200, display_edgeitems=5)
+    ... # doctest: +SKIP
+    """
+
+    def __init__(self, **kwargs):
+        self.old = {}
+        for k, v in kwargs.items():
+            if k not in _OPTIONS:
+                raise ValueError('Argument {} is not in the set of valid options {}'.format(k, set(_OPTIONS)))
+            if k in _VALIDATORS:
+                _VALIDATORS[k](v)
+            self.old[k] = _OPTIONS[k]
+        _OPTIONS.update(kwargs)
+
+    def __enter__(self):
+        return
+
+    def __exit__(self, type, value, traceback):
+        _OPTIONS.update(self.old)
+
+
+def get_options():
+    """
+    Return the current options.
+
+    Returns
+    -------
+    Dictionary of current print options with keys
+
+        - display_precision: int or None
+        - display_width: int
+        - display_maxlines: int
+        - display_edgeitems : int
+
+    For a full description of these options, see :py:obj:`set_options`.
+
+    See Also
+    --------
+    set_options
+
+    Examples
+    --------
+    >>> get_options() # doctest: +SKIP
+    {'display_precision': None, 'display_width': 80, 'display_maxlines': 200, 'display_edgeitems': 5}
+    """
+    return _OPTIONS.copy()