Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

chore: upgrade Python bindings to kepler.gl 3.3.0-alpha.4 (React 19) (#3591)

Igor Dykhta28e8e3f516fd
diff --git a/.github/workflows/build-publish-pypi.yml b/.github/workflows/build-publish-pypi.yml
index 71931ad18..800e9a0c4 100644
--- a/.github/workflows/build-publish-pypi.yml
+++ b/.github/workflows/build-publish-pypi.yml
@@ -23,9 +23,10 @@ jobs:
run: |
MAJOR=$(node -p "require('./package.json').version.split('.')[0]")
CDN=$(grep -Po '(?<=DEFAULT_KEPLER_GL_CDN_VERSION = ")[^"]+' bindings/python/keplergl/_html_export.py)
+ CDN_MAJOR=$(echo "$CDN" | cut -d'.' -f1)
echo "package.json major: $MAJOR"
- echo "Python CDN version: $CDN"
- if [ "$MAJOR" != "$CDN" ]; then
+ echo "Python CDN version: $CDN (major: $CDN_MAJOR)"
+ if [ "$MAJOR" != "$CDN_MAJOR" ]; then
echo "::error::DEFAULT_KEPLER_GL_CDN_VERSION ($CDN) in _html_export.py does not match major version ($MAJOR) from package.json. Please update it."
exit 1
fi
diff --git a/bindings/python/DEVELOPMENT.md b/bindings/python/DEVELOPMENT.md
index 14d11bc6f..f4715028e 100644
--- a/bindings/python/DEVELOPMENT.md
+++ b/bindings/python/DEVELOPMENT.md
@@ -5,7 +5,7 @@ This guide explains how to set up kepler.gl for Jupyter for local development.
## Prerequisites
- Python >= 3.9
-- Node.js (for building the frontend)
+- Node.js >= 20 (for building the frontend)
- JupyterLab >= 4.0 or Notebook >= 7.0
## Installation
diff --git a/bindings/python/keplergl/_html_export.py b/bindings/python/keplergl/_html_export.py
index 88e9a8a03..a6d3bfc75 100644
--- a/bindings/python/keplergl/_html_export.py
+++ b/bindings/python/keplergl/_html_export.py
@@ -12,7 +12,14 @@ from typing import Optional
import pandas as pd
import geopandas as gpd
-DEFAULT_KEPLER_GL_CDN_VERSION = "3"
+DEFAULT_KEPLER_GL_CDN_VERSION = "3.3.0-alpha.4"
+
+REACT_VERSION = "19.1.0"
+REACT_DOM_VERSION = "19.1.0"
+REDUX_VERSION = "5.0.1"
+REACT_REDUX_VERSION = "9.3.0"
+STYLED_COMPONENTS_VERSION = "6.1.19"
+ES_MODULE_SHIMS_VERSION = "2.8.1"
def _dataset_to_csv(data) -> Optional[str]:
@@ -191,19 +198,73 @@ def export_map_html(
<!--Kepler css-->
<link href="https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.css" rel="stylesheet">
- <!--MapBox css-->
- <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.1.1/mapbox-gl.css" rel="stylesheet">
- <link href="https://unpkg.com/maplibre-gl@^3/dist/maplibre-gl.css" rel="stylesheet">
+ <!--MapLibre css-->
+ <link href="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.css" rel="stylesheet">
+
+ <!--
+ React >= 19 no longer ships UMD builds, so we load React and the other
+ peer dependencies as ES modules from esm.sh via an import map, then
+ expose them as window globals that the kepler.gl UMD bundle expects.
- <!-- Load React/Redux -->
- <script src="https://unpkg.com/[email protected]/umd/react.production.min.js" crossorigin></script>
- <script src="https://unpkg.com/[email protected]/umd/react-dom.production.min.js" crossorigin></script>
- <script src="https://unpkg.com/[email protected]/dist/redux.js" crossorigin></script>
- <script src="https://unpkg.com/[email protected]/dist/react-redux.min.js" crossorigin></script>
- <script src="https://unpkg.com/[email protected]/dist/styled-components.min.js" crossorigin></script>
+ es-module-shims runs in "shim mode" so the page also works when opened
+ as a local file:// (native import maps are blocked under file://).
+ -->
+ <script>
+ window.esmsInitOptions = {{shimMode: true, version: '{ES_MODULE_SHIMS_VERSION}'}};
+ </script>
+ <script async src="https://ga.jspm.io/npm:es-module-shims@{ES_MODULE_SHIMS_VERSION}/dist/es-module-shims.js" crossorigin="anonymous"></script>
+
+ <script type="importmap-shim">
+ {{
+ "imports": {{
+ "react": "https://esm.sh/react@{REACT_VERSION}",
+ "react/jsx-runtime": "https://esm.sh/react@{REACT_VERSION}/jsx-runtime",
+ "react-dom": "https://esm.sh/react-dom@{REACT_DOM_VERSION}?external=react",
+ "react-dom/client": "https://esm.sh/react-dom@{REACT_DOM_VERSION}/client?external=react",
+ "redux": "https://esm.sh/redux@{REDUX_VERSION}",
+ "react-redux": "https://esm.sh/react-redux@{REACT_REDUX_VERSION}?external=react,react-dom,redux",
+ "styled-components": "https://esm.sh/styled-components@{STYLED_COMPONENTS_VERSION}?external=react,react-dom"
+ }}
+ }}
+ </script>
- <!-- Load Kepler.gl -->
- <script src="https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.js" crossorigin></script>
+ <!--
+ Expose the ES modules as globals for the kepler.gl UMD bundle, then
+ dynamically load that bundle and run the bootstrap scripts once ready.
+ -->
+ <script type="module-shim">
+ import * as React from 'react';
+ import * as ReactDOM from 'react-dom';
+ import * as ReactDOMClient from 'react-dom/client';
+ import * as Redux from 'redux';
+ import * as ReactRedux from 'react-redux';
+ import * as StyledComponents from 'styled-components';
+
+ window.React = React.default || React;
+ window.ReactDOM = Object.assign({{}}, ReactDOM.default || ReactDOM, ReactDOMClient);
+ window.Redux = Redux.default || Redux;
+ window.ReactRedux = ReactRedux.default || ReactRedux;
+ window.styled = Object.assign(StyledComponents.default, StyledComponents);
+
+ function loadScript(src) {{
+ return new Promise(function(resolve, reject) {{
+ var s = document.createElement('script');
+ s.src = src; s.crossOrigin = 'anonymous';
+ s.onload = resolve; s.onerror = reject;
+ document.head.appendChild(s);
+ }});
+ }}
+
+ loadScript('https://unpkg.com/kepler.gl@{kepler_gl_version}/umd/keplergl.min.js')
+ .then(function() {{
+ document.querySelectorAll('script[type="text/kepler-bootstrap"]').forEach(function(node) {{
+ var s = document.createElement('script');
+ s.text = node.textContent;
+ document.body.appendChild(s);
+ }});
+ }})
+ .catch(function(err) {{ console.error('kepler.gl: failed to load UMD bundle', err); }});
+ </script>
<style type="text/css">
body {{margin: 0; padding: 0; overflow: hidden;}}
@@ -216,7 +277,7 @@ def export_map_html(
<body>
<div id="app"></div>
- <script>
+ <script type="text/kepler-bootstrap">
/** STORE **/
const reducers = (function createReducers(redux, keplerGl) {{
return redux.combineReducers({{
@@ -238,14 +299,13 @@ def export_map_html(
}}(Redux, middleWares));
const store = (function createStore(redux, enhancers) {{
- return redux.createStore(reducers, {{}}, redux.compose(enhancers));
+ return redux.legacy_createStore(reducers, {{}}, redux.compose(enhancers));
}}(Redux, enhancers));
/** END STORE **/
/** COMPONENTS **/
var KeplerElement = (function makeKeplerElement(react, keplerGl, mapboxToken) {{
return function App() {{
- var rootElm = react.useRef(null);
var _useState = react.useState({{
width: window.innerWidth,
height: window.innerHeight
@@ -283,14 +343,13 @@ def export_map_html(
/** END COMPONENTS **/
/** Render **/
- (function render(react, reactDOM, app) {{
- const container = document.getElementById('app');
- const root = reactDOM.createRoot(container);
+ (function render(reactDOM, app) {{
+ const root = reactDOM.createRoot(document.getElementById('app'));
root.render(app);
- }}(React, ReactDOM, app));
+ }}(ReactDOM, app));
</script>
- <script>
+ <script type="text/kepler-bootstrap">
(function customize(keplerGl, store) {{
var datasets = [];
{dataset_js}
diff --git a/bindings/python/package.json b/bindings/python/package.json
index 6119327fc..a565dde34 100644
--- a/bindings/python/package.json
+++ b/bindings/python/package.json
@@ -10,29 +10,29 @@
},
"devDependencies": {
"@anywidget/types": "^0.2.0",
- "@types/react": "^18.2.0",
- "@types/react-dom": "^18.2.0",
+ "@types/react": "^19.0.0",
+ "@types/react-dom": "^19.0.0",
"@typescript-eslint/eslint-plugin": "^7.0.0",
"@typescript-eslint/parser": "^7.0.0",
"esbuild": "^0.20.0",
"eslint": "^8.57.0",
"prettier": "^3.2.0",
- "typescript": "^5.4.0"
+ "typescript": "^5.6.0"
},
"dependencies": {
- "@kepler.gl/actions": "^3.2.0",
- "@kepler.gl/components": "^3.2.0",
- "@kepler.gl/processors": "^3.2.0",
- "@kepler.gl/reducers": "^3.2.0",
- "@kepler.gl/schemas": "^3.2.0",
- "@kepler.gl/styles": "^3.2.0",
+ "@kepler.gl/actions": "^3.3.0-alpha.4",
+ "@kepler.gl/components": "^3.3.0-alpha.4",
+ "@kepler.gl/processors": "^3.3.0-alpha.4",
+ "@kepler.gl/reducers": "^3.3.0-alpha.4",
+ "@kepler.gl/schemas": "^3.3.0-alpha.4",
+ "@kepler.gl/styles": "^3.3.0-alpha.4",
"apache-arrow": "^21.0.0",
"assert": "^2.1.0",
"events": "^3.3.0",
- "react": "^18.2.0",
- "react-dom": "^18.2.0",
- "react-redux": "^8.0.5",
- "redux": "^4.2.1",
+ "react": "^19.0.0",
+ "react-dom": "^19.0.0",
+ "react-redux": "^9.1.0",
+ "redux": "^5.0.0",
"styled-components": "^6.4.3"
}
}
diff --git a/bindings/python/src/store.ts b/bindings/python/src/store.ts
index 8bfecff5d..12f312c0b 100644
--- a/bindings/python/src/store.ts
+++ b/bindings/python/src/store.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: MIT
// Copyright contributors to the kepler.gl project
-import {createStore as createReduxStore, combineReducers, applyMiddleware, compose} from 'redux';
+import {legacy_createStore as createReduxStore, combineReducers, applyMiddleware, compose, type StoreEnhancer} from 'redux';
import {keplerGlReducer, enhanceReduxMiddleware} from '@kepler.gl/reducers';
export const KEPLER_ID = 'jupyter_kepler';
@@ -21,6 +21,5 @@ export function createStore() {
const middlewares = enhanceReduxMiddleware([]);
const enhancers = [applyMiddleware(...middlewares)];
- // @ts-expect-error Redux types are not compatible with TypeScript
- return createReduxStore(reducers, {}, compose(...enhancers));
+ return createReduxStore(reducers, {}, compose(...enhancers) as StoreEnhancer);
}
diff --git a/bindings/python/tests/test_html_export.py b/bindings/python/tests/test_html_export.py
index c75bb1048..a5d2e7975 100644
--- a/bindings/python/tests/test_html_export.py
+++ b/bindings/python/tests/test_html_export.py
@@ -14,8 +14,13 @@ from keplergl import KeplerGl
from keplergl._html_export import (
_dataset_to_csv,
_dataset_to_geojson,
+ _geojson_dataset_names,
+ _fixup_geojson_columns,
_serialize_datasets_for_html,
export_map_html,
+ ES_MODULE_SHIMS_VERSION,
+ REACT_VERSION,
+ REDUX_VERSION,
)
@@ -229,6 +234,97 @@ class TestSerializeDatasetsForHtml:
assert "2024" in js
+class TestGeojsonDatasetNames:
+ """Tests for _geojson_dataset_names."""
+
+ def test_identifies_geodataframe(self, sample_gdf):
+ names = _geojson_dataset_names({"geo": sample_gdf})
+ assert "geo" in names
+
+ def test_identifies_geojson_dict(self):
+ geojson = {"type": "FeatureCollection", "features": []}
+ names = _geojson_dataset_names({"fc": geojson})
+ assert "fc" in names
+
+ def test_excludes_dataframe(self, sample_df):
+ names = _geojson_dataset_names({"df": sample_df})
+ assert "df" not in names
+
+ def test_excludes_csv_string(self):
+ names = _geojson_dataset_names({"csv": "a,b\n1,2"})
+ assert "csv" not in names
+
+ def test_mixed_datasets(self, sample_df, sample_gdf):
+ names = _geojson_dataset_names({"tab": sample_df, "geo": sample_gdf})
+ assert "geo" in names
+ assert "tab" not in names
+
+ def test_empty_dict(self):
+ assert _geojson_dataset_names({}) == set()
+
+
+class TestFixupGeojsonColumns:
+ """Tests for _fixup_geojson_columns."""
+
+ def _layer(self, data_id, geojson_col="geometry"):
+ return {
+ "id": "layer1",
+ "config": {
+ "dataId": data_id,
+ "columns": {"geojson": geojson_col},
+ },
+ }
+
+ def _config(self, layers):
+ return {"config": {"visState": {"layers": layers}}}
+
+ def test_patches_geometry_column(self):
+ config = self._config([self._layer("geo")])
+ result = _fixup_geojson_columns(config, {"geo"})
+ col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ assert col == "_geojson"
+
+ def test_skips_non_geojson_dataset(self, sample_df):
+ config = self._config([self._layer("tabular")])
+ result = _fixup_geojson_columns(config, {"geo"})
+ col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ assert col == "geometry"
+
+ def test_skips_already_correct_column(self):
+ config = self._config([self._layer("geo", "_geojson")])
+ result = _fixup_geojson_columns(config, {"geo"})
+ col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ assert col == "_geojson"
+
+ def test_returns_none_config_unchanged(self):
+ assert _fixup_geojson_columns(None, {"geo"}) is None
+
+ def test_returns_empty_config_unchanged(self):
+ result = _fixup_geojson_columns({}, {"geo"})
+ assert result == {}
+
+ def test_returns_config_unchanged_for_empty_geojson_names(self):
+ config = self._config([self._layer("geo")])
+ result = _fixup_geojson_columns(config, set())
+ col = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ assert col == "geometry"
+
+ def test_does_not_mutate_original(self):
+ config = self._config([self._layer("geo")])
+ original_col = config["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ _fixup_geojson_columns(config, {"geo"})
+ assert config["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"] == original_col
+
+ def test_multiple_layers(self):
+ layers = [self._layer("geo"), self._layer("other", "geometry")]
+ config = self._config(layers)
+ result = _fixup_geojson_columns(config, {"geo"})
+ patched = result["config"]["visState"]["layers"][0]["config"]["columns"]["geojson"]
+ skipped = result["config"]["visState"]["layers"][1]["config"]["columns"]["geojson"]
+ assert patched == "_geojson"
+ assert skipped == "geometry"
+
+
class TestExportMapHtml:
"""Tests for the full export_map_html function."""
@@ -246,18 +342,22 @@ class TestExportMapHtml:
assert "unpkg.com/[email protected]/umd/keplergl.min.js" in html
assert "unpkg.com/[email protected]/umd/keplergl.min.css" in html
- def test_default_uses_latest_stable_cdn_tag(self, sample_df):
+ def test_default_cdn_version(self, sample_df):
html = export_map_html(data={"test": sample_df}, config={})
- assert "unpkg.com/kepler.gl@3/umd/keplergl.min.js" in html
- assert "unpkg.com/kepler.gl@3/umd/keplergl.min.css" in html
+ assert "unpkg.com/[email protected]/umd/keplergl.min.js" in html
+ assert "unpkg.com/[email protected]/umd/keplergl.min.css" in html
def test_contains_react_redux_deps(self, sample_df):
html = export_map_html(data={"test": sample_df}, config={})
- assert "react.production.min.js" in html
- assert "react-dom.production.min.js" in html
- assert "redux.js" in html
- assert "react-redux.min.js" in html
- assert "styled-components.min.js" in html
+ # React 19 dropped UMD builds; dependencies are now loaded via an ESM
+ # import map (es-module-shims) rather than classic <script> UMD tags.
+ assert "esm.sh/react@" in html
+ assert "esm.sh/react-dom@" in html
+ assert "esm.sh/redux@" in html
+ assert "esm.sh/react-redux@" in html
+ assert "esm.sh/styled-components@" in html
+ assert "importmap-shim" in html
+ assert "es-module-shims" in html
def test_contains_dataset(self, sample_df):
html = export_map_html(data={"my_data": sample_df}, config={})
@@ -340,6 +440,61 @@ class TestExportMapHtml:
html = export_map_html(data={"d": sample_df}, config={})
assert "<title>kepler.gl embedded map</title>" in html
+ def test_esm_shims_version_in_html(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={})
+ assert ES_MODULE_SHIMS_VERSION in html
+ assert f"es-module-shims@{ES_MODULE_SHIMS_VERSION}" in html
+
+ def test_react_version_in_importmap(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={})
+ assert f"esm.sh/react@{REACT_VERSION}" in html
+
+ def test_redux_version_in_importmap(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={})
+ assert f"esm.sh/redux@{REDUX_VERSION}" in html
+
+ def test_module_shim_bootstrap_type(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={})
+ assert 'type="text/kepler-bootstrap"' in html
+ assert 'type="module-shim"' in html
+
+ def test_app_name_html_escaped_in_title(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={}, app_name="<My & Map>")
+ assert "<title>&lt;My &amp; Map&gt; embedded map</title>" in html
+
+ def test_no_datasets(self):
+ html = export_map_html(data={}, config={})
+ assert "<!DOCTYPE html>" in html
+ assert "var datasets = [];" in html
+
+ def test_fixup_geojson_columns_applied_in_export(self):
+ """GeoDataFrame export should patch geometry column ref to _geojson."""
+ gdf = gpd.GeoDataFrame(
+ {"name": ["SF"]},
+ geometry=[Point(-122.4, 37.8)],
+ crs="EPSG:4326",
+ )
+ config = {
+ "config": {"visState": {"layers": [{
+ "id": "l1",
+ "config": {
+ "dataId": "places",
+ "columns": {"geojson": "geometry"},
+ },
+ }]}}
+ }
+ html = export_map_html(data={"places": gdf}, config=config)
+ assert '"_geojson"' in html
+ assert '"geometry"' not in html.split("var config =")[1]
+
+ def test_center_map_false_by_default(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={})
+ assert "centerMap: false" in html
+
+ def test_empty_mapbox_token(self, sample_df):
+ html = export_map_html(data={"d": sample_df}, config={}, mapbox_token="")
+ assert 'MAPBOX_TOKEN = ""' in html
+
class TestSaveToHtml:
"""Tests for the KeplerGl.save_to_html widget method."""
@@ -353,7 +508,7 @@ class TestSaveToHtml:
content = f.read()
assert "<!DOCTYPE html>" in content
assert "cities" in content
- assert "unpkg.com/kepler.gl@3/umd/keplergl.min.js" in content
+ assert "unpkg.com/[email protected]/umd/keplergl.min.js" in content
def test_saves_with_config(self, sample_df, tmp_path):
config = {"version": "v1", "config": {"mapState": {"zoom": 5}}}
@@ -476,3 +631,30 @@ class TestSaveToHtml:
content = f.read()
assert "<title>Override embedded map</title>" in content
assert '"Override"' in content
+
+ def test_center_map_default_true_in_save_to_html(self, sample_df, tmp_path):
+ """save_to_html defaults center_map=True (unlike export_map_html's False)."""
+ widget = KeplerGl(data={"d": sample_df})
+ out = str(tmp_path / "map.html")
+ widget.save_to_html(file_name=out)
+ with open(out) as f:
+ content = f.read()
+ assert "centerMap: true" in content
+
+ def test_mapbox_token_inherited_from_widget(self, sample_df, tmp_path):
+ widget = KeplerGl(data={"d": sample_df}, mapbox_token="pk.widget_token")
+ out = str(tmp_path / "map.html")
+ widget.save_to_html(file_name=out)
+ with open(out) as f:
+ content = f.read()
+ assert "pk.widget_token" in content
+
+ def test_mapbox_token_override_in_save(self, sample_df, tmp_path):
+ widget = KeplerGl(data={"d": sample_df}, mapbox_token="pk.widget_token")
+ out = str(tmp_path / "map.html")
+ widget.save_to_html(file_name=out, mapbox_token="pk.override_token")
+ with open(out) as f:
+ content = f.read()
+ assert "pk.override_token" in content
+ assert "pk.widget_token" not in content
+
diff --git a/bindings/python/tests/test_serializers.py b/bindings/python/tests/test_serializers.py
index 80e2f4681..75e18025d 100644
--- a/bindings/python/tests/test_serializers.py
+++ b/bindings/python/tests/test_serializers.py
@@ -467,3 +467,68 @@ class TestEdgeCases:
result = serialize_dataset(df, "mixed")
assert result["format"] == "df"
assert len(result["data"]["columns"]) == 4
+
+ def test_serialize_geojson_string_is_detected(self):
+ """A valid GeoJSON string should be routed to geojson format, not csv."""
+ import json
+ geojson_str = json.dumps({
+ "type": "FeatureCollection",
+ "features": [],
+ })
+ result = serialize_dataset(geojson_str, "geo")
+ assert result["format"] == "geojson"
+ assert result["data"]["type"] == "FeatureCollection"
+
+ def test_serialize_plain_csv_string_is_csv(self):
+ """A plain CSV string should not be confused with GeoJSON."""
+ csv = "lat,lng\n37.77,-122.42"
+ result = serialize_dataset(csv, "csv")
+ assert result["format"] == "csv"
+ assert result["data"] == csv
+
+ def test_serialize_dataframe_with_nan(self):
+ """NaN values in a DataFrame should not raise during serialization,
+ and the row containing NaN should be preserved (not dropped)."""
+ import math
+ df = pd.DataFrame({'a': [1.0, float('nan'), 3.0]})
+ result = serialize_dataset(df, "nan_test")
+ assert result["format"] == "df"
+ rows = result["data"]["data"]
+ assert len(rows) == 3
+ assert rows[0][0] == pytest.approx(1.0)
+ assert math.isnan(rows[1][0])
+ assert rows[2][0] == pytest.approx(3.0)
+
+ def test_serialize_dataframe_arrow_with_nan(self):
+ """Arrow serialization of a DataFrame containing NaN should not raise,
+ and NaN should round-trip as null in Arrow."""
+ import base64
+ import pyarrow as pa
+ df = pd.DataFrame({'a': [1.0, float('nan'), 3.0]})
+ result = serialize_dataset(df, "nan_arrow", use_arrow=True)
+ assert result["format"] == "arrow"
+ table = pa.ipc.open_stream(base64.b64decode(result["data"])).read_all()
+ assert table.num_rows == 3
+ values = table.column('a').to_pylist()
+ assert values[0] == pytest.approx(1.0)
+ assert values[1] is None # NaN becomes null in Arrow
+ assert values[2] == pytest.approx(3.0)
+
+ def test_data_to_json_returns_all_datasets(self, sample_df, sample_gdf):
+ """data_to_json should serialize every dataset in the dict."""
+ from keplergl.serializers import data_to_json
+
+ class FakeWidget:
+ _use_arrow = False
+
+ result = data_to_json({"tab": sample_df, "geo": sample_gdf}, FakeWidget())
+ assert "tab" in result
+ assert "geo" in result
+ assert result["tab"]["format"] == "df"
+ assert result["geo"]["format"] == "geoarrow"
+
+ def test_data_from_json_passthrough(self, sample_df):
+ """data_from_json is a passthrough — returned value equals input."""
+ from keplergl.serializers import data_from_json
+ payload = {"foo": {"id": "foo", "format": "csv", "data": "a,b\n1,2"}}
+ assert data_from_json(payload, None) is payload
diff --git a/bindings/python/tests/test_widget.py b/bindings/python/tests/test_widget.py
index 00f7c5166..55c894ca8 100644
--- a/bindings/python/tests/test_widget.py
+++ b/bindings/python/tests/test_widget.py
@@ -69,3 +69,66 @@ def test_add_data_use_arrow_none_preserves_widget_setting(sample_df):
widget = KeplerGl(use_arrow=True)
widget.add_data(sample_df, name="test")
assert widget._use_arrow is True
+
+
+def test_widget_default_mapbox_token():
+ widget = KeplerGl()
+ assert widget.mapbox_token == ""
+
+
+def test_widget_mapbox_token_stored():
+ widget = KeplerGl(mapbox_token="pk.abc123")
+ assert widget.mapbox_token == "pk.abc123"
+
+
+def test_widget_default_theme():
+ widget = KeplerGl()
+ assert widget.theme == ""
+
+
+def test_widget_theme_stored():
+ widget = KeplerGl(theme="light")
+ assert widget.theme == "light"
+
+
+def test_widget_default_app_name():
+ widget = KeplerGl()
+ assert widget.app_name == "kepler.gl"
+
+
+def test_widget_app_name_stored():
+ widget = KeplerGl(app_name="My Dashboard")
+ assert widget.app_name == "My Dashboard"
+
+
+def test_widget_show_docs_compat():
+ """show_docs is a deprecated no-op; should not raise."""
+ KeplerGl(show_docs=True)
+
+
+def test_add_data_replaces_existing(sample_df):
+ import pandas as pd
+ widget = KeplerGl(data={"cities": sample_df})
+ new_df = pd.DataFrame({"x": [99]})
+ widget.add_data(new_df, name="cities")
+ assert "cities" in widget.data
+ # Serialized data should reflect the new single-column DataFrame, not the
+ # original two-column one.
+ from keplergl.serializers import serialize_dataset
+ stored = serialize_dataset(widget.data["cities"], "cities")
+ assert stored["data"]["columns"] == ["x"]
+
+
+def test_init_with_multiple_datasets(sample_df, sample_gdf):
+ widget = KeplerGl(data={"tab": sample_df, "geo": sample_gdf})
+ assert "tab" in widget.data
+ assert "geo" in widget.data
+
+
+def test_add_data_does_not_remove_existing(sample_df):
+ import pandas as pd
+ widget = KeplerGl(data={"first": sample_df})
+ widget.add_data(pd.DataFrame({"x": [1]}), name="second")
+ assert "first" in widget.data
+ assert "second" in widget.data
+