ml-dash 0.6.1__py3-none-any.whl

ml_dash/auth/token_storage.py

@@ -0,0 +1,262 @@
+"""Token storage backends for ml-dash authentication."""
+
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+from .exceptions import StorageError
+
+
+class TokenStorage(ABC):
+    """Abstract base class for token storage backends."""
+
+    @abstractmethod
+    def store(self, key: str, value: str) -> None:
+        """Store a token.
+
+        Args:
+            key: Storage key
+            value: Token string to store
+        """
+        pass
+
+    @abstractmethod
+    def load(self, key: str) -> Optional[str]:
+        """Load a token.
+
+        Args:
+            key: Storage key
+
+        Returns:
+            Token string or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete a token.
+
+        Args:
+            key: Storage key
+        """
+        pass
+
+
+class KeyringStorage(TokenStorage):
+    """OS keyring storage backend (macOS Keychain, Windows Credential Manager, Linux Secret Service)."""
+
+    SERVICE_NAME = "ml-dash"
+
+    def __init__(self):
+        """Initialize keyring storage."""
+        try:
+            import keyring
+            self.keyring = keyring
+        except ImportError:
+            raise StorageError(
+                "keyring library not installed. "
+                "Install with: pip install keyring"
+            )
+
+    def store(self, key: str, value: str) -> None:
+        """Store token in OS keyring."""
+        try:
+            self.keyring.set_password(self.SERVICE_NAME, key, value)
+        except Exception as e:
+            raise StorageError(f"Failed to store token in keyring: {e}")
+
+    def load(self, key: str) -> Optional[str]:
+        """Load token from OS keyring."""
+        try:
+            return self.keyring.get_password(self.SERVICE_NAME, key)
+        except Exception as e:
+            raise StorageError(f"Failed to load token from keyring: {e}")
+
+    def delete(self, key: str) -> None:
+        """Delete token from OS keyring."""
+        try:
+            self.keyring.delete_password(self.SERVICE_NAME, key)
+        except Exception:
+            # Silently ignore if key doesn't exist
+            pass
+
+
+class EncryptedFileStorage(TokenStorage):
+    """Encrypted file storage backend using Fernet symmetric encryption."""
+
+    def __init__(self, config_dir: Path):
+        """Initialize encrypted file storage.
+
+        Args:
+            config_dir: Configuration directory path
+        """
+        self.config_dir = Path(config_dir)
+        self.tokens_file = self.config_dir / "tokens.encrypted"
+        self.key_file = self.config_dir / "encryption.key"
+
+        try:
+            from cryptography.fernet import Fernet
+            self.Fernet = Fernet
+        except ImportError:
+            raise StorageError(
+                "cryptography library not installed. "
+                "Install with: pip install cryptography"
+            )
+
+        # Ensure config directory exists
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Generate or load encryption key
+        if not self.key_file.exists():
+            key = self.Fernet.generate_key()
+            self.key_file.write_bytes(key)
+            self.key_file.chmod(0o600)  # User read/write only
+        else:
+            key = self.key_file.read_bytes()
+
+        self.cipher = self.Fernet(key)
+
+    def _load_all(self) -> dict:
+        """Load all tokens from encrypted file."""
+        if not self.tokens_file.exists():
+            return {}
+
+        try:
+            encrypted = self.tokens_file.read_bytes()
+            decrypted = self.cipher.decrypt(encrypted)
+            return json.loads(decrypted)
+        except Exception as e:
+            raise StorageError(f"Failed to decrypt tokens file: {e}")
+
+    def _save_all(self, data: dict) -> None:
+        """Save all tokens to encrypted file."""
+        try:
+            plaintext = json.dumps(data).encode()
+            encrypted = self.cipher.encrypt(plaintext)
+            self.tokens_file.write_bytes(encrypted)
+            self.tokens_file.chmod(0o600)  # User read/write only
+        except Exception as e:
+            raise StorageError(f"Failed to encrypt tokens file: {e}")
+
+    def store(self, key: str, value: str) -> None:
+        """Store token in encrypted file."""
+        all_tokens = self._load_all()
+        all_tokens[key] = value
+        self._save_all(all_tokens)
+
+    def load(self, key: str) -> Optional[str]:
+        """Load token from encrypted file."""
+        all_tokens = self._load_all()
+        return all_tokens.get(key)
+
+    def delete(self, key: str) -> None:
+        """Delete token from encrypted file."""
+        all_tokens = self._load_all()
+        if key in all_tokens:
+            del all_tokens[key]
+            self._save_all(all_tokens)
+
+
+class PlaintextFileStorage(TokenStorage):
+    """Plaintext file storage backend (INSECURE - only for testing/fallback)."""
+
+    _warning_shown = False
+
+    def __init__(self, config_dir: Path):
+        """Initialize plaintext file storage.
+
+        Args:
+            config_dir: Configuration directory path
+        """
+        self.config_dir = Path(config_dir)
+        self.tokens_file = self.config_dir / "tokens.json"
+
+        # Ensure config directory exists
+        self.config_dir.mkdir(parents=True, exist_ok=True)
+
+        # Show security warning on first use
+        if not PlaintextFileStorage._warning_shown:
+            try:
+                from rich.console import Console
+                console = Console()
+                console.print(
+                    "\n[bold red]WARNING: Storing tokens in plaintext![/bold red]\n"
+                    "[yellow]Your authentication tokens are being stored unencrypted.[/yellow]\n"
+                    "[yellow]This is insecure and only recommended for testing.[/yellow]\n\n"
+                    "To use secure storage:\n"
+                    "  • Install keyring: pip install keyring\n"
+                    "  • Or encrypted storage will be used automatically\n"
+                )
+            except ImportError:
+                print("WARNING: Storing tokens in plaintext! This is insecure.")
+
+            PlaintextFileStorage._warning_shown = True
+
+    def _load_all(self) -> dict:
+        """Load all tokens from file."""
+        if not self.tokens_file.exists():
+            return {}
+
+        try:
+            with open(self.tokens_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            return {}
+
+    def _save_all(self, data: dict) -> None:
+        """Save all tokens to file."""
+        with open(self.tokens_file, "w") as f:
+            json.dump(data, f, indent=2)
+        self.tokens_file.chmod(0o600)  # User read/write only
+
+    def store(self, key: str, value: str) -> None:
+        """Store token in plaintext file."""
+        all_tokens = self._load_all()
+        all_tokens[key] = value
+        self._save_all(all_tokens)
+
+    def load(self, key: str) -> Optional[str]:
+        """Load token from plaintext file."""
+        all_tokens = self._load_all()
+        return all_tokens.get(key)
+
+    def delete(self, key: str) -> None:
+        """Delete token from plaintext file."""
+        all_tokens = self._load_all()
+        if key in all_tokens:
+            del all_tokens[key]
+            self._save_all(all_tokens)
+
+
+def get_token_storage(config_dir: Optional[Path] = None) -> TokenStorage:
+    """Auto-detect and return appropriate storage backend.
+
+    Tries backends in order of security:
+    1. KeyringStorage (OS keyring)
+    2. EncryptedFileStorage (encrypted file)
+    3. PlaintextFileStorage (plaintext file with warning)
+
+    Args:
+        config_dir: Configuration directory (defaults to ~/.ml-dash)
+
+    Returns:
+        TokenStorage instance
+    """
+    if config_dir is None:
+        config_dir = Path.home() / ".ml-dash"
+
+    # Try keyring first
+    try:
+        return KeyringStorage()
+    except (ImportError, StorageError):
+        pass
+
+    # Try encrypted file storage
+    try:
+        return EncryptedFileStorage(config_dir)
+    except (ImportError, StorageError):
+        pass
+
+    # Fallback to plaintext (with warning)
+    return PlaintextFileStorage(config_dir)

ml_dash/auto_start.py

@@ -0,0 +1,52 @@
+"""
+Pre-configured experiment singleton for ML-Dash SDK.
+
+Provides a pre-configured experiment singleton named 'dxp' in remote mode.
+Requires authentication - run 'ml-dash login' first.
+Requires manual start using 'with' statement or explicit start() call.
+
+Usage:
+    # First, authenticate
+    # $ ml-dash login
+
+    from ml_dash import dxp
+
+    # Use with statement (recommended)
+    with dxp.run:
+        dxp.log().info("Hello from dxp!")
+        dxp.params.set(lr=0.001)
+        dxp.metrics("loss").append(step=0, value=0.5)
+    # Automatically completes on exit from with block
+
+    # Or start/complete manually
+    dxp.run.start()
+    dxp.log().info("Training...")
+    dxp.run.complete()
+"""
+
+import atexit
+from .experiment import Experiment
+
+# Create pre-configured singleton experiment in remote mode
+# Uses default remote server (https://api.dash.ml)
+# Token is auto-loaded from storage when first used
+# If not authenticated, operations will fail with AuthenticationError
+dxp = Experiment(
+    name="dxp",
+    project="scratch",
+    remote="https://api.dash.ml",
+)
+
+# Register cleanup handler to complete experiment on Python exit (if still open)
+def _cleanup():
+    """Complete the dxp experiment on exit if still open."""
+    if dxp._is_open:
+        try:
+            dxp.run.complete()
+        except Exception:
+            # Silently ignore errors during cleanup
+            pass
+
+atexit.register(_cleanup)
+
+__all__ = ["dxp"]

ml_dash/cli.py

@@ -0,0 +1,79 @@
+"""ML-Dash command-line interface."""
+
+import argparse
+import sys
+from typing import Optional, List
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Create the main CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="ml-dash",
+        description="ML-Dash: ML experiment tracking and data storage CLI",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    # Add subcommands
+    subparsers = parser.add_subparsers(
+        dest="command",
+        help="Available commands",
+        metavar="COMMAND",
+    )
+
+    # Import and add command parsers
+    from .cli_commands import upload, download, list as list_cmd, login, logout
+
+    # Authentication commands
+    login.add_parser(subparsers)
+    logout.add_parser(subparsers)
+
+    # Data commands
+    upload.add_parser(subparsers)
+    download.add_parser(subparsers)
+    list_cmd.add_parser(subparsers)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """
+    Main CLI entry point.
+
+    Args:
+        argv: Command-line arguments (defaults to sys.argv[1:])
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    # If no command specified, show help
+    if args.command is None:
+        parser.print_help()
+        return 0
+
+    # Route to command handlers
+    if args.command == "login":
+        from .cli_commands import login
+        return login.cmd_login(args)
+    elif args.command == "logout":
+        from .cli_commands import logout
+        return logout.cmd_logout(args)
+    elif args.command == "upload":
+        from .cli_commands import upload
+        return upload.cmd_upload(args)
+    elif args.command == "download":
+        from .cli_commands import download
+        return download.cmd_download(args)
+    elif args.command == "list":
+        from .cli_commands import list as list_cmd
+        return list_cmd.cmd_list(args)
+
+    # Unknown command (shouldn't happen due to subparsers)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ml_dash/cli_commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for ML-Dash."""