knowflow 0.1.0__py3-none-any.whl

knowflow/adapters/storage/quark.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+"""
+knowflow/adapters/storage/quark.py — 夸克网盘 storage backend
+==============================================================
+Requires: kuake_cli installed + cookie configured.
+
+Config:
+  path: str  (default: /KnowFlow)  — 夸克网盘内的根目录
+  temp_dir: str  (default: /tmp/knowflow-quark)  — 本地缓存目录
+
+由于夸克网盘没有文件系统操作（没有 stat/mtime），
+本适配器用本地 temp_dir 做缓存，同步到夸克。
+"""
+import json
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+from knowflow.core.storage import (
+    StorageAdapter, StorageItem, StorageError, StorageNotFoundError
+)
+
+
+KUAKE_HOME = os.path.expanduser("~/.config/kuake")
+
+
+class QuarkStorage(StorageAdapter):
+    """
+    夸克网盘存储后端
+
+    工作方式：
+      - 读：先从夸克下载到本地缓存 → 读缓存
+      - 写：先写本地缓存 → 再上传到夸克
+      - 列表：调 kuake list
+    """
+
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        cfg = config or {}
+        self.remote_root = cfg.get("path", "/KnowFlow").rstrip("/")
+        self.temp_dir = Path(cfg.get("temp_dir", "/tmp/knowflow-quark"))
+        self.temp_dir.mkdir(parents=True, exist_ok=True)
+        self._check_kuake()
+
+    def _check_kuake(self):
+        """验证 kuake 可用"""
+        try:
+            result = subprocess.run(
+                ["kuake", "user"],
+                capture_output=True, text=True, timeout=15,
+                cwd=KUAKE_HOME,
+            )
+            if result.returncode != 0:
+                raise StorageError(
+                    f"夸克网盘连接失败。请检查 cookie 是否过期。\n"
+                    f"  {result.stderr.strip()}"
+                )
+        except FileNotFoundError:
+            raise StorageError(
+                "未找到 kuake 命令。请安装: https://github.com/kuake-cli/kuake"
+            )
+
+    def _kuake(self, *args, timeout=60) -> str:
+        """执行 kuake 命令"""
+        try:
+            result = subprocess.run(
+                ["kuake", *args],
+                capture_output=True, text=True, timeout=timeout,
+                cwd=KUAKE_HOME,
+            )
+            if result.returncode != 0:
+                raise StorageError(
+                    f"kuake {' '.join(args)} 失败: {result.stderr.strip()}"
+                )
+            return result.stdout.strip()
+        except subprocess.TimeoutExpired:
+            raise StorageError(f"kuake 命令超时 ({timeout}s)")
+
+    def _local_path(self, path: str) -> Path:
+        """远程路径 → 本地缓存路径"""
+        clean = path.lstrip("/")
+        return self.temp_dir / clean
+
+    def _remote_path(self, path: str) -> str:
+        """相对路径 → 夸克完整路径"""
+        return f"{self.remote_root}/{path.lstrip('/')}"
+
+    def _ensure_remote_dirs(self, path: str):
+        """确保夸克远程目录存在"""
+        parent = Path(path).parent.as_posix().strip("/")
+        # 文件在根目录（如 hello.txt），无需创建目录
+        if not parent or parent == ".":
+            return
+        parts = parent.split("/")
+        current = self.remote_root
+        for part in parts:
+            current = f"{current}/{part}"
+            exists = False
+            try:
+                self._kuake("list", current, timeout=15)
+                exists = True
+            except StorageError:
+                pass
+            if not exists:
+                parent = current.rsplit("/", 1)[0] if "/" in current else ""
+                self._kuake("create", part, parent, timeout=15)
+
+    def read(self, path: str) -> str:
+        local = self._local_path(path)
+        if not local.exists():
+            self._download(path)
+        return local.read_text(encoding="utf-8")
+
+    def read_binary(self, path: str) -> bytes:
+        local = self._local_path(path)
+        if not local.exists():
+            self._download(path)
+        return local.read_bytes()
+
+    def write(self, path: str, content: str) -> str:
+        local = self._local_path(path)
+        local.parent.mkdir(parents=True, exist_ok=True)
+        local.write_text(content, encoding="utf-8")
+        self._upload(path)
+        return ""
+
+    def write_binary(self, path: str, content: bytes) -> str:
+        local = self._local_path(path)
+        local.parent.mkdir(parents=True, exist_ok=True)
+        local.write_bytes(content)
+        self._upload(path)
+        return ""
+
+    def delete(self, path: str) -> bool:
+        remote = self._remote_path(path)
+        local = self._local_path(path)
+        try:
+            self._kuake("delete", remote)
+        except StorageError:
+            pass
+        if local.exists():
+            local.unlink()
+        return True
+
+    def exists(self, path: str) -> bool:
+        """检查文件是否存在（先查本地缓存，再查夸克远程）"""
+        # 1. 查本地缓存
+        local = self._local_path(path)
+        if local.exists():
+            return True
+        # 2. 查夸克远程（用 list 查父目录）
+        parent_dir = Path(path).parent.as_posix().strip("/")
+        try:
+            items = self.list(parent_dir)
+            target = Path(path).name
+            return any(i.path == target for i in items)
+        except StorageError:
+            return False
+
+    def list(self, prefix: str = "") -> list[StorageItem]:
+        remote = self._remote_path(prefix) if prefix else self.remote_root
+        try:
+            output = self._kuake("list", remote, timeout=30)
+        except StorageError:
+            return []
+
+        try:
+            data = json.loads(output)
+        except json.JSONDecodeError:
+            return []
+
+        items = []
+        for entry in data.get("data", {}).get("list", []):
+            items.append(StorageItem(
+                path=entry.get("file_name", ""),
+                size=entry.get("size", 0),
+                modified_at=0,  # 夸克API不提供mtime
+                is_dir=entry.get("dir", False),
+                etag=entry.get("fid", ""),
+            ))
+        return items
+
+    def walk(self, prefix: str = "") -> list[StorageItem]:
+        """递归列出所有文件（夸克API不支持递归，只能逐层遍历）"""
+        items = []
+        queue = [prefix]
+        seen = set()
+        while queue:
+            current = queue.pop(0)
+            if current in seen:
+                continue
+            seen.add(current)
+            try:
+                children = self.list(current)
+            except StorageError:
+                continue
+            for child in children:
+                full_path = f"{current}/{child.path}".strip("/")
+                if child.is_dir:
+                    queue.append(full_path)
+                else:
+                    items.append(StorageItem(
+                        path=full_path,
+                        size=child.size,
+                        modified_at=child.modified_at,
+                        etag=child.etag,
+                    ))
+        return items
+
+    def _download(self, path: str):
+        """从夸克下载文件到本地缓存"""
+        remote = self._remote_path(path)
+        local = self._local_path(path)
+        local.parent.mkdir(parents=True, exist_ok=True)
+        self._kuake("download", remote, str(local), timeout=120)
+
+    def _upload(self, path: str):
+        """从本地缓存上传到夸克"""
+        local = self._local_path(path)
+        if not local.exists():
+            raise StorageNotFoundError(f"本地缓存不存在: {path}")
+        self._ensure_remote_dirs(path)
+        remote = self._remote_path(path)
+        self._kuake("upload", str(local), remote, timeout=120)

