maplibreum 0.2.0__tar.gz

maplibreum-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-20
+
+### Added
+- Added a complete-style dropdown control, external ES-module and stylesheet loading, structured vector-feature popups, reusable feature-state hover handling, and page-level dashboard elements.
+- Retained initial source definitions on the generated map runtime so large mutable GeoJSON sources can be reused without serializing a second copy.
+- Added five production field-test examples reproducing the distinct MapLibre applications deployed by `opensidewalkmap_beta`: the main node map, accessible routing, hazard analysis, completeness analysis, and data-acquisition dashboard.
+
+### Changed
+- Standardized generated maps on MapLibre GL JS 6.0.0 and its ES module build.
+- Added an independent jsDelivr fallback for the MapLibre runtime and stylesheet.
+- Normalized raw GeoJSON and `__geo_interface__` objects into valid GeoJSON sources.
+- Expanded CI across Python 3.9–3.13 with separate browser, documentation, and package-release gates.
+- Added eight-shard browser validation for all implemented gallery examples.
+- Added live-CDN smoke tests for unpkg and the forced jsDelivr fallback.
+- Added a clean-wheel installation and standalone-render smoke test.
+
+### Fixed
+- JSON-encoded floating-panel HTML so backticks and `${...}` text cannot break out of a JavaScript template literal, and removed its unnecessary delayed insertion race.
+- Declared the existing runtime use of `requests` as an installation dependency.
+- Made every implemented gallery example generate a browser-testable HTML page.
+- Served browser tests over local HTTP and adapted MapLibre 6's ES module
+  version API to the generated page's browser-global compatibility contract.
+- Repaired strict Sphinx documentation builds and clarified package discovery for bundled templates.
+
+## [0.1.0] - 2025-09-15
+### Added
+- Initial MapLibre integration with a `Map` object that renders interactive maps in notebooks and exported HTML.
+- Layer primitives including GeoJSON overlays, choropleths, clustered data sources, and time-aware visualisations.
+- Media overlays for static imagery and video along with floating image support.
+- Marker utilities with HTML, DivIcon, and Beautify icon support plus draggable markers and clustering helpers.
+- Map controls such as mini map, measure, search, draw tools, layer toggles, and camera helpers.
+- Terrain, sky, and fog helpers alongside expression builders for data-driven styling.
+- Event wiring for click, move, and draw callbacks in Jupyter environments.
+
+[Unreleased]: https://github.com/kauevestena/maplibreum_prototype/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/kauevestena/maplibreum_prototype/releases/tag/v0.2.0
+[0.1.0]: https://github.com/kauevestena/maplibreum_prototype/tree/e0ed3869ac734cfd8077f1f1a6b9b8245ff066e8

maplibreum-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kauê de Moraes Vestena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maplibreum-0.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include maplibreum/templates *.html

