portolan-python 0.1.0__py3-none-any.whl

portolan/__init__.py

@@ -0,0 +1,29 @@
+"""Public API for Portolan catalog access."""
+
+from __future__ import annotations
+
+from portolan.catalog import Asset, AssetFormat, Catalog, Collection, Item, Link, is_stac_metadata
+from portolan.registry import (
+    DEFAULT_REGISTRY_URL,
+    RegistryCatalogEntry,
+    download_registry_catalog,
+    load_registry_entries,
+)
+from portolan.validation import ValidationError, ValidationResult, Validator
+
+__all__ = [
+    "Asset",
+    "AssetFormat",
+    "Catalog",
+    "Collection",
+    "DEFAULT_REGISTRY_URL",
+    "Item",
+    "Link",
+    "RegistryCatalogEntry",
+    "ValidationError",
+    "ValidationResult",
+    "Validator",
+    "download_registry_catalog",
+    "is_stac_metadata",
+    "load_registry_entries",
+]

portolan/catalog.py

@@ -0,0 +1,307 @@
+"""Domain model and catalog traversal for Portolan/STAC catalogs."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any
+from urllib.parse import unquote, urljoin, urlparse
+from urllib.request import Request, urlopen
+
+JsonObject = dict[str, Any]
+STAC_DOCUMENT_TYPES = frozenset({"Catalog", "Collection", "Feature"})
+
+
+class AssetFormat(Enum):
+    """Known cloud-native asset formats represented by Portolan catalogs."""
+
+    GEOPARQUET = "GeoParquet"
+    COG = "COG"
+    PMTILES = "PMTiles"
+    UNKNOWN = "Unknown"
+
+
+@dataclass(frozen=True)
+class Link:
+    """A STAC link with its HREF resolved against the containing document."""
+
+    rel: str
+    href: str
+    media_type: str | None
+    title: str | None
+    raw: JsonObject
+
+
+@dataclass(frozen=True)
+class Asset:
+    """A STAC asset with Portolan-friendly accessors."""
+
+    key: str
+    href: str
+    media_type: str | None
+    roles: tuple[str, ...]
+    title: str | None
+    description: str | None
+    raw: JsonObject
+
+    @property
+    def format(self) -> AssetFormat:
+        """Return the known Portolan asset format, without reading the asset bytes."""
+        media_type = self.media_type or ""
+        href_path = urlparse(self.href).path.lower()
+        if media_type == "application/vnd.apache.parquet" or href_path.endswith(".parquet"):
+            return AssetFormat.GEOPARQUET
+        if (
+            media_type == "image/tiff; application=geotiff; profile=cloud-optimized"
+            or href_path.endswith((".tif", ".tiff"))
+        ):
+            return AssetFormat.COG
+        if media_type == "application/vnd.pmtiles" or href_path.endswith(".pmtiles"):
+            return AssetFormat.PMTILES
+        return AssetFormat.UNKNOWN
+
+
+class Catalog:
+    """A loaded Portolan catalog root."""
+
+    def __init__(self, data: JsonObject, href: str) -> None:
+        self._data = data
+        self._href = href
+
+    @classmethod
+    def open(cls, source: str | Path) -> Catalog:
+        """Open a local or remote Portolan catalog document."""
+        href = _source_to_href(source)
+        data = _read_json_href(href)
+        return cls(data, href)
+
+    @property
+    def id(self) -> str:
+        return str(self._data.get("id", ""))
+
+    @property
+    def href(self) -> str:
+        return self._href
+
+    @property
+    def data(self) -> JsonObject:
+        return dict(self._data)
+
+    def links(self) -> Iterator[Link]:
+        yield from _links(self._data, self._href)
+
+    def collections(self) -> Iterator[Collection]:
+        """Yield child collections, including collections below child catalogs."""
+        yield from _collections_from_catalog(self._data, self._href, set())
+
+    def item_links(self) -> Iterator[Link]:
+        """Yield item links owned by this catalog subtree."""
+        yield from _item_links_from_document(self._data, self._href, set())
+
+
+class Collection:
+    """A loaded STAC Collection within a Portolan catalog."""
+
+    def __init__(self, data: JsonObject, href: str) -> None:
+        self._data = data
+        self._href = href
+
+    @classmethod
+    def open(cls, source: str | Path) -> Collection:
+        """Open a local or remote STAC Collection document."""
+        href = _source_to_href(source, default_document="collection.json")
+        data = _read_json_href(href)
+        return cls(data, href)
+
+    @property
+    def id(self) -> str:
+        return str(self._data.get("id", ""))
+
+    @property
+    def href(self) -> str:
+        return self._href
+
+    @property
+    def data(self) -> JsonObject:
+        return dict(self._data)
+
+    def links(self) -> Iterator[Link]:
+        yield from _links(self._data, self._href)
+
+    def assets(self) -> Iterator[Asset]:
+        yield from _assets(self._data, self._href)
+
+    def items(self) -> Iterator[Item]:
+        """Yield linked items from this collection."""
+        for link in self.item_links():
+            data = _read_json_href(link.href)
+            if data.get("type") == "Feature":
+                yield Item(data, link.href)
+
+    def item_links(self) -> Iterator[Link]:
+        """Yield item links owned by this collection.
+
+        A collection can group items behind child catalogs. Those items still
+        belong to the collection, so traversal follows child catalogs and stops
+        at child collections.
+        """
+        yield from _item_links_from_document(self._data, self._href, set())
+
+
+class Item:
+    """A loaded STAC Item."""
+
+    def __init__(self, data: JsonObject, href: str) -> None:
+        self._data = data
+        self._href = href
+
+    @classmethod
+    def open(cls, source: str | Path) -> Item:
+        """Open a local or remote STAC Item document."""
+        href = _source_to_href(source, default_document="item.json")
+        data = _read_json_href(href)
+        return cls(data, href)
+
+    @property
+    def id(self) -> str:
+        return str(self._data.get("id", ""))
+
+    @property
+    def href(self) -> str:
+        return self._href
+
+    @property
+    def data(self) -> JsonObject:
+        return dict(self._data)
+
+    def links(self) -> Iterator[Link]:
+        yield from _links(self._data, self._href)
+
+    def assets(self) -> Iterator[Asset]:
+        yield from _assets(self._data, self._href)
+
+
+def is_stac_metadata(source: str | Path) -> bool:
+    """Return whether ``source`` is a STAC Catalog, Collection, or Item document."""
+    if isinstance(source, Path) and source.suffix.lower() != ".json":
+        return False
+    try:
+        data = _read_json_href(_source_to_href(source, default_document="catalog.json"))
+    except (OSError, TypeError, ValueError, json.JSONDecodeError):
+        return False
+    return data.get("type") in STAC_DOCUMENT_TYPES
+
+
+def _collections_from_catalog(
+    data: JsonObject, href: str, visited: set[str]
+) -> Iterator[Collection]:
+    if href in visited:
+        return
+    visited.add(href)
+    for link in _links(data, href):
+        if link.rel != "child":
+            continue
+        child = _read_json_href(link.href)
+        child_type = child.get("type")
+        if child_type == "Collection":
+            yield Collection(child, link.href)
+        elif child_type == "Catalog":
+            yield from _collections_from_catalog(child, link.href, visited)
+
+
+def _item_links_from_document(data: JsonObject, href: str, visited: set[str]) -> Iterator[Link]:
+    if href in visited:
+        return
+    visited.add(href)
+    for link in _links(data, href):
+        if link.rel == "item":
+            yield link
+        elif link.rel == "child":
+            child = _read_json_href(link.href)
+            if child.get("type") == "Catalog":
+                yield from _item_links_from_document(child, link.href, visited)
+
+
+def _links(data: JsonObject, document_href: str) -> Iterator[Link]:
+    links = data.get("links")
+    if not isinstance(links, list):
+        return
+    for raw_link in links:
+        if not isinstance(raw_link, dict):
+            continue
+        rel = raw_link.get("rel")
+        href = raw_link.get("href")
+        if not isinstance(rel, str) or not isinstance(href, str):
+            continue
+        media_type = raw_link.get("type")
+        title = raw_link.get("title")
+        yield Link(
+            rel=rel,
+            href=_resolve_href(document_href, href),
+            media_type=media_type if isinstance(media_type, str) else None,
+            title=title if isinstance(title, str) else None,
+            raw=dict(raw_link),
+        )
+
+
+def _assets(data: JsonObject, document_href: str) -> Iterator[Asset]:
+    assets = data.get("assets")
+    if not isinstance(assets, dict):
+        return
+    for key, raw_asset in assets.items():
+        if not isinstance(key, str) or not isinstance(raw_asset, dict):
+            continue
+        href = raw_asset.get("href")
+        if not isinstance(href, str):
+            continue
+        media_type = raw_asset.get("type") or raw_asset.get("media_type")
+        roles = raw_asset.get("roles")
+        title = raw_asset.get("title")
+        description = raw_asset.get("description")
+        yield Asset(
+            key=key,
+            href=_resolve_href(document_href, href),
+            media_type=media_type if isinstance(media_type, str) else None,
+            roles=tuple(role for role in roles if isinstance(role, str))
+            if isinstance(roles, list)
+            else (),
+            title=title if isinstance(title, str) else None,
+            description=description if isinstance(description, str) else None,
+            raw=dict(raw_asset),
+        )
+
+
+def _source_to_href(source: str | Path, *, default_document: str = "catalog.json") -> str:
+    if isinstance(source, Path):
+        path = source
+    else:
+        parsed = urlparse(source)
+        if parsed.scheme in {"http", "https", "file"}:
+            return source
+        path = Path(source)
+    if path.is_dir():
+        path = path / default_document
+    return path.resolve().as_uri()
+
+
+def _read_json_href(href: str) -> JsonObject:
+    parsed = urlparse(href)
+    if parsed.scheme in {"http", "https"}:
+        request = Request(href, headers={"User-Agent": "portolan-python"})
+        with urlopen(request, timeout=30) as response:
+            data = json.loads(response.read().decode("utf-8"))
+    elif parsed.scheme == "file":
+        path = Path(unquote(parsed.path))
+        data = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        data = json.loads(Path(href).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise TypeError(f"Expected JSON object from {href}")
+    return data
+
+
+def _resolve_href(document_href: str, href: str) -> str:
+    return urljoin(document_href, href)

portolan/py.typed

@@ -0,0 +1 @@
+

portolan/registry.py

@@ -0,0 +1,152 @@
+"""Read and fetch Portolan registry exports."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from urllib.parse import urljoin, urlparse
+from urllib.request import Request, urlopen
+
+JsonObject = dict[str, Any]
+
+DEFAULT_REGISTRY_URL = (
+    "https://raw.githubusercontent.com/portolan-sdi/portolan-registry/"
+    "refs/heads/main/exports/catalogs.json"
+)
+
+
+@dataclass(frozen=True)
+class RegistryCatalogEntry:
+    """One catalog entry from a Portolan registry export."""
+
+    id: str
+    url: str
+    title: str | None = None
+    status: str | None = None
+
+
+def load_registry_entries(
+    registry_url: str = DEFAULT_REGISTRY_URL,
+    *,
+    fetch_json: Callable[[str], JsonObject] | None = None,
+    catalog_ids: set[str] | None = None,
+    include_stale: bool = False,
+    limit: int | None = None,
+) -> list[RegistryCatalogEntry]:
+    """Load catalog entries from a Portolan registry export."""
+    fetch = fetch_json or _fetch_json
+    registry = fetch(registry_url)
+    entries: list[RegistryCatalogEntry] = []
+    for link in registry.get("links", []):
+        if not isinstance(link, dict) or link.get("rel") != "child":
+            continue
+        href = link.get("href")
+        registry_id = link.get("portolan_registry:id")
+        if not isinstance(href, str) or not isinstance(registry_id, str):
+            continue
+        status = link.get("portolan_registry:status")
+        if status != "valid" and not include_stale:
+            continue
+        if catalog_ids is not None and registry_id not in catalog_ids:
+            continue
+        title = link.get("title")
+        entries.append(
+            RegistryCatalogEntry(
+                id=registry_id,
+                url=href,
+                title=title if isinstance(title, str) else None,
+                status=status if isinstance(status, str) else None,
+            )
+        )
+        if limit is not None and len(entries) >= limit:
+            break
+    return entries
+
+
+def download_registry_catalog(
+    catalog_url: str,
+    output_dir: Path,
+    *,
+    fetch_json: Callable[[str], JsonObject] | None = None,
+) -> Path:
+    """Download a published catalog snapshot for local workflows."""
+    fetch = fetch_json or _fetch_json
+    catalog = fetch(catalog_url)
+    catalog_id = str(catalog.get("id") or _fallback_catalog_id(catalog_url))
+    catalog_root = output_dir / catalog_id
+    _write_catalog_tree(catalog_url, catalog, catalog_url, catalog_root, fetch)
+    return catalog_root
+
+
+def _fetch_json(url: str) -> JsonObject:
+    request = Request(url, headers={"User-Agent": "portolan-python"})
+    with urlopen(request, timeout=30) as response:
+        data = json.loads(response.read().decode("utf-8"))
+    if not isinstance(data, dict):
+        raise TypeError(f"Expected JSON object from {url}")
+    return data
+
+
+def _write_catalog_tree(
+    document_url: str,
+    document: JsonObject,
+    root_url: str,
+    output_root: Path,
+    fetch_json: Callable[[str], JsonObject],
+) -> None:
+    relative_path = _relative_document_path(root_url, document_url)
+    target = output_root / relative_path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if document.get("type") == "Collection":
+        document = _with_absolute_asset_hrefs(document_url, document)
+    target.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+
+    for link in document.get("links", []):
+        if not isinstance(link, dict) or link.get("rel") != "child":
+            continue
+        href = link.get("href")
+        if not isinstance(href, str):
+            continue
+        child_url = urljoin(document_url, href)
+        child = fetch_json(child_url)
+        if child.get("type") in {"Catalog", "Collection"}:
+            _write_catalog_tree(child_url, child, root_url, output_root, fetch_json)
+
+
+def _with_absolute_asset_hrefs(document_url: str, collection: JsonObject) -> JsonObject:
+    assets = collection.get("assets")
+    if not isinstance(assets, dict):
+        return collection
+    updated = dict(collection)
+    updated_assets: dict[str, Any] = {}
+    for key, asset in assets.items():
+        if not isinstance(asset, dict):
+            updated_assets[key] = asset
+            continue
+        href = asset.get("href")
+        if isinstance(href, str):
+            rewritten = dict(asset)
+            rewritten["href"] = urljoin(document_url, href)
+            updated_assets[key] = rewritten
+        else:
+            updated_assets[key] = asset
+    updated["assets"] = updated_assets
+    return updated
+
+
+def _relative_document_path(root_url: str, document_url: str) -> Path:
+    root_path = Path(urlparse(root_url).path).parent
+    document_path = Path(urlparse(document_url).path)
+    try:
+        relative = document_path.relative_to(root_path)
+    except ValueError:
+        return Path(document_path.name or "catalog.json")
+    return relative
+
+
+def _fallback_catalog_id(catalog_url: str) -> str:
+    parent = Path(urlparse(catalog_url).path).parent.name
+    return parent or "catalog"

