portolan-cli 0.1.3__tar.gz → 0.2.0__tar.gz

portolan_cli-0.2.0/.github/SOCIAL_PREVIEW.md

@@ -0,0 +1,30 @@
+# GitHub Social Preview Setup
+
+To configure the repository's social preview image:
+
+1. Go to repository **Settings** → **General**
+2. Scroll to **Social preview**
+3. Click **Edit**
+4. Upload the image at `docs/assets/images/social-card.png` (3500x1440px)
+
+This will make the Portolan logo and cover image appear when sharing the repository on social media, Slack, Discord, etc.
+
+## Files Available
+
+- **Logo (square)**: `docs/assets/images/logo.png` (1000x1000)
+- **Logo (vector)**: `docs/assets/images/logo.svg`
+- **Social card**: `docs/assets/images/social-card.png` (3500x1440)
+
+## Brand Colors
+
+- **Background**: `#eaedf9`
+- **Dark text**: `#202a4f`
+- **Primary**: `#4163cc`
+- **Gradient**: `#395eca` → `#848bd8`
+
+## Typography
+
+- **Font**: Archivo Medium
+- **Designer**: Omnibus-Type
+- **License**: Open Font License
+- **Icon**: Designed by Icons By Alfredo

{portolan_cli-0.1.3 → portolan_cli-0.2.0}/CHANGELOG.md

