itables 2.2.5__tar.gz → 2.4.0rc0__tar.gz

{itables-2.2.5 → itables-2.4.0rc0}/.gitignore

@@ -28,7 +28,11 @@ node_modules
 dt_bundle.js
 dt_bundle.css
 
-# Streamlit package
+# Dash component
+src/itables_for_dash/*.js*
+src/itables_for_dash/_imports_.py
+
+# Streamlit component
 src/itables/itables_for_streamlit
 
 # Jupyter Widget

{itables-2.2.5 → itables-2.4.0rc0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: itables
-Version: 2.2.5
+Version: 2.4.0rc0
 Summary: Pandas and Polar DataFrames as interactive DataTables
 Project-URL: Homepage, https://mwouts.github.io/itables/
 Project-URL: Documentation, https://mwouts.github.io/itables
@@ -39,14 +39,12 @@ Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 Requires-Dist: ipython
 Requires-Dist: numpy
 Requires-Dist: pandas
@@ -57,9 +55,13 @@ Requires-Dist: polars; extra == 'all'
 Requires-Dist: pyarrow; extra == 'all'
 Requires-Dist: pytz; extra == 'all'
 Requires-Dist: traitlets; extra == 'all'
+Requires-Dist: typeguard>=4.4.1; extra == 'all'
 Requires-Dist: world-bank-data; extra == 'all'
+Provides-Extra: check-type
+Requires-Dist: typeguard>=4.4.1; extra == 'check-type'
 Provides-Extra: dev
 Requires-Dist: anywidget; extra == 'dev'
+Requires-Dist: dash; extra == 'dev'
 Requires-Dist: ipykernel; extra == 'dev'
 Requires-Dist: jupyterlab; extra == 'dev'
 Requires-Dist: jupytext; extra == 'dev'
@@ -73,6 +75,7 @@ Requires-Dist: pytz; extra == 'dev'
 Requires-Dist: requests; extra == 'dev'
 Requires-Dist: shiny; extra == 'dev'
 Requires-Dist: traitlets; extra == 'dev'
+Requires-Dist: typeguard>=4.4.1; extra == 'dev'
 Requires-Dist: watchfiles; extra == 'dev'
 Requires-Dist: world-bank-data; extra == 'dev'
 Provides-Extra: polars
@@ -85,6 +88,7 @@ Provides-Extra: style
 Requires-Dist: matplotlib; extra == 'style'
 Provides-Extra: test
 Requires-Dist: anywidget; extra == 'test'
+Requires-Dist: dash; extra == 'test'
 Requires-Dist: ipykernel; extra == 'test'
 Requires-Dist: jupytext; extra == 'test'
 Requires-Dist: matplotlib; extra == 'test'
@@ -97,6 +101,7 @@ Requires-Dist: pytz; extra == 'test'
 Requires-Dist: requests; extra == 'test'
 Requires-Dist: shiny; extra == 'test'
 Requires-Dist: traitlets; extra == 'test'
+Requires-Dist: typeguard>=4.4.1; extra == 'test'
 Requires-Dist: world-bank-data; extra == 'test'
 Provides-Extra: widget
 Requires-Dist: anywidget; extra == 'widget'
@@ -112,10 +117,11 @@ Description-Content-Type: text/markdown
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/itables.svg)](https://anaconda.org/conda-forge/itables)
 [![pyversions](https://img.shields.io/pypi/pyversions/itables.svg)](https://pypi.python.org/pypi/itables)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Jupyter Widget](https://img.shields.io/badge/Jupyter-Widget-F37626.svg?style=flat&logo=Jupyter)](https://mwouts.github.io/itables/widget.html)
+[![Jupyter Widget](https://img.shields.io/badge/Jupyter-Widget-F37626.svg?style=flat&logo=Jupyter)](https://mwouts.github.io/itables/apps/widget.html)
+[![Dash Component](https://img.shields.io/badge/Dash-Plotly-1098F7.svg?style=flat&logo=Plotly)](https://mwouts.github.io/itables/apps/dash.html)
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_red.svg)](https://itables.streamlit.app)
 
-This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.
+This packages changes how Pandas and Polars DataFrames are rendered in Python notebooks and applications.
 With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)
 that you can sort, paginate, scroll or filter.
 
@@ -143,26 +149,20 @@ or
 conda install itables -c conda-forge
 ```
 
-Activate the interactive mode for all series and dataframes with
+Activate the interactive mode for all series and dataframes in Jupyter with
 ```python
-from itables import init_notebook_mode
+import itables
 
-init_notebook_mode(all_interactive=True)
+itables.init_notebook_mode()
 ```
 and then render any DataFrame as an interactive table that you can sort, search and explore:
 ![df](docs/df_example.png)
 
-If you prefer to render only selected DataFrames as interactive tables, use `itables.show` to show just one Series or DataFrame as an interactive table:
+If you prefer to render only selected DataFrames as interactive tables, call `itables.init_notebook_mode(all_interactive=False)`, then use `itables.show` to show just one Series or DataFrame as an interactive table:
 ![show](docs/show_df.png)
 
-Since ITables v1.0, the [jQuery](https://jquery.com/) and [DataTables](https://datatables.net/) libraries and CSS
-are injected in the notebook when you execute `init_notebook_mode` with its default argument `connected=False`.
-Thanks to this the interactive tables will work even without a connection to the internet.
 
-If you prefer to load the libraries dynamically (and keep the notebook lighter), use `connected=True` when you
-execute `init_notebook_mode`.
-
-## Supported environments
+## ITables in Notebooks
 
 ITables works in all the usual Jupyter Notebook environments, including Jupyter Notebook, Jupyter Lab, Jupyter nbconvert (i.e. the tables are still interactive in the HTML export of a notebook), Jupyter Book, Google Colab and Kaggle.
 
@@ -170,7 +170,18 @@ You can also use ITables in [Quarto](https://mwouts.github.io/itables/quarto.htm
 
 ITables works well in VS Code, both in Jupyter Notebooks and in interactive Python sessions.
 
-Last but not least, ITables is also available as
+## ITables in Python applications
+
+ITables is also available as
 - a [Jupyter Widget](https://mwouts.github.io/itables/widget.html)
+- a [Dash](https://mwouts.github.io/itables/dash.html) component
 - a [Streamlit](https://mwouts.github.io/itables/streamlit.html) component,
 - and it also works in [Shiny](https://mwouts.github.io/itables/shiny.html) applications.
+
+## Licence
+
+ITables is developed by [Marc Wouts](https://github.com/mwouts) on [GitHub](https://github.com/mwouts/itables),
+under a MIT license.
+
+ITables is a wrapper for [datatables.net](https://datatables.net/) which is developed by Allan Jardine
+[(sponsor him!)](https://github.com/sponsors/AllanJard), also under a MIT license.

{itables-2.2.5 → itables-2.4.0rc0}/README.md

@@ -7,10 +7,11 @@
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/itables.svg)](https://anaconda.org/conda-forge/itables)
 [![pyversions](https://img.shields.io/pypi/pyversions/itables.svg)](https://pypi.python.org/pypi/itables)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Jupyter Widget](https://img.shields.io/badge/Jupyter-Widget-F37626.svg?style=flat&logo=Jupyter)](https://mwouts.github.io/itables/widget.html)
+[![Jupyter Widget](https://img.shields.io/badge/Jupyter-Widget-F37626.svg?style=flat&logo=Jupyter)](https://mwouts.github.io/itables/apps/widget.html)
+[![Dash Component](https://img.shields.io/badge/Dash-Plotly-1098F7.svg?style=flat&logo=Plotly)](https://mwouts.github.io/itables/apps/dash.html)
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_red.svg)](https://itables.streamlit.app)
 
-This packages changes how Pandas and Polars DataFrames are rendered in Jupyter Notebooks.
+This packages changes how Pandas and Polars DataFrames are rendered in Python notebooks and applications.
 With `itables` you can display your tables as interactive [DataTables](https://datatables.net/)
 that you can sort, paginate, scroll or filter.
 
@@ -38,26 +39,20 @@ or
 conda install itables -c conda-forge
 ```
 
-Activate the interactive mode for all series and dataframes with
+Activate the interactive mode for all series and dataframes in Jupyter with
 ```python
-from itables import init_notebook_mode
+import itables
 
-init_notebook_mode(all_interactive=True)
+itables.init_notebook_mode()
 ```
 and then render any DataFrame as an interactive table that you can sort, search and explore:
 ![df](docs/df_example.png)
 
-If you prefer to render only selected DataFrames as interactive tables, use `itables.show` to show just one Series or DataFrame as an interactive table:
+If you prefer to render only selected DataFrames as interactive tables, call `itables.init_notebook_mode(all_interactive=False)`, then use `itables.show` to show just one Series or DataFrame as an interactive table:
 ![show](docs/show_df.png)
 
-Since ITables v1.0, the [jQuery](https://jquery.com/) and [DataTables](https://datatables.net/) libraries and CSS
-are injected in the notebook when you execute `init_notebook_mode` with its default argument `connected=False`.
-Thanks to this the interactive tables will work even without a connection to the internet.
 
-If you prefer to load the libraries dynamically (and keep the notebook lighter), use `connected=True` when you
-execute `init_notebook_mode`.
-
-## Supported environments
+## ITables in Notebooks
 
 ITables works in all the usual Jupyter Notebook environments, including Jupyter Notebook, Jupyter Lab, Jupyter nbconvert (i.e. the tables are still interactive in the HTML export of a notebook), Jupyter Book, Google Colab and Kaggle.
 
@@ -65,7 +60,18 @@ You can also use ITables in [Quarto](https://mwouts.github.io/itables/quarto.htm
 
 ITables works well in VS Code, both in Jupyter Notebooks and in interactive Python sessions.
 
-Last but not least, ITables is also available as
+## ITables in Python applications
+
+ITables is also available as
 - a [Jupyter Widget](https://mwouts.github.io/itables/widget.html)
+- a [Dash](https://mwouts.github.io/itables/dash.html) component
 - a [Streamlit](https://mwouts.github.io/itables/streamlit.html) component,
 - and it also works in [Shiny](https://mwouts.github.io/itables/shiny.html) applications.
+
+## Licence
+
+ITables is developed by [Marc Wouts](https://github.com/mwouts) on [GitHub](https://github.com/mwouts/itables),
+under a MIT license.
+
+ITables is a wrapper for [datatables.net](https://datatables.net/) which is developed by Allan Jardine
+[(sponsor him!)](https://github.com/sponsors/AllanJard), also under a MIT license.

itables-2.4.0rc0/itables/__init__.py

@@ -0,0 +1,18 @@
+from itables import downsample, options, sample_dfs, widget
+
+from .javascript import init_notebook_mode, show, to_html_datatable
+from .typing import JavascriptCode, JavascriptFunction
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    "to_html_datatable",
+    "show",
+    "init_notebook_mode",
+    "JavascriptCode",
+    "JavascriptFunction",
+    "options",
+    "downsample",
+    "sample_dfs",
+    "widget",
+]

itables-2.4.0rc0/itables/dash.py

@@ -0,0 +1,15 @@
+from itables import __version__
+from itables_for_dash import (
+    ITABLE_PROPERTIES,
+    ITable,
+    ITableOutputs,
+    updated_itable_outputs,
+)
+
+__all__ = [
+    "ITable",
+    "ITABLE_PROPERTIES",
+    "ITableOutputs",
+    "updated_itable_outputs",
+    "__version__",
+]

itables-2.4.0rc0/itables/datatables_format.py

@@ -0,0 +1,147 @@
+import json
+import warnings
+from typing import Optional
+
+import numpy as np
+import pandas as pd
+import pandas.io.formats.format as fmt
+
+try:
+    import polars as pl
+except ImportError:
+    pl = None
+
+
+def _format_column(x, escape_html: bool):
+    dtype_kind = x.dtype.kind
+    if dtype_kind in ["b", "i"]:
+        return x
+
+    if dtype_kind == "s":
+        if escape_html:
+            return x
+        return [escape_html_chars(i) for i in x]
+
+    try:
+        x = fmt.format_array(x._values, None, justify="all", leading_space=False)  # type: ignore
+    except TypeError:
+        # Older versions of Pandas don't have 'leading_space'
+        x = fmt.format_array(x._values, None, justify="all")  # type: ignore
+
+    if dtype_kind == "f":
+        try:
+            x = np.array(x).astype(float)
+        except ValueError:
+            pass
+
+        x = [escape_non_finite_float(f) for f in x]
+
+    if escape_html:
+        return [escape_html_chars(i) for i in x]
+
+    return x
+
+
+def escape_non_finite_float(value):
+    """Encode non-finite float values to strings that will be parsed by parseJSON"""
+    if not isinstance(value, float):
+        return value
+    if np.isnan(value):
+        return "___NaN___"
+    if value == np.inf:
+        return "___Infinity___"
+    if value == -np.inf:
+        return "___-Infinity___"
+    return value
+
+
+def escape_html_chars(value):
+    """Escape HTML special characters"""
+    if isinstance(value, str):
+        from pandas.io.formats.printing import pprint_thing  # type: ignore
+
+        return pprint_thing(
+            value, escape_chars={"&": r"&amp;", "<": r"&lt;", ">": r"&gt;"}
+        ).strip()
+    return value
+
+
+def generate_encoder(warn_on_unexpected_types=True):
+    class TableValuesEncoder(json.JSONEncoder):
+        def default(self, o):
+            if isinstance(o, (bool, int, float, str)):
+                return json.JSONEncoder.default(self, o)
+            if isinstance(o, np.bool_):
+                return bool(o)
+            if isinstance(o, np.integer):
+                return int(o)
+            if isinstance(o, np.floating):
+                return float(o)
+            try:
+                if o is pd.NA:
+                    return str(o)
+            except AttributeError:
+                pass
+
+            if warn_on_unexpected_types:
+                warnings.warn(
+                    f"Unexpected type '{type(o)}' for '{o}'.\n"
+                    "You can report this warning at https://github.com/mwouts/itables/issues\n"
+                    "To silence this warning, please run:\n"
+                    "    itables.options.warn_on_unexpected_types = False",
+                    category=RuntimeWarning,
+                )
+            return str(o)
+
+    return TableValuesEncoder
+
+
+def _isetitem(df, i, value):
+    """Older versions of Pandas don't have df.isetitem"""
+    try:
+        df.isetitem(i, value)
+    except AttributeError:
+        df.iloc[:, i] = value
+
+
+def datatables_rows(
+    df,
+    column_count: Optional[int] = None,
+    warn_on_unexpected_types: bool = False,
+    escape_html: bool = True,
+):
+    """Format the values in the table and return the data, row by row, as requested by DataTables"""
+    # We iterate over columns using an index rather than the column name
+    # to avoid an issue in case of duplicated column names #89
+    if column_count is None or len(df.columns) == column_count:
+        empty_columns = []
+    else:
+        # When the header requires more columns (#141), we append empty columns on the left
+        missing_columns = column_count - len(df.columns)
+        assert missing_columns > 0
+        empty_columns = [[None] * len(df)] * missing_columns
+
+    try:
+        # Pandas DataFrame
+        data = list(
+            zip(
+                *(
+                    empty_columns
+                    + [_format_column(x, escape_html) for _, x in df.items()]
+                )
+            )
+        )
+        return json.dumps(
+            data,
+            cls=generate_encoder(warn_on_unexpected_types),
+            allow_nan=False,
+        )
+    except AttributeError:
+        # Polars DataFrame
+        data = df.rows()
+        data = [[escape_non_finite_float(f) for f in row] for row in data]
+
+        if escape_html:
+            data = [[escape_html_chars(i) for i in row] for row in data]
+
+        return json.dumps(data, cls=generate_encoder(False), allow_nan=False)

{itables-2.2.5/src → itables-2.4.0rc0}/itables/downsample.py

@@ -1,9 +1,8 @@
 import math
+from typing import Union
 
 import pandas as pd
 
-from .datatables_format import _isetitem
-
 
 def nbytes(df):
     try:
@@ -31,7 +30,9 @@ def as_nbytes(mem):
     return int(float(mem))
 
 
-def downsample(df, max_rows=0, max_columns=0, max_bytes=0):
+def downsample(
+    df, max_rows: int = 0, max_columns: int = 0, max_bytes: Union[int, str] = 0
+):
     """Return a subset of the dataframe that fits the limits"""
     org_rows, org_columns, org_bytes = len(df), len(df.columns), nbytes(df)
     max_bytes_numeric = as_nbytes(max_bytes)
@@ -113,16 +114,16 @@ def _downsample(df, max_rows=0, max_columns=0, max_bytes=0, target_aspect_ratio=
         first_half = max_columns - second_half
         assert first_half >= second_half
         if second_half:
-            try:
+            if isinstance(df, pd.DataFrame):
                 df = pd.concat(
                     (df.iloc[:, :first_half], df.iloc[:, -second_half:]), axis=1
                 )
-            except AttributeError:
+            else:
                 df = df[df.columns[:first_half]].hstack(df[df.columns[-second_half:]])
         else:
-            try:
+            if isinstance(df, pd.DataFrame):
                 df = df.iloc[:, :first_half]
-            except AttributeError:
+            else:
                 df = df[df.columns[:first_half]]
 
     df_nbytes = nbytes(df)
@@ -146,12 +147,14 @@ def _downsample(df, max_rows=0, max_columns=0, max_bytes=0, target_aspect_ratio=
             )
 
         # max_bytes is smaller than the average size of one cell
-        try:
-            df = df.iloc[:1, :1]
-            _isetitem(df, 0, ["..."])
-        except AttributeError:
+        if isinstance(df, pd.DataFrame):
+            return pd.DataFrame("...", index=df.index[:1], columns=df.columns[:1])
+
+        else:
             import polars as pl  # noqa
 
+            assert isinstance(df, pl.DataFrame)
+
             df = pl.DataFrame({df.columns[0]: ["..."]})
         return df
 

itables-2.4.0rc0/itables/html/datatables_template.html

@@ -0,0 +1,14 @@
+<!--| quarto-html-table-processing: none -->
+<table id="table_id"></table>
+<link href="https://www.unpkg.com/dt_for_itables/dt_bundle.css" rel="stylesheet">
+<script type="module">
+    import { ITable, jQuery as $ } from 'https://www.unpkg.com/dt_for_itables/dt_bundle.js';
+
+    document.querySelectorAll("#table_id:not(.dataTable)").forEach(table => {
+        if (!(table instanceof HTMLTableElement))
+            return;
+
+        let dt_args = {};
+        new ITable(table, dt_args);
+    });
+</script>