portolan/validation.py

@@ -0,0 +1,165 @@
+"""Small programmatic validation API for Portolan/STAC structures."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from portolan.catalog import Catalog
+
+JsonObject = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class ValidationError:
+    """One validation finding."""
+
+    code: str
+    path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Validation outcome."""
+
+    errors: tuple[ValidationError, ...]
+
+    @property
+    def valid(self) -> bool:
+        return not self.errors
+
+
+class Validator:
+    """Validate loaded Portolan catalog structures."""
+
+    @staticmethod
+    def validate(catalog: Catalog) -> ValidationResult:
+        """Validate a catalog and return structured findings."""
+        errors: list[ValidationError] = []
+        _validate_catalog_document(catalog.data, "catalog", errors)
+        for collection in catalog.collections():
+            collection_path = f"collection.{collection.id}"
+            _validate_collection_document(collection.data, collection_path, errors)
+            for item in collection.items():
+                _validate_item_document(item.data, f"item.{item.id}", errors)
+        return ValidationResult(errors=tuple(errors))
+
+
+def _validate_catalog_document(data: JsonObject, path: str, errors: list[ValidationError]) -> None:
+    _require_string(data, "type", path, errors)
+    _require_string(data, "stac_version", path, errors)
+    _require_string(data, "id", path, errors)
+    _require_string(data, "description", path, errors)
+    _validate_links(data, path, errors)
+
+
+def _validate_collection_document(
+    data: JsonObject, path: str, errors: list[ValidationError]
+) -> None:
+    _require_string(data, "type", path, errors)
+    _require_string(data, "stac_version", path, errors)
+    _require_string(data, "id", path, errors)
+    _require_string(data, "description", path, errors)
+    _require_string(data, "license", path, errors)
+    if not isinstance(data.get("extent"), dict):
+        errors.append(
+            ValidationError(
+                code="PTL-STAC-001",
+                path=f"{path}.extent",
+                message="extent is required",
+            )
+        )
+    _validate_links(data, path, errors)
+    _validate_assets(data, path, errors)
+
+
+def _validate_item_document(data: JsonObject, path: str, errors: list[ValidationError]) -> None:
+    _require_string(data, "type", path, errors)
+    _require_string(data, "stac_version", path, errors)
+    _require_string(data, "id", path, errors)
+    _require_string(data, "collection", path, errors)
+    if not isinstance(data.get("properties"), dict):
+        errors.append(
+            ValidationError(
+                code="PTL-STAC-001",
+                path=f"{path}.properties",
+                message="properties is required",
+            )
+        )
+    _validate_links(data, path, errors)
+    _validate_assets(data, path, errors)
+
+
+def _validate_assets(data: JsonObject, path: str, errors: list[ValidationError]) -> None:
+    assets = data.get("assets")
+    if assets is None:
+        return
+    if not isinstance(assets, dict):
+        errors.append(
+            ValidationError(
+                code="PTL-STAC-003",
+                path=f"{path}.assets",
+                message="assets must be an object",
+            )
+        )
+        return
+    for key, asset in assets.items():
+        asset_path = f"{path}.assets.{key}"
+        if not isinstance(asset, dict):
+            errors.append(
+                ValidationError(
+                    code="PTL-STAC-003",
+                    path=asset_path,
+                    message="asset must be an object",
+                )
+            )
+            continue
+        _require_string(asset, "href", asset_path, errors, code="PTL-STAC-003")
+
+
+def _validate_links(data: JsonObject, path: str, errors: list[ValidationError]) -> None:
+    links = data.get("links")
+    if links is None:
+        return
+    if not isinstance(links, list):
+        errors.append(
+            ValidationError(
+                code="PTL-STAC-002",
+                path=f"{path}.links",
+                message="links must be an array",
+            )
+        )
+        return
+    for index, link in enumerate(links):
+        link_path = f"{path}.links[{index}]"
+        if not isinstance(link, dict):
+            errors.append(
+                ValidationError(
+                    code="PTL-STAC-002",
+                    path=link_path,
+                    message="link must be an object",
+                )
+            )
+            continue
+        _require_string(link, "rel", link_path, errors, code="PTL-STAC-002")
+        _require_string(link, "href", link_path, errors, code="PTL-STAC-002")
+
+
+def _require_string(
+    data: JsonObject,
+    field: str,
+    path: str,
+    errors: list[ValidationError],
+    *,
+    code: str = "PTL-STAC-001",
+) -> None:
+    value = data.get(field)
+    if not isinstance(value, str) or not value:
+        errors.append(
+            ValidationError(
+                code=code,
+                path=f"{path}.{field}",
+                message=f"{field} is required",
+            )
+        )

portolan_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+portolan/__init__.py,sha256=F2FcjOpJKeDI17ckinCrb80wWh7Wg8Glv3xZYVlJr54,713
+portolan/catalog.py,sha256=zE5aVm3xXY6WZeSx2zaxWJgAloqqEFhgdHkT6oTt1aw,9768
+portolan/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+portolan/registry.py,sha256=9ASCT6vI6JmU92W9K8MOU6mLTCkW73lCmgKqjbvaRLI,5116
+portolan/validation.py,sha256=ZRjshZaErO-By0K653ruFL7EgIKBrOMvMqapLUEVfvo,5163
+portolan_python-0.1.0.dist-info/METADATA,sha256=HiK2CYsK29RnyCAYyIKUoYNJl_gyZTicNGu6rADUsCU,7154
+portolan_python-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+portolan_python-0.1.0.dist-info/RECORD,,

portolan_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any