Source code for cli_helpers.tabular_output.preprocessors

# -*- 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


[docs]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 ], )
[docs]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], )
[docs]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)
[docs]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, )
[docs]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, )
[docs]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], )
[docs]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
[docs]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
[docs]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 <http://pygments.org/>`_ 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 <https://pygments.org/docs/styles#creating-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
[docs]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