portolan-python 0.1.0__tar.gz

portolan_python-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install build and test tools
+        run: python -m pip install --upgrade build twine ".[dev]"
+
+      - name: Check tag and package versions
+        shell: bash
+        run: |
+          package_version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          test "${GITHUB_REF_NAME}" = "v${package_version}"
+
+      - name: Test
+        run: pytest
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Preserve distributions for PyPI
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Create GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "${GITHUB_REF_NAME}" dist/* --generate-notes --verify-tag
+
+  publish-pypi:
+    needs: release
+    if: vars.PUBLISH_PYPI == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

portolan_python-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]

portolan_python-0.1.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: help setup test coverage lint typecheck check build clean
+
+UV ?= uv
+
+help:
+	@printf '%s\n' 'Targets: setup test coverage lint typecheck check build clean'
+
+setup:
+	$(UV) sync --extra dev
+
+test:
+	$(UV) run --extra dev pytest
+
+coverage:
+	$(UV) run --extra dev pytest --cov=portolan --cov-report=term-missing
+
+lint:
+	$(UV) run --extra dev ruff check .
+
+typecheck:
+	$(UV) run --extra dev mypy
+
+check: lint typecheck test
+
+build:
+	$(UV) build
+
+clean:
+	rm -rf dist build *.egg-info .pytest_cache .ruff_cache .mypy_cache htmlcov

portolan_python-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.5
+Name: portolan-python
+Version: 0.1.0
+Summary: A lightweight Python implementation of the Portolan specification.
+Author: Portolan contributors
+License: Apache-2.0
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.18.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.13.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Portolan Python
+
+A lightweight Python implementation of the Portolan specification.
+
+`portolan-python` provides the core domain model, catalog access, validation, and conformance APIs required to work with Portolan catalogs from Python applications.
+
+The project intentionally focuses on **Portolan itself**, rather than on geospatial data processing.
+
+It does not aim to replace GDAL, Rasterio, GeoPandas, GeoParquet tooling, tile generators, GIS servers, or other specialized geospatial software.
+
+## Motivation
+
+Portolan defines an opinionated way of organizing and describing cloud-native geospatial data using existing standards and formats such as STAC, GeoParquet, COG, PMTiles, COPC, and Zarr.
+
+Applications integrating with Portolan need a reliable implementation of that contract.
+
+Without a reusable core library, every integration would need to independently implement:
+
+* Portolan catalog semantics;
+* STAC traversal;
+* collection and asset handling;
+* Portolan-specific requirements;
+* link and HREF resolution;
+* metadata validation;
+* conformance rules;
+* serialization and deserialization.
+
+`portolan-python` provides that reusable implementation.
+
+The core design principle is:
+
+> **Portolan defines the contract. Specialized tools implement data processing.**
+
+For example, this library may determine that an asset is a GeoParquet asset and expose its URI and metadata. It does not need to read the GeoParquet rows itself.
+
+Likewise, it may identify a COG asset without becoming a raster processing library.
+
+## Scope
+
+`portolan-python` is responsible for the Portolan domain model and specification semantics.
+
+Expected responsibilities include:
+
+* opening Portolan catalogs;
+* creating Portolan catalogs;
+* reading and writing Portolan/STAC metadata;
+* navigating catalogs, collections, items, assets, and links;
+* resolving relative and absolute HREFs;
+* exposing Portolan extensions and metadata;
+* validating Portolan structures;
+* checking Portolan conformance;
+* exposing asset type and media-type information;
+* handling specification versions;
+* providing stable Python APIs for applications built on Portolan.
+
+A conceptual API may look like:
+
+```python
+from portolan import Catalog
+
+catalog = Catalog.open("https://example.com/catalog.json")
+
+for collection in catalog.collections():
+    print(collection.id)
+
+    for asset in collection.assets():
+        print(asset.href)
+        print(asset.media_type)
+        print(asset.roles)
+```
+
+Validation should similarly be available programmatically:
+
+```python
+from portolan import Catalog, Validator
+
+catalog = Catalog.open("./catalog.json")
+
+result = Validator.validate(catalog)
+
+if not result.valid:
+    for error in result.errors:
+        print(error)
+```
+
+The exact API will evolve during implementation, but it should remain small, explicit, typed, and independent from any CLI.
+
+## Non-goals
+
+This project should **not** become a general-purpose geospatial processing library.
+
+In particular, the core should not be responsible for:
+
+* reading GeoParquet feature data;
+* writing GeoParquet datasets;
+* converting Shapefile to GeoParquet;
+* creating COGs;
+* reading raster pixels;
+* creating PMTiles;
+* processing COPC;
+* converting MrSID or ECW;
+* extracting data from WFS;
+* extracting data from ArcGIS;
+* extracting data from CARTO;
+* publishing data to GeoServer;
+* running pygeoapi;
+* managing QGIS projects.
+
+Those capabilities belong to specialized libraries, applications, or optional integrations.
+
+Portolan should be opinionated about **what constitutes a conformant Portolan catalog and asset**, not unnecessarily opinionated about **which software must produce or consume those assets**.
+
+## Architecture
+
+```text
+                    Portolan Specification
+                             │
+                             ▼
+                      portolan-python
+                   ┌────────────────────┐
+                   │ Domain model       │
+                   │ Catalog access     │
+                   │ STAC semantics     │
+                   │ Portolan semantics │
+                   │ HREF resolution    │
+                   │ Validation         │
+                   │ Conformance        │
+                   └─────────┬──────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              ▼              ▼              ▼
+         portolan-cli   portolan-geoserver  other apps
+```
+
+## Relationship with `portolan-cli`
+
+`portolan-cli` should consume this library rather than implement Portolan domain logic itself.
+
+For example:
+
+```text
+portolan validate
+portolan inspect
+portolan registry list
+```
+
+should be CLI representations of APIs provided by the Portolan Python ecosystem.
+
+The CLI should remain an interface layer.
+
+## Relationship with `portolan-geoserver`
+
+`portolan-geoserver` uses this library to understand Portolan catalogs and uses `python-geoservercloud` to interact with GeoServer.
+
+The responsibilities remain separated:
+
+```text
+portolan-python
+    │
+    │ understands Portolan
+    ▼
+portolan-geoserver
+    │
+    │ maps Portolan resources to GeoServer
+    ▼
+python-geoservercloud
+    │
+    │ manages GeoServer
+    ▼
+GeoServer
+```
+
+`portolan-python` therefore contains no GeoServer-specific logic.
+
+## Relationship with `portolan-java`
+
+`portolan-java` is the Java counterpart of this project.
+
+The two libraries should implement the same **conceptual Portolan contract**, while following the conventions of their respective languages.
+
+They should not necessarily expose identical classes or method signatures.
+
+The Portolan specification remains the source of truth.
+
+```text
+                 Portolan Specification
+                    /             \
+                   /               \
+          portolan-python      portolan-java
+```
+
+## Design principles
+
+1. Specification first.
+2. Small and stable public API.
+3. No CLI dependency.
+4. No GIS server dependency.
+5. No mandatory geospatial processing stack.
+6. Specialized formats are represented, not reimplemented.
+7. External applications should not need to reimplement Portolan semantics.
+8. The library should be suitable as a dependency of long-lived applications.
+
+## Local documentation
+
+- [Scope](docs/scope.md) defines what belongs in this core library.
+- [Examples](docs/examples.md) shows basic API usage.
+- [Development](docs/development.md) lists setup, test, and build commands.
+- [Distribution](docs/distribution.md) explains releases, `pip`, and PyPI publishing.
+
+---

portolan_python-0.1.0/README.md

@@ -0,0 +1,210 @@
+# Portolan Python
+
+A lightweight Python implementation of the Portolan specification.
+
+`portolan-python` provides the core domain model, catalog access, validation, and conformance APIs required to work with Portolan catalogs from Python applications.
+
+The project intentionally focuses on **Portolan itself**, rather than on geospatial data processing.
+
+It does not aim to replace GDAL, Rasterio, GeoPandas, GeoParquet tooling, tile generators, GIS servers, or other specialized geospatial software.
+
+## Motivation
+
+Portolan defines an opinionated way of organizing and describing cloud-native geospatial data using existing standards and formats such as STAC, GeoParquet, COG, PMTiles, COPC, and Zarr.
+
+Applications integrating with Portolan need a reliable implementation of that contract.
+
+Without a reusable core library, every integration would need to independently implement:
+
+* Portolan catalog semantics;
+* STAC traversal;
+* collection and asset handling;
+* Portolan-specific requirements;
+* link and HREF resolution;
+* metadata validation;
+* conformance rules;
+* serialization and deserialization.
+
+`portolan-python` provides that reusable implementation.
+
+The core design principle is:
+
+> **Portolan defines the contract. Specialized tools implement data processing.**
+
+For example, this library may determine that an asset is a GeoParquet asset and expose its URI and metadata. It does not need to read the GeoParquet rows itself.
+
+Likewise, it may identify a COG asset without becoming a raster processing library.
+
+## Scope
+
+`portolan-python` is responsible for the Portolan domain model and specification semantics.
+
+Expected responsibilities include:
+
+* opening Portolan catalogs;
+* creating Portolan catalogs;
+* reading and writing Portolan/STAC metadata;
+* navigating catalogs, collections, items, assets, and links;
+* resolving relative and absolute HREFs;
+* exposing Portolan extensions and metadata;
+* validating Portolan structures;
+* checking Portolan conformance;
+* exposing asset type and media-type information;
+* handling specification versions;
+* providing stable Python APIs for applications built on Portolan.
+
+A conceptual API may look like:
+
+```python
+from portolan import Catalog
+
+catalog = Catalog.open("https://example.com/catalog.json")
+
+for collection in catalog.collections():
+    print(collection.id)
+
+    for asset in collection.assets():
+        print(asset.href)
+        print(asset.media_type)
+        print(asset.roles)
+```
+
+Validation should similarly be available programmatically:
+
+```python
+from portolan import Catalog, Validator
+
+catalog = Catalog.open("./catalog.json")
+
+result = Validator.validate(catalog)
+
+if not result.valid:
+    for error in result.errors:
+        print(error)
+```
+
+The exact API will evolve during implementation, but it should remain small, explicit, typed, and independent from any CLI.
+
+## Non-goals
+
+This project should **not** become a general-purpose geospatial processing library.
+
+In particular, the core should not be responsible for:
+
+* reading GeoParquet feature data;
+* writing GeoParquet datasets;
+* converting Shapefile to GeoParquet;
+* creating COGs;
+* reading raster pixels;
+* creating PMTiles;
+* processing COPC;
+* converting MrSID or ECW;
+* extracting data from WFS;
+* extracting data from ArcGIS;
+* extracting data from CARTO;
+* publishing data to GeoServer;
+* running pygeoapi;
+* managing QGIS projects.
+
+Those capabilities belong to specialized libraries, applications, or optional integrations.
+
+Portolan should be opinionated about **what constitutes a conformant Portolan catalog and asset**, not unnecessarily opinionated about **which software must produce or consume those assets**.
+
+## Architecture
+
+```text
+                    Portolan Specification
+                             │
+                             ▼
+                      portolan-python
+                   ┌────────────────────┐
+                   │ Domain model       │
+                   │ Catalog access     │
+                   │ STAC semantics     │
+                   │ Portolan semantics │
+                   │ HREF resolution    │
+                   │ Validation         │
+                   │ Conformance        │
+                   └─────────┬──────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              ▼              ▼              ▼
+         portolan-cli   portolan-geoserver  other apps
+```
+
+## Relationship with `portolan-cli`
+
+`portolan-cli` should consume this library rather than implement Portolan domain logic itself.
+
+For example:
+
+```text
+portolan validate
+portolan inspect
+portolan registry list
+```
+
+should be CLI representations of APIs provided by the Portolan Python ecosystem.
+
+The CLI should remain an interface layer.
+
+## Relationship with `portolan-geoserver`
+
+`portolan-geoserver` uses this library to understand Portolan catalogs and uses `python-geoservercloud` to interact with GeoServer.
+
+The responsibilities remain separated:
+
+```text
+portolan-python
+    │
+    │ understands Portolan
+    ▼
+portolan-geoserver
+    │
+    │ maps Portolan resources to GeoServer
+    ▼
+python-geoservercloud
+    │
+    │ manages GeoServer
+    ▼
+GeoServer
+```
+
+`portolan-python` therefore contains no GeoServer-specific logic.
+
+## Relationship with `portolan-java`
+
+`portolan-java` is the Java counterpart of this project.
+
+The two libraries should implement the same **conceptual Portolan contract**, while following the conventions of their respective languages.
+
+They should not necessarily expose identical classes or method signatures.
+
+The Portolan specification remains the source of truth.
+
+```text
+                 Portolan Specification
+                    /             \
+                   /               \
+          portolan-python      portolan-java
+```
+
+## Design principles
+
+1. Specification first.
+2. Small and stable public API.
+3. No CLI dependency.
+4. No GIS server dependency.
+5. No mandatory geospatial processing stack.
+6. Specialized formats are represented, not reimplemented.
+7. External applications should not need to reimplement Portolan semantics.
+8. The library should be suitable as a dependency of long-lived applications.
+
+## Local documentation
+
+- [Scope](docs/scope.md) defines what belongs in this core library.
+- [Examples](docs/examples.md) shows basic API usage.
+- [Development](docs/development.md) lists setup, test, and build commands.
+- [Distribution](docs/distribution.md) explains releases, `pip`, and PyPI publishing.
+
+---

portolan_python-0.1.0/docs/development.md

@@ -0,0 +1,40 @@
+# Development
+
+The project uses `uv` for dependency management and build isolation.
+
+## Setup
+
+```bash
+make setup
+```
+
+This installs runtime and development dependencies from `pyproject.toml`.
+
+## Test and check
+
+```bash
+make test
+make lint
+make typecheck
+make check
+```
+
+`make check` runs lint, type checking, and the test suite. The test command also
+enforces the configured coverage floor.
+
+## Build
+
+```bash
+make build
+```
+
+The build target creates source and wheel distributions in `dist/`.
+
+## Clean local artifacts
+
+```bash
+make clean
+```
+
+This removes local build, cache, and coverage directories. It does not remove
+source files or the virtual environment.

portolan_python-0.1.0/docs/distribution.md

@@ -0,0 +1,54 @@
+# Distribution
+
+Tagged releases provide immutable Python source and wheel archives. PyPI is the
+preferred package index once its trusted publisher is configured.
+
+## Release artifacts
+
+Push a tag that matches the version in `pyproject.toml`:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The release workflow runs the tests, builds both distributions, checks their
+metadata, and creates a GitHub release. It attaches the `.whl` and `.tar.gz`
+files to that release.
+
+The workflow rejects a tag that does not match the project version. Change the
+version in `pyproject.toml` before the next release.
+
+## Install from GitHub
+
+Install the wheel attached to a release:
+
+```bash
+python -m pip install \
+  https://github.com/jemacchi/portolan-python/releases/download/v0.1.0/portolan_python-0.1.0-py3-none-any.whl
+```
+
+This path needs no package index account.
+
+## Publish to PyPI
+
+The workflow supports PyPI trusted publishing. It uses a short-lived identity
+token, so the repository does not store a permanent PyPI API token.
+
+Complete these steps once:
+
+1. Create the `portolan-python` project on PyPI, or add a pending publisher.
+2. Add a trusted GitHub publisher for `jemacchi/portolan-python`.
+3. Set the workflow name to `release.yml` and the environment to `pypi`.
+4. Create the `pypi` environment in the GitHub repository.
+5. Add the repository variable `PUBLISH_PYPI` with the value `true`.
+
+After this setup, each valid version tag also publishes to PyPI. Consumers can
+then use the normal command:
+
+```bash
+python -m pip install portolan-python==0.1.0
+```
+
+PyPI does not permit replacing a published version. Increase the version before
+you publish another release.