API¶
Building the presentation model¶
-
table_compositor.table_compositor.build_presentation_model(*, df, output_format='xlsx', data_value_func=None, column_style_func=None, data_style_func=None, header_style_func=None, header_value_func=None, index_style_func=None, index_value_func=None, index_name_func=None, index_name_style_func=None, engine='openpyxl', **kwargs)[source]¶ Construct and return the presentation model that will be used while rendering to html/xlsx formats. The returned object has all the information required to render the tables in the requested format. The details of the object is transparent to the caller. It is only exposed for certain advanced operations.
Parameters: - df – The dataframe representation of the table. The shape of the dataframe closely resembles the table that will be rendered in the requested format.
- output_format – ‘html’ or ‘xlsx’
- data_value_func – example: lambda idx, col: df.loc[idx, col], assuming df is in the closure. This can be None, if no data transformation is required to the values already present in the source df
- column_style_func – the function can substitute the data_style_func, if the same style can be applied for the whole column. This argument should be prefered over the data_style_func argument. Using this option provides better performance since the fewer objects will be created internally and fewer callbacks are made to this function when compared to data_style_func.This argument only applies to the data contained in the dataframe and not the cell where the headers are rendered. For fine grained control at cell level, the data_style_func argument can be used. For more information on return values of this function, refer to the documentation for data_style_func argument.
- data_style_func – used to provide style at the cell level. Example: lambda idx, col: return dict(font=Font(…)), where Font is the openpyxl object and font is the attr available in the cell instance of openpyxl. For xlsx, the keys in the dict are the attrs of the cell object in openpyxl and the values correspond to the value of that attribute. Example are found in xlsx_styles module. For html, the key-value pairs are any values that go into to the style attribute of a td, th cell in html. Examples are found in html_styles module. example: dict(background-color=’#F8F8F8’). When performance becomes an issue, and cell level control is not needed, it is recommended to use the column_style_func argument rathat than this argument. If the prefered engine is XlswWriter, then the style dictionary returned should have key/values compatible with the Format object declarted in the XlsxWriter library. A reference can be found in ``xlsx_styles.XlsxWriterStyleHelper` class
- header_value_func – func that takes a object of type IndexNode. The IndexNode contains the attributes that refer to the header being rendered. The returned value from this function is displayed in place of the header in the dataframe at the location. The two properties available on the IndexNode object are value and key. The key is useful to identify the exact index and level in context while working with multi-hierarchical columns.
- header_style_func – func that takes a object of type IndexNode. The return value of this function is similar to data_style_func.
- index_value_func – func that takes a object of type IndexNode. The IndexNode contains the attributes that refer to the index being rendered. The returned value from this function is displayed in place of the index in the dataframe at the location.
- index_style_func – func that takes a object of type IndexNode. The return value of this function is similar to data_style_func.
- index_name_func – func that returns a string for index name (value to be displayed on top-left corner, above the index column)
- index_name_style – the style value same as data_style_func that will be used to style the cell
- engine – required while building presentation model for xlsx. Argument ignored for HTML rendering. This argument is used to provide the default callback style functions, where the style dictionary returned by the callback functions should be compatible with the engine being used.
- kwargs –
‘hide_index’ - if True, then hide the index column, default=False
’hide_header, - if True, then hide the header, default=False
’use_convert’ - if True, do some conversions from dataframe values to values excel can understand for example np.NaN are converted to NaN strings
Returns: A presentation model, to be used to create layout and provide the layout to the html or xlsx writers.
About the callback functions provided as arguments:
Note that callback function provided as arguments to this function are provided with either a tuple of index, col arguments are some information regarding the index or headers being rendered. Therefore, a common pattern would be to capture the dataframe being rendered in a closure of this callback func before passing them as arugments.
For example:
df = pd.DataFrame(dict(a=[1, 2, 3]))
- def data_value_func():
- def _inner(idx, col):
- return df.loc[idx, col] * 10.3
return _inner
pm = build_presentation_model(df=df, data_value_func=data_value_func())
Rendering to XLSX¶
Rendering to HTML¶
-
class
table_compositor.html_writer.HTMLWriter[source]¶ -
static
to_html(layout, orientation='vertical', **kwargs)[source]¶ Take a layout which contains a list of presentation models builts using the build_presentation_model function.
Parameters: - layout – An nested list of presentation_models, examples: [presentation_model] or [presentation_model1, presentation_mode2]. Not all nested layouts work very well in HTML, currently
- orientation – if vertical, the top level presentation model elements are rendered vertically, and for every nested level the orientation is flipped. if horizontal, then the behavior is inverse
- kwargs – all key-value pairs available in kwargs are directly set as value of the style attribute of table tag. example dict(backgroud-color=’#FF88FF’), is used as <table style=’background-color:#FF88FF’>..</table>
Returns: Return a HTML formatted string. The outermost tag of the returned string is the <table>
-
static
Helper XLSX Styles¶
-
class
table_compositor.xlsx_styles.OpenPyxlStyleHelper[source]¶ -
default_header_style[source]¶ Provides styles for default headers for OpenPyxl engine
Parameters: - alignment – ‘center’, ‘left’, ‘right’ used for horizontal alignment
- font – an openpyxl.Font instance
- bgColor – hex color that will be used as background color in the fill pattern
- border – an openpyxl.Border instance, defaults to thin white border
Returns: A dict of key-values pairs, where each key is a attr of the cell object in openyxl and value is valid value of that attr.
-
get_style[source]¶ Helper method to return a openpyxl Style
Parameters: - number_format – an xlsx compatibale number format string
- bg_color – hex color that will be used as background color in the fill pattern
- border – an openpyxl.Border instance, defaults to thin white border
Returns: A dict of key-values pairs, where each key is a attr of the cell object in openyxl and value is valid value of that attr.
-
-
class
table_compositor.xlsx_styles.XlsxWriterStyleHelper[source]¶ Class provides style objects for XlsxWriter library uses to render xlsx files
-
static
default_header_style(*, number_format='General', alignment='center', font=None, bgColor='#4F81BD', border=<object object>)[source]¶ Provides styles for default headers for XlsxWriter engine
Parameters: - alignment – ‘center’, ‘left’, ‘right’ used for horizontal alignment
- font – an openpyxl.Font instance
- bgColor – hex color that will be used as background color in the fill pattern
- border – an openpyxl.Border instance, defaults to thin white border
Returns: A dict of key-values pairs, where each key is a attr of the cell object in openyxl and value is valid value of that attr.
-
static
get_style(number_format='General', bg_color=None, border=<object object>)[source]¶ Helper method to return Style dictionary for XlsxWriter engine
Parameters: - number_format – an xlsx compatibale number format string
- bg_color – hex color that will be used as background color in the fill pattern
- border – an openpyxl.Border instance, defaults to thin white border
Returns: A dict of key-values pairs, where each key/value is compatible with the Format object in XlsxWriter library.
-
static
-
class
table_compositor.xlsx_styles.XLSXWriterDefaults[source]¶ Class provides defaults callback funcs that can be used while calling the build_presentation_model.
-
static
data_style_func(df)[source]¶ Default value that can be used as callback for data_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes idx, col as arguments and returns a openpyxl compatible style dictionary
-
static
data_value_func(df)[source]¶ Default value that can be used as callback for data_value_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: A function that takes idx, col as arguments and returns the df.loc[idx, col] value
-
static
header_style_func(df)[source]¶ Default value that can be used as callback for data_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes node as arguments and returns a openpyxl compatible style dictionary
-
static
header_value_func(df)[source]¶ Default value that can be used as callback for data_header_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes node as arguments and returns node.value
-
static
index_name_style_func(df)[source]¶ Default value that can be used as callback for index_name_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes index.name as arguments and returns a openpyxl compatible style dictionary
-
static
index_name_value_func(df)[source]¶ Default value that can be used as callback for index_name_value_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes index.name as arguments and returns index.name if not None, else ‘’
-
static
Helper HTML Styles¶
-
class
table_compositor.html_styles.HTMLWriterDefaults[source]¶ Class provides defaults callback funcs that can be used while calling the build_presentation_model.
-
static
data_style_func(df)[source]¶ Default value that can be used as callback for data_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes idx, col as arguments and returns a dictionary of html style attributes
-
static
data_value_func(df, dollar_columns=None)[source]¶ Default value that can be used as callback for data_value_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: A function that takes idx, col as arguments and returns the df.loc[idx, col] value
-
static
header_style_func(df)[source]¶ Default value that can be used as callback for header_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes node as argument and returns a dictionary of html style attributes
-
static
header_value_func(df)[source]¶ Default value that can be used as callback for header_value_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: A function that takes node as arguments and returns the node.value
-
static
index_name_style_func(df)[source]¶ Default value that can be used as callback for index_name_style_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: a function table takes index.name as argument and returns a dictionary of html style attributes
-
static
index_name_value_func(df)[source]¶ Default value that can be used as callback for index_name_value_func
Parameters: df – the dataframe that will be used to build the presentation model Returns: A function that takes index.name as argument and return index.name if not None else ‘’
-
static