df2tables: Pandas and Polars DataFrames to Interactive DataTables

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Tomasz_Sl from gravatar.com Tomasz_Sl

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: Tomasz Sługocki
  • Tags DataTables , HTML , Javascript , Pandas , Polars
  • Provides-Extra: pandas , polars
Report project as malware

Project description

df2tables - Pandas & Polars DataFrames to Interactive HTML Tables

PyPI version

df2tables is a Python utility for exporting Pandas and Polars DataFrames into interactive HTML tables using DataTables - a powerful JavaScript library.
It’s built to embed seamlessly into Flask, Django, FastAPI, or any web framework.

By rendering tables directly from JavaScript arrays, this tool delivers fast performance and compact file sizes, enabling smooth browsing of large datasets while maintaining full responsiveness.

Minimal dependencies: only pandas or polars (you don’t need pandas installed if using polars).

Converting a DataFrame to an interactive table takes just one function call:

render(df, **kwargs) 
# or for web frameworks:
render_inline(df, **kwargs)

Features

  • Converts pandas and polars dataframes interactive standalone HTML tables
  • Web Framework Ready: Specifically designed for easy embedding in Flask, Django, FastAPI, and other web frameworks
  • Browse large datasets using filters and sorting
  • Works independently of Jupyter or live server (though notebook rendering is supported)
  • Useful for training dataset inspection and feature engineering: Quickly browse through large datasets, identify outliers, and data quality issues interactively
  • Customization: Configuring DataTables from Python (new)

Screenshots

df2tables demo with 1,000,000 rows

A standalone HTML file containing a JavaScript array as data source for DataTables has several advantages. For example, you can browse quite large datasets locally.

The column control feature provides dropdown filters for categorical data and search functionality for text columns, enhancing data exploration capabilities through the excellent DataTables Column Control extension.

Note: By default, filtering is enabled for all non-numeric columns.

Quick Start

The simplest function call with default arguments is:

df2tables.render(df, to_file='df.html')

Installation

pip install df2tables

Sample DataFrame

#render sample DataFrame
html_string = df2t.render_sample_df(to_file="sample_table.html")

Rendering in notebook

from df2tables import  render_nb

render_nb(df) #show interactive table in jupyter notebook

Note: Notebook rendering is currently supported in Jupyter, VS Code notebooks and marimo

Main Functions

render

df2t.render(
    df: pd.DataFrame,
    to_file: Optional[str] = None,
    title: str = "Title",
    precision: int = 2,
    num_html: List[str] = None,
    startfile: bool = True,
    templ_path: str = TEMPLATE_PATH,
    load_column_control: bool = True,
    js_opts: Optional[dict] = None,
    display_logo: bool = True
) -> Union[str, file_object]

Parameters:

  • df: Input pandas DataFrame
  • to_file: Output HTML file path. If None, returns HTML string instead of writing file
  • title: Title for the HTML table
  • precision: Number of decimal places for floating-point numbers
  • num_html: List of numeric column names to render with color-coded HTML formatting (negative values in red)
  • startfile: If True, automatically opens the generated HTML file in default browser
  • templ_path: Path to custom HTML template (uses default if not specified)
  • load_column_control: If True, integrates the DataTables Column Control extension programmatically for enhanced filtering and search capabilities (default: True)
  • js_opts: Dictionary of DataTables configuration options to customize table behavior (e.g., pagination, scrolling, layout, language).(default: None)
  • display_logo: If True, displays DataTables logo (default: True)

Returns:

  • HTML string if to_file=None
  • File object if to_file is specified

render_inline

df2t.render_inline(
    df: pd.DataFrame, 
    table_attrs: Dict = None,
    **kwargs
) -> str

Parameters:

This function is designed for integration with web applications and has the following characteristics:

  • Returns only the <table> markup and the associated JavaScript
  • Excludes <html>, <head>, and <body> tags
  • Useful for pages with multiple tables, as you can assign unique IDs via the table_attrs dictionary (e.g., {'id': 'my-unique-table'})
  • Important: This function does not include jQuery or DataTables library dependencies. You must include them manually in your host HTML page for the table to function correctly

Some key arguments are not applicable, such as title or display_logo, because the returned HTML contains only the table and JavaScript.

The new additional table_attrs argument accepts a dictionary of HTML table attributes, such as an ID or CSS class. This is especially useful for multiple tables on a single page (each must have a different ID).

See an example of multiple tables with different configuration options placed in separate tabs (jQuery UI Tabs): flask_multiple_tables_tabs.py

Minimal Flask Example

Here's a complete, minimal working Flask application that demonstrates how to properly embed a DataTable with all required dependencies:

import df2tables as df2t
from flask import Flask, render_template_string

app = Flask(__name__)

@app.route("/")
def home():
    # Generate sample data (or use your own DataFrame)
    df = df2t.get_sample_df()
    df_title = "DataFrame Rendered as DataTable inline in <strong>Flask</strong>"

    string_datatable = df2t.render_inline(df)

    # Embed in a complete HTML template with all required dependencies
    return render_template_string(
        """
        <!DOCTYPE html>
        <html>
        <head>
            <title>Flask Data Dashboard</title>
            <meta name="viewport" content="width=device-width, initial-scale=1">
            
            <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
            <link href="https://cdn.datatables.net/2.3.4/css/dataTables.dataTables.min.css" rel="stylesheet">
            <script src="https://cdn.datatables.net/2.3.4/js/dataTables.min.js"></script><!--[column_control-->
            <link href="https://cdn.datatables.net/columncontrol/1.1.0/css/columnControl.dataTables.min.css" rel="stylesheet">
            <script src="https://cdn.datatables.net/columncontrol/1.1.0/js/dataTables.columnControl.min.js"></script><!--column_control]-->

            <!-- Optional: PureCSS for styling -->
            <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/purecss@3.0.0/build/pure-min.css">
        </head>
        <body style="background-color: #f4f4f4;">
            <div style="background-color: #fff; padding: 20px; margin: 20px;">
                <h1>My Flask Data Dashboard</h1>
                {{ inline_datatable | safe }}
            </div>
        </body>
        </html>
        """,
        inline_datatable=string_datatable,
    )

