ocea 2.0.8.dev2__py3-none-any.whl

ocea/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError

ocea/__main__.py

@@ -0,0 +1,6 @@
+"""Convenience wrapper for ocea to run directly from source tree"""
+
+from ocea.cli import cli
+
+if __name__ == "__main__":
+    cli()

ocea/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.0.8.dev2'
+__version_tuple__ = version_tuple = (2, 0, 8, 'dev2')
+
+__commit_id__ = commit_id = None

ocea/api.py

@@ -0,0 +1,281 @@
+"""OCEA Python API.
+
+This module provides programmatic access to OCEA functionality
+for use in Python scripts and applications.
+
+Example:
+    from ocea.api import OCEA
+
+    ocea = OCEA()
+    droplets = ocea.list_droplets()
+    for d in droplets:
+        print(f"{d.name}: {d.status}")
+"""
+
+from pathlib import Path
+
+from ocea.config import get_config
+from ocea.models.droplet import Droplet
+from ocea.models.snapshot import Snapshot
+from ocea.services.database import DatabaseService
+from ocea.services.digitalocean import DOClient, DropletInfo, SnapshotInfo
+
+
+class OCEA:
+    """Main API class for OCEA operations.
+
+    Provides a high-level interface for managing DigitalOcean droplets
+    and snapshots with local database tracking.
+    """
+
+    def __init__(self, api_token: str | None = None, db_path: Path | None = None):
+        """Initialize OCEA API.
+
+        Args:
+            api_token: DigitalOcean API token. If not provided, will be loaded
+                from environment variable DO_API_TOKEN or config file.
+            db_path: Path to SQLite database. If not provided, uses default
+                location (~/.local/share/ocea/ocea.db on Linux).
+        """
+        self.config = get_config(db_path)
+        if api_token:
+            self.config.api_token = api_token
+        self.config.ensure_dirs()
+
+        self.db = DatabaseService(self.config.db_path)
+        self.db.init_db()
+
+        self._client: DOClient | None = None
+
+    @property
+    def client(self) -> DOClient:
+        """Get the DigitalOcean client (lazy initialization)."""
+        if self._client is None:
+            self.config.validate()
+            self._client = DOClient(self.config.api_token)
+        return self._client
+
+    def list_droplets(self, sync: bool = True) -> list[DropletInfo]:
+        """List all droplets from DigitalOcean.
+
+        Args:
+            sync: If True, sync results to local database.
+
+        Returns:
+            List of DropletInfo instances.
+        """
+        droplets = self.client.list_droplets()
+
+        if sync:
+            for d in droplets:
+                self.db.upsert_droplet(
+                    do_id=d.do_id,
+                    name=d.name,
+                    region=d.region,
+                    size=d.size,
+                    image=d.image,
+                    status=d.status,
+                    public_ip=d.public_ip,
+                    private_ip=d.private_ip,
+                )
+
+        return droplets
+
+    def list_droplets_local(self) -> list[Droplet]:
+        """List droplets from local database only.
+
+        Returns:
+            List of Droplet model instances.
+        """
+        return self.db.get_all_droplets()
+
+    def get_droplet(self, name: str) -> DropletInfo | None:
+        """Get a droplet by name.
+
+        Args:
+            name: Droplet name.
+
+        Returns:
+            DropletInfo or None if not found.
+        """
+        droplets = self.client.list_droplets()
+        return next((d for d in droplets if d.name == name), None)
+
+    def create_droplet(
+        self,
+        name: str,
+        region: str,
+        size: str,
+        image: str,
+        ssh_keys: list[str] | None = None,
+        tags: list[str] | None = None,
+    ) -> DropletInfo:
+        """Create a new droplet.
+
+        Args:
+            name: Droplet name.
+            region: Region slug (e.g., 'nyc1').
+            size: Size slug (e.g., 's-1vcpu-1gb').
+            image: Image slug or ID (e.g., 'ubuntu-24-04-x64').
+            ssh_keys: Optional list of SSH key IDs.
+            tags: Optional list of tags.
+
+        Returns:
+            DropletInfo for the created droplet.
+        """
+        droplet = self.client.create_droplet(
+            name=name,
+            region=region,
+            size=size,
+            image=image,
+            ssh_keys=ssh_keys,
+            tags=tags,
+        )
+
+        self.db.upsert_droplet(
+            do_id=droplet.do_id,
+            name=droplet.name,
+            region=droplet.region,
+            size=droplet.size,
+            image=droplet.image,
+            status=droplet.status,
+            public_ip=droplet.public_ip,
+            private_ip=droplet.private_ip,
+        )
+
+        return droplet
+
+    def power_on(self, name: str) -> bool:
+        """Power on a droplet.
+
+        Args:
+            name: Droplet name.
+
+        Returns:
+            True if power on was initiated.
+        """
+        droplet = self.get_droplet(name)
+        if droplet is None:
+            raise ValueError(f"Droplet '{name}' not found")
+
+        result = self.client.power_on(droplet.do_id)
+        if result:
+            self.db.update_droplet_status(droplet.do_id, "active")
+        return result
+
+    def power_off(self, name: str) -> bool:
+        """Power off a droplet (graceful shutdown).
+
+        Args:
+            name: Droplet name.
+
+        Returns:
+            True if shutdown was initiated.
+        """
+        droplet = self.get_droplet(name)
+        if droplet is None:
+            raise ValueError(f"Droplet '{name}' not found")
+
+        result = self.client.shutdown(droplet.do_id)
+        if result:
+            self.db.update_droplet_status(droplet.do_id, "off")
+        return result
+
+    def terminate(self, name: str, create_snapshot: bool = True) -> bool:
+        """Terminate (destroy) a droplet.
+
+        Args:
+            name: Droplet name.
+            create_snapshot: If True, create a snapshot before destroying.
+
+        Returns:
+            True if droplet was destroyed.
+        """
+        droplet = self.get_droplet(name)
+        if droplet is None:
+            raise ValueError(f"Droplet '{name}' not found")
+
+        if create_snapshot:
+            from datetime import datetime
+
+            snapshot_name = f"{name}-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+            self.create_snapshot(name, snapshot_name)
+
+        result = self.client.destroy(droplet.do_id)
+        if result:
+            self.db.update_droplet_status(droplet.do_id, "archive")
+        return result
+
+    def create_snapshot(self, droplet_name: str, snapshot_name: str) -> SnapshotInfo | None:
+        """Create a snapshot of a droplet.
+
+        Args:
+            droplet_name: Name of the droplet to snapshot.
+            snapshot_name: Name for the snapshot.
+
+        Returns:
+            SnapshotInfo or None if failed.
+        """
+        droplet = self.get_droplet(droplet_name)
+        if droplet is None:
+            raise ValueError(f"Droplet '{droplet_name}' not found")
+
+        snapshot = self.client.create_snapshot(droplet.do_id, snapshot_name)
+        if snapshot:
+            self.db.upsert_snapshot(
+                do_id=snapshot.do_id,
+                name=snapshot.name,
+                size_gigabytes=snapshot.size_gigabytes,
+                droplet_do_id=droplet.do_id,
+            )
+        return snapshot
+
+    def list_snapshots(self, sync: bool = True) -> list[SnapshotInfo]:
+        """List all snapshots.
+
+        Args:
+            sync: If True, sync results to local database.
+
+        Returns:
+            List of SnapshotInfo instances.
+        """
+        snapshots = self.client.list_snapshots()
+
+        if sync:
+            for s in snapshots:
+                self.db.upsert_snapshot(
+                    do_id=s.do_id,
+                    name=s.name,
+                    size_gigabytes=s.size_gigabytes,
+                    droplet_do_id=s.resource_id,
+                    created_at=s.created_at,
+                )
+
+        return snapshots
+
+    def list_snapshots_local(self) -> list[Snapshot]:
+        """List snapshots from local database only.
+
+        Returns:
+            List of Snapshot model instances.
+        """
+        return self.db.get_all_snapshots()
+
+    def delete_snapshot(self, snapshot_name: str) -> bool:
+        """Delete a snapshot.
+
+        Args:
+            snapshot_name: Snapshot name or ID.
+
+        Returns:
+            True if snapshot was deleted.
+        """
+        snapshots = self.client.list_snapshots()
+        snapshot = next((s for s in snapshots if s.name == snapshot_name or s.do_id == snapshot_name), None)
+        if snapshot is None:
+            raise ValueError(f"Snapshot '{snapshot_name}' not found")
+
+        result = self.client.delete_snapshot(snapshot.do_id)
+        if result:
+            self.db.delete_snapshot(snapshot.do_id)
+        return result

