Metadata-Version: 2.4
Name: geovizpy
Version: 0.1.5
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 excellent `geoviz` library. For detailed information on the underlying mapping logic, please refer to the [original geoviz documentation](https://github.com/neocarto/geoviz).

## 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, which include `playwright`.

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://your-username.github.io/geovizpy/). 