if __name__ == "__main__":
    app.run(debug=True)

Note: Pandas DataFrame indexes are not rendered by default. If you want to enable indexes in an HTML table, simply call df2tables.render(df.reset_index(), args...)

Customization: Configuring DataTables from Python

You can now customize DataTables behavior directly from Python by passing configuration options through the new js_opts parameter. This allows you to control DataTables options and features without modifying the HTML template.

Basic Usage

Simply pass a dictionary of DataTables options to the js_opts parameter in the render or render_inline function.

Examples

1. Customize Layout and Language

Rearrange control elements (such as the search bar and info display) using the layout option, or localize text:

custom_cfg = {
    "language": {
        "searchPlaceholder": "Search in all text columns"
    },
    "pageLength": 25, # number of table rows showing
    "layout": {
        "topStart": "info",
        "top1Start": "pageLength",
        "topEnd": "search", 
        "bottomEnd": "paging"
    }
}
df2t.render(df, js_opts=custom_cfg, to_file="localized_table.html")

2. Replace Paging with Scrolling

Disable pagination and enable vertical and horizontal scrolling for easier navigation of large datasets.

Note: Using scrollY with disabled paging can be slow for large DataFrames.

scroll_cfg = {
    "paging": False, # slow for large tables
    "scrollCollapse": False,
    "scrollY": '50vh',  
    "scrollX": "70vw"
}
df2t.render(df, js_opts=scroll_cfg, to_file="scrolling_table.html")

Error Handling

Invalid keys are ignored by DataTables, so malformed or non-existent options usually will not break table rendering.

Note: While invalid keys should be ignored, using a valid key with an incorrect value type may still cause an error in the browser's JavaScript console.

Available Configuration Options

Important Notes

Some configuration options require additional DataTables extensions or plugins (e.g., Buttons, FixedHeader). At this time, such plugin-dependent options are not yet supported.

For best results, start with core features such as layout or language options before exploring more advanced configurations.

For a complete list of available settings, refer to the official DataTables documentation and: https://datatables.net/examples/

It’s best to start with the core DataTables Features before adding advanced configurations.

Column Name Formatting

For better readability in table headers, df2tables automatically converts underscores to spaces in column names. This improves word wrapping and prevents excessively wide columns.

To disable this automatic word wrapping behavior, add the following CSS to your custom template:

span.dt-column-title { 
    white-space: nowrap; 
}

Bulk Dataset Processing

For exploratory data analysis across multiple datasets, you can generate tables programmatically. The example below uses the vega_datasets package, which provides easy access to a variety of sample datasets commonly used in data visualization and analysis.

Note: Install vega_datasets with pip install vega_datasets to run this example.

Quick Browse First 10 Vega Datasets

Error Handling

The module includes error handling for:

  • JSON serialization: Custom encoder handles complex pandas or Python data types
  • Column compatibility: Automatically converts problematic column types to string representation

Offline Usage

Note: "Offline" viewing assumes internet connectivity for CDN resources (DataTables, jQuery, PureCSS, DataTables Column Control extension). For truly offline usage, modify the template to reference local copies of these libraries instead of CDN links.

Appendix: Template Customization

Templates use comnt, a minimal markup system based on HTML/JS comments.

Custom Templates

Copy and modify datatable_templ.html to apply custom styling or libraries, then pass the new template path to templ_path.

Handle Pandas MultiIndex Columns (Experimental)

MultiIndex columns are automatically flattened with underscore separation.

License

MIT License
© Tomasz Sługocki

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Tomasz_Sl from gravatar.com Tomasz_Sl

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: Tomasz Sługocki
  • Tags DataTables , HTML , Javascript , Pandas , Polars
  • Provides-Extra: pandas , polars

Release history Release notifications | RSS feed

0.2.1

0.2.0

This version

0.1.9

0.1.8

0.1.7

0.1.6

0.1.5

0.1.4

0.1.3

0.1.2

0.1.1

0.1.0

0.0.8

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

0.0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

df2tables-0.1.9.tar.gz (18.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

df2tables-0.1.9-py2.py3-none-any.whl (21.3 kB view details)

Uploaded Python 2Python 3

File details

Details for the file df2tables-0.1.9.tar.gz.

File metadata

  • Download URL: df2tables-0.1.9.tar.gz
  • Upload date:
  • Size: 18.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for df2tables-0.1.9.tar.gz
Algorithm Hash digest
SHA256 413ac160c17b43c840b8912ba557273df80bc5e595f673fed40171964ff473ac
MD5 d76512d8b70c9fb847f8aee28442ff55
BLAKE2b-256 d780a176a07062a9580f5fb669b3f7387d2ff99d3d4a3a39d2cb43a9ffe81923

See more details on using hashes here.

File details

Details for the file df2tables-0.1.9-py2.py3-none-any.whl.

File metadata

  • Download URL: df2tables-0.1.9-py2.py3-none-any.whl
  • Upload date:
  • Size: 21.3 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for df2tables-0.1.9-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 d58a7bf2cc2d1326a9905177599b69ad9c63ce51f120043c5a008f68885d5f11
MD5 3e18ef86b83a5af027d376bcb47a5417
BLAKE2b-256 3125e84d37c73da61677e4279d41163b9cc4506c99dbe6f63464a96ba666f594

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page