earthforge-core 0.1.0__tar.gz

earthforge_core-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Claude
+.claude/

earthforge_core-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: earthforge-core
+Version: 0.1.0
+Summary: EarthForge core: shared types, config, storage, output, format detection
+License-Expression: GPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: obstore>=0.3
+Requires-Dist: orjson>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# earthforge-core
+
+Shared types, configuration, storage abstraction, output formatting, and format detection for EarthForge.
+
+See the [main README](../../README.md) for project documentation.

earthforge_core-0.1.0/README.md

@@ -0,0 +1,5 @@
+# earthforge-core
+
+Shared types, configuration, storage abstraction, output formatting, and format detection for EarthForge.
+
+See the [main README](../../README.md) for project documentation.

earthforge_core-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "earthforge-core"
+version = "0.1.0"
+description = "EarthForge core: shared types, config, storage, output, format detection"
+readme = "README.md"
+license = "GPL-3.0-or-later"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27",
+    "obstore>=0.3",
+    "pydantic>=2.0",
+    "rich>=13.0",
+    "orjson>=3.9",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/earthforge"]

earthforge_core-0.1.0/src/earthforge/core/__init__.py

@@ -0,0 +1,8 @@
+"""EarthForge core — shared types, configuration, storage, output, and format detection.
+
+This package provides the foundational layer that all EarthForge domain packages
+depend on. It wraps third-party libraries (httpx, obstore, rich) behind stable
+interfaces so domain code never imports them directly.
+"""
+
+__version__ = "0.1.0"

earthforge_core-0.1.0/src/earthforge/core/config.py

