# -*- coding: utf-8 -*-
"""These preprocessor functions are used to process data prior to output."""
import string
from cli_helpers import utils
from cli_helpers.compat import text_type, int_types, float_types, HAS_PYGMENTS, Token
def truncate_string(
data, headers, max_field_width=None, skip_multiline_string=True, **_
):
"""Truncate very long strings. Only needed for tabular
representation, because trying to tabulate very long data
is problematic in terms of performance, and does not make any
sense visually.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param int max_field_width: Width to truncate field for display
:return: The processed data and headers.
:rtype: tuple
"""
return (
(
[
utils.truncate_string(v, max_field_width, skip_multiline_string)
for v in row
]
for row in data
),
[
utils.truncate_string(h, max_field_width, skip_multiline_string)
for h in headers
],
)
def convert_to_string(data, headers, **_):
"""Convert all *data* and *headers* to strings.
Binary data that cannot be decoded is converted to a hexadecimal
representation via :func:`binascii.hexlify`.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:return: The processed data and headers.
:rtype: tuple
"""
return (
([utils.to_string(v) for v in row] for row in data),
[utils.to_string(h) for h in headers],
)
def override_missing_value(
data,
headers,
style=None,
missing_value_token=Token.Output.Null,
missing_value="",
**_,
):
"""Override missing values in the *data* with *missing_value*.
A missing value is any value that is :data:`None`.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param style: Style for missing_value.
:param missing_value_token: The Pygments token used for missing data.
:param missing_value: The default value to use for missing data.
:return: The processed data and headers.
:rtype: tuple
"""
def fields():
for row in data:
processed = []
for field in row:
if field is None and style and HAS_PYGMENTS:
styled = utils.style_field(
missing_value_token, missing_value, style
)
processed.append(styled)
elif field is None:
processed.append(missing_value)
else:
processed.append(field)
yield processed
return (fields(), headers)
def override_tab_value(data, headers, new_value=" ", **_):
"""Override tab values in the *data* with *new_value*.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param new_value: The new value to use for tab.
:return: The processed data and headers.
:rtype: tuple
"""
return (
(
[v.replace("\t", new_value) if isinstance(v, text_type) else v for v in row]
for row in data
),
headers,
)
def escape_newlines(data, headers, **_):
"""Escape newline characters (\n -> \\n, \r -> \\r)
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:return: The processed data and headers.
:rtype: tuple
"""
return (
(
[
v.replace("\r", r"\r").replace("\n", r"\n")
if isinstance(v, text_type)
else v
for v in row
]
for row in data
),
headers,
)
def bytes_to_string(data, headers, **_):
"""Convert all *data* and *headers* bytes to strings.
Binary data that cannot be decoded is converted to a hexadecimal
representation via :func:`binascii.hexlify`.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:return: The processed data and headers.
:rtype: tuple
"""
return (
([utils.bytes_to_string(v) for v in row] for row in data),
[utils.bytes_to_string(h) for h in headers],
)
def align_decimals(data, headers, column_types=(), **_):
"""Align numbers in *data* on their decimal points.
Whitespace padding is added before a number so that all numbers in a
column are aligned.
Outputting data before aligning the decimals::
1
2.1
10.59
Outputting data after aligning the decimals::
1
2.1
10.59
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param iterable column_types: The columns' type objects (e.g. int or float).
:return: The processed data and headers.
:rtype: tuple
"""
pointpos = len(headers) * [0]
data = list(data)
for row in data:
for i, v in enumerate(row):
if column_types[i] is float and type(v) in float_types:
v = text_type(v)
pointpos[i] = max(utils.intlen(v), pointpos[i])
def results(data):
for row in data:
result = []
for i, v in enumerate(row):
if column_types[i] is float and type(v) in float_types:
v = text_type(v)
result.append((pointpos[i] - utils.intlen(v)) * " " + v)
else:
result.append(v)
yield result
return results(data), headers
def quote_whitespaces(data, headers, quotestyle="'", **_):
"""Quote leading/trailing whitespace in *data*.
When outputing data with leading or trailing whitespace, it can be useful
to put quotation marks around the value so the whitespace is more
apparent. If one value in a column needs quoted, then all values in that
column are quoted to keep things consistent.
.. NOTE::
:data:`string.whitespace` is used to determine which characters are
whitespace.
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param str quotestyle: The quotation mark to use (defaults to ``'``).
:return: The processed data and headers.
:rtype: tuple
"""
whitespace = tuple(string.whitespace)
quote = len(headers) * [False]
data = list(data)
for row in data:
for i, v in enumerate(row):
v = text_type(v)
if v.startswith(whitespace) or v.endswith(whitespace):
quote[i] = True
def results(data):
for row in data:
result = []
for i, v in enumerate(row):
quotation = quotestyle if quote[i] else ""
result.append(
"{quotestyle}{value}{quotestyle}".format(
quotestyle=quotation, value=v
)
)
yield result
return results(data), headers
def style_output(
data,
headers,
style=None,
header_token=Token.Output.Header,
odd_row_token=Token.Output.OddRow,
even_row_token=Token.Output.EvenRow,
**_,
):
"""Style the *data* and *headers* (e.g. bold, italic, and colors)
.. NOTE::
This requires the `Pygments `_ library to
be installed. You can install it with CLI Helpers as an extra::
$ pip install cli_helpers[styles]
Example usage::
from cli_helpers.tabular_output.preprocessors import style_output
from pygments.style import Style
from pygments.token import Token
class YourStyle(Style):
default_style = ""
styles = {
Token.Output.Header: 'bold ansibrightred',
Token.Output.OddRow: 'bg:#eee #111',
Token.Output.EvenRow: '#0f0'
}
headers = ('First Name', 'Last Name')
data = [['Fred', 'Roberts'], ['George', 'Smith']]
data, headers = style_output(data, headers, style=YourStyle)
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param str/pygments.style.Style style: A Pygments style. You can `create
your own styles `_.
:param str header_token: The token type to be used for the headers.
:param str odd_row_token: The token type to be used for odd rows.
:param str even_row_token: The token type to be used for even rows.
:return: The styled data and headers.
:rtype: tuple
"""
from cli_helpers.utils import filter_style_table
relevant_styles = filter_style_table(
style, header_token, odd_row_token, even_row_token
)
if style and HAS_PYGMENTS:
if relevant_styles.get(header_token):
headers = [
utils.style_field(header_token, header, style) for header in headers
]
if relevant_styles.get(odd_row_token) or relevant_styles.get(even_row_token):
data = (
[
utils.style_field(
odd_row_token if i % 2 else even_row_token, f, style
)
for f in r
]
for i, r in enumerate(data, 1)
)
return iter(data), headers
def format_numbers(
data, headers, column_types=(), integer_format=None, float_format=None, **_
):
"""Format numbers according to a format specification.
This uses Python's format specification to format numbers of the following
types: :class:`int`, :class:`py2:long` (Python 2), :class:`float`, and
:class:`~decimal.Decimal`. See the :ref:`python:formatspec` for more
information about the format strings.
.. NOTE::
A column is only formatted if all of its values are the same type
(except for :data:`None`).
:param iterable data: An :term:`iterable` (e.g. list) of rows.
:param iterable headers: The column headers.
:param iterable column_types: The columns' type objects (e.g. int or float).
:param str integer_format: The format string to use for integer columns.
:param str float_format: The format string to use for float columns.
:return: The processed data and headers.
:rtype: tuple
"""
if (integer_format is None and float_format is None) or not column_types:
return iter(data), headers
def _format_number(field, column_type):
if integer_format and column_type is int and type(field) in int_types:
return format(field, integer_format)
elif float_format and column_type is float and type(field) in float_types:
return format(field, float_format)
return field
data = (
[_format_number(v, column_types[i]) for i, v in enumerate(row)] for row in data
)
return data, headers