knowflow/adapters/storage/s3.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+"""
+knowflow/adapters/storage/s3.py — S3-compatible storage
+=========================================================
+Requires: pip install knowflow[s3]  (installs boto3)
+
+Config:
+  bucket: str
+  prefix: str (optional, default: "")
+  region: str (optional, default: us-east-1)
+  endpoint_url: str (optional, for MinIO/R2)
+"""
+from knowflow.core.storage import (
+    StorageAdapter, StorageItem, StorageError, StorageNotFoundError
+)
+
+
+class S3Storage(StorageAdapter):
+    """
+    S3-compatible object storage backend.
+    
+    Works with: AWS S3, MinIO, Cloudflare R2, DigitalOcean Spaces, etc.
+    """
+    
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        self._import_check()
+        import boto3
+        self.bucket = config.get("bucket", "knowflow")
+        self.prefix = config.get("prefix", "").strip("/")
+        kwargs = {}
+        if config.get("endpoint_url"):
+            kwargs["endpoint_url"] = config["endpoint_url"]
+        if config.get("region"):
+            kwargs["region_name"] = config["region"]
+        self.client = boto3.client("s3", **kwargs)
+        # Ensure bucket exists
+        try:
+            self.client.head_bucket(Bucket=self.bucket)
+        except Exception:
+            self.client.create_bucket(Bucket=self.bucket)
+    
+    def _import_check(self):
+        try:
+            import boto3  # noqa
+        except ImportError:
+            raise StorageError(
+                "S3 support requires boto3. Install: pip install knowflow[s3]"
+            )
+    
+    def _key(self, path: str) -> str:
+        return f"{self.prefix}/{path}".strip("/")
+    
+    def read(self, path: str) -> str:
+        try:
+            obj = self.client.get_object(Bucket=self.bucket, Key=self._key(path))
+            return obj["Body"].read().decode("utf-8")
+        except self.client.exceptions.NoSuchKey:
+            raise StorageNotFoundError(f"Not found: {path}")
+    
+    def read_binary(self, path: str) -> bytes:
+        try:
+            obj = self.client.get_object(Bucket=self.bucket, Key=self._key(path))
+            return obj["Body"].read()
+        except self.client.exceptions.NoSuchKey:
+            raise StorageNotFoundError(f"Not found: {path}")
+    
+    def write(self, path: str, content: str) -> str:
+        self.client.put_object(Bucket=self.bucket, Key=self._key(path), Body=content.encode())
+        return ""
+    
+    def write_binary(self, path: str, content: bytes) -> str:
+        self.client.put_object(Bucket=self.bucket, Key=self._key(path), Body=content)
+        return ""
+    
+    def delete(self, path: str) -> bool:
+        try:
+            self.client.delete_object(Bucket=self.bucket, Key=self._key(path))
+            return True
+        except Exception:
+            return False
+    
+    def exists(self, path: str) -> bool:
+        try:
+            self.client.head_object(Bucket=self.bucket, Key=self._key(path))
+            return True
+        except Exception:
+            return False
+    
+    def list(self, prefix: str = "") -> list[StorageItem]:
+        key_prefix = self._key(prefix)
+        response = self.client.list_objects_v2(
+            Bucket=self.bucket, Prefix=key_prefix, Delimiter="/"
+        )
+        items = []
+        for obj in response.get("Contents", []):
+            name = obj["Key"][len(key_prefix):].lstrip("/")
+            if name:
+                items.append(StorageItem(
+                    path=f"{prefix}/{name}".strip("/"),
+                    size=obj["Size"],
+                    modified_at=obj["LastModified"].timestamp(),
+                ))
+        return items
+    
+    def walk(self, prefix: str = "") -> list[StorageItem]:
+        key_prefix = self._key(prefix)
+        response = self.client.list_objects_v2(Bucket=self.bucket, Prefix=key_prefix)
+        items = []
+        for obj in response.get("Contents", []):
+            rel = obj["Key"][len(self.prefix):].lstrip("/") if self.prefix else obj["Key"]
+            items.append(StorageItem(
+                path=rel,
+                size=obj["Size"],
+                modified_at=obj["LastModified"].timestamp(),
+            ))
+        return items

