diff --git a/.flake8 b/.flake8 deleted file mode 100644 index f77f556..0000000 --- a/.flake8 +++ /dev/null @@ -1,20 +0,0 @@ -# https://lintlyci.github.io/Flake8Rules/ -[flake8] -max-line-length = 88 -include = - #W292 No newline at end of file - W292, -ignore = - # E251 unexpected spaces around keyword / parameter equals - E251, - # sometimes I just want to line up decimal points... - # E201 whitespace after '[' - E201, - # E241 multiple spaces after ',' - E241, - # E731 do not assign a lambda expression, use a def - E731, - # https://stackoverflow.com/questions/67942075/w504-line-break-after-binary-operator - W503,W504, - # E272 multiple spaces before keyword - E272 diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml index 328dc44..9cc00a2 100644 --- a/.github/workflows/build_docs.yml +++ b/.github/workflows/build_docs.yml @@ -6,29 +6,29 @@ on: pull_request: branches: ['*'] +permissions: + contents: write + jobs: build-docs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: astral-sh/setup-uv@v7 with: - python-version: 3.11 + python-version: '3.11' - - name: Install dependencies - run: | - pip install --upgrade pip setuptools wheel - pip install .[all] + - uses: extractions/setup-just@v2 - name: Build the book - run: jupyter-book build docs/ --warningiserror --keep-going --all + run: just docs - name: Upload artifacts - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v6.0.0 with: name: html path: docs/_build/html diff --git a/.github/workflows/coverage-lint.yml b/.github/workflows/coverage-lint.yml deleted file mode 100644 index 0802169..0000000 --- a/.github/workflows/coverage-lint.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: coverage-lint - -on: - push: - branches: [master] - pull_request: - branches: ['*'] - -jobs: - tests: - name: Coverage and Lint - runs-on: ubuntu-22.04 - - steps: - - uses: actions/checkout@v4.1.1 - with: - submodules: recursive - - - uses: actions/setup-python@v5.0.0 - with: - python-version: 3.11 - - - name: Install from source - run: | - pip install --upgrade pip setuptools wheel - pip install .[test] - - - name: Lint - run: flake8 src/h3 tests - - - name: Pylint - # As a test for visibility of API bindings, we want to ensure that pylint has no - # `import-error` warnings for h3 imports. - run: pylint --disable=all --enable=import-error tests/ - - - name: Coverage - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest --cov-report=xml - - - name: Upload coverage to Codecov - uses: codecov/codecov-action@v4.3.0 - with: - file: ./coverage.xml - fail_ci_if_error: true - token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml new file mode 100644 index 0000000..8ec1ef1 --- /dev/null +++ b/.github/workflows/lint_and_coverage.yml @@ -0,0 +1,38 @@ +name: lint_and_coverage + +on: + push: + branches: [master] + pull_request: + branches: ['*'] + +permissions: + contents: read + +jobs: + linting: + name: Lint and Coverage + runs-on: ubuntu-24.04 + + steps: + - uses: actions/checkout@v6.0.2 + with: + submodules: recursive + + - uses: astral-sh/setup-uv@v7 + with: + python-version: '3.11' + + - uses: extractions/setup-just@v2 + + - name: Lint + run: just lint + + - name: Install + run: uv sync + + - name: Coverage - Library + run: just ci-test + + - name: Coverage - Cython + run: just ci-test-cython diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8075b01..f7a9854 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -14,17 +14,19 @@ jobs: strategy: matrix: os: [macos-latest, windows-latest, ubuntu-22.04] - python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] + python-version: ['3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15', '3.15t'] steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: actions/setup-python@v5.0.0 + - uses: astral-sh/setup-uv@v7 with: python-version: '${{ matrix.python-version }}' + - uses: extractions/setup-just@v2 + ## Start Windows stuff - uses: ilammy/msvc-dev-cmd@v1.13.0 if: startsWith(matrix.os, 'windows') @@ -36,13 +38,11 @@ jobs: echo "CXX=cl.exe" >> $GITHUB_ENV ## End Windows stuff - - name: Install from source - run: | - pip install --upgrade pip setuptools wheel - pip install .[test] + - name: Install + run: uv sync - name: Tests - run: | - pip install cython - cythonize tests/test_cython/cython_example.pyx - pytest + run: just ci-test + + - name: Cython Tests + run: just ci-test-cython diff --git a/.github/workflows/wheels.yml b/.github/workflows/wheels.yml index 659a193..1de5a80 100644 --- a/.github/workflows/wheels.yml +++ b/.github/workflows/wheels.yml @@ -23,32 +23,32 @@ jobs: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - name: Setup Python - uses: actions/setup-python@v5.0.0 + - uses: astral-sh/setup-uv@v7 with: - python-version: 3.11 + python-version: '3.11' + - name: Make sdist - run: | - python --version - pipx --version - pipx run build --sdist + run: uv build --sdist + # Test the sdist, NOT the local checkout. + # Use a fresh venv + uv pip install (not uv sync, which would build from source). - name: Install from sdist run: | - pip install --upgrade pip setuptools wheel + uv venv cp dist/h3-*.tar.gz h3.tar.gz - pip install h3.tar.gz[test] + uv pip install h3.tar.gz[numpy] pytest pytest-cov - name: Test sdist - run: pytest + # run pytest directly from the venv to avoid `uv run` syncing from the local checkout + run: .venv/bin/pytest - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v6.0.0 with: name: temp_result_sdist path: ./dist @@ -60,27 +60,40 @@ jobs: strategy: matrix: include: - - os: macos-13 - build: 'cp*-macosx_x86_64' - name: macOS13 - - os: macos-14 + - os: macos-15 build: 'cp*-macosx_arm64' - name: macOS14 + name: macOS15 - os: windows-latest build: 'cp3*-win_amd64' name: Windows 64-bit + - os: windows-11-arm + build: 'cp311-win_arm64' + name: Windows ARM64 3.11 + - os: windows-11-arm + build: 'cp312-win_arm64' + name: Windows ARM64 3.12 + - os: windows-11-arm + build: 'cp313-win_arm64' + name: Windows ARM64 3.13 + - os: windows-11-arm + build: 'cp314-win_arm64' + name: Windows ARM64 3.14 + - os: windows-11-arm + build: 'cp314t-win_arm64' + name: Windows ARM64 3.14t + - os: windows-11-arm + build: 'cp315-win_arm64' + name: Windows ARM64 3.15 + - os: windows-11-arm + build: 'cp315t-win_arm64' + name: Windows ARM64 3.15t + - os: ubuntu-22.04 build: 'cp*-manylinux_x86_64' name: Linux Intel glibc 64-bit - - os: ubuntu-22.04 - build: 'cp38-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.8 - - os: ubuntu-22.04 - build: 'cp39-musllinux_x86_64' - name: Linux Intel musl 64-bit 3.9 - os: ubuntu-22.04 build: 'cp310-musllinux_x86_64' name: Linux Intel musl 64-bit 3.10 @@ -90,13 +103,22 @@ jobs: - os: ubuntu-22.04 build: 'cp312-musllinux_x86_64' name: Linux Intel musl 64-bit 3.12 + - os: ubuntu-22.04 + build: 'cp313-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.13 + - os: ubuntu-22.04 + build: 'cp314-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.14 + - os: ubuntu-22.04 + build: 'cp314t-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.14t + - os: ubuntu-22.04 + build: 'cp315-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.15 + - os: ubuntu-22.04 + build: 'cp315t-musllinux_x86_64' + name: Linux Intel musl 64-bit 3.15t - - os: ubuntu-22.04 - build: 'cp38-manylinux_aarch64' - name: Linux Aarch64 3.8 - - os: ubuntu-22.04 - build: 'cp39-manylinux_aarch64' - name: Linux Aarch64 3.9 - os: ubuntu-22.04 build: 'cp310-manylinux_aarch64' name: Linux Aarch64 3.10 @@ -106,14 +128,40 @@ jobs: - os: ubuntu-22.04 build: 'cp312-manylinux_aarch64' name: Linux Aarch64 3.12 + - os: ubuntu-22.04 + build: 'cp313-manylinux_aarch64' + name: Linux Aarch64 3.13 + - os: ubuntu-22.04 + build: 'cp314-manylinux_aarch64' + name: Linux Aarch64 3.14 + - os: ubuntu-22.04 + build: 'cp314t-manylinux_aarch64' + name: Linux Aarch64 3.14t + - os: ubuntu-22.04 + build: 'cp315-manylinux_aarch64' + name: Linux Aarch64 3.15 + - os: ubuntu-22.04 + build: 'cp315t-manylinux_aarch64' + name: Linux Aarch64 3.15t steps: - - uses: actions/checkout@v4.1.1 + - uses: actions/checkout@v6.0.2 with: submodules: recursive - - uses: ilammy/msvc-dev-cmd@v1.13.0 - if: runner.os == 'Windows' + - uses: astral-sh/setup-uv@v7 + + - name: Set MSVC for Windows-x64 + uses: microsoft/setup-msbuild@v2 + if: matrix.os == 'windows-latest' + with: + msbuild-architecture: x64 + + - name: Set MSVC for Windows-ARM64 + uses: microsoft/setup-msbuild@v2 + if: matrix.os == 'windows-11-arm' + with: + msbuild-architecture: arm64 - name: Set Windows variables if: runner.os == 'Windows' @@ -124,23 +172,23 @@ jobs: - name: Set up QEMU if: runner.os == 'Linux' - uses: docker/setup-qemu-action@v3.0.0 + uses: docker/setup-qemu-action@v3.7.0 with: platforms: aarch64 - - uses: pypa/cibuildwheel@v2.17.0 + - uses: pypa/cibuildwheel@v4.2.1 env: + CIBW_BUILD_FRONTEND: 'build[uv]' CIBW_TEST_REQUIRES: pytest pytest-cov numpy CIBW_TEST_COMMAND: pytest {project}/tests CIBW_ARCHS_LINUX: auto aarch64 CIBW_BUILD: ${{ matrix.build }} - name: Check with Twine - run: | - pipx run twine check wheelhouse/* + run: uvx twine check wheelhouse/* - name: Upload artifacts to GitHub - uses: actions/upload-artifact@v4.3.1 + uses: actions/upload-artifact@v6.0.0 with: name: temp_result_${{ matrix.os }}-${{ strategy.job-index }} path: wheelhouse/*.whl @@ -150,7 +198,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Merge Artifacts - uses: actions/upload-artifact/merge@v4 + uses: actions/upload-artifact/merge@v6 with: name: wheels_and_sdist pattern: temp_result_* @@ -158,17 +206,35 @@ jobs: retention-days: 7 compression-level: 9 - to_pypi: + check_merged: needs: [merge] - if: github.event_name == 'release' && github.event.action == 'published' runs-on: ubuntu-latest - steps: - - uses: actions/download-artifact@v4.1.7 + - uses: astral-sh/setup-uv@v7 + with: + enable-cache: false + ignore-empty-workdir: true + + - name: Download merged artifacts + uses: actions/download-artifact@v7.0.0 with: name: wheels_and_sdist path: dist - - uses: pypa/gh-action-pypi-publish@v1.8.14 + - name: Check all wheels and sdist with Twine + run: uvx twine check dist/* + + to_pypi: + needs: [check_merged] + if: github.event_name == 'release' && github.event.action == 'published' + runs-on: ubuntu-latest + + steps: + - uses: actions/download-artifact@v7.0.0 + with: + name: wheels_and_sdist + path: dist + + - uses: pypa/gh-action-pypi-publish@v1.13.0 with: password: ${{ secrets.pypi_password }} diff --git a/.gitignore b/.gitignore index 8b6903b..1141de9 100644 --- a/.gitignore +++ b/.gitignore @@ -1,72 +1,57 @@ -h3c/ +# Byte-compiled / optimized *.py[cod] -.cache/ -h3/out/ +__pycache__/ + +# C extensions +*.so # Generated C code from Cython test tests/**/*.c # Cython HTML annotations *.html -# C extensions -*.so - -# Packages -*.egg +# Build artifacts +build/ +dist/ *.egg-info -dist -build -eggs -parts -bin -var -sdist -develop-eggs -.installed.cfg -# Installer logs -pip-log.txt - -# Unit test / coverage reports +# Coverage .coverage coverage.xml -.tox -nosetests.xml -.noseids -.pytest_cache - -# Mr Developer -.mr.developer.cfg -.project -.pydevproject - -*.csv -build/ -env/ -env_docs/ -docs/_build/ +coverage.lcov htmlcov/ -# vim/emacs backup files +# Test +.pytest_cache/ + +# Tools +.ruff_cache/ +.cache/ + +# Docs +_build/ +docs/_build/ + +# Environment +.venv/ +uv.lock + +# OS +.DS_Store + +# Editor backup files *~ \#*\# .\#* .*.sw* -#DB snapshots -db_snapshots/ - -#OSX -.DS_Store - -node_modules/ -bower_components/ -.sass-cache/ +# IDE .idea/ -.unison.* +# IPython / Jupyter .ipynb_checkpoints/ -_skbuild/ -# might want to remove this later when distributing -MANIFEST +# Legacy build dirs +_skbuild/ +h3c/ +h3/out/ diff --git a/CHANGELOG.md b/CHANGELOG.md index ee38256..0b6ee3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,8 +15,101 @@ avoid adding features or APIs which do not map onto the [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/). ## Unreleased +- Fix wheels for Python 3.14.6 free-threading +- Add Python 3.14t, 3.15 and 3.15t wheels +- Support `unit='rads'` in `average_hexagon_area` and `average_hexagon_edge_length` (#509) +- Add `container` option to `h3shape_to_geo` (#495) +- Fix Android cross-compilation with Buildozer (#494) +- Raise `ValueError` instead of `assert` in `geo_to_h3shape` (#500, #502) +- Fix `LatLngPoly` loop length check for closed rings (#505) +- Return `False` from `is_valid_*` for out-of-range integers (#507) +- Handle empty GeoJSON Polygon in `geo_to_h3shape` (#511) +- Fix duplicate cells from `h3shape_to_cells_experimental` for `LatLngMultiPoly` (#512) -None. +## [4.5.0] - 2026-05-29 + +- Final v4.5 release includes all v4.5.x changes below + +## [4.5.0a3] - 2026-05-22 + +- Update `h3lib` to v4.5.0 release (#491) + +## [4.5.0a2] - 2026-02-27 + +- `cells_to_h3shape`/`cells_to_geo` now handle all valid cell sets, including + sets that would produce global polygons crossing the antimeridian, poles, or are larger than a hemisphere + - Duplicate cells now raise `H3DuplicateInputError` + - Mixed-resolution cells now raise `H3ResMismatchError` + - Internal: switch from linked-list to array-based C API for cells-to-polygon conversion + +## [4.5.0a1] - 2026-02-25 + +- Update `h3lib` with draft v4.5 changes +- Drop Python 3.8 and 3.9 (EOL); minimum is now Python 3.10 +- Document Python 3.14 support +- Migrate build tooling from Makefile/pip to justfile/uv, including CI + +## [4.4.2] - 2026-01-29 + +- Check for error from `cellsToLinkedMultiPolygon` (#477) + +## [4.4.1] - 2025-12-15 + +- Fix PyPI publishing issue (#474) + +## [4.4.0] - 2025-12-12 (never published on PyPI) + +- Update `h3lib` to v4.4.1. (#470) + - Add new error codes: + - `H3IndexInvalidError` + - `H3BaseCellDomainError` + - `H3DigitDomainError` + - `H3DeletedDigitError` + - Add new functions: + - `is_valid_index` + - `get_index_digit` + - `construct_cell` + - `deconstruct_cell` + +## [4.3.1] - 2025-08-10 + +- Build wheels for Windows on ARM64 (#463) + +## [4.3.0] - 2025-06-17 + +- Update `h3lib` to v4.3.0. (#461) + - Uses `gridRing` (uber/h3#1016) instead of Cython fallback logic. + +## [4.2.2] - 2025-03-10 + +- Update h3lib to v4.2.1. (#450) + +## [4.2.1] - 2025-01-31 + +- Correct pyproject.toml links for PyPI (#441) +- Update coverage badge (#443) + +## [4.2.0] - 2025-01-26 + +- Update h3lib to v4.2.0. (#432) +- Add `h3shape_to_cells_experimental` (#436) + - Add `polygon_to_cells_experimental` alias + +## [4.1.2] - 2024-10-26 + +- Build Python 3.13 wheels (#425) + +## [4.1.1] - 2024-10-13 + +- Make sure docs and PyPI page are up-to-date. + +## [4.1.0] - 2024-10-13 + +- Final v4.1 release inculdes all v4.x changes below. + +## [4.1.0b3] - 2024-10-05 + +- Allow for `str` subtypes, like `numpy.str_` (#408) ## [4.1.0b2] - 2024-09-27 @@ -73,7 +166,7 @@ Beta release; feedback welcome! - Website and API documentation; along with docstring cleanup. - Add support for linters and IDE tooling (#213) - Remove Py 3.5 wheel for Windows (#214) -- Py 3.10 wheels and on more architectures (#220, #221, #223, #225) +- Py 3.10 wheels and on more architectures (#220, #221, #223, #225) - Greatly reduce sdist size (#227, #229) ## [3.7.3] - 2021-06-12 diff --git a/CMakeLists.txt b/CMakeLists.txt index 40ce38e..52a76f1 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,5 +1,16 @@ cmake_minimum_required(VERSION 3.15...3.26) +# --- BEGIN ANDROID CROSS-COMPILATION FIX --- +# Buildozer/python-for-android uses standard pip install which doesn't natively +# pass a CMake toolchain file to scikit-build-core. This detects the Android compiler +# from the environment and forces CMake into cross-compilation mode to prevent +# it from building host (x86_64) binaries. +if("$ENV{CC}" MATCHES "android" AND NOT DEFINED CMAKE_SYSTEM_NAME) + message(STATUS "Detected Android cross-compilation via environment variables. Setting CMAKE_SYSTEM_NAME=Android") + set(CMAKE_SYSTEM_NAME Android) +endif() +# --- END ANDROID CROSS-COMPILATION FIX --- + project(${SKBUILD_PROJECT_NAME} LANGUAGES C) set(CMAKE_POSITION_INDEPENDENT_CODE ON) diff --git a/dev_notes.md b/dev_notes.md index 71d514d..65b4f62 100644 --- a/dev_notes.md +++ b/dev_notes.md @@ -2,11 +2,21 @@ ## Install for development -- `git clone git@github.com:uber/h3-py.git` +This repo uses [`just`](https://github.com/casey/just) for running common development commands. + +To get started: + +- `git clone --recurse-submodules git@github.com:uber/h3-py.git` + - or fork the repository and `git clone --recurse-submodules https://github.com/{username}/h3-py.git` - `cd h3-py` -- `make init` -- `make test` -- `make lint` +- `just lint` +- `just test` +- `just test-cython` + +To build and view docs: + +- `just docs` +- `just view` ## Docstrings @@ -49,6 +59,7 @@ git submodule update --init - update `CHANGELOG.md` to reflect any changes since the last release - update the `h3-py` version in `pyproject.toml` +- if updating the C `h3lib` version, update the version badge on the readme - create PR, get reviews, and merge with these changes - go to https://github.com/uber/h3-py/releases and "Draft a new release" - set the tag version and the release to the version. e.g., `v3.7.2` diff --git a/docs/api_quick.md b/docs/api_quick.md index 5503bae..6694ed4 100644 --- a/docs/api_quick.md +++ b/docs/api_quick.md @@ -25,6 +25,7 @@ and should be generally aligned with the is_res_class_III is_valid_directed_edge is_valid_vertex + is_valid_index ``` ## Index representation @@ -49,6 +50,9 @@ and should be generally aligned with the get_num_cells get_resolution get_base_cell_number + get_index_digit + construct_cell + deconstruct_cell ``` ## Geographic coordinates @@ -161,6 +165,17 @@ Note that this is reversed from [``__geo_interface__``](https://gist.github.com/ cells_to_geo ``` +#### Additional functions + +```{eval-rst} +.. currentmodule:: h3 + +.. autosummary:: + polygon_to_cells + polygon_to_cells_experimental + h3shape_to_cells_experimental +``` + ## Specialized functions diff --git a/docs/polygon_tutorial.ipynb b/docs/polygon_tutorial.ipynb index 7e0a1e9..e8df06a 100644 --- a/docs/polygon_tutorial.ipynb +++ b/docs/polygon_tutorial.ipynb @@ -41,32 +41,36 @@ "import contextily as cx\n", "import matplotlib.pyplot as plt\n", "\n", + "\n", "def plot_df(df, column=None, ax=None):\n", - " 'Plot based on the `geometry` column of a GeoPandas dataframe'\n", + " \"Plot based on the `geometry` column of a GeoPandas dataframe\"\n", " df = df.copy()\n", - " df = df.to_crs(epsg=3857) # web mercator\n", + " df = df.to_crs(epsg=3857) # web mercator\n", "\n", " if ax is None:\n", - " fig, ax = plt.subplots(figsize=(8,8))\n", + " _, ax = plt.subplots(figsize=(8,8))\n", " ax.get_xaxis().set_visible(False)\n", " ax.get_yaxis().set_visible(False)\n", - " \n", + "\n", " df.plot(\n", " ax=ax,\n", " alpha=0.5, edgecolor='k',\n", " column=column, categorical=True,\n", - " legend=True, legend_kwds={'loc': 'upper left'}, \n", + " legend=True, legend_kwds={'loc': 'upper left'},\n", " )\n", " cx.add_basemap(ax, crs=df.crs, source=cx.providers.CartoDB.Positron)\n", "\n", + "\n", "def plot_shape(shape, ax=None):\n", " df = geopandas.GeoDataFrame({'geometry': [shape]}, crs='EPSG:4326')\n", " plot_df(df, ax=ax)\n", "\n", + "\n", "def plot_cells(cells, ax=None):\n", " shape = h3.cells_to_h3shape(cells)\n", " plot_shape(shape, ax=ax)\n", "\n", + "\n", "def plot_shape_and_cells(shape, res=9):\n", " fig, axs = plt.subplots(1,2, figsize=(10,5), sharex=True, sharey=True)\n", " plot_shape(shape, ax=axs[0])\n", @@ -263,6 +267,7 @@ " def __geo_interface__(self):\n", " return self.d\n", "\n", + "\n", "geo = MockGeo(d)\n", "h3.geo_to_h3shape(geo)" ] @@ -902,14 +907,6 @@ "source": [ "plot_df(df, column='BoroName')" ] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "cd012d79-a653-4d5d-bb30-408031301015", - "metadata": {}, - "outputs": [], - "source": [] } ], "metadata": { @@ -928,7 +925,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.2" + "version": "3.11.8" } }, "nbformat": 4, diff --git a/justfile b/justfile new file mode 100644 index 0000000..d8e44fb --- /dev/null +++ b/justfile @@ -0,0 +1,61 @@ +# disable editable installs so uv sync does a full build of the C extension +export UV_NO_EDITABLE := "1" + +_: + just --list + +# force-rebuild the C extension to avoid stale builds +reinstall: + uv cache clean h3 + uv sync --reinstall-package h3 + +# locally, always reinstall before testing +test: reinstall ci-test +test-cython: reinstall ci-test-cython + +fix: + uvx ruff check --fix + +lab: + uv sync --group docs + uv run jupyter lab + +view: + open docs/_build/html/index.html + +purge: + just _rm .venv + just _rm '*.pytest_cache' + just _rm .DS_Store + just _rm '*.egg-info' + just _rm dist + just _rm '*.ipynb_checkpoints' + just _rm __pycache__ + just _rm uv.lock + just _rm .coverage + just _rm build + just _rm _build + just _rm _skbuild + just _rm .ruff_cache + uv cache clean h3 + +_rm pattern: + -@find . -name "{{pattern}}" -prune -exec rm -rf {} + + + +# Recipes below are used by CI workflows (.github/workflows/). +# Changes here may break CI — update the workflows accordingly. + +ci-test: + uv run pytest tests/test_lib --cov=h3 --cov=tests/test_lib --cov-fail-under=100 + +ci-test-cython: + uv run --with cython --with setuptools cythonize tests/test_cython/cython_example.pyx + uv run pytest tests/test_cython --cov=tests/test_cython + +lint: + uvx ruff check + +docs: + uv sync --group docs + uv run jupyter-book build docs/ --warningiserror --keep-going --all diff --git a/makefile b/makefile deleted file mode 100644 index a838caa..0000000 --- a/makefile +++ /dev/null @@ -1,48 +0,0 @@ -.PHONY: init clear rebuild purge test lint lab ipython - -PYTHON=$(shell command -v python || command -v python3) - - -build-docs: - ./env/bin/pip install .[all] - ./env/bin/jupyter-book build docs/ --warningiserror --keep-going --all - -open: - open docs/_build/html/index.html - -init: purge - git submodule update --init - $(PYTHON) -m venv env - ./env/bin/pip install --upgrade pip wheel setuptools - ./env/bin/pip install .[test] - -clear: - -./env/bin/pip uninstall -y h3 - -@rm -rf MANIFEST - -@rm -rf .pytest_cache _skbuild dist .coverage build docs/_build .ruff_cache - -@find . -type d -name '__pycache__' | xargs rm -r - -@find . -type d -name '*.egg-info' | xargs rm -r - -@find . -type f -name '*.pyc' | xargs rm -r - -@find . -type f -name '*.so' | xargs rm -r - -@find . -type d -name '*.ipynb_checkpoints' | xargs rm -r - -@find ./tests -type f -name '*.c' | xargs rm -r - -@find ./tests -type f -name '*.html' | xargs rm -r - -rebuild: clear - ./env/bin/pip install .[test] - -purge: clear - -@rm -rf env - -test: - ./env/bin/pip install cython - ./env/bin/cythonize tests/test_cython/cython_example.pyx - ./env/bin/pytest - -lint: - ./env/bin/flake8 src/h3 tests - ./env/bin/pylint --disable=all --enable=import-error tests/ - -lab: - ./env/bin/pip install .[all] - ./env/bin/jupyter lab diff --git a/pyproject.toml b/pyproject.toml index e448802..4430799 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.1.0b2' +version = '4.5.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} @@ -14,7 +14,7 @@ authors = [ maintainers = [ { name = 'AJ Friend', email = 'ajfriend@gmail.com' }, ] -requires-python = '>=3.8' +requires-python = '>=3.10' dependencies = [] @@ -25,11 +25,13 @@ classifiers = [ 'License :: OSI Approved :: Apache Software License', 'Programming Language :: C', 'Programming Language :: Cython', - 'Programming Language :: Python :: 3.8', - 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Programming Language :: Python :: 3.12', + 'Programming Language :: Python :: 3.13', + 'Programming Language :: Python :: 3.14', + 'Programming Language :: Python :: 3.15', + 'Programming Language :: Python :: Free Threading', 'Operating System :: MacOS :: MacOS X', 'Operating System :: POSIX :: Linux', 'Operating System :: Microsoft :: Windows', @@ -37,19 +39,21 @@ classifiers = [ ] [project.urls] -Homepage = 'https://github.com/organization/package' -Documentation = 'https://package.readthedocs.io/' -'Bug Tracker' = 'https://github.com/organization/package/issues' -Discussions = 'https://github.com/organization/package/discussions' -Changelog = 'https://package.readthedocs.io/en/latest/changelog.html' +Homepage = 'https://github.com/uber/h3-py' +Documentation = 'https://uber.github.io/h3-py/' +'Bug Tracker' = 'https://github.com/uber/h3-py/issues' +Discussions = 'https://github.com/uber/h3-py/discussions' +Changelog = 'https://uber.github.io/h3-py/_changelog.html' [project.optional-dependencies] numpy = ['numpy'] -test = ['pytest', 'pytest-cov', 'flake8', 'pylint', 'numpy'] -all = [ - 'jupyter-book', - 'flake8', + +[dependency-groups] +dev = ['pytest', 'pytest-cov', 'numpy'] +docs = [ + 'numpy', + 'jupyter-book<2', 'sphinx>=7.3.3', # https://github.com/sphinx-doc/sphinx/issues/12290 'jupyterlab', 'jupyterlab-geojson', @@ -59,14 +63,10 @@ all = [ 'contextily', 'cartopy', 'geoviews', - 'numpy', - 'pytest', - 'pytest-cov', - 'pylint', ] [tool.pytest.ini_options] -addopts = "--cov=h3 --cov=tests --cov-report=term-missing --durations=10" +addopts = "--cov-report=term-missing --durations=10" [tool.coverage.run] omit = [ @@ -76,18 +76,68 @@ omit = [ ] +[tool.uv] +default-groups = ['dev'] + [tool.scikit-build] sdist.exclude = [ 'src/h3lib', 'docs', 'dev_notes.md', - 'makefile', + 'justfile', + '.github', + '.gitignore', + '.gitmodules', ] sdist.include = [ 'src/h3lib/LICENSE', 'src/h3lib/README.md', 'src/h3lib/VERSION', 'src/h3lib/CMakeLists.txt', + 'src/h3lib/h3.pc.in', 'src/h3lib/cmake/*', 'src/h3lib/src/h3lib/*' ] + + +[tool.ruff] +src = [ + 'src', + 'tests', +] +line-length = 88 + +[tool.ruff.lint] +flake8-quotes.inline-quotes = 'single' + +# https://docs.astral.sh/ruff/rules/ +preview = true # https://docs.astral.sh/ruff/preview/#selecting-single-preview-rules +select = [ + 'A', + # 'B', # todo + # 'COM', # todo + 'E', + 'F', + 'Q', + 'W', + # 'D', # todo. this is nice! + # 'PL', # todo. some interesting ideas + # 'DOC', # todo: interesting +] +ignore = [ + 'E221', # Multiple spaces before operator + 'E231', # Missing whitespace after ',' + 'E241', # Multiple spaces after ',' + 'E251', # Unexpected spaces around keyword / parameter equals + 'E272', # Multiple spaces before keyword + 'E731', # Do not assign a `lambda` expression, use a `def` + # 'PLR2004', +] + +[tool.ruff.lint.per-file-ignores] +'*.ipynb' = [ + 'E501', # Line too long (104 > 88) +] +'test*.py' = [ + # 'D', # maybe just the need for docstring +] diff --git a/readme.md b/readme.md index fafc529..8cb052b 100644 --- a/readme.md +++ b/readme.md @@ -1,31 +1,15 @@ -H3 Logo +H3 Logo # **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python - - [![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3) [![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3) [![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py) -[![version](https://img.shields.io/badge/h3-v3.7.1-blue.svg)](https://github.com/uber/h3/releases/tag/v3.7.1) +[![version](https://img.shields.io/badge/h3-v4.5.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.5.0) [![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE) [![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions) -[![codecov](https://codecov.io/gh/uber/h3-py/branch/master/graph/badge.svg)](https://codecov.io/gh/uber/h3-py) - - ----- -## ANNOUNCEMENT: v4.0.0 beta released! -Install the latest beta version with `pip install h3 --pre` -or with -`pip install 'h3==4.0.0b3'`.
-Feedback is welcome via -[Issues](https://github.com/uber/h3-py/issues/new), -[Discussions](https://github.com/uber/h3/discussions), -and -[Slack](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg). - ----- +[![Coverage 100%](https://img.shields.io/badge/coverage-100%25-green.svg)](https://github.com/uber/h3-py/blob/master/.github/workflows/lint_and_coverage.yml#L31) Python bindings for the [H3 core library](https://h3geo.org/). @@ -107,5 +91,5 @@ Use `h3.versions()` to see the version numbers for both ```python >>> import h3 >>> h3.versions() -{'c': '3.6.3', 'python': '3.6.1'} +{'c': '4.1.0', 'python': '4.1.1'} ``` diff --git a/src/h3/__init__.py b/src/h3/__init__.py index 4f7cb32..1e4f4b8 100644 --- a/src/h3/__init__.py +++ b/src/h3/__init__.py @@ -26,4 +26,8 @@ from ._cy import ( H3MemoryAllocError, H3MemoryBoundsError, H3OptionInvalidError, + H3IndexInvalidError, + H3BaseCellDomainError, + H3DigitDomainError, + H3DeletedDigitError, ) diff --git a/src/h3/_cy/__init__.py b/src/h3/_cy/__init__.py index 804b6b0..70fa087 100644 --- a/src/h3/_cy/__init__.py +++ b/src/h3/_cy/__init__.py @@ -14,10 +14,13 @@ function interface and input conversion (string to int, for instance). """ from .cells import ( + is_valid_index, is_valid_cell, is_pentagon, get_base_cell_number, get_resolution, + get_index_digit, + construct_cell, cell_to_parent, grid_distance, grid_disk, @@ -58,6 +61,8 @@ from .latlng import ( cell_to_latlng, polygon_to_cells, polygons_to_cells, + polygon_to_cells_experimental, + polygons_to_cells_experimental, cell_to_boundary, directed_edge_to_boundary, great_circle_distance, @@ -107,4 +112,11 @@ from .error_system import ( H3MemoryAllocError, H3MemoryBoundsError, H3OptionInvalidError, + H3IndexInvalidError, + H3BaseCellDomainError, + H3DigitDomainError, + H3DeletedDigitError, + + get_H3_ERROR_END, + error_code_to_exception, ) diff --git a/src/h3/_cy/cells.pxd b/src/h3/_cy/cells.pxd index 06b35ee..1bc31b8 100644 --- a/src/h3/_cy/cells.pxd +++ b/src/h3/_cy/cells.pxd @@ -1,9 +1,12 @@ from .h3lib cimport bool, int64_t, H3int +cpdef bool is_valid_index(H3int h) cpdef bool is_valid_cell(H3int h) cpdef bool is_pentagon(H3int h) cpdef int get_base_cell_number(H3int h) except -1 cpdef int get_resolution(H3int h) except -1 +cpdef int get_index_digit(H3int h, int res) except -1 +cpdef H3int construct_cell(int baseCellNumber, const int[:] digits) except 0 cpdef int grid_distance(H3int h1, H3int h2) except -1 cpdef H3int[:] grid_disk(H3int h, int k) cpdef H3int[:] grid_ring(H3int h, int k) diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 2b57af2..f0667e5 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -1,13 +1,17 @@ +# cython: freethreading_compatible=True cimport h3lib from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes from .util cimport ( check_cell, - check_res, # we don't use? + check_index, check_distance, ) +from .util import EARTH_RADIUS_KM + from .error_system cimport ( + H3Error, check_for_error, check_for_error_msg, ) @@ -19,6 +23,14 @@ from .memory cimport ( # todo: add notes about Cython exception handling +cpdef bool is_valid_index(H3int h): + """Validates an H3 index (cell, vertex, or directed edge). + + Returns + ------- + boolean + """ + return h3lib.isValidIndex(h) == 1 # bool is a python type, so we don't need the except clause cpdef bool is_valid_cell(H3int h): @@ -49,6 +61,33 @@ cpdef int get_resolution(H3int h) except -1: return h3lib.getResolution(h) +cpdef int get_index_digit(H3int h, int res) except -1: + cdef: + int digit + + check_index(h) + + check_for_error( + h3lib.getIndexDigit(h, res, &digit) + ) + + return digit + +cpdef H3int construct_cell(int base_cell_number, const int[:] digits) except 0: + cdef: + H3int out + int res = len(digits) + H3Error err + + if res > 0: + err = h3lib.constructCell(res, base_cell_number, &digits[0], &out) + else: + err = h3lib.constructCell(res, base_cell_number, NULL, &out) + + check_for_error(err) + + return out + cpdef int grid_distance(H3int h1, H3int h2) except -1: """ Compute the grid distance between two cells @@ -87,41 +126,6 @@ cpdef H3int[:] grid_disk(H3int h, int k): return mv -cpdef H3int[:] _ring_fallback(H3int h, int k): - """ - `ring` tries to call `h3lib.hexRing` first; if that fails, we call - this function, which relies on `h3lib.kRingDistances`. - - Failures for `h3lib.hexRing` happen when the algorithm runs into a pentagon. - """ - cdef: - int64_t n - int[:] distances ## todo: weird, this needs to be specified to avoid errors. cython bug? - - check_cell(h) - check_distance(k) - - check_for_error( - h3lib.maxGridDiskSize(k, &n) - ) - hmm = H3MemoryManager(n) - - # parallel array of cell distances from `h`. - # idea: instead of a memoryview object, have a my_mv object that can return a ptr, but does the correct logic when it has length 0 - # then can always just return the pointer, instead of the weird &mv[0] syntax - distances = int_mv(n) - check_for_error( - h3lib.gridDiskDistances(h, k, hmm.ptr, &distances[0]) - ) - - for i,v in enumerate(distances): - if v != k: - hmm.ptr[i] = 0 - - mv = hmm.to_mv() - - return mv - cpdef H3int[:] grid_ring(H3int h, int k): """ Return cells at grid distance `== k` from `h`. Collection is "hollow" for k >= 1. @@ -131,11 +135,10 @@ cpdef H3int[:] grid_ring(H3int h, int k): n = 6*k if k > 0 else 1 hmm = H3MemoryManager(n) - err = h3lib.gridRingUnsafe(h, k, hmm.ptr) - if err: - mv = _ring_fallback(h, k) - else: - mv = hmm.to_mv() + check_for_error( + h3lib.gridRing(h, k, hmm.ptr) + ) + mv = hmm.to_mv() return mv @@ -321,7 +324,8 @@ cpdef double average_hexagon_area(int resolution, unit='km^2') except -1: # todo: multiple units convert = { 'km^2': 1.0, - 'm^2': 1000*1000.0 + 'm^2': 1000*1000.0, + 'rads^2': 1.0/(EARTH_RADIUS_KM*EARTH_RADIUS_KM), } try: diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index bd0aa7c..7364bd5 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -1,8 +1,11 @@ +# cython: freethreading_compatible=True cimport h3lib from .h3lib cimport bool, H3int from .error_system cimport check_for_error +from .util import EARTH_RADIUS_KM + from .memory cimport H3MemoryManager # todo: make bint @@ -85,7 +88,8 @@ cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1: # todo: multiple units convert = { 'km': 1.0, - 'm': 1000.0 + 'm': 1000.0, + 'rads': 1.0/EARTH_RADIUS_KM, } try: diff --git a/src/h3/_cy/error_system.pxd b/src/h3/_cy/error_system.pxd index af8c709..4a1e3b4 100644 --- a/src/h3/_cy/error_system.pxd +++ b/src/h3/_cy/error_system.pxd @@ -1,3 +1,6 @@ from .h3lib cimport H3Error + +cpdef error_code_to_exception(H3Error err) cdef check_for_error(H3Error err) cdef check_for_error_msg(H3Error err, str msg) +cpdef H3Error get_H3_ERROR_END() diff --git a/src/h3/_cy/error_system.pyx b/src/h3/_cy/error_system.pyx index fbdd918..5fe5cd9 100644 --- a/src/h3/_cy/error_system.pyx +++ b/src/h3/_cy/error_system.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True """ Exceptions from the h3-py library have three possible sources: @@ -60,6 +61,10 @@ Summarizing, all exceptions originating from the C library inherit from - H3MemoryAllocError - H3MemoryBoundsError - H3OptionInvalidError +- H3IndexInvalidError +- H3BaseCellDomainError +- H3DigitDomainError +- H3DeletedDigitError # TODO: add tests verifying that concrete exception classes have the right error codes associated with them @@ -87,6 +92,11 @@ from .h3lib cimport ( E_MEMORY_ALLOC, E_MEMORY_BOUNDS, E_OPTION_INVALID, + E_INDEX_INVALID, + E_BASE_CELL_DOMAIN, + E_DIGIT_DOMAIN, + E_DELETED_DIGIT, + H3_ERROR_END # sentinel value ) @contextmanager @@ -169,6 +179,10 @@ with _the_error(H3ValueError) as e: class H3NotNeighborsError(e): ... class H3ResMismatchError(e): ... class H3OptionInvalidError(e): ... + class H3IndexInvalidError(e): ... + class H3BaseCellDomainError(e): ... + class H3DigitDomainError(e): ... + class H3DeletedDigitError(e): ... """ @@ -192,6 +206,10 @@ error_mapping = { E_MEMORY_ALLOC: H3MemoryAllocError, E_MEMORY_BOUNDS: H3MemoryBoundsError, E_OPTION_INVALID: H3OptionInvalidError, + E_INDEX_INVALID: H3IndexInvalidError, + E_BASE_CELL_DOMAIN: H3BaseCellDomainError, + E_DIGIT_DOMAIN: H3DigitDomainError, + E_DELETED_DIGIT: H3DeletedDigitError, } # Go back and modify the class definitions so that each concrete exception @@ -207,25 +225,37 @@ for code, ex in error_mapping.items(): # TODO: Move the helpers to util? # TODO: Unclear how/where to expose these functions. cdef/cpdef? -cdef code_to_exception(H3Error err): +cpdef error_code_to_exception(H3Error err): + """ + Return Python exception corresponding to integer error code + given via the H3ErrorCodes enum in `h3api.h.in` in the C library. + """ if err == E_SUCCESS: return None elif err in error_mapping: return error_mapping[err] else: - raise UnknownH3ErrorCode(err) + return UnknownH3ErrorCode(err) cdef check_for_error(H3Error err): - ex = code_to_exception(err) + ex = error_code_to_exception(err) if ex: raise ex +cpdef H3Error get_H3_ERROR_END(): + """ + Return integer H3_ERROR_END from the H3ErrorCodes enum + in `h3api.h.in` in the C library, which is one greater than + the last valid error code. + """ + return H3_ERROR_END + # todo: There's no easy way to do `*args` in `cdef` functions, but I'm also # not sure this even needs to be a Cython `cdef` function at all, or that # any of the other helper functions need to be in Cython. # todo: Revisit after we've played with this a bit. # todo: also: maybe the extra messages aren't that much more helpful... cdef check_for_error_msg(H3Error err, str msg): - ex = code_to_exception(err) + ex = error_code_to_exception(err) if ex: raise ex(msg) diff --git a/src/h3/_cy/h3lib.pxd b/src/h3/_cy/h3lib.pxd index a578a8f..6ee3b41 100644 --- a/src/h3/_cy/h3lib.pxd +++ b/src/h3/_cy/h3lib.pxd @@ -1,7 +1,8 @@ +# cython: c_string_type=unicode, c_string_encoding=utf8 from cpython cimport bool from libc.stdint cimport uint32_t, uint64_t, int64_t -ctypedef basestring H3str +ctypedef object H3str cdef extern from 'h3api.h': cdef int H3_VERSION_MAJOR @@ -28,6 +29,11 @@ cdef extern from 'h3api.h': E_MEMORY_ALLOC = 13 E_MEMORY_BOUNDS = 14 E_OPTION_INVALID = 15 + E_INDEX_INVALID = 16 + E_BASE_CELL_DOMAIN = 17 + E_DIGIT_DOMAIN = 18 + E_DELETED_DIGIT = 19 + H3_ERROR_END # sentinel value ctypedef struct LatLng: double lat # in radians @@ -41,21 +47,6 @@ cdef extern from 'h3api.h': int i int j - ctypedef struct LinkedLatLng: - LatLng data 'vertex' - LinkedLatLng *next - - # renaming these for clarity - ctypedef struct LinkedGeoLoop: - LinkedLatLng *data 'first' - LinkedLatLng *_data_last 'last' # not needed in Cython bindings - LinkedGeoLoop *next - - ctypedef struct LinkedGeoPolygon: - LinkedGeoLoop *data 'first' - LinkedGeoLoop *_data_last 'last' # not needed in Cython bindings - LinkedGeoPolygon *next - ctypedef struct GeoLoop: int numVerts LatLng *verts @@ -70,12 +61,15 @@ cdef extern from 'h3api.h': int isResClassIII(H3int h) nogil int isValidDirectedEdge(H3int edge) nogil int isValidVertex(H3int v) nogil + int isValidIndex(H3int h) nogil double degsToRads(double degrees) nogil double radsToDegs(double radians) nogil int getResolution(H3int h) nogil int getBaseCellNumber(H3int h) nogil + H3Error getIndexDigit(H3int h, int res, int *out) nogil + H3Error constructCell(int res, int baseCellNumber, const int *digits, H3int *out) nogil H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil H3Error cellToLatLng(H3int h, LatLng *) nogil @@ -138,6 +132,7 @@ cdef extern from 'h3api.h': H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil + H3Error gridRing(H3int origin, int k, H3int *out) nogil H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil @@ -161,15 +156,15 @@ cdef extern from 'h3api.h': double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil - H3Error cellsToLinkedMultiPolygon(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out) - void destroyLinkedMultiPolygon(LinkedGeoPolygon *polygon) - H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out) - # ctypedef struct GeoMultiPolygon: - # int numPolygons - # GeoPolygon *polygons + H3Error maxPolygonToCellsSizeExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count) + H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t sz, H3int *out) + + ctypedef struct GeoMultiPolygon: + int numPolygons + GeoPolygon *polygons # int hexRange(H3int origin, int k, H3int *out) @@ -186,3 +181,11 @@ cdef extern from 'h3api.h': # void h3ToString(H3int h, char *str, size_t sz) # void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination) + + +# cellsToMultiPolygon and destroyGeoMultiPolygon are temporarily excluded +# from the public API, so we use an internal header until they're moved +# back into h3api.h +cdef extern from 'cellsToMultiPoly.h': + H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out) + void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly) diff --git a/src/h3/_cy/latlng.pyx b/src/h3/_cy/latlng.pyx index 493b85a..630d3ad 100644 --- a/src/h3/_cy/latlng.pyx +++ b/src/h3/_cy/latlng.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True from libc.stdint cimport uint64_t cimport h3lib @@ -196,6 +197,84 @@ def polygons_to_cells(polygons, int res): return hmm.to_mv() +def polygon_to_cells_experimental(outer, int res, int flag, holes=None): + """ Get the set of cells whose center is contained in a polygon. + + The polygon is defined similarity to the GeoJson standard, with an exterior + `outer` ring of lat/lng points, and a list of `holes`, each of which are also + rings of lat/lng points. + + Each ring may be in clockwise or counter-clockwise order + (right-hand rule or not), and may or may not be a closed loop (where the last + element is equal to the first). + The GeoJSON spec requires the right-hand rule and a closed loop, but + this function relaxes those constraints. + + Unlike the GeoJson standard, the elements of the lat/lng pairs of each + ring are in lat/lng order, instead of lng/lat order. + + We'll handle translation to different formats in the Python code, + rather than the Cython code. + + Parameters + ---------- + outer : list or tuple + A ring given by a sequence of lat/lng pairs. + res : int + The resolution of the output hexagons + flag : int + Polygon to cells flag, such as containment mode. + holes : list or tuple + A collection of rings, each given by a sequence of lat/lng pairs. + These describe any the "holes" in the polygon. + """ + cdef: + uint64_t n + + check_res(res) + + if not outer: + return H3MemoryManager(0).to_mv() + + gp = GeoPolygon(outer, holes=holes) + + check_for_error( + h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flag, &n) + ) + + hmm = H3MemoryManager(n) + check_for_error( + h3lib.polygonToCellsExperimental(&gp.gp, res, flag, n, hmm.ptr) + ) + mv = hmm.to_mv() + + return mv + + +def polygons_to_cells_experimental(polygons, int res, int flag): + mvs = [ + polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flag=flag) + for poly in polygons + ] + + n = sum(map(len, mvs)) + hmm = H3MemoryManager(n) + + # probably super inefficient, but it is working! + # tood: move this to C + # a cell can overlap more than one polygon, so skip the ones already added + seen = set() + k = 0 + for mv in mvs: + for v in mv: + if v not in seen: + seen.add(v) + hmm.ptr[k] = v + k += 1 + + return hmm.to_mv() + + def cell_to_boundary(H3int h): """Compose an array of geo-coordinates that outlines a hexagonal cell""" cdef: diff --git a/src/h3/_cy/memory.pyx b/src/h3/_cy/memory.pyx index 0852105..963b00d 100644 --- a/src/h3/_cy/memory.pyx +++ b/src/h3/_cy/memory.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True from cython.view cimport array from .h3lib cimport H3int diff --git a/src/h3/_cy/to_multipoly.pyx b/src/h3/_cy/to_multipoly.pyx index db29baa..cb5e5e2 100644 --- a/src/h3/_cy/to_multipoly.pyx +++ b/src/h3/_cy/to_multipoly.pyx @@ -1,60 +1,46 @@ +# cython: freethreading_compatible=True cimport h3lib from h3lib cimport H3int from .util cimport check_cell, coord2deg +from .error_system cimport check_for_error -# todo: it's driving me crazy that these three functions are all essentially the same linked list walker... -# grumble: no way to do iterators in with cdef functions! -cdef walk_polys(const h3lib.LinkedGeoPolygon* L): - out = [] - while L: - out += [walk_loops(L.data)] - L = L.next - - return out +cdef _loop_to_list(const h3lib.GeoLoop *loop): + return [coord2deg(loop.verts[v]) for v in range(loop.numVerts)] -cdef walk_loops(const h3lib.LinkedGeoLoop* L): - out = [] - while L: - out += [walk_coords(L.data)] - L = L.next - - return out +cdef _poly_to_lists(const h3lib.GeoPolygon *poly): + return ( + [_loop_to_list(&poly.geoloop)] + + [_loop_to_list(&poly.holes[h]) for h in range(poly.numHoles)] + ) -cdef walk_coords(const h3lib.LinkedLatLng* L): - out = [] - while L: - out += [coord2deg(L.data)] - L = L.next - - return out - -# todo: tuples instead of lists? def _to_multi_polygon(const H3int[:] cells): cdef: - h3lib.LinkedGeoPolygon polygon + h3lib.GeoMultiPolygon mpoly + H3int cell - for h in cells: - check_cell(h) + for cell in cells: + check_cell(cell) - h3lib.cellsToLinkedMultiPolygon(&cells[0], len(cells), &polygon) + check_for_error( + h3lib.cellsToMultiPolygon(&cells[0], len(cells), &mpoly) + ) - out = walk_polys(&polygon) - - # we're still responsible for cleaning up the passed in `polygon`, - # but not a problem here, since it is stack allocated - h3lib.destroyLinkedMultiPolygon(&polygon) + try: + out = [ + _poly_to_lists(&mpoly.polygons[p]) + for p in range(mpoly.numPolygons) + ] + finally: + h3lib.destroyGeoMultiPolygon(&mpoly) return out def cells_to_multi_polygon(const H3int[:] cells): - # todo: gotta be a more elegant way to handle these... if len(cells) == 0: return [] - multipoly = _to_multi_polygon(cells) - - return multipoly + return _to_multi_polygon(cells) diff --git a/src/h3/_cy/util.pxd b/src/h3/_cy/util.pxd index 4d7d962..b584d3a 100644 --- a/src/h3/_cy/util.pxd +++ b/src/h3/_cy/util.pxd @@ -8,6 +8,7 @@ cpdef H3str int_to_str(H3int x) cdef check_cell(H3int h) cdef check_edge(H3int e) -cdef check_res(int res) cdef check_vertex(H3int v) +cdef check_index(H3int h) +cdef check_res(int res) cdef check_distance(int k) diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 7b8a9f2..74e8f80 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -1,4 +1,12 @@ -from .h3lib cimport H3int, H3str, isValidCell, isValidDirectedEdge, isValidVertex +# cython: freethreading_compatible=True +from .h3lib cimport ( + H3int, + H3str, + isValidCell, + isValidDirectedEdge, + isValidVertex, + isValidIndex, +) cimport h3lib @@ -7,9 +15,14 @@ from .error_system import ( H3DomainError, H3DirEdgeInvalidError, H3CellInvalidError, - H3VertexInvalidError + H3VertexInvalidError, + H3IndexInvalidError, ) +# Must match EARTH_RADIUS_KM in h3lib's constants.h, which is not part of the +# public h3api.h header. Used to convert km based averages to radians. +EARTH_RADIUS_KM = 6371.007180918475 + cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: h3lib.LatLng c @@ -78,6 +91,10 @@ cdef check_vertex(H3int v): if isValidVertex(v) == 0: raise H3VertexInvalidError('Integer is not a valid H3 vertex: {}'.format(hex(v))) +cdef check_index(H3int h): + if isValidIndex(h) == 0: + raise H3IndexInvalidError('Integer is not a valid H3 index: {}'.format(hex(h))) + cdef check_res(int res): if (res < 0) or (res > 15): raise H3ResDomainError(res) diff --git a/src/h3/_cy/vertex.pyx b/src/h3/_cy/vertex.pyx index 26a674a..99cc5ef 100644 --- a/src/h3/_cy/vertex.pyx +++ b/src/h3/_cy/vertex.pyx @@ -1,3 +1,4 @@ +# cython: freethreading_compatible=True cimport h3lib from h3lib cimport bool, H3int diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 5c36295..68d18c2 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -54,7 +54,7 @@ class LatLngPoly(H3Shape): def __init__(self, outer, *holes): loops = [outer] + list(holes) for loop in loops: - if len(loop) in (1, 2): + if len(loop) > 0 and len(_open_ring(loop)) < 3: raise ValueError('Non-empty LatLngPoly loops need at least 3 points.') point_dimensions = set(map(len, loop)) @@ -184,13 +184,6 @@ LL0: lat/lng or lng/lat pair LL1: list of LL0s LL2: list of LL1s (i.e., a polygon with holes) LL3: list of LL2s (i.e., several polygons with holes) - - -## TODO - -- Allow user to specify "container" in `cells_to_geojson`. - - That is, they may want a MultiPolygon even if the output fits in a Polygon - - 'auto', Polygon, MultiPolygon, FeatureCollection, GeometryCollection, ... """ @@ -230,6 +223,10 @@ def _remove_z(ll1): def _LL2_to_polygon(ll2): + if len(ll2) == 0: + # empty GeoJSON Polygon, like `shapely.Polygon().__geo_interface__` + return LatLngPoly([]) + ll2 = [ _remove_z(ll1) for ll1 in ll2 @@ -308,7 +305,11 @@ def geo_to_h3shape(geo): # get dict geo = geo.__geo_interface__ - assert isinstance(geo, dict) # todo: remove + if not isinstance(geo, dict): + raise ValueError( + 'geo must be a dict or implement __geo_interface__, got: ' + + str(type(geo)) + ) t = geo['type'] coord = geo['coordinates'] @@ -325,14 +326,63 @@ def geo_to_h3shape(geo): return shape -def h3shape_to_geo(h3shape): +def h3shape_to_geo(h3shape, container='auto'): """ Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. ``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly`` + Parameters + ---------- + container : str, optional + Specify the desired GeoJSON output container. + Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature', + 'FeatureCollection', or 'GeometryCollection'. + Default is 'auto' (returns the simplest valid geometry). + Returns ------- dict """ - return h3shape.__geo_interface__ + base_geo = h3shape.__geo_interface__ + + # Return immediately if no wrapping is needed + if container == 'auto' or container == base_geo['type']: + return base_geo + + # Upgrade a Polygon to a MultiPolygon if explicitly requested + if container == 'MultiPolygon' and base_geo['type'] == 'Polygon': + return { + 'type': 'MultiPolygon', + 'coordinates': (base_geo['coordinates'],) + } + + if container == 'Feature': + return { + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + } + + if container == 'FeatureCollection': + return { + 'type': 'FeatureCollection', + 'features': [{ + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + }] + } + + if container == 'GeometryCollection': + return { + 'type': 'GeometryCollection', + 'geometries': [base_geo] + } + + # If we reach here, the requested container is either unknown or + # insufficient for the data (e.g., requesting a Polygon for MultiPolygon data). + raise ValueError( + f"Requested container '{container}' is invalid or insufficient " + f"for data of type '{base_geo['type']}'." + ) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 6035966..8eac4b1 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -1,4 +1,6 @@ # This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal +from array import array from ... import _cy from ..._h3shape import ( @@ -127,6 +129,20 @@ def average_hexagon_edge_length(res, unit='km'): return _cy.average_hexagon_edge_length(res, unit) +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError, OverflowError): + return False + + def is_valid_cell(h): """ Validates an H3 cell (hexagon or pentagon). @@ -138,13 +154,13 @@ def is_valid_cell(h): try: h = _in_scalar(h) return _cy.is_valid_cell(h) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False def is_valid_directed_edge(edge): """ - Validates an H3 unidirectional edge. + Validates an H3 directed edge. Returns ------- @@ -153,7 +169,7 @@ def is_valid_directed_edge(edge): try: e = _in_scalar(edge) return _cy.is_valid_directed_edge(e) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False @@ -458,8 +474,6 @@ def uncompact_cells(cells, res): ----- There is currently no guaranteed order of the output cells. """ - # TODO: add test to make sure an error is returned when input contains cell - # smaller than output res. hc = _in_collection(cells) hu = _cy.uncompact_cells(hc, res) @@ -467,6 +481,13 @@ def uncompact_cells(cells, res): return _out_collection(hu) +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + def h3shape_to_cells(h3shape, res): """ Return the collection of H3 cells at a given resolution whose center points @@ -506,10 +527,10 @@ def h3shape_to_cells(h3shape, res): # todo: not sure if i want this dispatch logic here. maybe in the objects? if isinstance(h3shape, LatLngPoly): poly = h3shape - mv = _cy.polygon_to_cells(poly.outer, res, holes=poly.holes) + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) elif isinstance(h3shape, LatLngMultiPoly): mpoly = h3shape - mv = _cy.polygons_to_cells(mpoly.polys, res) + mv = _cy.polygons_to_cells(mpoly.polys, res=res) elif isinstance(h3shape, H3Shape): raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) else: @@ -518,11 +539,99 @@ def h3shape_to_cells(h3shape, res): return _out_collection(mv) -def polygon_to_cells(h3shape, res): +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): """ - Alias for ``h3shape_to_cells``. + Alias for ``h3shape_to_cells_experimental``. """ - return h3shape_to_cells(h3shape, res) + return h3shape_to_cells_experimental(h3shape, res, contain) + + +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res = res, + holes = poly.holes, + flag = flag, + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) def cells_to_h3shape(cells, *, tight=True): @@ -640,10 +749,124 @@ def get_base_cell_number(h): Returns ------- int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 """ return _cy.get_base_cell_number(_in_scalar(h)) +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + def are_neighbor_cells(h1, h2): """ Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. @@ -1140,5 +1363,30 @@ def is_valid_vertex(v): try: v = _in_scalar(v) return _cy.is_valid_vertex(v) - except (ValueError, TypeError): + except (ValueError, TypeError, OverflowError): return False + + +if _out_scalar is _in_scalar: # pragma: no cover + # When _out_scalar is identity (basic_int, numpy_int, memview_int), + # bind scalar functions directly to their _cy counterparts to eliminate + # Python call frame and identity wrapper overhead (Issue #501). + # + # Coverage is only measured on the basic_str copy of this file, where + # this branch is never taken; it is exercised by the int API tests. + for _name in ( + 'latlng_to_cell', + 'cell_to_parent', + 'cell_to_center_child', + 'cells_to_directed_edge', + 'get_directed_edge_origin', + 'get_directed_edge_destination', + 'directed_edge_to_cells', + 'local_ij_to_cell', + 'cell_to_vertex', + ): + _fn = globals()[_name] + _cy_fn = getattr(_cy, _name) + _cy_fn.__doc__ = _fn.__doc__ + globals()[_name] = _cy_fn + del _name, _fn, _cy_fn diff --git a/src/h3lib b/src/h3lib index 5c91149..1b536c3 160000 --- a/src/h3lib +++ b/src/h3lib @@ -1 +1 @@ -Subproject commit 5c91149104ac02c4f06faa4fc557e69cf6b131ef +Subproject commit 1b536c34225191ba24a75a840f634d4a48c3b206 diff --git a/tests/polyfill/test_to_multipoly.py b/tests/polyfill/test_to_multipoly.py deleted file mode 100644 index 61f77f6..0000000 --- a/tests/polyfill/test_to_multipoly.py +++ /dev/null @@ -1,49 +0,0 @@ -import h3 - - -from .. import util as u - - -def test_cells_to_h3shape(): - h = '8928308280fffff' - cells = h3.grid_disk(h, 1) - - mpoly = h3.cells_to_h3shape(cells, tight=False) - poly = mpoly[0] - - poly2 = h3.LatLngPoly(poly.outer, *poly.holes) - out = h3.h3shape_to_cells(poly2, 9) - - assert u.same_set(out, cells) - - -def test_cells_to_h3shape_tight(): - h = '8928308280fffff' - cells = h3.grid_disk(h, 1) - - poly = h3.cells_to_h3shape(cells, tight=True) - poly2 = h3.LatLngPoly(poly.outer, *poly.holes) - out = h3.h3shape_to_cells(poly2, 9) - - assert u.same_set(out, cells) - - -def test_2_polys(): - h = '8928308280fffff' - cells = h3.grid_ring(h, 2) - cells = cells + [h] - # cells should be a center hex, and the 2-ring around it - # (with the 1-ring being absent) - - mpoly = h3.cells_to_h3shape(cells) - - out = [ - set(h3.h3shape_to_cells(poly, 9)) - for poly in mpoly - ] - - assert u.same_set( - set.union(*out), - cells - ) - assert set(map(len, out)) == {1, 12} diff --git a/tests/readme.md b/tests/readme.md new file mode 100644 index 0000000..0aba346 --- /dev/null +++ b/tests/readme.md @@ -0,0 +1,18 @@ +We separate the `h3-py` tests into two groups, organized by subfolder. + +We do this because we expect 100% coverage on the library tests, but are +still working through getting full coverage on the Cython tests. + + +## `test_lib` + +The tests in this folder are for the main `h3-py` Python API for folks +who are using the pure-Python library functionality. + +## `test_cython` + +The tests in this folder are for the advanced Cython API, that allows +for other *Cython* packages or scripts to use the Cython code provided +by the `h3-py` internals. + +Note that the "Cython API" of `h3-py` is not currently externally supported. diff --git a/tests/test_apis/test_basic_int.py b/tests/test_apis/test_basic_int.py deleted file mode 100644 index a567b3d..0000000 --- a/tests/test_apis/test_basic_int.py +++ /dev/null @@ -1,34 +0,0 @@ -import h3.api.basic_int as h3 - - -from .. import util as u - - -def test_int_output(): - lat = 37.7752702151959 - lng = -122.418307270836 - - assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 - assert h3.latlng_to_cell(lat, lng, 9) == 0x8928308280fffff - - -def test_grid_disk(): - expected = [ - 617700169957507071, - 617700169957769215, - 617700169958031359, - 617700169958293503, - 617700169961177087, - 617700169964847103, - 617700169965109247, - ] - - out = h3.grid_disk(617700169958293503, 1) - assert u.same_set(out, expected) - - -def test_compact_cells(): - h = 617700169958293503 - cells = h3.cell_to_children(h) - - assert h3.compact_cells(cells) == [h] diff --git a/tests/test_apis/test_memview_int.py b/tests/test_apis/test_memview_int.py deleted file mode 100644 index 0523794..0000000 --- a/tests/test_apis/test_memview_int.py +++ /dev/null @@ -1,25 +0,0 @@ -import h3.api.memview_int as h3 - - -def test1(): - lat, lng = 37.7752702151959, -122.418307270836 - assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 - - -def test_line(): - h1 = '8928308280fffff' - h2 = '8928308287bffff' - h1, h2 = h3.str_to_int(h1), h3.str_to_int(h2) - - out = h3.grid_path_cells(h1, h2) - - # todo: are we outputting `memoryviewslice`? should we just output a memoryview? - assert 'memoryview' in str(type(out)) - - expected = [ - 617700169958293503, - 617700169964847103, - 617700169965371391, - ] - - assert list(out) == expected diff --git a/tests/test_apis/test_numpy_int.py b/tests/test_apis/test_numpy_int.py deleted file mode 100644 index 2ffa43f..0000000 --- a/tests/test_apis/test_numpy_int.py +++ /dev/null @@ -1,33 +0,0 @@ -import h3.api.numpy_int as h3 -import numpy as np # only run this test suite if numpy is installed - -from .. import util as u - - -def test1(): - lat, lng = 37.7752702151959, -122.418307270836, - assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 - - -def test5(): - expected = { - 617700169957507071, - 617700169957769215, - 617700169958031359, - 617700169958293503, - 617700169961177087, - 617700169964847103, - 617700169965109247, - } - - out = h3.grid_disk(617700169958293503, 1) - assert isinstance(out, np.ndarray) - assert u.same_set(out, expected) - - -def test_compact_cells(): - h = 617700169958293503 - cells = h3.cell_to_children(h) - assert isinstance(cells, np.ndarray) - - assert h3.compact_cells(cells) == [h] diff --git a/tests/__init__.py b/tests/test_lib/__init__.py similarity index 100% rename from tests/__init__.py rename to tests/test_lib/__init__.py diff --git a/tests/polyfill/__init__.py b/tests/test_lib/polyfill/__init__.py similarity index 100% rename from tests/polyfill/__init__.py rename to tests/test_lib/polyfill/__init__.py diff --git a/tests/polyfill/test_h3.py b/tests/test_lib/polyfill/test_h3.py similarity index 73% rename from tests/polyfill/test_h3.py rename to tests/test_lib/polyfill/test_h3.py index 8d9d948..6327cf8 100644 --- a/tests/polyfill/test_h3.py +++ b/tests/test_lib/polyfill/test_h3.py @@ -117,6 +117,110 @@ def test_polygon_to_cells(): assert '89283095edbffff' in out +def test_polygon_to_cells_experimental(): + poly = h3.LatLngPoly(sf_7x7) + # Note that `polygon_to_cells_experimental` is an alias for + # `h3shape_to_cells_experimental` + out = h3.polygon_to_cells_experimental(poly, res=9, contain='center') + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental(): + poly = h3.LatLngPoly(sf_7x7) + + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='center') + + assert len(out) == 1253 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental_full(): + poly = h3.LatLngPoly(sf_7x7) + + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='full') + + assert len(out) == 1175 + assert '89283082a1bffff' in out + assert '89283080527ffff' not in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental_overlapping(): + poly = h3.LatLngPoly(sf_7x7) + + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='overlap') + + assert len(out) == 1334 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental_overlapping_bbox(): + poly = h3.LatLngPoly(sf_7x7) + out = h3.h3shape_to_cells_experimental(poly, res=9, contain='bbox_overlap') + + assert len(out) == 1416 + assert '89283080527ffff' in out + assert '89283095edbffff' in out + + +def test_h3shape_to_cells_experimental_invalid_mode(): + poly = h3.LatLngPoly(sf_7x7) + with pytest.raises(KeyError): + h3.h3shape_to_cells_experimental( + poly, + res = 9, + contain = 'contain_overlapping_bbox_abc', + ) + + +def test_poly_to_cells_experimental_mpoly(): + mpoly = h3.LatLngMultiPoly( + h3.LatLngPoly(sf_hole1), + h3.LatLngPoly(sf_hole2), + ) + + assert ( + set(h3.h3shape_to_cells_experimental(mpoly, res=9)) + == + set(h3.h3shape_to_cells_experimental(mpoly, res=9, contain='center')) + ) + + assert ( + set(h3.h3shape_to_cells_experimental(mpoly, res=9)) + < + set(h3.h3shape_to_cells_experimental( + mpoly, + res = 9, + contain = 'overlap' + )) + ) + + assert 120 == len(h3.h3shape_to_cells_experimental( + mpoly, + res = 9, + contain = 'overlap' + )) + + +def test_poly_to_cells_experimental_mpoly_no_duplicates(): + # cells that overlap both polygons should only be returned once + a = h3.LatLngPoly([(37.70, -122.50), (37.70, -122.45), (37.75, -122.45)]) + b = h3.LatLngPoly([(37.70, -122.449), (37.70, -122.40), (37.75, -122.40)]) + mpoly = h3.LatLngMultiPoly(a, b) + + out = h3.h3shape_to_cells_experimental(mpoly, res=7, contain='overlap') + + expected = set(h3.h3shape_to_cells_experimental(a, res=7, contain='overlap')) + expected |= set(h3.h3shape_to_cells_experimental(b, res=7, contain='overlap')) + assert len(out) == len(expected) + assert set(out) == expected + + def test_polyfill_with_hole(): poly = h3.LatLngPoly(sf_7x7, sf_hole1) @@ -212,6 +316,23 @@ def test_geo_to_h3shape_passthrough(): assert h3.geo_to_h3shape(shape) is shape +def test_geo_to_h3shape_rejects_non_dict(): + with pytest.raises(ValueError, match='dict or implement __geo_interface__'): + h3.geo_to_h3shape('not a geo object') + + +def test_geo_to_h3shape_empty_polygon(): + # e.g., shapely.Polygon().__geo_interface__ + geo = MockGeoInterface({'type': 'Polygon', 'coordinates': ()}) + + shape = h3.geo_to_h3shape(geo) + assert isinstance(shape, h3.LatLngPoly) + assert shape.outer == () + assert shape.holes == () + + assert h3.geo_to_cells(geo, 9) == [] + + def test_polyfill_down_under(): sydney = [ (-33.8556, 151.1979), diff --git a/tests/polyfill/test_polyfill.py b/tests/test_lib/polyfill/test_polyfill.py similarity index 95% rename from tests/polyfill/test_polyfill.py rename to tests/test_lib/polyfill/test_polyfill.py index 1431b87..f70c639 100644 --- a/tests/polyfill/test_polyfill.py +++ b/tests/test_lib/polyfill/test_polyfill.py @@ -145,9 +145,15 @@ def test_bad_geo_input(): with pytest.raises(ValueError): h3.h3shape_to_cells('not a shape', 9) + with pytest.raises(ValueError): + h3.h3shape_to_cells_experimental('not a shape', res=9) + with pytest.raises(ValueError): h3.geo_to_cells({'type': 'not a shape', 'coordinates': None}, 9) + with pytest.raises(ValueError): + h3.geo_to_cells('not a shape', 9) + def test_cells_to_geo(): h = '89754e64993ffff' diff --git a/tests/polyfill/test_polyfill_ordering.py b/tests/test_lib/polyfill/test_polyfill_ordering.py similarity index 100% rename from tests/polyfill/test_polyfill_ordering.py rename to tests/test_lib/polyfill/test_polyfill_ordering.py diff --git a/tests/polyfill/test_polygon_class.py b/tests/test_lib/polyfill/test_polygon_class.py similarity index 64% rename from tests/polyfill/test_polygon_class.py rename to tests/test_lib/polyfill/test_polygon_class.py index 3996d30..a3639b6 100644 --- a/tests/polyfill/test_polygon_class.py +++ b/tests/test_lib/polyfill/test_polygon_class.py @@ -44,5 +44,22 @@ def test_bad_subclass(): shoop = H3Shoop() shoop.__geo_interface__() + with pytest.raises(ValueError): h3.h3shape_to_cells(shoop, res=9) + + with pytest.raises(ValueError): + h3.h3shape_to_cells_experimental(shoop, res=9) + + +def test_closed_loop_with_too_few_points(): + # a closed loop of 3 points only has 2 distinct points once the + # repeated closing point is removed + a, b = (37.68, -122.54), (37.82, -122.34) + outer = [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)] + + with pytest.raises(ValueError, match='at least 3 points'): + h3.LatLngPoly([a, b, a]) + + with pytest.raises(ValueError, match='at least 3 points'): + h3.LatLngPoly(outer, [a, b, a]) diff --git a/tests/test_lib/polyfill/test_to_multipoly.py b/tests/test_lib/polyfill/test_to_multipoly.py new file mode 100644 index 0000000..80c5a75 --- /dev/null +++ b/tests/test_lib/polyfill/test_to_multipoly.py @@ -0,0 +1,360 @@ +import pytest + +import h3 +from h3._cy.error_system import H3DuplicateInputError, H3ResMismatchError, H3FailedError + +from .. import util as u + + +def assert_cells_roundtrip(cells): + """Convert cells to multi-polygon and back, checking we recover the original set.""" + res = h3.get_resolution(cells[0]) + mpoly = h3.cells_to_h3shape(cells, tight=False) + + recovered = h3.h3shape_to_cells(mpoly, res) + + assert u.same_set(recovered, cells) + + +def test_cells_to_h3shape(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + mpoly = h3.cells_to_h3shape(cells, tight=False) + poly = mpoly[0] + + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert u.same_set(out, cells) + + +def test_cells_to_h3shape_tight(): + h = '8928308280fffff' + cells = h3.grid_disk(h, 1) + + poly = h3.cells_to_h3shape(cells, tight=True) + poly2 = h3.LatLngPoly(poly.outer, *poly.holes) + out = h3.h3shape_to_cells(poly2, 9) + + assert u.same_set(out, cells) + + +def test_2_polys(): + h = '8928308280fffff' + cells = h3.grid_ring(h, 2) + cells = cells + [h] + # cells should be a center hex, and the 2-ring around it + # (with the 1-ring being absent) + + mpoly = h3.cells_to_h3shape(cells) + + out = [ + set(h3.h3shape_to_cells(poly, 9)) + for poly in mpoly + ] + + assert u.same_set( + set.union(*out), + cells + ) + assert set(map(len, out)) == {1, 12} + + +def test_empty(): + mpoly = h3.cells_to_h3shape([], tight=False) + assert isinstance(mpoly, h3.LatLngMultiPoly) + assert len(mpoly) == 0 + + mpoly = h3.cells_to_h3shape([], tight=True) + assert isinstance(mpoly, h3.LatLngMultiPoly) + assert len(mpoly) == 0 + + +def test_all_res0_cells(): + cells = h3.get_res0_cells() + mpoly = h3.cells_to_h3shape(cells, tight=False) + + # We should get an "entire globe" multipolygon back + # The current implementation returns 8 triangles + assert len(mpoly) == 8 + for poly in mpoly: + assert len(poly.outer) == 3 + assert len(poly.holes) == 0 + + # Roundtrip fails: h3shape_to_cells recovers only 69/122 cells. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells2 = h3.h3shape_to_cells(mpoly, 0) + assert len(cells2) == 69 + + +def test_pentagons(): + for res in range(16): + cells = h3.get_pentagons(res) + mpoly = h3.cells_to_h3shape(cells, tight=False) + + if res % 2 == 0: + expected_verts = 5 + else: + # pentagons have distortion vertices at odd resolutions + expected_verts = 10 + + assert len(mpoly) == 12 + for poly in mpoly: + assert len(poly.holes) == 0 + assert len(poly.outer) == expected_verts + + assert_cells_roundtrip(cells) + + +def test_duplicate_cells_error(): + cell = '8928308280fffff' + with pytest.raises(H3DuplicateInputError): + h3.cells_to_h3shape([cell, cell]) + + +def test_mixed_resolution_error(): + with pytest.raises(H3ResMismatchError): + h3.cells_to_h3shape(['8027fffffffffff', '81efbffffffffff']) + + +def test_three_polygons(): + cells = [ + '8027fffffffffff', '802bfffffffffff', '804dfffffffffff', + '8067fffffffffff', '806dfffffffffff', '8049fffffffffff', + '805ffffffffffff', '8057fffffffffff', '807dfffffffffff', + '80a5fffffffffff', '80a9fffffffffff', '808bfffffffffff', + '801bfffffffffff', '8035fffffffffff', '803ffffffffffff', + '8053fffffffffff', '8043fffffffffff', '8021fffffffffff', + '8011fffffffffff', '801ffffffffffff', '8097fffffffffff', + ] + + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 3 + hole_counts = [len(p.holes) for p in mpoly] + + # Polygons are ordered by size, and we know the hole counts of each + assert hole_counts == [3, 1, 0] + + assert_cells_roundtrip(cells) + + +def test_issue_1049(): + cells = [ + '827487fffffffff', '82748ffffffffff', '827497fffffffff', + '82749ffffffffff', '8274affffffffff', '8274c7fffffffff', + '8274cffffffffff', '8274d7fffffffff', '8274e7fffffffff', + '8274effffffffff', '8274f7fffffffff', '82754ffffffffff', + '827c07fffffffff', '827c27fffffffff', '827c2ffffffffff', + '827c37fffffffff', '827d87fffffffff', '827d8ffffffffff', + '827d97fffffffff', '827d9ffffffffff', '827da7fffffffff', + '827daffffffffff', '82801ffffffffff', '8280a7fffffffff', + '8280affffffffff', '8280b7fffffffff', '828197fffffffff', + '82819ffffffffff', '8281a7fffffffff', '8281b7fffffffff', + '828207fffffffff', '82820ffffffffff', '828227fffffffff', + '82822ffffffffff', '8282e7fffffffff', '828307fffffffff', + '82830ffffffffff', '82831ffffffffff', '82832ffffffffff', + '828347fffffffff', '82834ffffffffff', '828357fffffffff', + '82835ffffffffff', '828367fffffffff', '828377fffffffff', + '82a447fffffffff', '82a457fffffffff', '82a45ffffffffff', + '82a467fffffffff', '82a46ffffffffff', '82a477fffffffff', + '82a4c7fffffffff', '82a4cffffffffff', '82a4d7fffffffff', + '82a4e7fffffffff', '82a4effffffffff', '82a4f7fffffffff', + '82a547fffffffff', '82a54ffffffffff', '82a557fffffffff', + '82a55ffffffffff', '82a567fffffffff', '82a577fffffffff', + '82a837fffffffff', '82a897fffffffff', '82a8a7fffffffff', + '82a8b7fffffffff', '82a917fffffffff', '82a927fffffffff', + '82a937fffffffff', '82a987fffffffff', '82a98ffffffffff', + '82a997fffffffff', '82a99ffffffffff', '82a9a7fffffffff', + '82a9affffffffff', '82ac47fffffffff', '82ac57fffffffff', + '82ac5ffffffffff', '82ac67fffffffff', '82ac6ffffffffff', + '82ac77fffffffff', '82ad47fffffffff', '82ad4ffffffffff', + '82ad57fffffffff', '82ad5ffffffffff', '82ad67fffffffff', + '82ad77fffffffff', '82c207fffffffff', '82c217fffffffff', + '82c227fffffffff', '82c237fffffffff', '82c287fffffffff', + '82c28ffffffffff', '82c29ffffffffff', '82c2a7fffffffff', + '82c2affffffffff', '82c2b7fffffffff', '82c307fffffffff', + '82c317fffffffff', '82c31ffffffffff', '82c337fffffffff', + '82cfb7fffffffff', '82d0c7fffffffff', '82d0d7fffffffff', + '82d0dffffffffff', '82d0e7fffffffff', '82d0f7fffffffff', + '82d147fffffffff', '82d157fffffffff', '82d15ffffffffff', + '82d167fffffffff', '82d177fffffffff', '82d187fffffffff', + '82d18ffffffffff', '82d197fffffffff', '82d19ffffffffff', + '82d1a7fffffffff', '82d1affffffffff', '82dc47fffffffff', + '82dc57fffffffff', '82dc5ffffffffff', '82dc67fffffffff', + '82dc6ffffffffff', '82dc77fffffffff', '82dcc7fffffffff', + '82dccffffffffff', '82dcd7fffffffff', '82dce7fffffffff', + '82dceffffffffff', '82dcf7fffffffff', '82dd1ffffffffff', + '82dd47fffffffff', '82dd4ffffffffff', '82dd57fffffffff', + '82dd5ffffffffff', '82dd6ffffffffff', '82dd87fffffffff', + '82dd8ffffffffff', '82dd97fffffffff', '82dd9ffffffffff', + '82ddaffffffffff', '82ddb7fffffffff', '82dec7fffffffff', + '82decffffffffff', '82ded7fffffffff', '82dee7fffffffff', + '82deeffffffffff', '82def7fffffffff', '82df0ffffffffff', + '82df1ffffffffff', '82df47fffffffff', '82df4ffffffffff', + '82df57fffffffff', '82df5ffffffffff', '82df77fffffffff', + '82df8ffffffffff', '82df9ffffffffff', '82e6c7fffffffff', + '82e6cffffffffff', '82e6d7fffffffff', '82e6dffffffffff', + '82e6effffffffff', '82e6f7fffffffff', + ] + + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 12 + for poly in mpoly: + assert len(poly.holes) == 0 + + assert_cells_roundtrip(cells) + + +def test_equator_cells(): + """Continuous band of cells overlapping the equator. + """ + cells = [ + '81807ffffffffff', '817efffffffffff', '81723ffffffffff', + '817ebffffffffff', '817c3ffffffffff', '817e3ffffffffff', + '817a3ffffffffff', '8166fffffffffff', '8172bffffffffff', + '816afffffffffff', '81933ffffffffff', '8168fffffffffff', + '8188fffffffffff', '81853ffffffffff', '817f7ffffffffff', + '8180bffffffffff', '81783ffffffffff', '81743ffffffffff', + '8170bffffffffff', '8173bffffffffff', '8179bffffffffff', + '817cbffffffffff', '8188bffffffffff', '81857ffffffffff', + '816f7ffffffffff', '8177bffffffffff', '81617ffffffffff', + '816f3ffffffffff', '8174bffffffffff', '8180fffffffffff', + '817a7ffffffffff', '81767ffffffffff', '81757ffffffffff', + '81957ffffffffff', '81787ffffffffff', '81847ffffffffff', + '81653ffffffffff', '817bbffffffffff', '816cfffffffffff', + '816abffffffffff', '815f3ffffffffff', '817c7ffffffffff', + '8168bffffffffff', '818cbffffffffff', '818cfffffffffff', + '818afffffffffff', '8174fffffffffff', '8172fffffffffff', + '8170fffffffffff', '816fbffffffffff', '81657ffffffffff', + '816c7ffffffffff', '8186bffffffffff', '81763ffffffffff', + '818a7ffffffffff', '8186fffffffffff', '81707ffffffffff', + '8182bffffffffff', '818f3ffffffffff', '8182fffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 1 + + # Roundtrip fails: h3shape_to_cells recovers only 18/60 cells. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells2 = h3.h3shape_to_cells(mpoly, 1) + assert len(cells2) == 18 + + +def test_prime_meridian(): + """Continuous band of cells overlapping the prime meridian. + """ + cells = [ + '81efbffffffffff', '81c07ffffffffff', '81d1bffffffffff', + '81097ffffffffff', '8109bffffffffff', '81d0bffffffffff', + '81987ffffffffff', '81017ffffffffff', '81e67ffffffffff', + '81ddbffffffffff', '81ac7ffffffffff', '8158bffffffffff', + '81397ffffffffff', '81593ffffffffff', '81c17ffffffffff', + '81827ffffffffff', '81197ffffffffff', '81eebffffffffff', + '81383ffffffffff', '81dcbffffffffff', '81757ffffffffff', + '81093ffffffffff', '81073ffffffffff', '8159bffffffffff', + '81f17ffffffffff', '81187ffffffffff', '81007ffffffffff', + '81997ffffffffff', '81753ffffffffff', '81033ffffffffff', + '81f2bffffffffff', '8138bffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 0 + assert len(poly.outer) == 128 + + # Roundtrip fails: h3shape_to_cells raises on this global polygon. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + with pytest.raises(H3FailedError): + h3.h3shape_to_cells(mpoly, 1) + + +def test_anti_meridian(): + """Continuous band of cells overlapping the anti-meridian.""" + cells = [ + '817ebffffffffff', '8133bffffffffff', '81047ffffffffff', + '81f3bffffffffff', '81dbbffffffffff', '8132bffffffffff', + '810cbffffffffff', '81bb3ffffffffff', '81db3ffffffffff', + '81bafffffffffff', '81177ffffffffff', '817fbffffffffff', + '81ba3ffffffffff', '815abffffffffff', '815bbffffffffff', + '81eafffffffffff', '81ed7ffffffffff', '81057ffffffffff', + '819a7ffffffffff', '81eabffffffffff', '819b7ffffffffff', + '81167ffffffffff', '81227ffffffffff', '8171bffffffffff', + '81237ffffffffff', '810dbffffffffff', '81033ffffffffff', + '81f2bffffffffff', '8147bffffffffff', '81f33ffffffffff', + ] + mpoly = h3.cells_to_h3shape(cells, tight=False) + + assert len(mpoly) == 1 + poly = mpoly[0] + assert len(poly.holes) == 0 + assert len(poly.outer) == 117 + + # Roundtrip fails: h3shape_to_cells raises on this global polygon. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + with pytest.raises(H3FailedError): + h3.h3shape_to_cells(mpoly, 1) + + +def test_issue_482_with_antimeridian(): + """From https://github.com/uber/h3-py/issues/482 + + Test three versions: the full set, removal of antimeridian overlaps, and removal + of one cell by the north pole also causing roundtrip issues. + + Roundtrip works after removal of all troublesome cells. + """ + cells0 = { + '8001fffffffffff', '8005fffffffffff', '8009fffffffffff', '800bfffffffffff', + '8011fffffffffff', '8015fffffffffff', '8017fffffffffff', '801ffffffffffff', + '8021fffffffffff', '8025fffffffffff', '802dfffffffffff', '802ffffffffffff', + '8031fffffffffff', '8033fffffffffff', '803dfffffffffff', '803ffffffffffff', + '8041fffffffffff', '8043fffffffffff', '804bfffffffffff', '804ffffffffffff', + '8053fffffffffff', '8059fffffffffff', '8061fffffffffff', '8063fffffffffff', + '8065fffffffffff', '8069fffffffffff', '806bfffffffffff', '8073fffffffffff', + '8077fffffffffff', + } + + # remove cells that overlap the antimeridian + cells1 = cells0 - {'8005fffffffffff', '8017fffffffffff', '8033fffffffffff'} + + # remove cell that is very close to north pole (maybe touches) + cells2 = cells1 - {'8001fffffffffff'} + + # --- cells0: all 29 cells --- + mpoly = h3.cells_to_h3shape(cells0, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip fails: recovers ~23/29, and not even a subset of the original. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells_out = h3.h3shape_to_cells(mpoly, 0) + assert len(cells_out) < len(cells0) # exact count differs by OS + assert not (set(cells_out) <= cells0) + + # --- cells1: remove antimeridian-crossing cells (26 remaining) --- + mpoly = h3.cells_to_h3shape(cells1, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip fails: recovers 18/26, and not even a subset of the original. + # TODO: assert_cells_roundtrip when h3shape_to_cells handles global polygons. + cells_out = h3.h3shape_to_cells(mpoly, 0) + assert len(cells_out) == 18 + assert not (set(cells_out) <= cells1) + + # --- cells2: also remove near-pole cell (25 remaining) --- + mpoly = h3.cells_to_h3shape(cells2, tight=False) + assert len(mpoly) == 1 + assert len(mpoly[0].holes) == 0 + assert len(mpoly[0].outer) == 37 + + # Roundtrip succeeds. + assert_cells_roundtrip(list(cells2)) diff --git a/tests/test_apis/__init__.py b/tests/test_lib/test_apis/__init__.py similarity index 100% rename from tests/test_apis/__init__.py rename to tests/test_lib/test_apis/__init__.py diff --git a/tests/test_apis/test_api_bindings_match.py b/tests/test_lib/test_apis/test_api_bindings_match.py similarity index 100% rename from tests/test_apis/test_api_bindings_match.py rename to tests/test_lib/test_apis/test_api_bindings_match.py diff --git a/tests/test_lib/test_apis/test_basic_int.py b/tests/test_lib/test_apis/test_basic_int.py new file mode 100644 index 0000000..3f3b14c --- /dev/null +++ b/tests/test_lib/test_apis/test_basic_int.py @@ -0,0 +1,56 @@ +import h3.api.basic_int as h3 + + +from .. import util as u + + +def test_int_output(): + lat = 37.7752702151959 + lng = -122.418307270836 + + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + assert h3.latlng_to_cell(lat, lng, 9) == 0x8928308280fffff + + +def test_grid_disk(): + expected = [ + 617700169957507071, + 617700169957769215, + 617700169958031359, + 617700169958293503, + 617700169961177087, + 617700169964847103, + 617700169965109247, + ] + + out = h3.grid_disk(617700169958293503, 1) + assert u.same_set(out, expected) + + +def test_compact_cells(): + h = 617700169958293503 + cells = h3.cell_to_children(h) + + assert h3.compact_cells(cells) == [h] + + +def test_identity_scalar_bindings(): + """ + Ensure scalar functions in int APIs are bound directly to _cy implementations + to eliminate wrapper and identity call overhead (Issue #501). + """ + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex + + # Ensure docstrings and signatures are intact + assert h3.latlng_to_cell.__doc__ is not None + assert 'latlng_to_cell' in h3.latlng_to_cell.__name__ diff --git a/tests/test_apis/test_basic_str.py b/tests/test_lib/test_apis/test_basic_str.py similarity index 57% rename from tests/test_apis/test_basic_str.py rename to tests/test_lib/test_apis/test_basic_str.py index 0c65a82..fccc164 100644 --- a/tests/test_apis/test_basic_str.py +++ b/tests/test_lib/test_apis/test_basic_str.py @@ -22,3 +22,22 @@ def test5(): out = h3.grid_disk('8928308280fffff', 1) assert u.same_set(out, expected) + + +def test_string_subtypes(): + + class my_str(str): + pass + + expected = [ + '89283082873ffff', + '89283082877ffff', + '8928308283bffff', + '89283082807ffff', + '8928308280bffff', + '8928308280fffff', + '89283082803ffff' + ] + + out = h3.grid_disk(my_str('8928308280fffff'), 1) + assert u.same_set(out, expected) diff --git a/tests/test_apis/test_collection_inputs.py b/tests/test_lib/test_apis/test_collection_inputs.py similarity index 100% rename from tests/test_apis/test_collection_inputs.py rename to tests/test_lib/test_apis/test_collection_inputs.py diff --git a/tests/test_apis/test_ico_faces.py b/tests/test_lib/test_apis/test_ico_faces.py similarity index 100% rename from tests/test_apis/test_ico_faces.py rename to tests/test_lib/test_apis/test_ico_faces.py diff --git a/tests/test_lib/test_apis/test_memview_int.py b/tests/test_lib/test_apis/test_memview_int.py new file mode 100644 index 0000000..f608f54 --- /dev/null +++ b/tests/test_lib/test_apis/test_memview_int.py @@ -0,0 +1,39 @@ +import h3.api.memview_int as h3 + + +def test1(): + lat, lng = 37.7752702151959, -122.418307270836 + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + + +def test_line(): + h1 = '8928308280fffff' + h2 = '8928308287bffff' + h1, h2 = h3.str_to_int(h1), h3.str_to_int(h2) + + out = h3.grid_path_cells(h1, h2) + + # todo: are we outputting `memoryviewslice`? should we just output a memoryview? + assert 'memoryview' in str(type(out)) + + expected = [ + 617700169958293503, + 617700169964847103, + 617700169965371391, + ] + + assert list(out) == expected + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex diff --git a/tests/test_lib/test_apis/test_numpy_int.py b/tests/test_lib/test_apis/test_numpy_int.py new file mode 100644 index 0000000..6bcd0b6 --- /dev/null +++ b/tests/test_lib/test_apis/test_numpy_int.py @@ -0,0 +1,66 @@ +import h3.api.numpy_int as h3 +import numpy as np # only run this test suite if numpy is installed + +from .. import util as u + + +def test1(): + lat, lng = ( + 37.7752702151959, + -122.418307270836, + ) + assert h3.latlng_to_cell(lat, lng, 9) == 617700169958293503 + + +def test5(): + expected = { + 617700169957507071, + 617700169957769215, + 617700169958031359, + 617700169958293503, + 617700169961177087, + 617700169964847103, + 617700169965109247, + } + + out = h3.grid_disk(617700169958293503, 1) + assert isinstance(out, np.ndarray) + assert u.same_set(out, expected) + + +def test_compact_cells(): + h = 617700169958293503 + cells = h3.cell_to_children(h) + assert isinstance(cells, np.ndarray) + + assert h3.compact_cells(cells) == [h] + + +def test_numpy_str(): + expected = [ + 617700169957507071, + 617700169957769215, + 617700169958031359, + 617700169958293503, + 617700169961177087, + 617700169964847103, + 617700169965109247, + ] + cells = np.array([h3.int_to_str(h) for h in expected]) + got = [h3.str_to_int(c) for c in cells] + + assert expected == got + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex diff --git a/tests/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py similarity index 73% rename from tests/test_cells_and_edges.py rename to tests/test_lib/test_cells_and_edges.py index d23ff4d..65d9d13 100644 --- a/tests/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -8,6 +8,10 @@ from h3 import ( H3ResMismatchError, H3CellInvalidError, H3NotNeighborsError, + H3DigitDomainError, + H3BaseCellDomainError, + H3DeletedDigitError, + H3IndexInvalidError, ) @@ -127,9 +131,7 @@ def test_parent_err(): except Exception as e: msg = str(e) - # todo: revist this weird formatting stuff - expected = 'Invalid parent resolution -1 for cell {}.' - expected = expected.format(hex(h3.str_to_int(h))) + expected = f'Invalid parent resolution -1 for cell 0x{h}.' assert msg == expected @@ -289,11 +291,11 @@ def test_average_hexagon_area(): def test_average_hexagon_edge_length(): expected_in_km = { - 0: 1107.712591000, - 1: 418.676005500, - 2: 158.244655800, - 9: 0.174375668, - 15: 0.000509713, + 0: 1281.256011, + 1: 483.0568391, + 2: 182.5129565, + 9: 0.200786148, + 15: 0.000584169, } out = { @@ -452,8 +454,12 @@ def test_versions(): v_c = Version(v['c']) v_p = Version(v['python']) - # of X.Y.Z, X and Y must match - assert v_c.release[:2] == v_p.release[:2] + # For all releases (including pre-release), major version must match + assert v_c.release[0] == v_p.release[0] + + if not v_p.is_prerelease: # pragma: no cover + # of X.Y.Z, X and Y must match + assert v_c.release[:2] == v_p.release[:2] def test_str_int_convert(): @@ -474,6 +480,14 @@ def test_edge_is_valid_fail(): assert not h3.is_valid_directed_edge(e_invalid) +def test_is_valid_out_of_uint64_range(): + for h in ['10000000000000000', '-1']: + assert not h3.is_valid_index(h) + assert not h3.is_valid_cell(h) + assert not h3.is_valid_directed_edge(h) + assert not h3.is_valid_vertex(h) + + def test_get_pentagons(): out = h3.get_pentagons(0) @@ -597,3 +611,163 @@ def test_to_local_ij_self(): out = h3.cell_to_local_ij(h, h) assert out == (-858, -2766) + + +def test_is_valid_index(): + assert h3.is_valid_index('8001fffffffffff') + assert not h3.is_valid_index('8a28308280fffff') + assert not h3.is_valid_index(123) + assert not h3.is_valid_index('abcd') + + +def test_is_valid_index_2(): + import h3.api.basic_int as h3 + + h = h3.latlng_to_cell(0,0,9) + assert h3.is_valid_index(h) + assert not h3.is_valid_index(h + 1) + assert not h3.is_valid_directed_edge(h) + assert not h3.is_valid_vertex(h) + + e = h3.origin_to_directed_edges(h)[0] + assert h3.is_valid_index(e) + assert not h3.is_valid_index(e + 1) + assert not h3.is_valid_cell(e) + assert not h3.is_valid_vertex(e) + + v = h3.cell_to_vertex(h, 0) + assert h3.is_valid_index(v) + assert not h3.is_valid_index(v + 1) + assert not h3.is_valid_cell(v) + assert not h3.is_valid_directed_edge(v) + + +def test_get_index_digit(): + assert h3.get_index_digit('822377fffffffff', 1) == 5 + assert h3.get_index_digit('822377fffffffff', 2) == 6 + assert h3.get_index_digit('822377fffffffff', 3) == 7 + assert h3.get_index_digit('822377fffffffff', 15) == 7 + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff', 16) + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff', 0) + + with pytest.raises(H3ResDomainError): + h3.get_index_digit('822377fffffffff',-1) + + +def test_get_index_digit_non_cells(): + h = h3.construct_cell(111, 3, 6, 4) + assert h == '83def4fffffffff' + + e = h3.origin_to_directed_edges(h)[0] + assert e == '113def4fffffffff' + assert h3.is_valid_directed_edge(e) + assert h3.get_index_digit(e, 1) == 3 + assert h3.get_index_digit(e, 2) == 6 + assert h3.get_index_digit(e, 3) == 4 + + e = h3.int_to_str(1 + h3.str_to_int(e)) + assert not h3.is_valid_directed_edge(e) + assert not h3.is_valid_index(e) + with pytest.raises(H3IndexInvalidError): + h3.get_index_digit(e, 1) + + v = h3.cell_to_vertexes(h)[0] + assert v == '223de1afffffffff' + assert h3.is_valid_vertex(v) + assert h3.get_index_digit(v, 1) == 0 + assert h3.get_index_digit(v, 2) == 3 + assert h3.get_index_digit(v, 3) == 2 + + v = h3.int_to_str(1 + h3.str_to_int(v)) + assert not h3.is_valid_vertex(v) + assert not h3.is_valid_index(v) + with pytest.raises(H3IndexInvalidError): + h3.get_index_digit(v, 1) + + +def test_construct_cell(): + bc = 17 + assert h3.construct_cell(bc, 5, 6) == '822377fffffffff' + assert h3.construct_cell(bc) == '8023fffffffffff' + + digits = [0] * 15 + assert h3.construct_cell(bc, *digits) == '8f2200000000000' + + with pytest.raises(H3ResDomainError): + digits = [0] * 16 + h3.construct_cell(bc, *digits) + + with pytest.raises(ValueError): + digits = [1,2,3,4] + h3.construct_cell(bc, *digits, res=2) + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, 1, 7) # 7 is not a valid digit + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, 45) # 45 is not a valid digit + + with pytest.raises(H3DigitDomainError): + h3.construct_cell(121, -1) # -1 is not a valid digit + + with pytest.raises(H3BaseCellDomainError): + h3.construct_cell(122) # one past last base cell number + + with pytest.raises(H3DeletedDigitError): + # 4 is a pentagon base cell. first nonzero digit can't be a 1 + h3.construct_cell(4, 1) + + with pytest.raises(H3DeletedDigitError): + # 4 is a pentagon base cell. first nonzero digit can't be a 1 + h3.construct_cell(4, 0,0,0, 0, 1) + + +def test_deconstruct_cell(): + h = '822377fffffffff' + assert h3.deconstruct_cell(h) == [17, 5, 6] + + +def test_construct_cell_inverses(): + # demonstrate functions are inverses of each other + + h = '8ff3ac688d63446' + components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6] + + assert h3.construct_cell(*components) == h + assert h3.deconstruct_cell(h) == components + + assert h3.construct_cell(*h3.deconstruct_cell(h)) == h + assert h3.deconstruct_cell(h3.construct_cell(*components)) == components + + +def test_construct_cell_inverses_int_api(): + # same inverse test as above, but in int api + import h3.api.basic_int as h3 + + h = 0x8ff3ac688d63446 + components = [121, 6, 5, 4, 3, 2, 1, 0, 6, 5, 4, 3, 2, 1, 0, 6] + + assert h3.construct_cell(*components) == h + assert h3.deconstruct_cell(h) == components + + assert h3.construct_cell(*h3.deconstruct_cell(h)) == h + assert h3.deconstruct_cell(h3.construct_cell(*components)) == components + + +def test_center_child_with_deconstruct(): + for h in h3.get_res0_cells(): + h3.construct_cell(*h3.deconstruct_cell(h), 0) == h3.cell_to_center_child(h) + + +def test_uncompact_cells_invalid_resolution(): + # Create a valid cell at resolution 5 + h_res5 = h3.latlng_to_cell(0, 0, 5) + + # Attempting to uncompact to a coarser resolution (4) + # should raise an H3ResMismatchError + with pytest.raises(H3ResMismatchError): + h3.uncompact_cells({h_res5}, 4) diff --git a/tests/test_error_codes.py b/tests/test_lib/test_error_codes.py similarity index 65% rename from tests/test_error_codes.py rename to tests/test_lib/test_error_codes.py index 9961178..4ae1d37 100644 --- a/tests/test_error_codes.py +++ b/tests/test_lib/test_error_codes.py @@ -1,6 +1,10 @@ import pytest import h3 +from h3._cy import ( + error_code_to_exception, + get_H3_ERROR_END, +) # todo: maybe check the `check_for_error` function behavior directly? @@ -12,24 +16,30 @@ h3_exceptions = { h3.H3GridNavigationError: None, h3.H3MemoryError: None, h3.H3ValueError: None, - - h3.H3FailedError: 1, - h3.H3DomainError: 2, - h3.H3LatLngDomainError: 3, - h3.H3ResDomainError: 4, - h3.H3CellInvalidError: 5, - h3.H3DirEdgeInvalidError: 6, - h3.H3UndirEdgeInvalidError: 7, - h3.H3VertexInvalidError: 8, - h3.H3PentagonError: 9, - h3.H3DuplicateInputError: 10, - h3.H3NotNeighborsError: 11, - h3.H3ResMismatchError: 12, - h3.H3MemoryAllocError: 13, - h3.H3MemoryBoundsError: 14, - h3.H3OptionInvalidError: 15, } +for e in range(1, get_H3_ERROR_END()): + ex = error_code_to_exception(e) + h3_exceptions[ex] = e + + +def test_num_error_codes(): + assert get_H3_ERROR_END() >= 20 + assert error_code_to_exception(19) == h3.H3DeletedDigitError + + # H3_ERROR_END (and beyond) shouldn't be a valid error code + code = get_H3_ERROR_END() + assert isinstance( + error_code_to_exception(code), + h3.UnknownH3ErrorCode + ) + + code = get_H3_ERROR_END() + 1 + assert isinstance( + error_code_to_exception(code), + h3.UnknownH3ErrorCode + ) + def test_error_codes_match(): """ diff --git a/tests/test_lib/test_geojson_containers.py b/tests/test_lib/test_geojson_containers.py new file mode 100644 index 0000000..a890c27 --- /dev/null +++ b/tests/test_lib/test_geojson_containers.py @@ -0,0 +1,62 @@ +import pytest +from h3._h3shape import LatLngPoly, h3shape_to_geo, LatLngMultiPoly + + +def test_h3shape_to_geo_containers(): + # Create a basic dummy polygon for testing + poly = LatLngPoly( + [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)] + ) + + # Test 'auto' (Default behavior should return a Polygon) + auto_geo = h3shape_to_geo(poly, container='auto') + assert auto_geo['type'] == 'Polygon' + + # Test MultiPolygon wrapper + mp_geo = h3shape_to_geo(poly, container='MultiPolygon') + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 + + # Test Feature wrapper + feat_geo = h3shape_to_geo(poly, container='Feature') + assert feat_geo['type'] == 'Feature' + assert feat_geo['geometry']['type'] == 'Polygon' + + # Test FeatureCollection wrapper + fc_geo = h3shape_to_geo(poly, container='FeatureCollection') + assert fc_geo['type'] == 'FeatureCollection' + assert len(fc_geo['features']) == 1 + assert fc_geo['features'][0]['type'] == 'Feature' + assert fc_geo['features'][0]['geometry']['type'] == 'Polygon' + + # Test GeometryCollection wrapper + gc_geo = h3shape_to_geo(poly, container='GeometryCollection') + assert gc_geo['type'] == 'GeometryCollection' + assert len(gc_geo['geometries']) == 1 + assert gc_geo['geometries'][0]['type'] == 'Polygon' + + +def test_h3shape_to_geo_invalid_containers(): + # 1. Test an unknown container string + poly = LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + with pytest.raises(ValueError, match='invalid or insufficient'): + h3shape_to_geo(poly, container='InvalidString') + + # 2. Test an insufficient container (MultiPolygon data into a Polygon container) + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) + with pytest.raises(ValueError, match='invalid or insufficient'): + h3shape_to_geo(mpoly, container='Polygon') + + +def test_h3shape_to_geo_exact_match(): + # Test that requesting a MultiPolygon for MultiPolygon data succeeds + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) + + mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon') + + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 diff --git a/tests/test_h3.py b/tests/test_lib/test_h3.py similarity index 100% rename from tests/test_h3.py rename to tests/test_lib/test_h3.py diff --git a/tests/test_length_area.py b/tests/test_lib/test_length_area.py similarity index 80% rename from tests/test_length_area.py rename to tests/test_lib/test_length_area.py index 1003f56..ca38257 100644 --- a/tests/test_length_area.py +++ b/tests/test_lib/test_length_area.py @@ -86,6 +86,30 @@ def test_areas_at_00(): assert u.approx2(out, areas_rads2) +def test_average_hexagon_area_rads(): + # the ratio between km^2 and rads^2 should match the one used by cell_area + h = '89754e64993ffff' + ratio = h3.cell_area(h, unit='km^2') / h3.cell_area(h, unit='rads^2') + + for res in range(16): + km2 = h3.average_hexagon_area(res, unit='km^2') + rads2 = h3.average_hexagon_area(res, unit='rads^2') + + assert km2 / rads2 == pytest.approx(ratio) + + +def test_average_hexagon_edge_length_rads(): + # the ratio between km and rads should match the one used by edge_length + e = '139754e64993ffff' + ratio = h3.edge_length(e, unit='km') / h3.edge_length(e, unit='rads') + + for res in range(16): + km = h3.average_hexagon_edge_length(res, unit='km') + rads = h3.average_hexagon_edge_length(res, unit='rads') + + assert km / rads == pytest.approx(ratio) + + def test_bad_units(): h = '89754e64993ffff' e = '139754e64993ffff' diff --git a/tests/util.py b/tests/test_lib/util.py similarity index 100% rename from tests/util.py rename to tests/test_lib/util.py