overturemaps 1.0.2__tar.gz → 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/dependabot.yml +4 -4
- {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/build-binaries.yml +17 -3
- {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/publish-pypi.yml +27 -4
- overturemaps-2.0.0/.github/workflows/release.yml +71 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/.github/workflows/test-run.yml +3 -3
- overturemaps-2.0.0/CONTRIBUTING.md +68 -0
- overturemaps-2.0.0/PKG-INFO +91 -0
- overturemaps-2.0.0/README.md +66 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/SPEC.md +13 -12
- overturemaps-2.0.0/docs/cli.md +70 -0
- overturemaps-2.0.0/docs/performance.md +16 -0
- overturemaps-2.0.0/docs/python-api.md +49 -0
- overturemaps-2.0.0/docs/screenshot.png +0 -0
- overturemaps-2.0.0/overturemaps/_http.py +23 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/changelog.py +2 -2
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/core.py +3 -3
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/models.py +1 -16
- {overturemaps-1.0.2 → overturemaps-2.0.0}/pyproject.toml +15 -2
- overturemaps-2.0.0/tests/test_http.py +56 -0
- overturemaps-2.0.0/uv.lock +1537 -0
- overturemaps-1.0.2/CONTRIBUTING.md +0 -53
- overturemaps-1.0.2/PKG-INFO +0 -190
- overturemaps-1.0.2/README.md +0 -165
- overturemaps-1.0.2/uv.lock +0 -1040
- {overturemaps-1.0.2 → overturemaps-2.0.0}/.gitignore +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/CODEOWNERS +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/LICENSE +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/benchmarks/bench_count_rows.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/benchmarks/bench_geojson_writer.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/justfile +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/__init__.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/__main__.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/cli.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/examples/geopandas_example.ipynb +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/releases.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/state.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/overturemaps/writers.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/pytest.ini +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/__init__.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_changelog.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_download.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_gers.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_cli_releases.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_copy.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_core.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_gers.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_main.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_models.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_releases.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_state.py +0 -0
- {overturemaps-1.0.2 → overturemaps-2.0.0}/tests/test_writers.py +0 -0
|
@@ -15,13 +15,13 @@ updates:
|
|
|
15
15
|
labels:
|
|
16
16
|
- "bot"
|
|
17
17
|
commit-message:
|
|
18
|
-
prefix: "
|
|
18
|
+
prefix: "chore"
|
|
19
19
|
include: "scope"
|
|
20
20
|
cooldown:
|
|
21
21
|
default-days: 7
|
|
22
22
|
|
|
23
|
-
# Maintain Python dependencies
|
|
24
|
-
- package-ecosystem: "
|
|
23
|
+
# Maintain Python dependencies (pyproject.toml and uv.lock)
|
|
24
|
+
- package-ecosystem: "uv"
|
|
25
25
|
directory: "/"
|
|
26
26
|
schedule:
|
|
27
27
|
interval: "weekly"
|
|
@@ -33,7 +33,7 @@ updates:
|
|
|
33
33
|
labels:
|
|
34
34
|
- "bot"
|
|
35
35
|
commit-message:
|
|
36
|
-
prefix: "
|
|
36
|
+
prefix: "chore"
|
|
37
37
|
include: "scope"
|
|
38
38
|
cooldown:
|
|
39
39
|
default-days: 7
|
|
@@ -44,12 +44,26 @@ jobs:
|
|
|
44
44
|
persist-credentials: false
|
|
45
45
|
|
|
46
46
|
- name: Install uv
|
|
47
|
-
uses: astral-sh/setup-uv@
|
|
47
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
48
48
|
with:
|
|
49
49
|
enable-cache: false
|
|
50
50
|
|
|
51
|
+
- name: Stamp version
|
|
52
|
+
id: stamp
|
|
53
|
+
shell: bash
|
|
54
|
+
env:
|
|
55
|
+
TAG: ${{ github.event.release.tag_name }}
|
|
56
|
+
run: |
|
|
57
|
+
if [ "$GITHUB_EVENT_NAME" = "release" ]; then
|
|
58
|
+
version="${TAG#v}"
|
|
59
|
+
else
|
|
60
|
+
version="0.0.0.dev${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT}"
|
|
61
|
+
fi
|
|
62
|
+
uv version "$version" --frozen
|
|
63
|
+
echo "version=$version" >> "$GITHUB_OUTPUT"
|
|
64
|
+
|
|
51
65
|
- name: Install dependencies
|
|
52
|
-
run: uv sync --group binary
|
|
66
|
+
run: uv sync --group binary --frozen
|
|
53
67
|
|
|
54
68
|
- name: Get version
|
|
55
69
|
id: version
|
|
@@ -95,7 +109,7 @@ jobs:
|
|
|
95
109
|
|
|
96
110
|
- name: Upload artifact (dry run)
|
|
97
111
|
if: github.event_name == 'workflow_dispatch'
|
|
98
|
-
uses: actions/upload-artifact@
|
|
112
|
+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
99
113
|
with:
|
|
100
114
|
name: overturemaps-${{ matrix.target }}
|
|
101
115
|
path: ${{ env.BINARY_PATH }}
|
|
@@ -30,15 +30,38 @@ jobs:
|
|
|
30
30
|
persist-credentials: false
|
|
31
31
|
|
|
32
32
|
- name: Install uv
|
|
33
|
-
uses: astral-sh/setup-uv@
|
|
33
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
34
34
|
with:
|
|
35
35
|
enable-cache: false
|
|
36
36
|
|
|
37
|
+
- name: Stamp version
|
|
38
|
+
id: stamp
|
|
39
|
+
env:
|
|
40
|
+
TAG: ${{ github.event.release.tag_name }}
|
|
41
|
+
run: |
|
|
42
|
+
if [ "$GITHUB_EVENT_NAME" = "release" ]; then
|
|
43
|
+
version="${TAG#v}"
|
|
44
|
+
else
|
|
45
|
+
version="0.0.0.dev${GITHUB_RUN_ID}${GITHUB_RUN_ATTEMPT}"
|
|
46
|
+
fi
|
|
47
|
+
uv version "$version" --frozen
|
|
48
|
+
echo "version=$version" >> "$GITHUB_OUTPUT"
|
|
49
|
+
|
|
37
50
|
- name: Build package
|
|
38
51
|
run: uv build
|
|
39
52
|
|
|
53
|
+
- name: Check package metadata
|
|
54
|
+
run: uvx twine check --strict dist/*
|
|
55
|
+
|
|
56
|
+
- name: Check built versions
|
|
57
|
+
env:
|
|
58
|
+
EXPECTED_VERSION: ${{ steps.stamp.outputs.version }}
|
|
59
|
+
run: |
|
|
60
|
+
test -f "dist/overturemaps-${EXPECTED_VERSION}-py3-none-any.whl"
|
|
61
|
+
test -f "dist/overturemaps-${EXPECTED_VERSION}.tar.gz"
|
|
62
|
+
|
|
40
63
|
- name: Upload dist artifacts
|
|
41
|
-
uses: actions/upload-artifact@
|
|
64
|
+
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
42
65
|
with:
|
|
43
66
|
name: dist
|
|
44
67
|
path: dist/
|
|
@@ -54,13 +77,13 @@ jobs:
|
|
|
54
77
|
id-token: write # OIDC — required for PyPI trusted publishing
|
|
55
78
|
steps:
|
|
56
79
|
- name: Download dist artifacts
|
|
57
|
-
uses: actions/download-artifact@
|
|
80
|
+
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
58
81
|
with:
|
|
59
82
|
name: dist
|
|
60
83
|
path: dist/
|
|
61
84
|
|
|
62
85
|
- name: Publish
|
|
63
|
-
uses: pypa/gh-action-pypi-publish@
|
|
86
|
+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
|
|
64
87
|
with:
|
|
65
88
|
repository-url: ${{ github.event_name == 'workflow_dispatch' && env.TEST_PYPI_URL || '' }}
|
|
66
89
|
skip-existing: ${{ github.event_name == 'workflow_dispatch' }} # Don't fail on version conflicts during test-publishing
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Cuts a GitHub Release from Conventional Commits on every push to main.
|
|
2
|
+
# Nothing is committed back to main; release notes are generated on the GitHub Release.
|
|
3
|
+
#
|
|
4
|
+
# The release is created with the overture-releaser GitHub App's token, not GITHUB_TOKEN:
|
|
5
|
+
# GITHUB_TOKEN-created releases don't fire `release: published`.
|
|
6
|
+
name: Release
|
|
7
|
+
|
|
8
|
+
on:
|
|
9
|
+
push:
|
|
10
|
+
branches:
|
|
11
|
+
- main
|
|
12
|
+
|
|
13
|
+
permissions: {}
|
|
14
|
+
|
|
15
|
+
concurrency:
|
|
16
|
+
group: ${{ github.workflow }}
|
|
17
|
+
cancel-in-progress: false
|
|
18
|
+
|
|
19
|
+
jobs:
|
|
20
|
+
release:
|
|
21
|
+
name: Create release
|
|
22
|
+
if: github.repository == 'OvertureMaps/overturemaps-py'
|
|
23
|
+
runs-on: ubuntu-latest
|
|
24
|
+
permissions:
|
|
25
|
+
contents: read
|
|
26
|
+
id-token: write # OIDC access to the AWS role that reads the releaser app PEM
|
|
27
|
+
steps:
|
|
28
|
+
- name: Checkout code
|
|
29
|
+
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
30
|
+
with:
|
|
31
|
+
fetch-depth: 0
|
|
32
|
+
persist-credentials: false
|
|
33
|
+
|
|
34
|
+
- name: Install uv
|
|
35
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
36
|
+
with:
|
|
37
|
+
enable-cache: false
|
|
38
|
+
|
|
39
|
+
- name: Configure AWS credentials
|
|
40
|
+
uses: aws-actions/configure-aws-credentials@e1253824e5c10ff9df46874f81ed3ec929e19cfd # v6.3.0
|
|
41
|
+
with:
|
|
42
|
+
aws-region: us-west-2
|
|
43
|
+
role-to-assume: arn:aws:iam::816069134238:role/gha-releaser-secrets-reader
|
|
44
|
+
role-session-name: GitHubActions_${{ github.job }}_${{ github.run_id }}
|
|
45
|
+
|
|
46
|
+
- name: Fetch releaser PEM from Secrets Manager
|
|
47
|
+
uses: aws-actions/aws-secretsmanager-get-secrets@2297f9a879480a9e3af9b293ed15c70caf8e1c88 # v3.0.2
|
|
48
|
+
with:
|
|
49
|
+
secret-ids: |
|
|
50
|
+
RELEASER_APP_PEM, omf-github-terraform/releaser/pem
|
|
51
|
+
|
|
52
|
+
- name: Generate app token
|
|
53
|
+
id: app-token
|
|
54
|
+
uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
|
|
55
|
+
with:
|
|
56
|
+
client-id: Iv23lijru2e660v1zJQO # overture-releaser app ID, not sensitive
|
|
57
|
+
private-key: ${{ env.RELEASER_APP_PEM }} # zizmor: ignore[secrets-outside-env]
|
|
58
|
+
permission-contents: write
|
|
59
|
+
|
|
60
|
+
- name: Create release
|
|
61
|
+
env:
|
|
62
|
+
GH_TOKEN: ${{ steps.app-token.outputs.token }}
|
|
63
|
+
run: |
|
|
64
|
+
version=$(uv run --only-group release semantic-release version --print)
|
|
65
|
+
tag="v${version}"
|
|
66
|
+
if git rev-parse --verify --quiet "refs/tags/${tag}" >/dev/null; then
|
|
67
|
+
echo "${tag} already exists; no releasable commits."
|
|
68
|
+
exit 0
|
|
69
|
+
fi
|
|
70
|
+
gh release create "${tag}" --repo "${GITHUB_REPOSITORY}" --target "${GITHUB_SHA}" \
|
|
71
|
+
--title "${tag}" --generate-notes
|
|
@@ -21,14 +21,14 @@ jobs:
|
|
|
21
21
|
contents: read
|
|
22
22
|
strategy:
|
|
23
23
|
matrix:
|
|
24
|
-
python-version: ["3.
|
|
24
|
+
python-version: ["3.11", "3.12", "3.13", "3.14"]
|
|
25
25
|
steps:
|
|
26
26
|
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
27
27
|
with:
|
|
28
28
|
persist-credentials: false
|
|
29
29
|
|
|
30
30
|
- name: Install uv
|
|
31
|
-
uses: astral-sh/setup-uv@
|
|
31
|
+
uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
|
|
32
32
|
with:
|
|
33
33
|
enable-cache: true
|
|
34
34
|
python-version: ${{ matrix.python-version }}
|
|
@@ -52,6 +52,6 @@ jobs:
|
|
|
52
52
|
runs-on: ubuntu-latest
|
|
53
53
|
permissions: {}
|
|
54
54
|
steps:
|
|
55
|
-
- uses: lowlydba/are-we-good@
|
|
55
|
+
- uses: lowlydba/are-we-good@6b10e5f2697555fbaf7f8f37ce38d4454c954a4c # v1.2.2
|
|
56
56
|
with:
|
|
57
57
|
jobs: ${{ toJSON(needs) }}
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
## Publishing
|
|
4
|
+
|
|
5
|
+
### Overview
|
|
6
|
+
|
|
7
|
+
The package is published to [PyPI](https://pypi.org/project/overturemaps/) via the
|
|
8
|
+
[`publish-pypi.yml`](.github/workflows/publish-pypi.yml) GitHub Actions workflow using
|
|
9
|
+
[OIDC trusted publishing](https://docs.pypi.org/trusted-publishers/), no API token should be used. This repo, workflow, and GitHub environment have been pre-configured in PyPI and Test PyPI for publishing.
|
|
10
|
+
|
|
11
|
+
### Releasing a new version
|
|
12
|
+
|
|
13
|
+
Releases run automatically on every push to `main`. Do not edit `project.version` by hand; it is a
|
|
14
|
+
`0.0.0` placeholder. The publish and binary workflows stamp the release tag's version into the
|
|
15
|
+
build without committing it. The squash-merged PR title drives the next version, so PRs must use
|
|
16
|
+
[Conventional Commits](https://www.conventionalcommits.org/):
|
|
17
|
+
|
|
18
|
+
- `fix:` and `perf:` release a patch; `feat:` releases a minor version.
|
|
19
|
+
- Add `!` or a `BREAKING CHANGE:` footer for a major version.
|
|
20
|
+
- `docs:`, `chore:`, `ci:`, `test:`, and `build:` do not trigger a release.
|
|
21
|
+
|
|
22
|
+
This repository uses squash merges so the PR title is the commit message read by the release
|
|
23
|
+
workflow. Release notes are published on the GitHub Release; no version commit or `CHANGELOG.md`
|
|
24
|
+
is written back to `main`.
|
|
25
|
+
|
|
26
|
+
Publishing a GitHub Release triggers the following:
|
|
27
|
+
|
|
28
|
+
- The publish-pypi workflow builds the package and publishes to PyPI in the
|
|
29
|
+
[`pypi` GitHub environment](https://github.com/OvertureMaps/overturemaps-py/deployments).
|
|
30
|
+
- The build-binaries workflow builds cross-OS binaries and attaches them to the release.
|
|
31
|
+
- `brew`'s BrewTestBot scans PyPI every 3 hours and updates our
|
|
32
|
+
[Homebrew formula](https://github.com/Homebrew/homebrew-core/blob/main/Formula/o/overturemaps.rb).
|
|
33
|
+
|
|
34
|
+
### Dry-run / Test PyPI
|
|
35
|
+
|
|
36
|
+
Trigger `publish-pypi.yml` manually to publish to
|
|
37
|
+
[Test PyPI](https://test.pypi.org/project/overturemaps/) instead of production PyPI. This is useful
|
|
38
|
+
for verifying the build and publish pipeline without affecting the real package index. Manual runs
|
|
39
|
+
stamp a unique `0.0.0.dev<run_id><attempt>` version. The workflow uses `skip-existing: true` for test
|
|
40
|
+
publishes so version conflicts do not fail the run. Manually trigger `build-binaries.yml` to inspect
|
|
41
|
+
binary artifacts with the same development version format without attaching them to a release.
|
|
42
|
+
|
|
43
|
+
### Environments
|
|
44
|
+
|
|
45
|
+
| GitHub environment | Target index | Trigger |
|
|
46
|
+
|--------------------|--------------|---------|
|
|
47
|
+
| `pypi` | PyPI (production) | GitHub Release published |
|
|
48
|
+
| `test-pypi` | Test PyPI | Manual `workflow_dispatch` |
|
|
49
|
+
|
|
50
|
+
Both environments are configured with OIDC trusted publisher entries on their respective package
|
|
51
|
+
indexes; no secrets or API tokens are stored in the repository.
|
|
52
|
+
|
|
53
|
+
## Testing
|
|
54
|
+
|
|
55
|
+
Tests run on pull requests and pushes to `main` via [`test-run.yml`](.github/workflows/test-run.yml).
|
|
56
|
+
|
|
57
|
+
To run tests locally:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
uv sync --dev
|
|
61
|
+
uv run pytest tests/ -v
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
A CLI smoke test is also included in CI:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
uv run overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
|
|
68
|
+
```
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: overturemaps
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: Python tools for interacting with Overture Maps (overturemaps.org) data.
|
|
5
|
+
Project-URL: Homepage, https://overturemaps.org
|
|
6
|
+
Project-URL: Source, https://github.com/OvertureMaps/overturemaps-py
|
|
7
|
+
Project-URL: Issues, https://github.com/OvertureMaps/overturemaps-py/issues
|
|
8
|
+
Author-email: Jacob Wasserman <jwasserman@meta.com>
|
|
9
|
+
Maintainer-email: Adam Lastowka <adam@overturemaps.org>, Dana Bauer <dana@overturemaps.org>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: GIS,geojson,geospatial,mapping,maps,opendata,overture,parquet,shapely
|
|
13
|
+
Requires-Python: >=3.11
|
|
14
|
+
Requires-Dist: click>=8.3.0
|
|
15
|
+
Requires-Dist: colorama>=0.4.6
|
|
16
|
+
Requires-Dist: numpy>=1.26.4
|
|
17
|
+
Requires-Dist: orjson>=3.9.0
|
|
18
|
+
Requires-Dist: pyarrow>=15.0.2
|
|
19
|
+
Requires-Dist: pyfiglet>=1.0.2
|
|
20
|
+
Requires-Dist: shapely>=2.1.0
|
|
21
|
+
Requires-Dist: tqdm>=4.67.3
|
|
22
|
+
Provides-Extra: geopandas
|
|
23
|
+
Requires-Dist: geopandas>=1.1.0; extra == 'geopandas'
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
[](https://pypi.org/project/overturemaps/)
|
|
27
|
+
[](https://anaconda.org/conda-forge/overturemaps)
|
|
28
|
+
[](https://formulae.brew.sh/formula/overturemaps)
|
|
29
|
+
[](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
|
|
30
|
+
[](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
|
|
31
|
+
|
|
32
|
+
# overturemaps-py
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<img src="docs/screenshot.png" alt="overturemaps cli screenshot" width="800">
|
|
36
|
+
</p>
|
|
37
|
+
|
|
38
|
+
Official Python command-line tool of the [Overture Maps Foundation](https://overturemaps.org).
|
|
39
|
+
|
|
40
|
+
Overture provides free and open geospatial map data, from many different sources and normalized to a
|
|
41
|
+
[common schema](https://github.com/OvertureMaps/schema). This tool helps to download Overture data
|
|
42
|
+
within a region of interest and converts it to a few different file formats. For more information about accessing
|
|
43
|
+
Overture data, see the [official documentation site](https://docs.overturemaps.org).
|
|
44
|
+
|
|
45
|
+
## Installation
|
|
46
|
+
|
|
47
|
+
Install with pip:
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install overturemaps
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Also available via:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Homebrew
|
|
57
|
+
brew install overturemaps
|
|
58
|
+
|
|
59
|
+
# conda-forge
|
|
60
|
+
conda install -c conda-forge overturemaps
|
|
61
|
+
|
|
62
|
+
# uvx
|
|
63
|
+
uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
Download building footprints for a bounding box as GeoParquet:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Commands
|
|
76
|
+
|
|
77
|
+
The CLI includes these top-level commands:
|
|
78
|
+
|
|
79
|
+
- `download`: download Overture data, optionally clipped to a bounding box.
|
|
80
|
+
- `gers`: look up a single feature by GERS ID.
|
|
81
|
+
- `releases`: inspect available Overture releases.
|
|
82
|
+
- `changelog`: query GERS feature changes across releases.
|
|
83
|
+
|
|
84
|
+
Run `overturemaps --help` for the full command tree.
|
|
85
|
+
|
|
86
|
+
## Documentation
|
|
87
|
+
|
|
88
|
+
- [CLI guide](docs/cli.md)
|
|
89
|
+
- [Python API guide](docs/python-api.md)
|
|
90
|
+
- [Performance notes](docs/performance.md)
|
|
91
|
+
- [Contributing guide](CONTRIBUTING.md)
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
[](https://pypi.org/project/overturemaps/)
|
|
2
|
+
[](https://anaconda.org/conda-forge/overturemaps)
|
|
3
|
+
[](https://formulae.brew.sh/formula/overturemaps)
|
|
4
|
+
[](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
|
|
5
|
+
[](https://github.com/OvertureMaps/overturemaps-py/releases/latest)
|
|
6
|
+
|
|
7
|
+
# overturemaps-py
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<img src="docs/screenshot.png" alt="overturemaps cli screenshot" width="800">
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
Official Python command-line tool of the [Overture Maps Foundation](https://overturemaps.org).
|
|
14
|
+
|
|
15
|
+
Overture provides free and open geospatial map data, from many different sources and normalized to a
|
|
16
|
+
[common schema](https://github.com/OvertureMaps/schema). This tool helps to download Overture data
|
|
17
|
+
within a region of interest and converts it to a few different file formats. For more information about accessing
|
|
18
|
+
Overture data, see the [official documentation site](https://docs.overturemaps.org).
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
Install with pip:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install overturemaps
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Also available via:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Homebrew
|
|
32
|
+
brew install overturemaps
|
|
33
|
+
|
|
34
|
+
# conda-forge
|
|
35
|
+
conda install -c conda-forge overturemaps
|
|
36
|
+
|
|
37
|
+
# uvx
|
|
38
|
+
uvx overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
## Quick Start
|
|
43
|
+
|
|
44
|
+
Download building footprints for a bounding box as GeoParquet:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geoparquet --type=building -o boston.parquet
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Commands
|
|
51
|
+
|
|
52
|
+
The CLI includes these top-level commands:
|
|
53
|
+
|
|
54
|
+
- `download`: download Overture data, optionally clipped to a bounding box.
|
|
55
|
+
- `gers`: look up a single feature by GERS ID.
|
|
56
|
+
- `releases`: inspect available Overture releases.
|
|
57
|
+
- `changelog`: query GERS feature changes across releases.
|
|
58
|
+
|
|
59
|
+
Run `overturemaps --help` for the full command tree.
|
|
60
|
+
|
|
61
|
+
## Documentation
|
|
62
|
+
|
|
63
|
+
- [CLI guide](docs/cli.md)
|
|
64
|
+
- [Python API guide](docs/python-api.md)
|
|
65
|
+
- [Performance notes](docs/performance.md)
|
|
66
|
+
- [Contributing guide](CONTRIBUTING.md)
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# overturemaps-py — Project Specification
|
|
2
2
|
|
|
3
3
|
**Version**: 0.21.0
|
|
4
|
-
**Python**: ≥ 3.
|
|
4
|
+
**Python**: ≥ 3.11
|
|
5
5
|
**License**: MIT
|
|
6
6
|
**Maintainers**: Adam Lastowka, Dana Bauer (@overturemaps.org)
|
|
7
7
|
|
|
@@ -103,7 +103,7 @@ Serialization: `as_tuple()`, `as_dict()`, `from_dict()`.
|
|
|
103
103
|
|
|
104
104
|
Values: `geojson`, `geojsonseq`, `geoparquet`.
|
|
105
105
|
|
|
106
|
-
|
|
106
|
+
Uses `enum.StrEnum` (Python ≥ 3.11).
|
|
107
107
|
|
|
108
108
|
### 3.4 `PipelineState` Dataclass
|
|
109
109
|
|
|
@@ -404,8 +404,8 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
|
|
|
404
404
|
|
|
405
405
|
### 10.4 Compatibility
|
|
406
406
|
|
|
407
|
-
- **Python**: 3.
|
|
408
|
-
- **StrEnum
|
|
407
|
+
- **Python**: 3.11, 3.12, 3.13, 3.14 (tested in CI matrix).
|
|
408
|
+
- **StrEnum**: use stdlib `enum.StrEnum`.
|
|
409
409
|
- **geopandas**: Optional extra. Library must import and function without it. `HAS_GEOPANDAS` flag gates all geopandas usage. Stub `GeoDataFrame` class prevents `NameError` at import time.
|
|
410
410
|
|
|
411
411
|
### 10.5 Observability
|
|
@@ -490,7 +490,7 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
|
|
|
490
490
|
### 13.1 Test workflow
|
|
491
491
|
|
|
492
492
|
- Triggers: push to `main`, PR to `main`.
|
|
493
|
-
- Matrix: Python 3.
|
|
493
|
+
- Matrix: Python 3.11, 3.12, 3.13, 3.14.
|
|
494
494
|
- Steps: checkout → setup-uv (with cache) → `uv sync --dev` → `pytest tests/ -v` → CLI smoke test.
|
|
495
495
|
- Smoke test: Boston buildings download to file, format `geojson`.
|
|
496
496
|
- Rollup job `are-we-good` must always run; blocks merge on any matrix failure.
|
|
@@ -532,7 +532,7 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
|
|
|
532
532
|
- **Type annotations**: all public API functions should have full type annotations. Internal helpers may be unannotated where obvious.
|
|
533
533
|
- **Docstrings**: not required by convention. Add only where behavior is non-obvious (e.g. STAC fallback design, binary search invariants).
|
|
534
534
|
- **No mutable default arguments**.
|
|
535
|
-
- **StrEnum
|
|
535
|
+
- **StrEnum** string behavior (`str()`, lowercase auto values) must be tested.
|
|
536
536
|
|
|
537
537
|
### 14.2 Error handling principles
|
|
538
538
|
|
|
@@ -559,13 +559,14 @@ State file path = `{output_path}.state` (e.g. `boston.geojson.state`).
|
|
|
559
559
|
|
|
560
560
|
- **Build backend**: `hatchling`
|
|
561
561
|
- **Package manager / task runner**: `uv` + `just`
|
|
562
|
-
- **Version source**: `
|
|
563
|
-
- **Release cadence**:
|
|
562
|
+
- **Version source**: Release tag stamped into `project.version` at build time; committed version is a `0.0.0` placeholder
|
|
563
|
+
- **Release cadence**: Automatic on pushes to `main` when Conventional Commit titles require a bump
|
|
564
564
|
- **PyPI package name**: `overturemaps`
|
|
565
565
|
- **Standalone binaries**: Built via PyInstaller on release; attached to GitHub Release as assets for linux-x86_64, macos-arm64, macos-x86_64, windows-x86_64. Local build: `just build-binary`.
|
|
566
566
|
- **`python -m overturemaps`**: Supported via `overturemaps/__main__.py`; same entry point used by PyInstaller.
|
|
567
567
|
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
568
|
+
Squash-merged PR titles use Conventional Commits to choose the next version. The release workflow
|
|
569
|
+
creates a GitHub Release with generated notes. Publishing that release triggers the PyPI and binary
|
|
570
|
+
workflows; Homebrew updates from PyPI. Manual builds use a unique `0.0.0.dev<run_id><attempt>`
|
|
571
|
+
version. The publishing workflow checks both distribution metadata and version consistency before
|
|
572
|
+
uploading artifacts.
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# CLI guide
|
|
2
|
+
|
|
3
|
+
`overturemaps` downloads Overture data directly from Overture's S3 bucket and exposes a small set of commands for common data access tasks.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
- `download`: download Overture data, optionally clipped to a bounding box.
|
|
8
|
+
- `gers`: look up a single feature by GERS ID.
|
|
9
|
+
- `releases`: inspect available Overture releases.
|
|
10
|
+
- `changelog`: query GERS feature changes across releases.
|
|
11
|
+
|
|
12
|
+
Run `overturemaps --help` for the top-level command tree.
|
|
13
|
+
|
|
14
|
+
## download
|
|
15
|
+
|
|
16
|
+
`download` streams Overture data in the requested output format. When you provide a bounding box, the Parquet readers use summary statistics to minimize transferred data.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
overturemaps download --bbox=-71.068,42.353,-71.058,42.363 -f geojson --type=building -o boston.geojson
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Options:
|
|
23
|
+
|
|
24
|
+
- `--bbox`: west, south, east, north longitude and latitude coordinates. When omitted, the entire dataset for the specified type is downloaded.
|
|
25
|
+
- `-f`: required output format. Supported values are `geojson`, `geojsonseq`, and `geoparquet`.
|
|
26
|
+
- `--output` or `-o`: output file path. When omitted, output is written to stdout.
|
|
27
|
+
- `--type` or `-t`: required Overture data type such as `building` or `place`.
|
|
28
|
+
- `--connect_timeout`: socket connection timeout in seconds.
|
|
29
|
+
- `--request_timeout`: socket read timeout in seconds on Windows and macOS.
|
|
30
|
+
- `--stac` or `--no-stac`: choose whether to resolve the latest release through the [STAC catalog](https://stac.overturemaps.org/).
|
|
31
|
+
|
|
32
|
+
To find a bounding box, [boundingbox.klokantech.com](https://boundingbox.klokantech.com/) can export coordinates in the format the CLI expects.
|
|
33
|
+
|
|
34
|
+
## gers
|
|
35
|
+
|
|
36
|
+
`gers` looks up a feature in the GERS Registry and, when present in the latest release, writes it in the requested format.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
overturemaps gers 08f28d1c-bf17-4c5c-bc1b-0f1f7b0d4abc -f geojsonseq
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Options:
|
|
43
|
+
|
|
44
|
+
- `-f`: output format. Defaults to `geojsonseq`.
|
|
45
|
+
- `--output` or `-o`: output file path. When omitted, output is written to stdout.
|
|
46
|
+
- `--connect_timeout`: socket connection timeout in seconds.
|
|
47
|
+
- `--request_timeout`: socket read timeout in seconds on Windows and macOS.
|
|
48
|
+
|
|
49
|
+
## releases
|
|
50
|
+
|
|
51
|
+
`releases` inspects published Overture releases.
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
overturemaps releases list
|
|
55
|
+
overturemaps releases latest
|
|
56
|
+
overturemaps releases exists 2025-09-24.0
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Run `overturemaps releases --help` for the full subcommand set.
|
|
60
|
+
|
|
61
|
+
## changelog
|
|
62
|
+
|
|
63
|
+
`changelog` queries GERS feature changes across releases.
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
overturemaps changelog summary --theme=buildings
|
|
67
|
+
overturemaps changelog query --theme=places --bbox=-71.068,42.353,-71.058,42.363
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Run `overturemaps changelog --help` for the full subcommand set.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Performance notes
|
|
2
|
+
|
|
3
|
+
Benchmarks use synthetic data on Apple M-series hardware.
|
|
4
|
+
|
|
5
|
+
| Output format | Geometry | Rows | Time |
|
|
6
|
+
| ------------- | -------- | ------ | ------------------ |
|
|
7
|
+
| GeoJSON | Points | 10 000 | 31 ms |
|
|
8
|
+
| GeoJSON | Polygons | 10 000 | 44 ms |
|
|
9
|
+
| GeoParquet | n/a | n/a | network/disk bound |
|
|
10
|
+
|
|
11
|
+
Run the benchmarks locally with:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
uv sync --group dev
|
|
15
|
+
pytest benchmarks/ -v
|
|
16
|
+
```
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Python API guide
|
|
2
|
+
|
|
3
|
+
`overturemaps` is also a Python library. Import directly from `overturemaps` to query Overture data without using the CLI.
|
|
4
|
+
|
|
5
|
+
## record_batch_reader
|
|
6
|
+
|
|
7
|
+
`record_batch_reader` returns a `pyarrow.RecordBatchReader`. This is the lowest-level entry point and works with Arrow-compatible tooling.
|
|
8
|
+
|
|
9
|
+
```python
|
|
10
|
+
from overturemaps import record_batch_reader
|
|
11
|
+
|
|
12
|
+
bbox = (-71.068, 42.353, -71.058, 42.363)
|
|
13
|
+
reader = record_batch_reader("building", bbox=bbox)
|
|
14
|
+
|
|
15
|
+
if reader is not None:
|
|
16
|
+
table = reader.read_all()
|
|
17
|
+
print(table.schema)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## geodataframe
|
|
21
|
+
|
|
22
|
+
`geodataframe` loads data into a `geopandas.GeoDataFrame`.
|
|
23
|
+
|
|
24
|
+
Install optional dependencies with either `pip install overturemaps[geopandas]` or `pip install geopandas`.
|
|
25
|
+
|
|
26
|
+
```python
|
|
27
|
+
from overturemaps import geodataframe
|
|
28
|
+
|
|
29
|
+
bbox = (-71.068, 42.353, -71.058, 42.363)
|
|
30
|
+
gdf = geodataframe("building", bbox=bbox)
|
|
31
|
+
print(gdf.head())
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Writing formats
|
|
35
|
+
|
|
36
|
+
Use `get_writer` and `copy` from `overturemaps.writers` to write data to GeoJSON, GeoJSONSeq, or GeoParquet without using the CLI.
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from overturemaps import record_batch_reader
|
|
40
|
+
from overturemaps.writers import copy, get_writer
|
|
41
|
+
|
|
42
|
+
bbox = (-71.068, 42.353, -71.058, 42.363)
|
|
43
|
+
reader = record_batch_reader("building", bbox=bbox)
|
|
44
|
+
|
|
45
|
+
with get_writer("geojson", "boston.geojson", schema=reader.schema) as writer:
|
|
46
|
+
copy(reader, writer)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Supported format strings: `geojson`, `geojsonseq`, `geoparquet`.
|
|
Binary file
|