knowflow/adapters/storage/webdav.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+"""
+knowflow/adapters/storage/webdav.py — WebDAV storage backend
+=============================================================
+WebDAV protocol — works with: NextCloud, Synology NAS, ownCloud, etc.
+
+Config:
+  base_url: str   — WebDAV endpoint (e.g. https://nextcloud.example.com/remote.php/dav/files/user)
+  username: str   — WebDAV username
+  password: str   — WebDAV password or app token
+  path: str       — Root path within WebDAV (default: /KnowFlow)
+
+Requires: requests (already installed in the environment)
+"""
+import os
+import json
+from pathlib import Path
+from urllib.parse import quote
+from xml.etree import ElementTree as ET
+from knowflow.core.storage import (
+    StorageAdapter, StorageItem, StorageError, StorageNotFoundError
+)
+
+
+WEBDAV_NS = {
+    "d": "DAV:",
+}
+
+
+class WebDAVStorage(StorageAdapter):
+    """
+    WebDAV 存储后端
+
+    兼容：
+      - NextCloud
+      - Synology Drive
+      - ownCloud
+      - Apache mod_dav
+      - 任何标准 WebDAV 服务
+    """
+
+    def __init__(self, config: dict = None):
+        super().__init__(config)
+        cfg = config or {}
+        self.base_url = cfg["base_url"].rstrip("/")
+        self.auth = (cfg.get("username", ""), cfg.get("password", ""))
+        self.root = cfg.get("path", "/KnowFlow").rstrip("/")
+        self._session = None
+        self._check()
+
+    @property
+    def _http(self):
+        """Lazy-import requests to avoid hard dependency"""
+        if self._session is None:
+            import requests
+            self._session = requests.Session()
+            self._session.auth = self.auth
+            self._session.headers.update({
+                "User-Agent": "KnowFlow/0.1.0",
+            })
+        return self._session
+
+    def _check(self):
+        """验证连接"""
+        try:
+            resp = self._http.request("PROPFIND", f"{self.base_url}{self.root}",
+                                       headers={"Depth": "0"}, timeout=15)
+            resp.raise_for_status()
+        except Exception as e:
+            raise StorageError(
+                f"WebDAV 连接失败: {e}\n"
+                f"  URL: {self.base_url}{self.root}\n"
+                f"  请检查 base_url/username/password 是否正确"
+            )
+
+    def _url(self, path: str) -> str:
+        """相对路径 → 完整 URL"""
+        clean = path.lstrip("/")
+        full = f"{self.root}/{clean}"
+        return f"{self.base_url}{full}"
+
+    def _parse_propfind(self, xml: str) -> list[StorageItem]:
+        """解析 PROPFIND 响应 XML → StorageItem 列表"""
+        items = []
+        root = ET.fromstring(xml)
+        for resp in root.findall("d:response", WEBDAV_NS):
+            href = resp.findtext("d:href", "", WEBDAV_NS)
+            if not href:
+                continue
+
+            # 取相对路径
+            rel = href.replace(self.base_url, "").replace(self.root, "").strip("/")
+            if not rel:
+                continue
+
+            prop = resp.find("d:propstat/d:prop", WEBDAV_NS)
+            if prop is None:
+                continue
+
+            is_dir = prop.find("d:resourcetype/d:collection", WEBDAV_NS) is not None
+            size_text = prop.findtext("d:getcontentlength", "0", WEBDAV_NS)
+            size = int(size_text) if size_text.isdigit() else 0
+            mtime_text = prop.findtext("d:getlastmodified", "", WEBDAV_NS)
+            mtime = 0
+            if mtime_text:
+                import email.utils
+                try:
+                    mtime = email.utils.parsedate_to_datetime(mtime_text).timestamp()
+                except Exception:
+                    pass
+
+            items.append(StorageItem(
+                path=rel,
+                size=size,
+                modified_at=mtime,
+                is_dir=is_dir,
+            ))
+        return items
+
+    def read(self, path: str) -> str:
+        resp = self._http.get(self._url(path), timeout=30)
+        if resp.status_code == 404:
+            raise StorageNotFoundError(f"Not found: {path}")
+        resp.raise_for_status()
+        return resp.text
+
+    def read_binary(self, path: str) -> bytes:
+        resp = self._http.get(self._url(path), timeout=30)
+        if resp.status_code == 404:
+            raise StorageNotFoundError(f"Not found: {path}")
+        resp.raise_for_status()
+        return resp.content
+
+    def write(self, path: str, content: str) -> str:
+        self._ensure_parent(path)
+        resp = self._http.put(self._url(path), data=content.encode("utf-8"), timeout=60)
+        resp.raise_for_status()
+        return ""
+
+    def write_binary(self, path: str, content: bytes) -> str:
+        self._ensure_parent(path)
+        resp = self._http.put(self._url(path), data=content, timeout=60)
+        resp.raise_for_status()
+        return ""
+
+    def delete(self, path: str) -> bool:
+        resp = self._http.request("DELETE", self._url(path), timeout=30)
+        if resp.status_code == 404:
+            return False
+        resp.raise_for_status()
+        return True
+
+    def exists(self, path: str) -> bool:
+        resp = self._http.request("PROPFIND", self._url(path),
+                                   headers={"Depth": "0"}, timeout=15)
+        return resp.status_code == 207  # Multi-Status = found
+
+    def list(self, prefix: str = "") -> list[StorageItem]:
+        url = self._url(prefix) if prefix else f"{self.base_url}{self.root}"
+        resp = self._http.request("PROPFIND", url,
+                                   headers={"Depth": "1"}, timeout=30)
+        if resp.status_code != 207:
+            return []
+        all_items = self._parse_propfind(resp.text)
+        # 排除自身
+        root_name = prefix.rstrip("/").split("/")[-1] if prefix else ""
+        return [i for i in all_items if i.path != root_name and i.path]
+
+    def walk(self, prefix: str = "") -> list[StorageItem]:
+        """递归列出所有文件"""
+        url = self._url(prefix) if prefix else f"{self.base_url}{self.root}"
+        resp = self._http.request("PROPFIND", url,
+                                   headers={"Depth": "infinity"}, timeout=60)
+        if resp.status_code != 207:
+            return []
+        all_items = self._parse_propfind(resp.text)
+        root_name = prefix.rstrip("/").split("/")[-1] if prefix else ""
+        return [i for i in all_items if i.path != root_name and i.path and not i.is_dir]
+
+    def _ensure_parent(self, path: str):
+        """确保父目录存在（通过 PROPFIND + MKCOL）"""
+        parent = Path(path).parent.as_posix().strip("/")
+        if not parent or parent == ".":
+            return
+        parts = parent.split("/")
+        current = f"{self.base_url}{self.root}"
+        for part in parts:
+            current = f"{current}/{quote(part, safe='')}"
+            resp = self._http.request("PROPFIND", current,
+                                       headers={"Depth": "0"}, timeout=15)
+            if resp.status_code != 207:
+                # 目录不存在，创建
+                resp = self._http.request("MKCOL", current, timeout=15)
+                if resp.status_code not in (201, 405):  # 201 Created, 405 Already exists
+                    resp.raise_for_status()