portolan-cli 0.1.2__py3-none-any.whl → 0.2.0__py3-none-any.whl

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/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/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.2.0.dist-info/METADATA

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: portolan-cli
+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
+Project-URL: Documentation, https://github.com/portolan-sdi/portolan-cli#readme
+Project-URL: Source, https://github.com/portolan-sdi/portolan-cli
+Author-email: Nissim Lebovits <nlebovits@pm.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cloud-native,geospatial,gis,io
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+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'
+Requires-Dist: commitizen>=4.13.4; extra == 'dev'
+Requires-Dist: hypothesis>=6.151.5; extra == 'dev'
+Requires-Dist: mutmut>=3.4.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
+Requires-Dist: pytest-benchmark>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: radon>=6.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.14.11; extra == 'dev'
+Requires-Dist: vulture>=2.14; extra == 'dev'
+Requires-Dist: xenon>=0.9.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
+Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <img src="docs/assets/images/cover.png" alt="Portolan" width="600"/>
+</div>
+
+---
+
+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?
+
+| Benefit | How |
+|---------|-----|
+| **Scalable** | Cloud object storage that scales to petabytes |
+| **Open** | 100% open source, open formats (GeoParquet, COG, STAC, Iceberg) |
+| **AI-Ready** | STAC metadata enables semantic search and LLM integration |
+| **Cheap** | Pay only for storage + egress — no servers to run |
+| **Sovereign** | Host anywhere (AWS, GCS, Azure, MinIO, Cloudflare R2) |
+| **Breaks the GIS silo** | Query with DuckDB, Snowflake, BigQuery, Databricks, Pandas — not just GIS tools |
+
+## What It Does
+
+- **Convert** vector/raster data to cloud-native formats (GeoParquet, COG)
+- **Generate** STAC catalogs with rich metadata, thumbnails, and MapLibre styles
+- **Version** datasets with checksums and history tracking
+- **Sync** to S3, GCS, Azure, or any S3-compatible storage
+
+## Quick Example
+
+```bash
+portolan init
+portolan dataset add census.parquet --title "Census 2022" --auto
+portolan remote add prod s3://my-bucket/catalog
+portolan sync
+```
+
+## Installation
+
+### Recommended: pipx (for global use)
+
+```bash
+pipx install portolan-cli
+```
+
+This installs `portolan` in an isolated environment while making the command globally available.
+
+If you don't have pipx installed:
+```bash
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+### Alternative: pip
+
+```bash
+pip install portolan-cli
+```
+
+**Note:** This installs into your global or user site-packages and may conflict with other packages.
+
+### For Development
+
+Use [uv](https://github.com/astral-sh/uv) for local development:
+
+```bash
+git clone https://github.com/portolan-sdi/portolan-cli.git
+cd portolan-cli
+uv sync --all-extras
+uv run portolan --help
+```
+
+See [Contributing Guide](docs/contributing.md) for full development setup.
+
+## Documentation
+
+- [Contributing Guide](docs/contributing.md)
+- [Architecture](context/architecture.md)
+- [Roadmap](ROADMAP.md)
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE)

portolan_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+portolan_cli/__init__.py,sha256=k2RodeI9pun6dtZsitWo_4TCFdDH513Uxp5vrpEYJ3A,132
+portolan_cli/catalog.py,sha256=Z5I6O0sZtAL2oiTof63P-HWc2nh-GleuPF3CR9xdw6Y,2634
+portolan_cli/cli.py,sha256=Oq8HCKDp3vSXB6cPGgU1avoKcJUSAPEToM46nwDY6K4,1130
+portolan_cli/output.py,sha256=3aNXrQIXYSnGrFEBnYGQNZzgN5B6tgt1uC_4tekBxII,3694
+portolan_cli-0.2.0.dist-info/METADATA,sha256=RQwTK3OUxUfSIiEpAkzXz5RP8LMloDcKqzK8P9XVvbE,4873
+portolan_cli-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+portolan_cli-0.2.0.dist-info/entry_points.txt,sha256=qcxazmDwTESEd44qYETCxUy-mJPcNs3Tyk8PRrl9Shs,46
+portolan_cli-0.2.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+portolan_cli-0.2.0.dist-info/RECORD,,

portolan_cli-0.1.2.dist-info/METADATA

@@ -1,49 +0,0 @@
-Metadata-Version: 2.4
-Name: portolan-cli
-Version: 0.1.2
-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
-Project-URL: Documentation, https://github.com/portolan-sdi/portolan-cli#readme
-Project-URL: Source, https://github.com/portolan-sdi/portolan-cli
-Author-email: Nissim Lebovits <nlebovits@pm.me>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: cloud-native,geospatial,gis,io
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: GIS
-Requires-Python: >=3.10
-Requires-Dist: click>=8.3.1
-Provides-Extra: dev
-Requires-Dist: bandit>=1.9.3; extra == 'dev'
-Requires-Dist: codespell>=2.4.1; extra == 'dev'
-Requires-Dist: commitizen>=4.13.4; extra == 'dev'
-Requires-Dist: hypothesis>=6.151.5; extra == 'dev'
-Requires-Dist: mutmut>=3.4.0; extra == 'dev'
-Requires-Dist: mypy>=1.19.1; extra == 'dev'
-Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
-Requires-Dist: pre-commit>=4.5.1; extra == 'dev'
-Requires-Dist: pytest-benchmark>=5.0.0; extra == 'dev'
-Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
-Requires-Dist: pytest-timeout>=2.3.1; extra == 'dev'
-Requires-Dist: pytest>=9.0.2; extra == 'dev'
-Requires-Dist: radon>=6.0.1; extra == 'dev'
-Requires-Dist: ruff>=0.14.11; extra == 'dev'
-Requires-Dist: vulture>=2.14; extra == 'dev'
-Requires-Dist: xenon>=0.9.3; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: mkdocs-material>=9.7.1; extra == 'docs'
-Requires-Dist: mkdocs>=1.6.1; extra == 'docs'
-Requires-Dist: mkdocstrings[python]>=1.0.0; extra == 'docs'
-Description-Content-Type: text/markdown
-
-# portolan-cli
-A CLI tool for managing cloud-native geospatial data.

portolan_cli-0.1.2.dist-info/RECORD

@@ -1,8 +0,0 @@
-portolan_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-portolan_cli/cli.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-portolan_cli/output.py,sha256=3aNXrQIXYSnGrFEBnYGQNZzgN5B6tgt1uC_4tekBxII,3694
-portolan_cli-0.1.2.dist-info/METADATA,sha256=UWtB-aBi-p6XZYTf6OsI0Iu3fFPwzSMmvckJ-ygDNG4,2181
-portolan_cli-0.1.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-portolan_cli-0.1.2.dist-info/entry_points.txt,sha256=qcxazmDwTESEd44qYETCxUy-mJPcNs3Tyk8PRrl9Shs,46
-portolan_cli-0.1.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-portolan_cli-0.1.2.dist-info/RECORD,,