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:
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.
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.
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.
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.
Formats the data as an integer. This formatter accepts one additional optional argument:
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.
Formats the data as a percent. This formatter accepts one additional optional argument:
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.
Formats column data as strings. Essentially, this will simply coerce values to strings. It also accepts a couple optional formatting parameters:
This column is left-aligned by default.
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:
This column is left-aligned by default.
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.
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.
Formats the column as a month. Expects the underlying values to be Python datetime or date objects. For example, 'Jan 2011'.