ocea/cli.py

@@ -0,0 +1,90 @@
+"""OCEA CLI - DigitalOcean management with local inventory tracking.
+
+To install run ``pip install .`` (or ``pip install -e .`` for editable mode)
+which will install the command ``ocea`` inside your current environment.
+"""
+
+import logging
+
+import click
+
+from ocea import __version__
+from ocea.commands import down, list_cmd, new, reboot, snap, status, up
+
+__author__ = "Kevin Steptoe"
+__copyright__ = "Kevin Steptoe"
+__license__ = "MIT"
+
+_logger = logging.getLogger(__name__)
+
+
+def setup_logging(loglevel: int) -> None:
+    """Setup basic logging.
+
+    Args:
+        loglevel: Minimum loglevel for emitting messages
+    """
+    import sys
+
+    logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s"
+    logging.basicConfig(
+        level=loglevel,
+        stream=sys.stderr,
+        format=logformat,
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
+@click.version_option(__version__, "--version", "-V")
+@click.option("-v", "--verbose", "loglevel", flag_value=logging.INFO, help="Enable verbose logging")
+@click.option("-vv", "--debug", "loglevel", flag_value=logging.DEBUG, help="Enable debug logging")
+@click.pass_context
+def cli(ctx: click.Context, loglevel: int | None) -> None:
+    """OCEA - DigitalOcean CLI with local inventory tracking.
+
+    Manage your DigitalOcean droplets and snapshots with a local SQLite database
+    for inventory tracking.
+
+    \b
+    Quick start:
+      export DO_API_TOKEN=your-token
+      ocea list              # List all droplets
+      ocea status            # Show local inventory
+      ocea new myserver -r nyc1 -s s-1vcpu-1gb -i ubuntu-24-04-x64
+
+    \b
+    Commands:
+      list    List droplets from DigitalOcean
+      status  Show local inventory status
+      new     Create a new droplet
+      up      Power on a droplet
+      down    Power off or terminate a droplet
+      reboot  Reboot a droplet
+      snap    Create or manage snapshots
+    """
+    ctx.ensure_object(dict)
+    if loglevel:
+        setup_logging(loglevel)
+        _logger.debug(f"OCEA version {__version__}")
+
+    # Show help if no command is provided
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+# Register commands
+cli.add_command(list_cmd, name="list")
+cli.add_command(up)
+cli.add_command(down)
+cli.add_command(new)
+cli.add_command(reboot)
+cli.add_command(snap)
+cli.add_command(status)
+
+
+if __name__ == "__main__":
+    cli()

ocea/commands/__init__.py

@@ -0,0 +1,11 @@
+"""CLI commands for OCEA."""
+
+from ocea.commands.down import down
+from ocea.commands.list_cmd import list_cmd
+from ocea.commands.new import new
+from ocea.commands.reboot import reboot
+from ocea.commands.snap import snap
+from ocea.commands.status import status
+from ocea.commands.up import up
+
+__all__ = ["list_cmd", "up", "down", "new", "reboot", "snap", "status"]

ocea/commands/down.py

@@ -0,0 +1,229 @@
+"""Down command - power off or terminate a droplet."""
+
+import json
+import re
+from datetime import datetime
+
+import click
+from rich.console import Console
+
+from ocea.config import get_config
+from ocea.services.database import DatabaseService
+from ocea.services.digitalocean import DOClient
+
+
+def _format_elapsed(seconds: int) -> str:
+    """Format elapsed seconds as human-readable string."""
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes = seconds // 60
+    secs = seconds % 60
+    return f"{minutes}m {secs}s" if secs else f"{minutes}m"
+
+
+def _get_snapshot_base_name(name: str) -> str:
+    """Extract the base droplet name, stripping auto-generated suffixes.
+
+    Strips DO console size/region suffixes (e.g. -s-2vcpu-8gb-160gb-intel-lon1-01)
+    and snapshot timestamp suffixes (-YYYYMMDD-HHMMSS) to prevent names from
+    snowballing across terminate/restore cycles.
+    """
+    # Strip DO auto-generated size suffix (e.g. -s-2vcpu-8gb-...)
+    match = re.search(r"-s-\d+vcpu-", name)
+    if match:
+        name = name[: match.start()]
+    # Strip snapshot timestamp suffix (-YYYYMMDD-HHMMSS)
+    match = re.search(r"-\d{8}-\d{6}", name)
+    if match:
+        name = name[: match.start()]
+    return name
+
+
+@click.command("down", context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("identifier")
+@click.option("--terminate", is_flag=True, help="Destroy the droplet (auto-snapshots first)")
+@click.option("--no-snapshot", is_flag=True, help="Skip auto-snapshot when terminating")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.pass_context
+def down(
+    ctx: click.Context,
+    identifier: str,
+    terminate: bool,
+    no_snapshot: bool,
+    as_json: bool,
+) -> None:
+    """Power off or terminate a droplet.
+
+    IDENTIFIER is the droplet name or ID to power off.
+
+    By default, performs a graceful shutdown.
+    Use --terminate to destroy the droplet (creates snapshot first by default).
+    Use --terminate --no-snapshot to destroy without creating a snapshot.
+    """
+    config = get_config()
+    console = Console()
+    try:
+        config.validate()
+    except ValueError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise SystemExit(1) from None
+    config.ensure_dirs()
+
+    db = DatabaseService(config.db_path)
+    db.init_db()
+
+    client = DOClient(config.api_token)
+
+    # Find the droplet
+    droplet = db.get_droplet_by_name_or_id(identifier)
+
+    if droplet is None:
+        # Try to find via API
+        api_droplets = client.list_droplets()
+        api_droplet = next((d for d in api_droplets if d.name == identifier or d.do_id == identifier), None)
+
+        if api_droplet is None:
+            console.print(f"[red]Droplet '{identifier}' not found.[/red]")
+            raise SystemExit(1)
+
+        droplet_id = api_droplet.do_id
+        droplet_name = api_droplet.name
+    else:
+        droplet_id = droplet.do_id
+        droplet_name = droplet.name
+
+    # Get floating IP info before any changes (for restore later)
+    floating_ip = db.get_floating_ip_for_droplet(droplet_id)
+    floating_ip_addr = floating_ip.ip_address if floating_ip else None
+
+    if terminate:
+        # Terminate the droplet
+        snapshot_name = None
+
+        if not no_snapshot:
+            # Create snapshot before terminating
+            snapshot_name = f"{_get_snapshot_base_name(droplet_name)}-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+            console.print(f"[yellow]Creating snapshot '{snapshot_name}' before terminating...[/yellow]")
+
+            result = client.create_snapshot(droplet_id, snapshot_name)
+            if result:
+                action_id, snap_name = result
+                console.print(f"[green]Snapshot creation initiated: {snap_name}[/green]")
+
+                with console.status(
+                    "[yellow]Waiting for snapshot to complete (this may take a few minutes)...[/yellow]"
+                ) as spinner:
+
+                    def _progress(elapsed: int, status: str) -> None:
+                        spinner.update(
+                            f"[yellow]Waiting for snapshot to complete[/yellow]"
+                            f" [dim]· {status} · {_format_elapsed(elapsed)}[/dim]"
+                        )
+
+                    snapshot = client.wait_for_snapshot(
+                        action_id=action_id,
+                        snapshot_name=snap_name,
+                        droplet_id=droplet_id,
+                        progress_callback=_progress,
+                    )
+                if snapshot:
+                    db.upsert_snapshot(
+                        do_id=snapshot.do_id,
+                        name=snapshot.name,
+                        size_gigabytes=snapshot.size_gigabytes,
+                        droplet_do_id=droplet_id,
+                    )
+                    console.print(f"[green]Snapshot '{snap_name}' completed.[/green]")
+                else:
+                    console.print("[red]Snapshot failed or timed out. Aborting termination.[/red]")
+                    raise SystemExit(1)
+            else:
+                console.print("[red]Failed to create snapshot. Aborting termination.[/red]")
+                raise SystemExit(1)
+
+        console.print(f"[yellow]Destroying droplet '{droplet_name}'...[/yellow]")
+
+        if client.destroy(droplet_id):
+            db.update_droplet_status(droplet_id, "archive")
+
+            # Log the terminate action with all metadata for future restore
+            db.log_action(
+                action_type="terminate",
+                droplet_do_id=droplet_id,
+                droplet_name=droplet_name,
+                snapshot_name=snapshot_name,
+                floating_ip=floating_ip_addr,
+                details={
+                    "region": droplet.region if droplet else None,
+                    "size": droplet.size if droplet else None,
+                    "image": droplet.image if droplet else None,
+                    "public_ip": droplet.public_ip if droplet else None,
+                },
+            )
+
+            if as_json:
+                result = {
+                    "action": "terminated",
+                    "droplet": droplet_name,
+                    "do_id": droplet_id,
+                }
+                if snapshot_name:
+                    result["snapshot"] = snapshot_name
+                if floating_ip_addr:
+                    result["floating_ip_preserved"] = floating_ip_addr
+                click.echo(json.dumps(result, indent=2))
+            else:
+                console.print(f"[green]Droplet '{droplet_name}' has been terminated.[/green]")
+                if snapshot_name:
+                    console.print(f"[dim]Snapshot '{snapshot_name}' is being created.[/dim]")
+                    console.print(
+                        "[dim]Note: Snapshots take several minutes to complete. Use 'ocea snap --list' to check.[/dim]"
+                    )
+                if floating_ip_addr:
+                    console.print(f"[dim]Floating IP {floating_ip_addr} preserved for restore.[/dim]")
+        else:
+            db.log_action(
+                action_type="terminate",
+                droplet_do_id=droplet_id,
+                droplet_name=droplet_name,
+                status="failed",
+            )
+            console.print(f"[red]Failed to destroy droplet '{droplet_name}'[/red]")
+            raise SystemExit(1)
+
+    else:
+        # Graceful shutdown
+        console.print(f"[yellow]Shutting down '{droplet_name}'...[/yellow]")
+
+        if client.shutdown(droplet_id):
+            db.update_droplet_status(droplet_id, "off")
+            db.log_action(
+                action_type="down",
+                droplet_do_id=droplet_id,
+                droplet_name=droplet_name,
+            )
+
+            if as_json:
+                click.echo(
+                    json.dumps(
+                        {
+                            "action": "shutdown",
+                            "droplet": droplet_name,
+                            "do_id": droplet_id,
+                            "status": "initiated",
+                        },
+                        indent=2,
+                    )
+                )
+            else:
+                console.print(f"[green]Shutdown initiated for '{droplet_name}'[/green]")
+                console.print("[dim]Run 'ocea list' to check status.[/dim]")
+        else:
+            db.log_action(
+                action_type="down",
+                droplet_do_id=droplet_id,
+                droplet_name=droplet_name,
+                status="failed",
+            )
+            console.print(f"[red]Failed to shutdown '{droplet_name}'[/red]")
+            raise SystemExit(1)