dotflow 1.0.0.dev3__tar.gz → 1.0.1__tar.gz

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotflow
-Version: 1.0.0.dev3
+Version: 1.0.1
 Summary: 🎲 Dotflow turns an idea into flow! Lightweight Python library for execution pipelines with retry, parallel, cron and async support.
 License: Apache License
                                     Version 2.0, January 2004
@@ -196,7 +196,7 @@ License-File: LICENSE
 Keywords: pipeline,workflow,etl,task-runner,orchestration,automation,parallel,async,retry,data-pipeline,scheduler,cron,cron-job
 Author: Fernando Celmer
 Author-email: email@fernandocelmer.com
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Classifier: Development Status :: 4 - Beta
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
@@ -205,7 +205,6 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Distributed Computing
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/dotflow/__init__.py

@@ -1,6 +1,6 @@
 """Dotflow __init__ module."""
 
-__version__ = "1.0.0.dev3"
+__version__ = "1.0.1"
 __description__ = "🎲 Dotflow turns an idea into flow!"
 
 from .core.action import Action as action

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/dotflow/abc/flow.py

@@ -1,5 +1,7 @@
 """Flow ABC"""
 
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 from uuid import UUID
 

dotflow-1.0.1/dotflow/abc/storage.py

@@ -0,0 +1,77 @@
+"""Storage ABC"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from dotflow.core.context import Context
+
+
+class Storage(ABC):
+    """Storage"""
+
+    def __init__(self, *args, **kwargs):
+        pass
+
+    @abstractmethod
+    def post(
+        self,
+        key: str,
+        context: Context,
+        ttl: int | None = None,
+        fingerprint: str | None = None,
+    ) -> None:
+        """Persist context under key."""
+
+    @abstractmethod
+    def get(self, key: str) -> Context:
+        """Return stored context or empty Context()."""
+
+    @abstractmethod
+    def key(self, task: Callable) -> str:
+        """Storage key for task."""
+
+    def clear(self, workflow_id: str) -> None:
+        """Remove every entry under workflow_id.
+
+        Default implementation delegates to ``delete_prefix``. External
+        subclasses may override directly.
+        """
+        self.delete_prefix(f"{workflow_id}-")
+
+    def delete(self, key: str) -> bool:
+        """Remove key. Returns True when present.
+
+        Optional in 1.x. Becomes abstract in 2.0.
+        """
+        raise NotImplementedError
+
+    def delete_prefix(self, prefix: str) -> int:
+        """Remove keys starting with prefix. Returns count.
+
+        Optional in 1.x. Becomes abstract in 2.0.
+        """
+        raise NotImplementedError
+
+    def list_keys(self, prefix: str) -> Iterable[str]:
+        """Iterate keys starting with prefix.
+
+        Optional in 1.x. Becomes abstract in 2.0.
+        """
+        raise NotImplementedError
+
+    def atomic_swap(
+        self,
+        key: str,
+        expected: Any,
+        new: Any,
+        ttl: int | None = None,
+        fingerprint: str | None = None,
+    ) -> bool:
+        """Replace value when current equals expected.
+
+        Optional in 1.x. Becomes abstract in 2.0.
+        """
+        raise NotImplementedError

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/dotflow/cli/commands/__init__.py

@@ -4,6 +4,8 @@ from dotflow.cli.commands.cloud import CloudGenerateCommand, CloudListCommand
 from dotflow.cli.commands.deploy import DeployCommand
 from dotflow.cli.commands.init import InitCommand
 from dotflow.cli.commands.log import LogCommand
+from dotflow.cli.commands.login import LoginCommand
+from dotflow.cli.commands.logout import LogoutCommand
 from dotflow.cli.commands.schedule import ScheduleCommand
 from dotflow.cli.commands.start import StartCommand
 
@@ -13,6 +15,8 @@ __all__ = [
     "DeployCommand",
     "InitCommand",
     "LogCommand",
+    "LoginCommand",
+    "LogoutCommand",
     "ScheduleCommand",
     "StartCommand",
 ]

dotflow-1.0.1/dotflow/cli/commands/login.py

@@ -0,0 +1,115 @@
+"""Command login module."""
+
+from __future__ import annotations
+
+import os
+import time
+import webbrowser
+
+from requests import RequestException, post
+from rich import print  # type: ignore
+
+from dotflow.cli.command import Command
+from dotflow.core.config_file import save_cloud_config
+from dotflow.settings import Settings as settings
+
+DEFAULT_BASE_URL = "https://www.host.dotflow.io/api/v1"
+DEVICE_ENDPOINT = "/cli/device"
+TOKEN_ENDPOINT = "/cli/token"
+TIMEOUT = 15
+DEFAULT_INTERVAL = 5
+MAX_POLL_INTERVAL = 60
+
+
+class LoginCommand(Command):
+    def setup(self):
+        base_url = self._resolve_base_url()
+
+        handshake = self._start_device(base_url)
+        if handshake is None:
+            return
+
+        print(settings.INFO_ALERT, f"Opening {handshake['verification_uri']}")
+        print(settings.INFO_ALERT, f"Code: {handshake['user_code']}")
+
+        webbrowser.open(handshake["verification_uri"])
+
+        token = self._poll_token(base_url, handshake)
+
+        if not token:
+            return
+
+        save_cloud_config(token=token, base_url=base_url)
+        print(settings.INFO_ALERT, "Authenticated.")
+
+    def _resolve_base_url(self) -> str:
+        """``SERVER_BASE_URL`` env var wins over the default."""
+        explicit = os.environ.get("SERVER_BASE_URL")
+        return explicit.rstrip("/") if explicit else DEFAULT_BASE_URL
+
+    def _start_device(self, base_url: str) -> dict | None:
+        try:
+            response = post(
+                f"{base_url}{DEVICE_ENDPOINT}",
+                timeout=TIMEOUT,
+            )
+            response.raise_for_status()
+            return response.json()
+        except RequestException as error:
+            print(
+                settings.ERROR_ALERT,
+                f"Could not reach Dotflow Cloud: {error}",
+            )
+            return None
+
+    def _poll_token(self, base_url: str, handshake: dict) -> str | None:
+        interval = handshake.get("interval") or DEFAULT_INTERVAL
+        deadline = time.monotonic() + (handshake.get("expires_in") or 300)
+
+        while time.monotonic() < deadline:
+            try:
+                response = post(
+                    f"{base_url}{TOKEN_ENDPOINT}",
+                    json={"device_code": handshake["device_code"]},
+                    timeout=TIMEOUT,
+                )
+            except RequestException as error:
+                print(settings.ERROR_ALERT, f"Network error: {error}")
+                return None
+
+            if response.status_code == 200:
+                return response.json().get("api_token")
+
+            detail = self._detail(response)
+
+            if (
+                response.status_code == 400
+                and detail == "authorization_pending"
+            ):
+                time.sleep(interval)
+                continue
+
+            if response.status_code == 400 and detail in (
+                "slow_down",
+                "slow down",
+            ):
+                interval = min(interval + 5, MAX_POLL_INTERVAL)
+                time.sleep(interval)
+                continue
+
+            if response.status_code == 410:
+                print(settings.ERROR_ALERT, "Authorization expired.")
+                return None
+
+            print(settings.ERROR_ALERT, f"{response.status_code}: {detail}")
+            return None
+
+        print(settings.ERROR_ALERT, "Timed out waiting for authorization.")
+        return None
+
+    @staticmethod
+    def _detail(response) -> str:
+        try:
+            return str(response.json().get("detail", response.text))
+        except ValueError:
+            return response.text

dotflow-1.0.1/dotflow/cli/commands/logout.py

@@ -0,0 +1,15 @@
+"""Command logout module."""
+
+from rich import print  # type: ignore
+
+from dotflow.cli.command import Command
+from dotflow.core.config_file import clear_cloud_config
+from dotflow.settings import Settings as settings
+
+
+class LogoutCommand(Command):
+    def setup(self):
+        if clear_cloud_config():
+            print(settings.INFO_ALERT, "Signed out.")
+        else:
+            print(settings.WARNING_ALERT, "No saved credentials.")

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/dotflow/cli/commands/start.py

@@ -51,12 +51,12 @@ class StartCommand(Command):
         if not callable(factory):
             raise InvalidWorkflowFactory(factory=self.params.workflow)
 
-        result = factory()
+        workflow = factory()
 
-        if not isinstance(result, DotFlow):
+        if not isinstance(workflow, DotFlow):
             raise InvalidWorkflowFactory(factory=self.params.workflow)
 
-        result.start(mode=self.params.mode, resume=self.params.resume)
+        workflow.start(mode=self.params.mode, resume=self.params.resume)
 
     def _new_workflow(self):
         storage = self._build_storage()

{dotflow-1.0.0.dev3 → dotflow-1.0.1}/dotflow/cli/setup.py

@@ -9,6 +9,8 @@ from dotflow.cli.commands import (
     DeployCommand,
     InitCommand,
     LogCommand,
+    LoginCommand,
+    LogoutCommand,
     ScheduleCommand,
     StartCommand,
 )
@@ -42,12 +44,26 @@ class Command:
 
         self.setup_init()
         self.setup_logs()
+        self.setup_login()
+        self.setup_logout()
         self.setup_start()
         self.setup_schedule()
         self.setup_cloud()
         self.setup_deploy()
         self.command()
 
+    def setup_login(self):
+        cmd = self.subparsers.add_parser(
+            "login", help="Authenticate the CLI via browser"
+        )
+        cmd.set_defaults(exec=LoginCommand)
+
+    def setup_logout(self):
+        cmd = self.subparsers.add_parser(
+            "logout", help="Remove saved CLI credentials"
+        )
+        cmd.set_defaults(exec=LogoutCommand)
+
     def setup_init(self):
         self.cmd_init = self.subparsers.add_parser(
             "init", help="Scaffold a new dotflow project"

dotflow-1.0.1/dotflow/cloud/aws/services/s3.py

@@ -0,0 +1,148 @@
+"""S3 operations — read and write objects."""
+
+from __future__ import annotations
+
+from json import dumps, loads
+
+from dotflow.cloud.core import ObjectStorage
+from dotflow.core.exception import ModuleNotFound
+
+_PRECONDITION_CODES = {
+    "PreconditionFailed",
+    "ConditionalRequestConflict",
+}
+
+
+class S3(ObjectStorage):
+    """Amazon S3 object storage."""
+
+    def __init__(self, bucket: str, prefix: str = "", region: str = None):
+        try:
+            import boto3
+        except ImportError:
+            raise ModuleNotFound(
+                module="boto3", library="dotflow[aws]"
+            ) from None
+
+        self._s3 = boto3.client("s3", region_name=region)
+        self.bucket = bucket
+        self.prefix = prefix
+
+        self._s3.head_bucket(Bucket=self.bucket)
+
+    def read(self, key: str) -> list:
+        """Read a JSON list from S3. Returns empty list if key not found."""
+        try:
+            response = self._s3.get_object(
+                Bucket=self.bucket,
+                Key=f"{self.prefix}{key}",
+            )
+            data = response["Body"].read().decode("utf-8")
+            return loads(data)
+        except self._s3.exceptions.NoSuchKey:
+            return []
+
+    def write(self, key: str, data: list) -> None:
+        """Write a JSON list to S3."""
+        self._s3.put_object(
+            Bucket=self.bucket,
+            Key=f"{self.prefix}{key}",
+            Body=dumps(data),
+            ContentType="application/json",
+        )
+
+    def delete(self, key: str) -> bool:
+        """Delete a single object."""
+        from botocore.exceptions import ClientError
+
+        full_key = f"{self.prefix}{key}"
+
+        try:
+            self._s3.head_object(Bucket=self.bucket, Key=full_key)
+        except ClientError as error:
+            code = error.response.get("Error", {}).get("Code")
+
+            if code in ("404", "NoSuchKey", "NotFound"):
+                return False
+
+            raise
+
+        self._s3.delete_object(Bucket=self.bucket, Key=full_key)
+
+        return True
+
+    def read_with_etag(self, key: str) -> tuple[list, str | None]:
+        """Return (data, etag). Etag is None when key is missing."""
+        try:
+            response = self._s3.get_object(
+                Bucket=self.bucket,
+                Key=f"{self.prefix}{key}",
+            )
+            data = response["Body"].read().decode("utf-8")
+
+            return loads(data), response.get("ETag")
+        except self._s3.exceptions.NoSuchKey:
+            return [], None
+
+    def write_if_match(self, key: str, data: list, etag: str | None) -> bool:
+        """Conditional PutObject. Returns False on precondition failure."""
+        from botocore.exceptions import ClientError
+
+        kwargs = {
+            "Bucket": self.bucket,
+            "Key": f"{self.prefix}{key}",
+            "Body": dumps(data),
+            "ContentType": "application/json",
+        }
+
+        if etag is None:
+            kwargs["IfNoneMatch"] = "*"
+        else:
+            kwargs["IfMatch"] = etag
+
+        try:
+            self._s3.put_object(**kwargs)
+            return True
+        except ClientError as error:
+            code = error.response.get("Error", {}).get("Code")
+
+            if code in _PRECONDITION_CODES:
+                return False
+
+            raise
+
+    def list_keys(self, sub_prefix: str) -> list[str]:
+        """Return keys starting with sub_prefix."""
+        full_prefix = f"{self.prefix}{sub_prefix}"
+        paginator = self._s3.get_paginator("list_objects_v2")
+        names = []
+        offset = len(self.prefix)
+
+        for page in paginator.paginate(Bucket=self.bucket, Prefix=full_prefix):
+            for item in page.get("Contents", []):
+                names.append(item["Key"][offset:])
+
+        return names
+
+    def delete_prefix(self, sub_prefix: str) -> None:
+        """Delete every object whose key starts with prefix + sub_prefix.
+
+        Empty ``sub_prefix`` is rejected to avoid accidentally wiping
+        the entire bucket prefix.
+        """
+        if not sub_prefix:
+            raise ValueError("delete_prefix requires a non-empty sub_prefix")
+
+        full_prefix = f"{self.prefix}{sub_prefix}"
+        paginator = self._s3.get_paginator("list_objects_v2")
+
+        for page in paginator.paginate(Bucket=self.bucket, Prefix=full_prefix):
+            objects = [
+                {"Key": item["Key"]} for item in page.get("Contents", [])
+            ]
+            if not objects:
+                continue
+            self._s3.delete_objects(
+                Bucket=self.bucket,
+                Delete={"Objects": objects},
+            )

dotflow-1.0.1/dotflow/cloud/gcp/services/gcs.py

@@ -0,0 +1,110 @@
+"""GCS operations — read and write objects."""
+
+from __future__ import annotations
+
+from json import dumps, loads
+
+from dotflow.cloud.core import ObjectStorage
+from dotflow.core.exception import ModuleNotFound
+
+
+class GCS(ObjectStorage):
+    """Google Cloud Storage object storage."""
+
+    def __init__(self, bucket: str, prefix: str = "", project: str = None):
+        try:
+            from google.api_core.exceptions import NotFound
+            from google.cloud import storage as gcs
+        except ImportError:
+            raise ModuleNotFound(
+                module="google-cloud-storage",
+                library="dotflow[gcp]",
+            ) from None
+
+        self._not_found = NotFound
+        self._client = gcs.Client(project=project)
+        self._bucket = self._client.bucket(bucket)
+        self._bucket.reload()
+        self.prefix = prefix
+
+    def read(self, key: str) -> list:
+        """Read a JSON list from GCS. Returns empty list if key not found."""
+        blob = self._bucket.blob(f"{self.prefix}{key}")
+        try:
+            data = blob.download_as_text()
+            return loads(data)
+        except self._not_found:
+            return []
+
+    def write(self, key: str, data: list) -> None:
+        """Write a JSON list to GCS."""
+        blob = self._bucket.blob(f"{self.prefix}{key}")
+        blob.upload_from_string(
+            dumps(data),
+            content_type="application/json",
+        )
+
+    def delete(self, key: str) -> bool:
+        """Delete a single blob."""
+        blob = self._bucket.blob(f"{self.prefix}{key}")
+
+        try:
+            blob.delete()
+            return True
+        except self._not_found:
+            return False
+
+    def read_with_generation(self, key: str) -> tuple[list, int | None]:
+        """Return (data, generation). Generation is None when missing."""
+        blob = self._bucket.blob(f"{self.prefix}{key}")
+
+        try:
+            data = blob.download_as_text()
+            return loads(data), blob.generation
+        except self._not_found:
+            return [], None
+
+    def write_if_generation_match(
+        self, key: str, data: list, generation: int | None
+    ) -> bool:
+        """Conditional upload. Returns False on precondition failure."""
+        from google.api_core.exceptions import PreconditionFailed
+
+        blob = self._bucket.blob(f"{self.prefix}{key}")
+        precondition = generation if generation is not None else 0
+
+        try:
+            blob.upload_from_string(
+                dumps(data),
+                content_type="application/json",
+                if_generation_match=precondition,
+            )
+            return True
+        except PreconditionFailed:
+            return False
+
+    def list_keys(self, sub_prefix: str) -> list[str]:
+        """Return blob names starting with sub_prefix."""
+        full_prefix = f"{self.prefix}{sub_prefix}"
+        offset = len(self.prefix)
+
+        return [
+            blob.name[offset:]
+            for blob in self._client.list_blobs(
+                self._bucket, prefix=full_prefix
+            )
+        ]
+
+    def delete_prefix(self, sub_prefix: str) -> None:
+        """Delete every blob whose name starts with prefix + sub_prefix.
+
+        Empty ``sub_prefix`` is rejected to avoid accidentally wiping
+        the entire bucket prefix.
+        """
+        if not sub_prefix:
+            raise ValueError("delete_prefix requires a non-empty sub_prefix")
+
+        full_prefix = f"{self.prefix}{sub_prefix}"
+
+        for blob in self._client.list_blobs(self._bucket, prefix=full_prefix):
+            blob.delete()

dotflow-1.0.1/dotflow/core/config_file.py

@@ -0,0 +1,95 @@
+"""Persistent CLI config stored at ``~/.dotflow/config.json``."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from pathlib import Path
+
+CONFIG_DIR_NAME = ".dotflow"
+CONFIG_FILE_NAME = "config.json"
+CLOUD_SECTION = "cloud"
+
+
+def config_path() -> Path:
+    """Return the absolute path of the CLI config file."""
+    return Path.home() / CONFIG_DIR_NAME / CONFIG_FILE_NAME
+
+
+def load_cloud_config() -> dict[str, str]:
+    """Read the ``cloud`` section from the config file. ``{}`` when absent."""
+    path = config_path()
+
+    if not path.exists():
+        return {}
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+
+    section = data.get(CLOUD_SECTION) if isinstance(data, dict) else None
+    if not isinstance(section, dict):
+        return {}
+
+    return {
+        key: str(value)
+        for key, value in section.items()
+        if isinstance(value, str)
+    }
+
+
+def save_cloud_config(token: str, base_url: str) -> Path:
+    """Persist ``cloud`` with the given token/base_url. Returns the file path."""
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        CLOUD_SECTION: {
+            "base_url": base_url,
+            "token": token,
+        }
+    }
+    content = json.dumps(payload, indent=2) + "\n"
+
+    fd = os.open(
+        str(path),
+        os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
+        0o600,
+    )
+    with contextlib.suppress(OSError):
+        os.fchmod(fd, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+
+    return path
+
+
+def clear_cloud_config() -> bool:
+    """Remove the config file. Returns True when something was deleted."""
+    path = config_path()
+
+    if not path.exists():
+        return False
+
+    try:
+        path.unlink()
+        return True
+    except OSError:
+        return False
+
+
+def resolve(key: str, env_var: str) -> str | None:
+    """Resolve a setting with env > file precedence. ``None`` when absent."""
+    env_value = os.environ.get(env_var)
+
+    if env_value:
+        return env_value
+
+    return load_cloud_config().get(key) or None