Column formatters

Formats define how values in a report should be output for display to the user. They generally take the underlying Python value and convert it into a string appropriate for display in the given medium. For example, an internal value of Decimal('9.99') might be converted to a display value of '$9.99' for monetary values.

All formatters accept the following optional keyword arguments:

• label: A string that will be used as the label for the column, as returned by the report_header method. By default, this will be automatically generated based on the column name.
• align: Either 'left' or 'right', used to determine the preferred alignment of the column data. If this is not supplied, the formatter will use its default alignment. Generally, number-type columns default to right-aligned, while other columns default to left-aligned.

Note

Many of the formatters rely on Python’s locale module to perform locale-dependent formatting. For example, if your locale is set to 'en_US', monetary values will be formatted as '$1,234.00'. If your locale is set to 'en_GB', monetary values will be formatted as '£1,123.00'. Your locale is set per Python thread, and should be set somewhere in your code that guarantees it will be run prior to any formatting operations. See Python’s documentation for the locale module for more.

Output formats

As a base, all formats have formatter functions defined for two types of output: HTML and CSV. You can pass in 'html' (the default) or 'csv' as the format option to your report’s report_rows and report_footer methods to format the output appropriately.

But you are not limited to HTML and CSV output formatting. If you want to format values differently for another medium, you can subclass any formats you use and add a format_NAME method. For example, you could add a format_pdf method. You would then pass in 'pdf' as the format option to your report’s report_rows and report_footer methods. See the docstring and code of the base Format class for more.

Formatter types

class blingalytics.formats.Hidden(label=None, align=None, sortable=True)

No particular formatting is performed, and this column should be hidden from the end user. This column will be marked as hidden in the header data returned by your report’s report_header method.

A hidden column is used for the internal ID returned with each row. You could also use these yourself to, for example, pass along a URL that gets formatted into a nice-looking link with some front-end JavaScript.

class blingalytics.formats.Bling(label=None, align=None, sortable=True)

Formats the column as monetary data. This is formatted as currency according to the thread-level locale setting. If being output for HTML, it will add grouping indicators (such as commas in the U.S.). If being output for CSV, it will not. By default, the column is right-aligned.

For example, in the 'en_US' locale, numbers will be formatted as '$1,234.56' for HTML or '$1234.56' for CSV.

class blingalytics.formats.Integer(grouping=True, **kwargs)

Formats the data as an integer. This formatter accepts one additional optional argument:

• grouping: Whether or not the formatted value should have groupings (such as a comma in the U.S.) when output for HTML. For example, when representing the number of pageviews per month, you would probably want separators; however, for an database ID you probably don’t. Defaults to True.

This formatting is based on the Python thread-level locale setting. For example, in the 'en_US' locale, numbers will be formatted as '1,234' for HTML or '1234' for CSV. By default, the column is right-aligned.

class blingalytics.formats.Percent(precision=1, **kwargs)

Formats the data as a percent. This formatter accepts one additional optional argument:

• precision: The number of decimal places of precision that should be kept for display. Defaults to 1.

This is formatted as a decimal number with a trailing percent sign. For example, numbers will be formatted as '12.3%' with a precision of 1. By default, this column is right-aligned.

class blingalytics.formats.String(title=False, truncate=None, **kwargs)

Formats column data as strings. Essentially, this will simply coerce values to strings. It also accepts a couple optional formatting parameters:

• title: If True, will title-case the string. Defaults to False.
• truncate: Set this to an integer value to truncate the string to that number of characters. Adds an ellipsis if truncation was performed. Defaults to not performing any truncation.

This column is left-aligned by default.

class blingalytics.formats.Boolean(terms=('Yes', 'No', ''), **kwargs)

Formatter for boolean data. This coerces the value to a boolean, and then presents a string representation of whether it’s true or false. It accepts one optional argument:

• terms: This is a tuple of three strings that determine how true, false, and null values will be represented, in that order. By default, it uses ('Yes', 'No', '').

This column is left-aligned by default.

class blingalytics.formats.Epoch(label=None, align=None, sortable=True)

Formats the column as a date. Expects the underlying data to be stored as an integer number of days since the UNIX epoch. (This storage method works great in conjunction with a database.ColumnTransform filter for doing timezone offsets.)

This date is formatted according to the Python thread’s locale setting. For example, in the 'en_US' locale, a date is formatted as ‘01/23/2011’. By default, the column is left-aligned.

class blingalytics.formats.Date(format=None, **kwargs)

Formats the column as a date. Expects the underlying data to be stored as a Python date or datetime object. This date is formatted according to the Python thread’s locale setting. For example, in the 'en_US' locale, a date is formatted as ‘01/23/2011’. By default, the column is left-aligned.

class blingalytics.formats.Month(label=None, align=None, sortable=True)

Formats the column as a month. Expects the underlying values to be Python datetime or date objects. For example, 'Jan 2011'.