@@ -1,3 +1,9 @@
+## v0.2.0 (2026-02-05)
+
+### Feat
+
+- **cli**: add `portolan init` command (#20)
+
 ## v0.1.3 (2026-02-05)
 
 ### Fix

{portolan_cli-0.1.3 → portolan_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: portolan-cli
-Version: 0.1.3
+Version: 0.2.0
 Summary: A CLI tool for managing cloud-native geospatial data
 Project-URL: Homepage, https://github.com/portolan-sdi/portolan-cli
 Project-URL: Bug Tracker, https://github.com/portolan-sdi/portolan-cli/issues
@@ -22,6 +22,9 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: GIS
 Requires-Python: >=3.10
 Requires-Dist: click>=8.3.1
+Requires-Dist: geoparquet-io>=0.3.0
+Requires-Dist: pyarrow<22.0.0,>=12.0.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: bandit>=1.9.3; extra == 'dev'
 Requires-Dist: codespell>=2.4.1; extra == 'dev'
@@ -46,14 +49,14 @@ Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <div align="center">
-  <img src="docs/assets/images/logo.svg" alt="Portolan Logo" width="200"/>
-  <h1>Portolan CLI</h1>
-  <p><strong>Cloud-native geospatial data catalogs, simplified</strong></p>
+  <img src="docs/assets/images/cover.png" alt="Portolan" width="600"/>
 </div>
 
 ---
 
-A CLI for publishing and managing **cloud-native geospatial data catalogs**. Portolan orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage—no running servers, just static files.
+Portolan enables organizations to share geospatial data in a low-cost, accessible, sovereign, and reliable way. Built on [cloud-native geospatial](https://cloudnativegeo.org) formats, a Portolan catalog is as interactive as any geospatial portal—but faster, more scalable, and much cheaper to run. A small government's vector data costs a few dollars a month; even full imagery and point clouds typically stay under $50/month.
+
+This CLI converts data to cloud-native formats (GeoParquet, COG), generates rich STAC metadata, and syncs to any object storage—no servers required.
 
 ## Why Portolan?
 

{portolan_cli-0.1.3 → portolan_cli-0.2.0}/README.md

@@ -1,12 +1,12 @@
 <div align="center">
-  <img src="docs/assets/images/logo.svg" alt="Portolan Logo" width="200"/>
-  <h1>Portolan CLI</h1>
-  <p><strong>Cloud-native geospatial data catalogs, simplified</strong></p>
+  <img src="docs/assets/images/cover.png" alt="Portolan" width="600"/>
 </div>
 
 ---
 
-A CLI for publishing and managing **cloud-native geospatial data catalogs**. Portolan orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage—no running servers, just static files.
+Portolan enables organizations to share geospatial data in a low-cost, accessible, sovereign, and reliable way. Built on [cloud-native geospatial](https://cloudnativegeo.org) formats, a Portolan catalog is as interactive as any geospatial portal—but faster, more scalable, and much cheaper to run. A small government's vector data costs a few dollars a month; even full imagery and point clouds typically stay under $50/month.
+
+This CLI converts data to cloud-native formats (GeoParquet, COG), generates rich STAC metadata, and syncs to any object storage—no servers required.
 
 ## Why Portolan?
 

portolan_cli-0.2.0/context/shared/known-issues/pyarrow-abseil-abi.md

@@ -0,0 +1,36 @@
+# Issue: PyArrow v22+ ABI incompatibility with abseil
+
+## Symptom
+
+Importing `geoparquet_io` (or any PyArrow-dependent library) fails with:
+
+```
+ImportError: .../pyarrow/libarrow_substrait.so.2200: undefined symbol: _ZN4absl12lts_2025012718container_internal24GetHashRefForEmptyHasherERKNS1_12CommonFieldsE
+```
+
+## Root cause
+
+PyArrow 22.0.0 was compiled against a newer version of the abseil (absl) C++ library than what's available on some Linux systems. The symbol `GetHashRefForEmptyHasher` was added in a recent abseil release, causing a linker failure when the system has an older abseil.
+
+This primarily affects:
+- Ubuntu 22.04 and older
+- Systems with system-installed abseil that conflicts with the bundled version
+- Environments where DuckDB or gRPC also link against abseil
+
+## Workaround
+
+Pin PyArrow to versions before 22.0.0 in `pyproject.toml`:
+
+```toml
+"pyarrow>=12.0.0,<22.0.0",  # v22+ has ABI incompatibility with abseil on some systems
+```
+
+## References
+
+- PyArrow 22.0.0 release: https://github.com/apache/arrow/releases/tag/apache-arrow-22.0.0
+- Similar issues in DuckDB: https://github.com/duckdb/duckdb/issues
+- abseil ABI stability discussion: https://github.com/abseil/abseil-cpp/issues
+
+## Regression test
+
+No automated test — this is an environment/binary compatibility issue. Tested manually by verifying `import geoparquet_io` succeeds after pinning.

{portolan_cli-0.1.3 → portolan_cli-0.2.0}/docs/index.md

@@ -8,7 +8,11 @@ hide:
 
 **Cloud-native geospatial data catalogs, simplified**
 
-A CLI for publishing and managing **cloud-native geospatial data catalogs**. Portolan orchestrates format conversion (GeoParquet, COG), versioning, and sync to object storage—no running servers, just static files.
+Portolan enables organizations to share geospatial data in a low-cost, accessible, sovereign, and reliable way. Built on [cloud-native geospatial](https://cloudnativegeo.org) formats, a Portolan catalog is as interactive as any geospatial portal—but faster, more scalable, and much cheaper to run.
+
+**Cost examples:** A small government's vector data costs a few dollars a month. Even full imagery and point clouds typically stay under $50/month.
+
+This CLI converts data to cloud-native formats (GeoParquet, COG), generates rich STAC metadata, and syncs to any object storage—no servers required.
 
 [Get Started](#installation){ .md-button .md-button--primary }
 [View on GitHub](https://github.com/portolan-sdi/portolan-cli){ .md-button }

portolan_cli-0.2.0/portolan_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Portolan CLI - Publish and manage cloud-native geospatial data catalogs."""
+
+from portolan_cli.cli import cli
+
+__all__ = ["cli"]

portolan_cli-0.2.0/portolan_cli/catalog.py

@@ -0,0 +1,94 @@
+"""Catalog management for Portolan.
+
+The Catalog class is the primary interface for working with Portolan catalogs.
+It wraps all catalog operations as methods, following ADR-0007 (CLI wraps API).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
+class CatalogExistsError(Exception):
+    """Raised when attempting to initialize a catalog that already exists."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__(f"Catalog already exists at {path}")
+
+
+class Catalog:
+    """A Portolan catalog backed by a .portolan directory.
+
+    The Catalog class provides the Python API for all catalog operations.
+    The CLI commands are thin wrappers around these methods.
+
+    Attributes:
+        root: The root directory containing the .portolan folder.
+    """
+
+    PORTOLAN_DIR = ".portolan"
+    CATALOG_FILE = "catalog.json"
+    STAC_VERSION = "1.0.0"
+
+    def __init__(self, root: Path) -> None:
+        """Initialize a Catalog instance.
+
+        Args:
+            root: The root directory containing the .portolan folder.
+        """
+        self.root = root
+
+    @property
+    def portolan_path(self) -> Path:
+        """Path to the .portolan directory."""
+        return self.root / self.PORTOLAN_DIR
+
+    @property
+    def catalog_file(self) -> Path:
+        """Path to the catalog.json file."""
+        return self.portolan_path / self.CATALOG_FILE
+
+    @classmethod
+    def init(cls, root: Path) -> Self:
+        """Initialize a new Portolan catalog.
+
+        Creates the .portolan directory and a minimal STAC catalog.json file.
+
+        Args:
+            root: The directory where the catalog should be created.
+
+        Returns:
+            A Catalog instance for the newly created catalog.
+
+        Raises:
+            CatalogExistsError: If a .portolan directory already exists.
+        """
+        portolan_path = root / cls.PORTOLAN_DIR
+
+        if portolan_path.exists():
+            raise CatalogExistsError(portolan_path)
+
+        # Create the .portolan directory
+        portolan_path.mkdir(parents=True)
+
+        # Create minimal STAC catalog
+        catalog_data = {
+            "type": "Catalog",
+            "stac_version": cls.STAC_VERSION,
+            "id": "portolan-catalog",
+            "description": "A Portolan-managed STAC catalog",
+            "links": [],
+        }
+
+        catalog_file = portolan_path / cls.CATALOG_FILE
+        catalog_file.write_text(json.dumps(catalog_data, indent=2))
+
+        return cls(root)

portolan_cli-0.2.0/portolan_cli/cli.py

@@ -0,0 +1,38 @@
+"""Portolan CLI - Command-line interface for managing cloud-native geospatial data.
+
+The CLI is a thin wrapper around the Python API (see catalog.py).
+All business logic lives in the library; the CLI handles user interaction.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from portolan_cli.catalog import Catalog, CatalogExistsError
+from portolan_cli.output import error, success
+
+
+@click.group()
+@click.version_option()
+def cli() -> None:
+    """Portolan - Publish and manage cloud-native geospatial data catalogs."""
+    pass
+
+
+@cli.command()
+@click.argument("path", type=click.Path(path_type=Path), default=".")
+def init(path: Path) -> None:
+    """Initialize a new Portolan catalog.
+
+    Creates a .portolan directory with a STAC catalog.json file.
+
+    PATH is the directory where the catalog should be created (default: current directory).
+    """
+    try:
+        Catalog.init(path)
+        success(f"Initialized Portolan catalog in {path.resolve()}")
+    except CatalogExistsError as err:
+        error(f"Catalog already exists at {path.resolve()}")
+        raise SystemExit(1) from err

{portolan_cli-0.1.3 → portolan_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "portolan-cli"
-version = "0.1.3"
+version = "0.2.0"
 description = "A CLI tool for managing cloud-native geospatial data"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -27,6 +27,9 @@ classifiers = [
 ]
 dependencies = [
     "click>=8.3.1",
+    "geoparquet-io>=0.3.0",
+    "pyarrow>=12.0.0,<22.0.0",  # v22+ has ABI incompatibility with abseil on some systems
+    "typing_extensions>=4.0.0; python_version < '3.11'",
 ]
 
 [project.scripts]
@@ -70,7 +73,7 @@ packages = ["portolan_cli"]
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.1.3"
+version = "0.2.0"
 version_files = ["pyproject.toml:^version"]
 tag_format = "v$version"
 update_changelog_on_bump = true
@@ -160,4 +163,4 @@ skips = []  # Add specific checks to skip if needed, e.g., ["B101"]
 min_confidence = 80
 paths = ["portolan_cli", "tests"]
 sort_by_size = true
-verbose = false
+verbose = false

portolan_cli-0.2.0/tests/unit/test_catalog_init.py

@@ -0,0 +1,65 @@
+"""Tests for Catalog.init() - the Python API for initializing a catalog."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from portolan_cli.catalog import Catalog, CatalogExistsError
+
+
+class TestCatalogInit:
+    """Tests for Catalog.init() method."""
+
+    @pytest.mark.unit
+    def test_init_creates_portolan_directory(self, tmp_path: Path) -> None:
+        """init() should create a .portolan directory."""
+        Catalog.init(tmp_path)
+
+        portolan_dir = tmp_path / ".portolan"
+        assert portolan_dir.exists()
+        assert portolan_dir.is_dir()
+
+    @pytest.mark.unit
+    def test_init_creates_catalog_json(self, tmp_path: Path) -> None:
+        """init() should create a catalog.json file with valid STAC structure."""
+        Catalog.init(tmp_path)
+
+        catalog_file = tmp_path / ".portolan" / "catalog.json"
+        assert catalog_file.exists()
+
+    @pytest.mark.unit
+    def test_init_catalog_json_has_required_stac_fields(self, tmp_path: Path) -> None:
+        """catalog.json must have required STAC Catalog fields."""
+        import json
+
+        Catalog.init(tmp_path)
+
+        catalog_file = tmp_path / ".portolan" / "catalog.json"
+        catalog = json.loads(catalog_file.read_text())
+
+        # Required STAC Catalog fields per spec
+        assert catalog["type"] == "Catalog"
+        assert catalog["stac_version"] == "1.0.0"
+        assert "id" in catalog
+        assert "description" in catalog
+        assert "links" in catalog
+
+    @pytest.mark.unit
+    def test_init_raises_error_if_catalog_exists(self, tmp_path: Path) -> None:
+        """init() should raise CatalogExistsError if .portolan already exists."""
+        # Create existing catalog
+        portolan_dir = tmp_path / ".portolan"
+        portolan_dir.mkdir()
+
+        with pytest.raises(CatalogExistsError):
+            Catalog.init(tmp_path)
+
+    @pytest.mark.unit
+    def test_init_returns_catalog_instance(self, tmp_path: Path) -> None:
+        """init() should return a Catalog instance for chaining."""
+        result = Catalog.init(tmp_path)
+
+        assert isinstance(result, Catalog)
+        assert result.root == tmp_path

portolan_cli-0.2.0/tests/unit/test_cli_init.py

@@ -0,0 +1,63 @@
+"""Tests for `portolan init` CLI command."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from portolan_cli.cli import cli
+
+
+class TestCliInit:
+    """Tests for the `portolan init` CLI command."""
+
+    @pytest.fixture
+    def runner(self) -> CliRunner:
+        """Create a Click test runner."""
+        return CliRunner()
+
+    @pytest.mark.unit
+    def test_init_creates_catalog_in_current_directory(
+        self, runner: CliRunner, tmp_path: Path
+    ) -> None:
+        """portolan init should create .portolan in the current directory."""
+        with runner.isolated_filesystem(temp_dir=tmp_path):
+            result = runner.invoke(cli, ["init"])
+
+            assert result.exit_code == 0
+            assert Path(".portolan").exists()
+            assert Path(".portolan/catalog.json").exists()
+
+    @pytest.mark.unit
+    def test_init_prints_success_message(self, runner: CliRunner, tmp_path: Path) -> None:
+        """portolan init should print a success message."""
+        with runner.isolated_filesystem(temp_dir=tmp_path):
+            result = runner.invoke(cli, ["init"])
+
+            assert result.exit_code == 0
+            assert "Initialized" in result.output or "✓" in result.output
+
+    @pytest.mark.unit
+    def test_init_fails_if_catalog_exists(self, runner: CliRunner, tmp_path: Path) -> None:
+        """portolan init should fail if .portolan already exists."""
+        with runner.isolated_filesystem(temp_dir=tmp_path):
+            Path(".portolan").mkdir()
+
+            result = runner.invoke(cli, ["init"])
+
+            assert result.exit_code != 0
+            assert "already exists" in result.output.lower()
+
+    @pytest.mark.unit
+    def test_init_accepts_path_argument(self, runner: CliRunner, tmp_path: Path) -> None:
+        """portolan init PATH should create catalog at specified path."""
+        with runner.isolated_filesystem(temp_dir=tmp_path):
+            target = Path("my-catalog")
+            target.mkdir()
+
+            result = runner.invoke(cli, ["init", str(target)])
+
+            assert result.exit_code == 0
+            assert (target / ".portolan").exists()