@@ -0,0 +1,239 @@
+"""EarthForge configuration management.
+
+Provides profile-based configuration backed by a TOML file at
+``~/.earthforge/config.toml``. Each profile bundles a STAC API endpoint,
+a storage backend selection, and backend-specific options (credentials,
+regions, endpoints). The ``default`` profile is used when no ``--profile``
+flag is given.
+
+Configuration file format::
+
+    [profiles.default]
+    stac_api = "https://earth-search.aws.element84.com/v1"
+    storage = "s3"
+
+    [profiles.default.storage_options]
+    region = "us-west-2"
+
+Functions:
+    load_profile: Async loader that reads config and returns a typed profile.
+    load_profile_sync: Convenience sync wrapper.
+    init_config: Creates a starter config file with a default profile.
+    config_dir: Returns the resolved config directory path.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Self
+
+from earthforge.core.errors import ConfigError
+
+logger = logging.getLogger(__name__)
+
+#: Supported storage backend identifiers.
+VALID_BACKENDS = frozenset({"s3", "gcs", "azure", "local"})
+
+#: Default STAC API endpoint used when none is configured.
+DEFAULT_STAC_API = "https://earth-search.aws.element84.com/v1"
+
+_DEFAULT_CONFIG = """\
+# EarthForge configuration
+# Documentation: https://earthforge-geo.github.io/earthforge/config
+
+[profiles.default]
+stac_api = "https://earth-search.aws.element84.com/v1"
+storage = "local"
+
+[profiles.default.storage_options]
+root = "."
+"""
+
+
+@dataclass(frozen=True, slots=True)
+class EarthForgeProfile:
+    """A named configuration profile.
+
+    Parameters:
+        name: Profile identifier (e.g. ``"default"``, ``"planetary"``).
+        stac_api: Base URL for the STAC API, or ``None`` if not configured.
+        storage_backend: One of ``"s3"``, ``"gcs"``, ``"azure"``, ``"local"``.
+        storage_options: Backend-specific key/value pairs (region, credentials, etc.).
+
+    Raises:
+        ConfigError: If ``storage_backend`` is not in ``VALID_BACKENDS``.
+    """
+
+    name: str
+    stac_api: str | None = None
+    storage_backend: str = "local"
+    storage_options: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.storage_backend not in VALID_BACKENDS:
+            msg = (
+                f"Unknown storage backend {self.storage_backend!r} in profile "
+                f"{self.name!r}. Valid options: {', '.join(sorted(VALID_BACKENDS))}"
+            )
+            raise ConfigError(msg)
+
+    @classmethod
+    def from_dict(cls, name: str, data: dict[str, object]) -> Self:
+        """Construct a profile from a parsed TOML dictionary.
+
+        Parameters:
+            name: The profile name key.
+            data: The TOML table for this profile.
+
+        Returns:
+            A validated ``EarthForgeProfile``.
+
+        Raises:
+            ConfigError: If required fields are missing or have wrong types.
+        """
+        stac_api = data.get("stac_api")
+        if stac_api is not None and not isinstance(stac_api, str):
+            raise ConfigError(f"Profile {name!r}: stac_api must be a string")
+
+        storage = data.get("storage", "local")
+        if not isinstance(storage, str):
+            raise ConfigError(f"Profile {name!r}: storage must be a string")
+
+        raw_options = data.get("storage_options", {})
+        if not isinstance(raw_options, dict):
+            raise ConfigError(f"Profile {name!r}: storage_options must be a table")
+
+        storage_options: dict[str, str] = {}
+        for k, v in raw_options.items():
+            if not isinstance(v, str):
+                raise ConfigError(
+                    f"Profile {name!r}: storage_options.{k} must be a string, "
+                    f"got {type(v).__name__}"
+                )
+            storage_options[k] = v
+
+        return cls(
+            name=name,
+            stac_api=stac_api if isinstance(stac_api, str) else None,
+            storage_backend=storage,
+            storage_options=storage_options,
+        )
+
+
+def config_dir() -> Path:
+    """Return the EarthForge configuration directory.
+
+    Returns:
+        ``Path("~/.earthforge")`` expanded to an absolute path.
+    """
+    return Path.home() / ".earthforge"
+
+
+def _config_file() -> Path:
+    """Return the path to the main config file."""
+    return config_dir() / "config.toml"
+
+
+async def load_profile(name: str = "default") -> EarthForgeProfile:
+    """Load a named profile from the configuration file.
+
+    If no config file exists, returns a built-in default profile (for the
+    ``"default"`` name) or raises ``ConfigError`` for any other name.
+
+    Parameters:
+        name: Profile name to load.
+
+    Returns:
+        The resolved ``EarthForgeProfile``.
+
+    Raises:
+        ConfigError: If the config file is malformed, the profile doesn't exist,
+                     or field validation fails.
+    """
+    path = _config_file()
+
+    if not path.exists():
+        logger.debug("No config file at %s, using built-in defaults", path)
+        if name == "default":
+            return EarthForgeProfile(
+                name="default",
+                stac_api=DEFAULT_STAC_API,
+                storage_backend="local",
+                storage_options={"root": "."},
+            )
+        raise ConfigError(
+            f"Profile {name!r} not found: no config file at {path}. "
+            f"Run 'earthforge config init' to create one."
+        )
+
+    try:
+        raw = path.read_bytes()
+        config = tomllib.loads(raw.decode("utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid TOML in {path}: {exc}") from exc
+    except OSError as exc:
+        raise ConfigError(f"Cannot read config file {path}: {exc}") from exc
+
+    profiles = config.get("profiles")
+    if not isinstance(profiles, dict):
+        raise ConfigError(f"Config file {path} is missing [profiles] section")
+
+    if name not in profiles:
+        available = ", ".join(sorted(profiles.keys())) or "(none)"
+        raise ConfigError(f"Profile {name!r} not found in {path}. Available: {available}")
+
+    profile_data = profiles[name]
+    if not isinstance(profile_data, dict):
+        raise ConfigError(f"Profile {name!r} must be a TOML table")
+
+    return EarthForgeProfile.from_dict(name, profile_data)
+
+
+def load_profile_sync(name: str = "default") -> EarthForgeProfile:
+    """Synchronous convenience wrapper for :func:`load_profile`.
+
+    Parameters:
+        name: Profile name to load.
+
+    Returns:
+        The resolved ``EarthForgeProfile``.
+
+    Raises:
+        ConfigError: Same conditions as :func:`load_profile`.
+    """
+    return asyncio.run(load_profile(name))
+
+
+async def init_config(*, overwrite: bool = False) -> Path:
+    """Create the default configuration file.
+
+    Parameters:
+        overwrite: If ``True``, replace an existing config file. If ``False``
+                   and the file already exists, raise ``ConfigError``.
+
+    Returns:
+        The path to the created config file.
+
+    Raises:
+        ConfigError: If the file exists and ``overwrite`` is ``False``,
+                     or if the directory cannot be created.
+    """
+    path = _config_file()
+
+    if path.exists() and not overwrite:
+        raise ConfigError(
+            f"Config file already exists at {path}. Use overwrite=True to replace it."
+        )
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_DEFAULT_CONFIG, encoding="utf-8")
+    except OSError as exc:
+        raise ConfigError(f"Cannot create config file at {path}: {exc}") from exc
+
+    logger.info("Created config file at %s", path)
+    return path

earthforge_core-0.1.0/src/earthforge/core/errors.py

@@ -0,0 +1,85 @@
+"""EarthForge error hierarchy.
+
+All exceptions raised by EarthForge inherit from ``EarthForgeError``. Each domain
+package defines its own subclasses (e.g. ``StacSearchError``, ``CogValidationError``)
+so callers can catch at whatever granularity they need. The ``exit_code`` attribute
+maps directly to CLI exit codes, letting the CLI layer translate library exceptions
+into meaningful shell return values without parsing message strings.
+"""
+
+from __future__ import annotations
+
+
+class EarthForgeError(Exception):
+    """Base exception for all EarthForge errors.
+
+    Parameters:
+        message: Human-readable description of the error.
+        exit_code: CLI exit code to use when this error propagates to the shell.
+                   Defaults to ``1`` (general error).
+
+    Attributes:
+        exit_code: The numeric exit code for CLI propagation.
+    """
+
+    exit_code: int = 1
+
+    def __init__(self, message: str, *, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+class ConfigError(EarthForgeError):
+    """Raised when configuration loading, parsing, or validation fails.
+
+    Examples: missing config file, invalid TOML, unknown profile name,
+    missing required field in a profile.
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 2) -> None:
+        super().__init__(message, exit_code=exit_code)
+
+
+class StorageError(EarthForgeError):
+    """Raised when a cloud storage operation fails.
+
+    Examples: permission denied on S3, object not found, network timeout,
+    invalid storage backend name.
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 3) -> None:
+        super().__init__(message, exit_code=exit_code)
+
+
+class HttpError(EarthForgeError):
+    """Raised when an HTTP request fails after retries.
+
+    Parameters:
+        message: Human-readable description.
+        status_code: The HTTP status code that triggered the error, if available.
+        exit_code: CLI exit code (defaults to ``4``).
+
+    Attributes:
+        status_code: The HTTP status code, or ``None`` for connection-level failures.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        exit_code: int = 4,
+    ) -> None:
+        super().__init__(message, exit_code=exit_code)
+        self.status_code = status_code
+
+
+class FormatDetectionError(EarthForgeError):
+    """Raised when format detection cannot determine the file type.
+
+    This typically means the file's magic bytes don't match any known format,
+    the extension is unrecognized, and content inspection was inconclusive.
+    """
+
+    def __init__(self, message: str, *, exit_code: int = 5) -> None:
+        super().__init__(message, exit_code=exit_code)