maplibreum-0.2.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: maplibreum
+Version: 0.2.0
+Summary: A Python library for creating interactive MapLibre maps, like Folium but for MapLibre.
+Author-email: Kauê de Moraes Vestena <kauemv2@gmail.com>
+License-Expression: MIT
+Project-URL: Documentation, https://kauevestena.github.io/maplibreum_prototype/docs/
+Project-URL: Source, https://github.com/kauevestena/maplibreum_prototype
+Project-URL: Issues, https://github.com/kauevestena/maplibreum_prototype/issues
+Project-URL: Changelog, https://github.com/kauevestena/maplibreum_prototype/blob/main/CHANGELOG.md
+Keywords: map,mapping,geospatial,GIS,MapLibre,Jupyter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Framework :: Jupyter
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Jinja2>=3.0
+Requires-Dist: MarkupSafe>=2.0
+Requires-Dist: ipython>=8.0
+Requires-Dist: ijson>=3.0
+Requires-Dist: rtree>=1.0.0
+Requires-Dist: requests>=2.0
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8.0; python_version < "3.10" and extra == "test"
+Requires-Dist: pytest>=8.0; python_version >= "3.10" and extra == "test"
+Requires-Dist: requests-mock>=1.9; extra == "test"
+Requires-Dist: playwright>=1.0; extra == "test"
+Requires-Dist: pytest-playwright>=0.5; extra == "test"
+Requires-Dist: geopandas>=0.10.0; extra == "test"
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.10.0; extra == "geo"
+Provides-Extra: all
+Requires-Dist: geopandas>=0.10.0; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="branding/logo-dark.svg">
+    <img src="branding/logo.svg" alt="MapLibreum logo" width="320">
+  </picture>
+</p>
+
+[![CI](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/ci.yml/badge.svg)](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/ci.yml)
+[![Documentation Build](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/deploy-unified-site.yml/badge.svg)](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/deploy-unified-site.yml)
+[![PyPI](https://img.shields.io/pypi/v/maplibreum.svg)](https://pypi.org/project/maplibreum/)
+
+# MapLibreum
+
+A Python library for creating interactive MapLibre maps, like Folium but for MapLibre.
+
+## Installation
+
+```bash
+pip install maplibreum
+```
+
+## Development
+
+```bash
+pip install -e .
+pytest
+```
+
+## Usage
+
+```python
+from maplibreum import Map
+
+# Create a map centered at a specific location
+m = Map(center=[-23.5505, -46.6333], zoom=10)
+
+# Pin a compatible MapLibre GL JS version (defaults to 6.0.0)
+m_custom = Map(maplibre_version="6.0.0")
+
+# Add a marker at the map center
+m.add_marker(popup="Hello, MapLibre!")
+
+# Or specify coordinates for the marker
+m.add_marker(coordinates=[-23.55, -46.63], popup="Another marker")
+
+# Add a heatmap layer from GeoJSON points
+geojson = {"type": "FeatureCollection", "features": []}
+source = {"type": "geojson", "data": geojson}
+m.add_heatmap_layer("heat", source)
+
+# Register event callbacks (Jupyter notebooks)
+def handle_click(evt):
+    print("Clicked at", evt["lngLat"])
+m.on_click(handle_click)
+
+# Enable built-in controls
+m.add_control("geolocate", "top-right", options={"trackUserLocation": True})
+m.add_control(
+    "attribution", "bottom-right", options={"customAttribution": "My Data"}
+)
+
+# Controls
+from maplibreum.controls import MiniMapControl, MeasureControl, SearchControl
+
+# Add a minimap
+m.add_control(MiniMapControl())
+
+# Add a measure control
+m.add_measure_control()
+
+# Add a search control
+# You will need an API key from a geocoding provider like Maptiler.
+# https://www.maptiler.com/cloud/keys/
+m.add_search_control(SearchControl(provider="maptiler", api_key="YOUR_API_KEY"))
+
+# Enable terrain and atmospheric effects
+m.add_dem_source("terrain", "https://example.com/dem.png")
+m.set_terrain("terrain")
+m.add_sky_layer()
+m.set_fog()
+
+# Save the map to an HTML file
+m.save("my_map.html")
+
+# Switch to an Albers projection and enable RTL/mobile options
+m.set_projection({"name": "albers", "parallels": [29.5, 45.5], "center": [-96, 37.8]})
+m.enable_rtl_text_plugin()
+m.set_mobile_behavior(cooperative_gestures=True, touch_zoom_rotate=False)
+```
+
+## Feature Demonstrations
+
+```python
+from maplibreum import (
+    Map,
+    Choropleth,
+    Marker,
+    MarkerCluster,
+    LayerControl,
+)
+
+m = Map()
+
+# Choropleth
+Choropleth(geojson_data).add_to(m)
+
+# Marker clusters
+cluster = MarkerCluster().add_to(m)
+Marker(coordinates=[0, 0]).add_to(cluster)
+
+# Clustered GeoJSON
+m.add_clustered_geojson(geojson_data)
+
+# Layer controls
+LayerControl().add_to(m)
+```
+
+## Expressions
+
+MapLibre uses array-based expressions for data-driven styling. The
+``maplibreum.expressions`` module provides helpers to construct and
+validate these expressions:
+
+```python
+from maplibreum.expressions import get, interpolate, var
+
+color = interpolate(
+    "linear",
+    var("heatmap-density"),
+    [(0, "blue"), (1, "red")],
+)
+```
+
+## Example Notebooks
+
+```bash
+jupyter notebook examples
+```
+
+### Live Examples Gallery
+
+View interactive examples deployed to GitHub Pages: [MapLibreum Examples Gallery](https://kauevestena.github.io/maplibreum_prototype/)
+
+The examples gallery is automatically generated from Jupyter notebooks in the `examples/` folder and showcases:
+- Creative MapLibreum examples and tutorials
+- Basic usage patterns
+- New features demonstrations  
+- Event handling and interactions
+
+To deploy examples to GitHub Pages, see the
+[GitHub Pages documentation](https://github.com/kauevestena/maplibreum_prototype/blob/main/docs/GITHUB_PAGES.md).
+
+## Changelog
+
+See the [CHANGELOG](CHANGELOG.md) for a detailed list of updates in each release.
+
+## Testing MapLibreum Functionality
+
+### Basic Testing
+
+Run the core test suite to verify MapLibreum's basic functionality:
+
+```bash
+# Install development dependencies
+pip install -e .
+pip install pytest jupyter
+
+# Run all basic tests
+pytest tests/ -v
+```
+
+### Advanced Testing: MapLibre Examples Validation
+
+To verify that MapLibreum is working properly and to check feature coverage against MapLibre GL JS, use the comprehensive testing suite in `development/maplibre_examples/`:
+
+#### MapLibre Examples Testing Suite
+
+The `development/maplibre_examples/` directory contains a systematic testing system that validates MapLibreum's capability to reproduce all official MapLibre GL JS examples. This provides:
+
+- **Automated validation** of feature coverage  
+- **Regression testing** for new releases
+- **Example conversion** from JavaScript to Python
+- **Performance benchmarking** against reference implementations
+
+#### Quick Status Check
+
+```bash
+# Install dependencies for the testing suite
+pip install requests beautifulsoup4
+
+# Check current implementation progress
+python -c "
+import json
+with open('development/maplibre_examples/status.json') as f:
+    data = json.load(f)
+total = len(data)
+implemented = sum(1 for v in data.values() if v['task_status'])
+print(f'MapLibreum Feature Coverage: {implemented}/{total} ({implemented/total*100:.1f}%)')
+print(f'Total MapLibre examples available: {total}')
+print(f'Examples successfully implemented: {implemented}')
+"
+```
+
+#### Running Example Tests
+
+```bash
+# Run all implemented example tests (when available)
+pytest tests/test_examples/ -v
+
+# Refresh examples from MapLibre.org (optional)
+python development/maplibre_examples/scrapping.py
+
+# Find next example to implement
+python -c "
+import json
+with open('development/maplibre_examples/status.json') as f:
+    data = json.load(f)
+for name, info in data.items():
+    if not info['task_status']:
+        print(f'Next unimplemented example: {name}')
+        print(f'MapLibre URL: {info[\"url\"]}')
+        break
+"
+```
+
+For detailed information about the testing suite, see the
+[MapLibre examples testing guide](https://github.com/kauevestena/maplibreum_prototype/blob/main/development/maplibre_examples/README.md).
+
+## Contributing
+
+Contributions are welcome! Please see the [issues page](https://github.com/kauevestena/maplibreum_prototype/issues) to see what needs to be done.
+
+## License
+
+This project is licensed under the MIT License; see the
+[LICENSE](https://github.com/kauevestena/maplibreum_prototype/blob/main/LICENSE)
+for details.

maplibreum-0.2.0/README.md

@@ -0,0 +1,237 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="branding/logo-dark.svg">
+    <img src="branding/logo.svg" alt="MapLibreum logo" width="320">
+  </picture>
+</p>
+
+[![CI](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/ci.yml/badge.svg)](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/ci.yml)
+[![Documentation Build](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/deploy-unified-site.yml/badge.svg)](https://github.com/kauevestena/maplibreum_prototype/actions/workflows/deploy-unified-site.yml)
+[![PyPI](https://img.shields.io/pypi/v/maplibreum.svg)](https://pypi.org/project/maplibreum/)
+
+# MapLibreum
+
+A Python library for creating interactive MapLibre maps, like Folium but for MapLibre.
+
+## Installation
+
+```bash
+pip install maplibreum
+```
+
+## Development
+
+```bash
+pip install -e .
+pytest
+```
+
+## Usage
+
+```python
+from maplibreum import Map
+
+# Create a map centered at a specific location
+m = Map(center=[-23.5505, -46.6333], zoom=10)
+
+# Pin a compatible MapLibre GL JS version (defaults to 6.0.0)
+m_custom = Map(maplibre_version="6.0.0")
+
+# Add a marker at the map center
+m.add_marker(popup="Hello, MapLibre!")
+
+# Or specify coordinates for the marker
+m.add_marker(coordinates=[-23.55, -46.63], popup="Another marker")
+
+# Add a heatmap layer from GeoJSON points
+geojson = {"type": "FeatureCollection", "features": []}
+source = {"type": "geojson", "data": geojson}
+m.add_heatmap_layer("heat", source)
+
+# Register event callbacks (Jupyter notebooks)
+def handle_click(evt):
+    print("Clicked at", evt["lngLat"])
+m.on_click(handle_click)
+
+# Enable built-in controls
+m.add_control("geolocate", "top-right", options={"trackUserLocation": True})
+m.add_control(
+    "attribution", "bottom-right", options={"customAttribution": "My Data"}
+)
+
+# Controls
+from maplibreum.controls import MiniMapControl, MeasureControl, SearchControl
+
+# Add a minimap
+m.add_control(MiniMapControl())
+
+# Add a measure control
+m.add_measure_control()
+
+# Add a search control
+# You will need an API key from a geocoding provider like Maptiler.
+# https://www.maptiler.com/cloud/keys/
+m.add_search_control(SearchControl(provider="maptiler", api_key="YOUR_API_KEY"))
+
+# Enable terrain and atmospheric effects
+m.add_dem_source("terrain", "https://example.com/dem.png")
+m.set_terrain("terrain")
+m.add_sky_layer()
+m.set_fog()
+
+# Save the map to an HTML file
+m.save("my_map.html")
+
+# Switch to an Albers projection and enable RTL/mobile options
+m.set_projection({"name": "albers", "parallels": [29.5, 45.5], "center": [-96, 37.8]})
+m.enable_rtl_text_plugin()
+m.set_mobile_behavior(cooperative_gestures=True, touch_zoom_rotate=False)
+```
+
+## Feature Demonstrations
+
+```python
+from maplibreum import (
+    Map,
+    Choropleth,
+    Marker,
+    MarkerCluster,
+    LayerControl,
+)
+
+m = Map()
+
+# Choropleth
+Choropleth(geojson_data).add_to(m)
+
+# Marker clusters
+cluster = MarkerCluster().add_to(m)
+Marker(coordinates=[0, 0]).add_to(cluster)
+
+# Clustered GeoJSON
+m.add_clustered_geojson(geojson_data)
+
+# Layer controls
+LayerControl().add_to(m)
+```
+
+## Expressions
+
+MapLibre uses array-based expressions for data-driven styling. The
+``maplibreum.expressions`` module provides helpers to construct and
+validate these expressions:
+
+```python
+from maplibreum.expressions import get, interpolate, var
+
+color = interpolate(
+    "linear",
+    var("heatmap-density"),
+    [(0, "blue"), (1, "red")],
+)
+```
+
+## Example Notebooks
+
+```bash
+jupyter notebook examples
+```
+
+### Live Examples Gallery
+
+View interactive examples deployed to GitHub Pages: [MapLibreum Examples Gallery](https://kauevestena.github.io/maplibreum_prototype/)
+
+The examples gallery is automatically generated from Jupyter notebooks in the `examples/` folder and showcases:
+- Creative MapLibreum examples and tutorials
+- Basic usage patterns
+- New features demonstrations  
+- Event handling and interactions
+
+To deploy examples to GitHub Pages, see the
+[GitHub Pages documentation](https://github.com/kauevestena/maplibreum_prototype/blob/main/docs/GITHUB_PAGES.md).
+
+## Changelog
+
+See the [CHANGELOG](CHANGELOG.md) for a detailed list of updates in each release.
+
+## Testing MapLibreum Functionality
+
+### Basic Testing
+
+Run the core test suite to verify MapLibreum's basic functionality:
+
+```bash
+# Install development dependencies
+pip install -e .
+pip install pytest jupyter
+
+# Run all basic tests
+pytest tests/ -v
+```
+
+### Advanced Testing: MapLibre Examples Validation
+
+To verify that MapLibreum is working properly and to check feature coverage against MapLibre GL JS, use the comprehensive testing suite in `development/maplibre_examples/`:
+
+#### MapLibre Examples Testing Suite
+
+The `development/maplibre_examples/` directory contains a systematic testing system that validates MapLibreum's capability to reproduce all official MapLibre GL JS examples. This provides:
+
+- **Automated validation** of feature coverage  
+- **Regression testing** for new releases
+- **Example conversion** from JavaScript to Python
+- **Performance benchmarking** against reference implementations
+
+#### Quick Status Check
+
+```bash
+# Install dependencies for the testing suite
+pip install requests beautifulsoup4
+
+# Check current implementation progress
+python -c "
+import json
+with open('development/maplibre_examples/status.json') as f:
+    data = json.load(f)
+total = len(data)
+implemented = sum(1 for v in data.values() if v['task_status'])
+print(f'MapLibreum Feature Coverage: {implemented}/{total} ({implemented/total*100:.1f}%)')
+print(f'Total MapLibre examples available: {total}')
+print(f'Examples successfully implemented: {implemented}')
+"
+```
+
+#### Running Example Tests
+
+```bash
+# Run all implemented example tests (when available)
+pytest tests/test_examples/ -v
+
+# Refresh examples from MapLibre.org (optional)
+python development/maplibre_examples/scrapping.py
+
+# Find next example to implement
+python -c "
+import json
+with open('development/maplibre_examples/status.json') as f:
+    data = json.load(f)
+for name, info in data.items():
+    if not info['task_status']:
+        print(f'Next unimplemented example: {name}')
+        print(f'MapLibre URL: {info[\"url\"]}')
+        break
+"
+```
+
+For detailed information about the testing suite, see the
+[MapLibre examples testing guide](https://github.com/kauevestena/maplibreum_prototype/blob/main/development/maplibre_examples/README.md).
+
+## Contributing
+
+Contributions are welcome! Please see the [issues page](https://github.com/kauevestena/maplibreum_prototype/issues) to see what needs to be done.
+
+## License
+
+This project is licensed under the MIT License; see the
+[LICENSE](https://github.com/kauevestena/maplibreum_prototype/blob/main/LICENSE)
+for details.

maplibreum-0.2.0/maplibreum/__init__.py

@@ -0,0 +1,57 @@
+from ._version import __version__
+from .babylon import BabylonLayer
+from .three import ThreeLayer
+from .choropleth import Choropleth
+from .cluster import ClusteredGeoJson, MarkerCluster, cluster_features
+from .core import (GeoJson, GeoJsonPopup, GeoJsonTooltip, LayerControl,
+                   MAPLIBRE_VERSION, LatLngPopup, Legend, Map, Marker, Popup,
+                   StateToggle, Tooltip)
+from .overlays import ImageOverlay, VideoOverlay
+from .markers import BeautifyIcon, DivIcon, Icon
+from .animation import AnimationLoop, TemporalInterval
+from .timedimension import TimeDimension
+from .controls import StorytellingControl, StyleSwitcherControl
+from . import controls
+from . import sources
+from . import layers
+from . import experimental
+from .custom import CustomGlobeLayer
+from .protocols import PMTilesProtocol, PMTilesSource
+
+__all__ = [
+    "Map",
+    "MAPLIBRE_VERSION",
+    "PMTilesProtocol",
+    "PMTilesSource",
+    "Marker",
+    "GeoJson", 
+    "Legend",
+    "LayerControl",
+    "Choropleth",
+    "Icon",
+    "DivIcon",
+    "BeautifyIcon",
+    "ImageOverlay",
+    "VideoOverlay",
+    "Tooltip",
+    "GeoJsonPopup",
+    "GeoJsonTooltip",
+    "LatLngPopup",
+    "Popup",
+    "StateToggle",
+    "TimeDimension",
+    "MarkerCluster",
+    "ClusteredGeoJson",
+    "cluster_features",
+    "__version__",
+    "StorytellingControl",
+    "StyleSwitcherControl",
+    "controls",
+    "sources",
+    "layers",
+    "AnimationLoop",
+    "TemporalInterval",
+    "CustomGlobeLayer",
+    "PMTilesProtocol",
+    "PMTilesSource",
+]

maplibreum-0.2.0/maplibreum/_version.py

@@ -0,0 +1,7 @@
+"""Project version information."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"