Metadata-Version: 2.1
Name: OvertureMaestro
Version: 0.6.1
Summary: An open-source tool for downloading Overture Maps data with quality of life features
Author-Email: Kamil Raczycki <kraczycki@kraina.ai>
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Requires-Dist: overturemaps>=0.8.0
Requires-Dist: geopandas>=1.0
Requires-Dist: shapely>=2.0.6
Requires-Dist: pyarrow>=16.0.0
Requires-Dist: rich>=12.0.0
Requires-Dist: geoarrow-rust-core>=0.4.0
Requires-Dist: pooch>=1.6.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: fsspec>=2021.04.0
Requires-Dist: geopy>=2.0.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: duckdb>=1.1.2
Requires-Dist: psutil>=5.6.2
Requires-Dist: rq-geo-toolkit>=2026.4.0
Provides-Extra: cli
Requires-Dist: typer[all]>=0.9.0; extra == "cli"
Requires-Dist: s2sphere>=0.2.5; extra == "cli"
Description-Content-Type: text/markdown

<p align="center">
  <img width="300" src="https://raw.githubusercontent.com/kraina-ai/overturemaestro/main/docs/assets/logos/overturemaestro_logo.png"><br/>
  <small>Generated using DALL·E 3 model with this prompt: Cute stylized conducting virtuoso using a paper map as music sheet. White background, minimalistic, vector graphics, clean background, encased in a circle. In navy and gold colours. Logo for a python library, should work well as small icon.</small>
</p>

<p align="center">
    <img alt="GitHub" src="https://img.shields.io/github/license/kraina-ai/overturemaestro?logo=apache&logoColor=%23fff">
    <img src="https://img.shields.io/github/checks-status/kraina-ai/overturemaestro/main?logo=GitHubActions&logoColor=%23fff" alt="Checks">
    <a href="https://github.com/kraina-ai/overturemaestro/actions/workflows/ci-dev.yml" target="_blank">
        <img alt="GitHub Workflow Status - DEV" src="https://img.shields.io/github/actions/workflow/status/kraina-ai/overturemaestro/ci-dev.yml?label=build-dev&logo=GitHubActions&logoColor=%23fff">
    </a>
    <a href="https://github.com/kraina-ai/overturemaestro/actions/workflows/ci-prod.yml" target="_blank">
        <img alt="GitHub Workflow Status - PROD" src="https://img.shields.io/github/actions/workflow/status/kraina-ai/overturemaestro/ci-prod.yml?label=build-prod&logo=GitHubActions&logoColor=%23fff">
    </a>
    <a href="https://results.pre-commit.ci/latest/github/kraina-ai/overturemaestro/main" target="_blank">
        <img src="https://results.pre-commit.ci/badge/github/kraina-ai/overturemaestro/main.svg" alt="pre-commit.ci status">
    </a>
    <a href="https://www.codefactor.io/repository/github/kraina-ai/overturemaestro"><img alt="CodeFactor Grade" src="https://img.shields.io/codefactor/grade/github/kraina-ai/overturemaestro?logo=codefactor&logoColor=%23fff"></a>
    <a href="https://app.codecov.io/gh/kraina-ai/overturemaestro/tree/main"><img alt="Codecov" src="https://img.shields.io/codecov/c/github/kraina-ai/overturemaestro?logo=codecov&token=PRS4E02ZX0&logoColor=%23fff"></a>
    <a href="https://pypi.org/project/overturemaestro" target="_blank">
        <img src="https://img.shields.io/pypi/v/overturemaestro?color=%2334D058&label=pypi%20package&logo=pypi&logoColor=%23fff" alt="Package version">
    </a>
    <a href="https://pypi.org/project/overturemaestro" target="_blank">
        <img src="https://img.shields.io/pypi/pyversions/overturemaestro.svg?color=%2334D058&logo=python&logoColor=%23fff" alt="Supported Python versions">
    </a>
    <a href="https://pypi.org/project/overturemaestro" target="_blank">
        <img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/overturemaestro">
    </a>
</p>

# OvertureMaestro

An open-source tool for reading OvertureMaps data with multiprocessing and additional Quality-of-Life features.

## What is **OvertureMaestro** 🎼🌍?

- Scalable reader for OvertureMaps data.
- Is based on top of `PyArrow`[^1].
- Saves files in the `GeoParquet`[^2] file format for easier integration with modern cloud stacks.
- Filters data based on geometry.
- Can filter data using PyArrow expressions.
- Utilizes multiprocessing for faster data download.
- Utilizes dedicated index of all features in the Overture Maps dataset to download only specific parts based on the geometry filter.
- Utilizes caching to reduce repeatable computations.
- Can be used as Python module as well as a beautiful CLI based on `Typer`[^3].

[^1]: [PyArrow Website](https://arrow.apache.org/docs/python/)
[^2]: [GeoParquet data format](https://geoparquet.org/)
[^3]: [Typer docs](https://typer.tiangolo.com/)

## Installing

### As pure Python module

```
pip install overturemaestro
```

### With beautiful CLI

```
pip install overturemaestro[cli]
```

### Required Python version?

OvertureMaestro supports **Python >= 3.10**

### Dependencies

Required:

- `overturemaps (>=0.8.0)`: Reusing oficial CLI library with dedicated schema related functions

- `pyarrow (>=16.0.0)`: For OvertureMaps GeoParquet dataset wrangling

- `geopandas (>=1.0)`: For returning GeoDataFrames and reading Geo files

- `shapely (>=2.0)`: For parsing WKT and GeoJSON strings and filtering data with STRIndex

- `geoarrow-rust-core (>=0.4.0)`: For transforming Arrow data to Shapely objects

- `duckdb (>=1.1.2)`: For transforming downloaded data to the wide format and sorting files by geometry

- `pooch (>=1.6.0)`: For downloading precalculated dataset indexes

- `rich (>=12.0.0)`: For showing progress bars

- `fsspec (>=2021.04.0)` & `aiohttp (>=3.8.0)`: For accessing AWS S3 datasets in PyArrow and GitHub files for precalculated datasets

- `geopy (>=2.0.0)`: For geocoding of strings

Optional:

- `typer[all] (>=0.9.0)` (click, colorama, rich, shellingham): Required in CLI

- `h3 (>=4.0.0b1)`: For reading H3 strings. Required in CLI

- `s2 (>=0.1.9)`: For transforming S2 indexes into geometries. Required in CLI

- `python-geohash (>=0.8)`: For transforming GeoHash indexes into geometries. Required in CLI

## Usage

TODO
