Metadata-Version: 2.4
Name: geonamecache
Version: 1.0.1
Summary: Lightweight geographic data cache built on geonamescache
License-Expression: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: geonamescache>=2.0.0
Requires-Dist: geocache-utils>=0.2.0

# geonamecache

Lightweight geographic data cache with deterministic cross-platform sampling.

Built on top of [geonamescache](https://pypi.org/project/geonamescache/), this
package adds cross-version reproducibility guarantees for seeded random
operations on geographic datasets.

## Installation

```bash
pip install geonamecache
```

## Quick start

```python
from geonamecache import GeonamesCache

gc = GeonamesCache()
cities = gc.get_cities()
countries = gc.get_countries()
```

## API

`GeonamesCache` exposes the same interface as `geonamescache.GeonamesCache`:

- `get_cities()` — dictionary of cities keyed by GeoNames ID
- `get_countries()` — dictionary of countries keyed by ISO code
- `get_continents()` — dictionary of continents
- `get_us_states()` / `get_us_counties()` — US administrative divisions
- `search_cities(query)` — search cities by alternate names

## Why not just use geonamescache?

`geonamecache` wraps `geonamescache` and adds a compatibility shim (via
`geocache-utils`) that normalises `random.sample` behaviour across Python
3.8–3.13. This ensures that pipelines using seeded randomness produce
identical results regardless of interpreter version.
