Metadata-Version: 2.4
Name: geomaplib
Version: 0.1.0rc1
Summary: Simple, opinionated geographic visualization for DataFrames.
Project-URL: Repository, https://github.com/anyx05/geomaplib
Project-URL: Issues, https://github.com/anyx05/geomaplib/issues
Author: Emmanuel Alabi
Maintainer: Emmanuel Alabi
License: MIT
License-File: LICENSE
Keywords: choropleth,geopandas,geospatial,matplotlib,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12
Requires-Dist: geopandas>=1.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# GeoMapLib

GeoMapLib is a small, opinionated Python library for creating trustworthy and
attractive geographic visualizations from Pandas and GeoPandas data.

The project is deliberately narrower than a GIS framework. GeoPandas remains
the geometry engine; GeoMapLib focuses on the repetitive visualization layer:
geography resolution, safe attribute joins, sensible map defaults, missing-data
handling, and Matplotlib rendering.

## Installation

```bash
python -m pip install geomaplib
```

GeoMapLib requires Python 3.12 or newer.

## Quick start

The first release focuses on one job: static continuous polygon choropleths.
The built-in world geography works offline and uses ISO 3166-1 alpha-3 country
identifiers.

```python
import geomaplib as gm
import pandas as pd

df = pd.DataFrame(
    {
        "iso_code": ["USA", "NGA", "TUR"],
        "value": [10.0, 25.0, 18.0],
    }
)
ax = gm.choropleth(
    data=df,
    geography="world",
    locations="iso_code",
    color="value",
)
```

The result is a static Matplotlib world map with the three matched countries
shaded on a continuous color scale and all other polygons shown with the
missing-data style. Input ISO values are stripped and uppercased; country-name
matching is not performed. See the
[world dataset documentation](https://github.com/anyx05/geomaplib/blob/HEAD/docs/datasets/world.md)
for source provenance, boundary conventions, and known coverage limitations.

Custom polygon geographies can be supplied as a GeoDataFrame:

```python
ax = gm.choropleth(
    data=df,
    geography=regions_gdf,
    feature_key="region_id",
    locations="region_id",
    color="value",
)
```

An existing local geography file works the same way by passing its path as
`geography="regions.geojson"`. If a GeoDataFrame already contains both its
geometry and values, use `gm.choropleth(data=regions_with_values,
color="value")` without join arguments.

`choropleth()` returns the exact Matplotlib `Axes` used for rendering, so it
composes with normal Matplotlib operations:

```python
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(10, 6))
returned = gm.choropleth(
    data=df,
    geography="world",
    locations="iso_code",
    color="value",
    ax=ax,
)
assert returned is ax
ax.set_title("Example")
fig.savefig("map.png")
```

## Design principles

- Functional, DataFrame-first public API.
- Composition over inheritance.
- Matplotlib-native rendering and styling.
- No global plotting-style mutation.
- Exact custom-geography joins; no fuzzy matching.
- ISO alpha-3 normalization only for the built-in country geography.
- Duplicate locations never aggregate silently.
- GeoPandas and Matplotlib remain available as escape hatches.
- New abstractions are added only when new requirements justify them.

## Development setup

```bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
```

## Quality checks

```bash
pytest --cov=geomaplib --cov-report=term-missing
ruff check .
ruff format --check .
mypy src/geomaplib
python -m build
```

## Documentation

- [Architecture](https://github.com/anyx05/geomaplib/blob/HEAD/docs/ARCHITECTURE.md)
- [Roadmap](https://github.com/anyx05/geomaplib/blob/HEAD/docs/ROADMAP.md)
- [Boundary and identifier policy](https://github.com/anyx05/geomaplib/blob/HEAD/docs/BOUNDARY_AND_IDENTIFIERS.md)
- [Built-in world geography](https://github.com/anyx05/geomaplib/blob/HEAD/docs/datasets/world.md)
- [Architecture decisions](https://github.com/anyx05/geomaplib/tree/HEAD/docs/decisions)

## v0.1 non-goals

Categorical choropleths, classification schemes, projections, point/bubble
maps, labels, density maps, remote geography downloads, interactive backends,
fuzzy country matching, and public `Map`/`Layer` builders are intentionally
deferred. See the roadmap for the planned evolution.
