geovizpy 0.1.7__tar.gz → 0.1.8__tar.gz

{geovizpy-0.1.7 → geovizpy-0.1.8}/PKG-INFO

@@ -1,118 +1,112 @@
-Metadata-Version: 2.4
-Name: geovizpy
-Version: 0.1.7
-Summary: A Python wrapper for the geoviz JavaScript library
-Author: fbxyz
-Project-URL: Source, https://codeberg.org/fbxyz/geovizpy
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-Provides-Extra: export
-Requires-Dist: playwright; extra == "export"
-Dynamic: author
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: project-url
-Dynamic: provides-extra
-Dynamic: requires-python
-Dynamic: summary
-
-# geovizpy
-
-**geovizpy** is a Python wrapper for the `geoviz` JavaScript library, designed to bring the power of D3.js-based thematic mapping to Python. It allows you to create high-quality, interactive maps directly from Python scripts or Jupyter notebooks.
-
-This library is a wrapper around the  `geoviz` library. For detailed information on the underlying mapping logic, please refer to the [original geoviz documentation](https://github.com/neocarto/geoviz).
-
-![Choropleth Map Example](https://codeberg.org/fbxyz/geovizpy/raw/branch/main/docs/source/_static/choropleth.png)
-
-## Features
-
-- **Simple, chainable API**: Build complex maps by chaining intuitive methods.
-- **Variety of Map Types**: Create choropleth, proportional symbol, typology, and other thematic maps.
-- **Interactive Controls**: Add hover-to-expand controls for toggling layer visibility and exporting the map as SVG or PNG.
-- **Customizable**: Extensive options to customize colors, legends, strokes, and more.
-- **Standalone HTML**: Renders self-contained HTML files with no server required.
-- **Image Export**: Save maps directly to PNG or SVG from Python (requires optional dependencies).
-
-## Installation
-
-### Standard Installation
-
-You can install the core library using pip:
-
-```bash
-pip install geovizpy
-```
-
-Or install directly from the source repository:
-
-```bash
-pip install git+https://codeberg.org/fbxyz/geovizpy.git
-```
-
-### For Image Export
-
-To save maps as PNG or SVG files directly from Python, you need to install the optional `export` dependencies:
-
-1.  **Install the extra dependencies:**
-
-    ```bash
-    pip install "geovizpy[export]"
-    ```
-
-2.  **Install Playwright's browser binaries:**
-
-    ```bash
-    playwright install
-    ```
-
-    On Linux, you may also need to install host dependencies:
-    
-    ```bash
-    sudo playwright install-deps
-    ```
-
-## Quick Start
-
-Here is a simple example of how to create a choropleth map:
-
-```python
-from geovizpy import Geoviz
-import json
-
-# Load your GeoJSON data
-# (Assuming 'world.json' is in a 'data' subdirectory)
-with open("data/world.json") as f:
-    world_data = json.load(f)
-
-# Initialize the map
-viz = Geoviz(projection="EqualEarth", width=800)
-
-# Add layers
-viz.outline()
-viz.graticule()
-
-# Add a choropleth layer
-viz.choro(
-    data=world_data,
-    var="gdppc",
-    colors="Blues",
-    legend=True,
-    leg_title="GDP per Capita"
-)
-
-# Add interactive controls
-viz.add_layer_control(layers=["choropleth_gdp"])
-viz.add_export_control()
-
-# Save the map
-viz.save("my_map.html")  # Renders an interactive HTML file
-# viz.save("my_map.png")   # Renders a static PNG image (requires export dependencies)
-```
-
-## Documentation
-
-For more detailed information on all available methods and parameters, please see the [full documentation](https://geovizpy.readthedocs.io/en/latest/).
+Metadata-Version: 2.4
+Name: geovizpy
+Version: 0.1.8
+Summary: A Python wrapper for the geoviz JavaScript library
+Author: fbxyz
+License: MIT
+Project-URL: Source, https://codeberg.org/fbxyz/geovizpy
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Provides-Extra: export
+Requires-Dist: playwright; extra == "export"
+Dynamic: requires-python
+
+# geovizpy
+
+**geovizpy** is a Python wrapper for the `geoviz` JavaScript library, designed to bring the power of D3.js-based thematic mapping to Python. It allows you to create high-quality, interactive maps directly from Python scripts or Jupyter notebooks.
+
+This library is a wrapper around the  `geoviz` library. For detailed information on the underlying mapping logic, please refer to the [original geoviz documentation](https://github.com/neocarto/geoviz).
+
+![Choropleth Map Example](https://codeberg.org/fbxyz/geovizpy/raw/branch/main/docs/source/_static/choropleth.png)
+
+## Features
+
+- **Simple, chainable API**: Build complex maps by chaining intuitive methods.
+- **Variety of Map Types**: Create choropleth, proportional symbol, typology, and other thematic maps.
+- **Interactive Controls**: Add hover-to-expand controls for toggling layer visibility and exporting the map as SVG or PNG.
+- **Customizable**: Extensive options to customize colors, legends, strokes, and more.
+- **Standalone HTML**: Renders self-contained HTML files with no server required.
+- **Image Export**: Save maps directly to PNG or SVG from Python (requires optional dependencies).
+
+## Installation
+
+### Standard Installation
+
+You can install the core library using pip:
+
+```bash
+pip install geovizpy
+```
+
+Or install directly from the source repository:
+
+```bash
+pip install git+https://codeberg.org/fbxyz/geovizpy.git
+```
+
+### For Image Export
+
+To save maps as PNG or SVG files directly from Python, you need to install the optional `export` dependencies:
+
+1.  **Install the extra dependencies:**
+
+    ```bash
+    pip install "geovizpy[export]"
+    ```
+
+2.  **Install Playwright's browser binaries:**
+
+    ```bash
+    playwright install
+    ```
+
+    On Linux, you may also need to install host dependencies:
+    
+    ```bash
+    sudo playwright install-deps
+    ```
+
+## Quick Start
+
+Here is a simple example of how to create a choropleth map:
+
+```python
+from geovizpy import Geoviz
+import json
+
+# Load your GeoJSON data
+# (Assuming 'world.json' is in a 'data' subdirectory)
+with open("data/world.json") as f:
+    world_data = json.load(f)
+
+# Initialize the map
+viz = Geoviz(projection="EqualEarth", width=800)
+
+# Add layers
+viz.outline()
+viz.graticule()
+
+# Add a choropleth layer
+viz.choro(
+    data=world_data,
+    var="gdppc",
+    colors="Blues",
+    legend=True,
+    leg_title="GDP per Capita"
+)
+
+# Add interactive controls
+viz.add_layer_control(layers=["choropleth_gdp"])
+viz.add_export_control()
+
+# Save the map
+viz.save("my_map.html")  # Renders an interactive HTML file
+# viz.save("my_map.png")   # Renders a static PNG image (requires export dependencies)
+```
+
+## Documentation
+
+For more detailed information on all available methods and parameters, please see the [full documentation](https://geovizpy.readthedocs.io/en/latest/).

geovizpy-0.1.8/docs/source/conf.py

@@ -0,0 +1,32 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../'))
+
+project = 'geovizpy'
+copyright = '2026, fbxyz'
+author = 'fbxyz'
+release = '0.1.3'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+except ImportError:
+    html_theme = 'alabaster'
+
+html_static_path = ['_static']
+
+# -- Options for autodoc -----------------------------------------------------
+autodoc_member_order = 'bysource'

geovizpy-0.1.8/examples/advanced_plots.py

@@ -0,0 +1,82 @@
+"""Example script demonstrating advanced plot types."""
+
+import json
+import os
+import random
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+continents = ["Africa", "Asia", "Europe", "North America", "South America", "Oceania"]
+symbols_list = ["star", "circle", "cross", "diamond", "square", "triangle"]
+
+for f in world_data.get("features", []):
+    f["properties"]["random_continent"] = random.choice(continents)
+    f["properties"]["random_symbol"] = random.choice(symbols_list)
+
+# 1. Typology Map
+viz1 = Geoviz(projection="EqualEarth", width=800)
+viz1.outline()
+viz1.graticule(stroke="white", strokeWidth=0.4)
+
+viz1.typo(
+    data=world_data,
+    var="random_continent",
+    colors="Pastel",
+    strokeWidth=0.5,
+    leg_title="Random Continent",
+    leg_pos=[10, 200]
+)
+viz1.header(text="Typology Map (Random Data)", fontSize=20)
+viz1.render_html(os.path.join(output_dir, "advanced_typo.html"))
+
+# 2. Proportional Symbols with Typology
+viz2 = Geoviz(projection="EqualEarth", width=800)
+viz2.outline()
+viz2.graticule()
+viz2.path(datum=world_data, fill="#eee")
+
+viz2.proptypo(
+    data=world_data,
+    var1="pop",
+    var2="random_continent",
+    k=50,
+    colors="Set1",
+    leg1_title="Population",
+    leg2_title="Continent",
+    leg1_pos=[10, 300],
+    leg2_pos=[10, 150]
+)
+viz2.header(text="Proportional Symbols + Typology", fontSize=20)
+viz2.render_html(os.path.join(output_dir, "advanced_proptypo.html"))
+
+# 3. Symbol Map
+viz3 = Geoviz(projection="EqualEarth", width=800)
+viz3.outline()
+viz3.graticule()
+viz3.path(datum=world_data, fill="#ddd")
+
+viz3.picto(
+    data=world_data,
+    var="random_symbol",
+    symbols=["star", "circle", "cross", "diamond", "square", "triangle"],
+    colors="black",
+    fill="red",
+    stroke="white",
+    strokeWidth=1,
+    k=15,
+    leg_title="Random Symbols",
+    leg_pos=[10, 200]
+)
+viz3.header(text="Symbol Map (Picto)", fontSize=20)
+viz3.render_html(os.path.join(output_dir, "advanced_symbol.html"))

geovizpy-0.1.8/examples/bubble.py

@@ -0,0 +1,46 @@
+"""Example script for creating a proportional symbol map (bubble map)."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+viz = Geoviz(projection="EqualEarth", zoomable=True)
+viz.outline()
+viz.graticule(stroke="white", strokeWidth=0.4)
+viz.path(datum=world_data, fill="white", fillOpacity=0.4)
+
+# Use viz.prop instead of viz.circle to get automatic legend handling
+viz.prop(
+    data=world_data,
+    var="pop", # 'var' is used instead of 'r' in viz.prop
+    fill="#f07d75",
+    tip="(d) => `${d.properties.NAMEen}\n${d.properties.pop / 1000} thousands inh.`",
+    leg_type="separate",
+    leg_title="Population",
+    leg_pos=[30, 30], # Added position to make sure it's visible
+    leg_title_fontSize=15
+)
+
+pops = [f["properties"]["pop"] for f in world_data.get("features", []) if "pop" in f["properties"]]
+
+viz.header(
+    fontSize=30,
+    text="A World Map With Bubbles",
+    fill="#267A8A",
+    fontWeight="bold",
+    fontFamily="Tangerine"
+)
+
+viz.render_html(os.path.join(output_dir, "bubble.html"))

geovizpy-0.1.8/examples/choropleth.py

@@ -0,0 +1,45 @@
+"""Example script for a choropleth map."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+viz = Geoviz(projection="EqualEarth")
+viz.outline()
+viz.graticule(stroke="white", step=30, strokeWidth=1.2)
+
+viz.choro(
+    data=world_data,
+    var="gdppc",
+    strokeWidth=0.3,
+    tip=True,
+    leg_type="horizontal",
+    leg_title="GDP per capita",
+    leg_subtitle="($ per inh.)",
+    leg_note="Source: worldbank, 2020",
+    leg_pos=[410, 370],
+    leg_values_round=0,
+    leg_missing_text="Missing values"
+)
+
+viz.header(
+    fontSize=30,
+    text="A Choropleth World Map",
+    fill="#267A8A",
+    fontWeight="bold",
+    fontFamily="Tangerine"
+)
+
+viz.render_html(os.path.join(output_dir, "choropleth.html"))

geovizpy-0.1.8/examples/choropleth_effect.py

@@ -0,0 +1,62 @@
+"""Example script demonstrating visual effects (shadow)."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+brazil = {
+    "type": "FeatureCollection",
+    "features": [f for f in world_data.get("features", []) if f["properties"].get("NAMEen") == "Brazil"]
+}
+
+viz = Geoviz(projection="EqualEarth")
+
+viz.effect_shadow(id="myshadow", dx=10, dy=10, opacity=0.5)
+
+viz.outline()
+viz.graticule(stroke="white", step=30, strokeWidth=1.2)
+
+viz.choro(
+    data=world_data,
+    var="gdppc",
+    strokeWidth=0.3,
+    tip=True,
+    leg_type="horizontal",
+    leg_title="GDP per capita",
+    leg_subtitle="($ per inh.)",
+    leg_note="Source: worldbank, 2020",
+    leg_pos=[410, 370],
+    leg_values_round=0,
+    leg_missing_text="Missing values"
+)
+
+if brazil["features"]:
+    viz.path(
+        data=brazil,
+        fill="none",
+        stroke="red",
+        strokeWidth=2,
+        filter="url(#myshadow)"
+    )
+
+viz.header(
+    fontSize=30,
+    text="Choropleth with Shadow Effect on Brazil",
+    fill="#267A8A",
+    fontWeight="bold",
+    fontFamily="Tangerine"
+)
+
+viz.render_html(os.path.join(output_dir, "choropleth_effect.html"))

geovizpy-0.1.8/examples/json_export.py

@@ -0,0 +1,37 @@
+"""Example script for exporting the map configuration to JSON."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+viz = Geoviz(projection="EqualEarth")
+viz.outline()
+viz.graticule(stroke="white", strokeWidth=0.4)
+viz.choro(
+    data=world_data,
+    var="gdppc",
+    strokeWidth=0.3,
+    tip=True,
+    leg_title="GDP per capita"
+)
+viz.header(text="Map from JSON Config", fontSize=30)
+
+config_json = viz.to_json()
+print("Configuration JSON (first 500 chars):")
+print(config_json[:500] + "...")
+
+with open(os.path.join(output_dir, "map_config.json"), "w") as f:
+    f.write(config_json)
+print(f"\nConfiguration saved to {os.path.join(output_dir, 'map_config.json')}")

geovizpy-0.1.8/examples/labels.py

@@ -0,0 +1,43 @@
+"""Example script for adding text labels to a map."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+countries_to_label = ["Brazil", "China", "United States", "France", "South Africa", "Australia"]
+labeled_features = [f for f in world_data.get("features", []) if f["properties"].get("NAMEen") in countries_to_label]
+labeled_data = {"type": "FeatureCollection", "features": labeled_features}
+
+viz = Geoviz(projection="EqualEarth")
+viz.outline()
+viz.graticule(stroke="white", strokeWidth=0.4)
+
+viz.path(datum=world_data, fill="#e0e0e0", stroke="white")
+
+viz.text(
+    data=labeled_data,
+    text="NAMEen",
+    fill="#333",
+    fontSize=14,
+    fontWeight="bold",
+    stroke="white",
+    strokeWidth=3,
+    paintOrder="stroke"
+)
+
+
+
+viz.header(text="Map with Labels", fontSize=20)
+viz.render_html(os.path.join(output_dir, "labels.html"))

geovizpy-0.1.8/examples/layer_control.py

@@ -0,0 +1,70 @@
+"""Example script for layer control and export functionality."""
+
+import json
+import os
+from geovizpy import Geoviz
+
+# Define output directory
+output_dir = os.path.join(os.path.dirname(__file__), "html")
+os.makedirs(output_dir, exist_ok=True)
+
+# Load world data
+data_path = os.path.join(os.path.dirname(__file__), "data", "world.json")
+try:
+    with open(data_path) as f:
+        world_data = json.load(f)
+except FileNotFoundError:
+    print(f"{data_path} not found.")
+    world_data = {}
+
+# Create a map
+viz = Geoviz(projection="EqualEarth", zoomable=True)
+viz.outline(id="outline")
+viz.graticule(stroke="white", strokeWidth=0.4, id="graticule")
+
+# Add a choropleth layer with an ID and legend position
+viz.choro(
+    data=world_data,
+    var="gdppc",
+    colors="Reds",
+    id="choropleth_gdp",
+    legend=True,
+    leg_title="GDP per Capita",
+    leg_pos=[10, 100]  # Position for the choro legend
+)
+
+# Add a proportional symbol layer with an ID and legend position
+viz.prop(
+    data=world_data,
+    var="pop",
+    fill="#4f8a8b",
+    stroke="white",
+    id="prop_population",
+    legend=True,
+    leg_title="Population",
+    leg_pos=[10, 250]  # Position for the prop legend
+)
+
+# Add the layer control widget (hover to expand)
+viz.add_layer_control(
+    layers=["choropleth_gdp", "prop_population", "graticule"],
+    title="Layers",
+    x=10,
+    y=10
+)
+
+# Add the export control widget (hover to expand)
+viz.add_export_control(
+    pos="top-right" # Or use x, y
+)
+
+# Add opacity control for multiple layers
+viz.add_opacity_control(
+    layers=["choropleth_gdp", "prop_population"],
+    title="Layers Opacity",
+    x=10,
+    y=90
+)
+
+viz.header(text="Map with Layer & Export Controls", fontSize=20)
+viz.render_html(os.path.join(output_dir, "layer_control_map.html"))