pocklo 0.2.0__py3-none-any.whl

pocklo-0.2.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: pocklo
+Version: 0.2.0
+Summary: Command-line client for the Pocklo file workspace
+Project-URL: Homepage, https://pocklo.jyonn.space/
+Project-URL: Documentation, https://pocklo.jyonn.space/cli
+Project-URL: Source, https://github.com/pocklo-app/pocklo-cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: qiniu<8,>=7.13
+Requires-Dist: rich<14,>=13.9
+Requires-Dist: requests<3,>=2.32
+
+# Pocklo CLI · 小兜
+
+`pocklo` is the command-line client for the Pocklo file workspace. It supports:
+
+- SSO-based login by exchanging an authorization `code` for the backend JWT token
+- Listing remote directories
+- Switching into a remote working directory with `cd`
+- Uploading a local file into a remote directory
+- Uploading a local directory recursively while recreating its folder structure remotely
+- Resumable multipart uploads with real remote-part progress
+
+## Install
+
+```bash
+python3 -m pip install pocklo
+```
+
+For local development:
+
+```bash
+pip install -e .
+```
+
+## Commands
+
+Print the SSO authorization URL:
+
+```bash
+pocklo login --print-url
+```
+
+Interactive login:
+
+```bash
+pocklo login
+```
+
+You can also paste the full callback URL directly:
+
+```bash
+pocklo login --code 'https://pocklo.jyonn.space/oauth/qtb/callback?code=...'
+```
+
+Show the authenticated user:
+
+```bash
+pocklo whoami
+```
+
+Change into a remote directory:
+
+```bash
+pocklo cd @Ab12Cd
+pocklo cd Projects
+pocklo cd ../Archive
+```
+
+Print the current remote directory:
+
+```bash
+pocklo pwd
+```
+
+List the current remote directory:
+
+```bash
+pocklo ls
+```
+
+List the remote root directory explicitly:
+
+```bash
+pocklo ls /
+```
+
+List a nested remote directory by relative path:
+
+```bash
+pocklo ls Photos/2024
+```
+
+List a remote resource directly by resource ID:
+
+```bash
+pocklo ls id:Ab12Cd
+```
+
+The shorter `@资源ID` form works too:
+
+```bash
+pocklo ls @Ab12Cd
+```
+
+Upload a local file into a remote directory:
+
+```bash
+pocklo upload ./report.pdf
+```
+
+Upload a local directory recursively. The local directory name is created or reused under the target remote directory:
+
+```bash
+pocklo upload ./albums
+```
+
+Only upload selected extensions:
+
+```bash
+pocklo upload ./albums /Photos --include-ext jpg --include-ext png
+```
+
+Exclude specific extensions:
+
+```bash
+pocklo upload ./albums /Photos --exclude-ext tmp --exclude-ext log
+```
+
+You can combine both flags. `--exclude-ext` takes precedence when both match the same file.
+
+Create a directory under the remote root:
+
+```bash
+pocklo mkdir Projects
+pocklo cd Projects
+pocklo mkdir 2026
+```
+
+Create a directory under a specific remote folder:
+
+```bash
+pocklo mkdir 2026 /Photos
+pocklo mkdir Archive @Ab12Cd
+```
+
+Rename a remote resource:
+
+```bash
+pocklo rename /Photos/old-name.jpg new-name.jpg
+```
+
+Move a remote resource into another remote directory:
+
+```bash
+pocklo mv new-name.jpg ../Archive
+```
+
+Delete a remote file:
+
+```bash
+pocklo rm new-name.jpg
+```
+
+Delete a non-empty remote directory recursively:
+
+```bash
+pocklo rm --recursive Archive
+```
+
+Download a remote file to the current directory:
+
+```bash
+pocklo download report.pdf
+```
+
+Download a remote file into a chosen local path:
+
+```bash
+pocklo download @Ab12Cd ./downloads/report.pdf
+```
+
+Download a remote directory recursively:
+
+```bash
+pocklo download @Ab12Cd ./downloads/Archive
+```
+
+Create a remote link resource:
+
+```bash
+pocklo link Search https://www.google.com
+```
+
+## State File
+
+The CLI stores the backend JWT token and the last fetched user payload in:
+
+```text
+~/.config/pocklo-cli/state.json
+```
+
+On first use, Pocklo imports existing login state and the remote working directory from `~/.config/htx-cli` or `~/.config/disk-cli` when present. Existing upload resume records remain in their configured directory. `DISK_*` environment variables are still read as fallbacks. Use `--config` to point to a different state file.
+
+Multipart upload resume records are stored under:
+
+```text
+~/.config/pocklo-cli/upload-records/
+```

pocklo-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pocklo_cli/__init__.py,sha256=QwLGZDZhVE7dBKbOwCLRt3tRMXTtg8fYYHHDXi3sZ1c,49
+pocklo_cli/__main__.py,sha256=PSQ4rpL0dG6f-qH4N7H-gD9igQkdHzH4yVZDcW8lfZo,80
+pocklo_cli/api.py,sha256=JDYwS8iHUA5ujxIQYVMLmwfN7sYsyLLWWyeoEuGiOJk,16288
+pocklo_cli/cli.py,sha256=VFYqwlLYOAbBL8BwqZUDRHtntCcC1wCKzwija-LD5BI,36101
+pocklo_cli/config.py,sha256=ylhWbh-rWmo9RkPm_yLQfaqx83deUgIPtl4FDCDpvh4,5735
+pocklo-0.2.0.dist-info/METADATA,sha256=NRv9eoigXtEuo-9ufFJqjrCx4Ex0KjHnklmELDVcfHM,3964
+pocklo-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pocklo-0.2.0.dist-info/entry_points.txt,sha256=ikMkStZExnopZOYi5YYHPqTuCGC2hC2hjoAJUba_OtU,47
+pocklo-0.2.0.dist-info/top_level.txt,sha256=JeKwepBYiVu3Marrp0WJFby7-pazJVpy2nxldJnzvkc,11
+pocklo-0.2.0.dist-info/RECORD,,

pocklo-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pocklo-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pocklo = pocklo_cli.cli:main

pocklo-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pocklo_cli

pocklo_cli/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

pocklo_cli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pocklo_cli/api.py

@@ -0,0 +1,426 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import time
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import urljoin, urlparse
+
+import requests
+from qiniu import Auth
+from qiniu.services.storage.uploader import ResumeUploaderV2, UploadProgressRecorder
+
+from .config import PockloSettings
+
+
+class PockloAPIError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        identifier: Optional[str] = None,
+        debug_msg: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.identifier = identifier
+        self.debug_msg = debug_msg
+
+
+@dataclass
+class UploadToken:
+    key: str
+    upload_token: str
+
+
+ProgressCallback = Callable[[int, Optional[int]], None]
+UploadPhaseCallback = Callable[[str], None]
+MAX_RETRIES = 5
+RETRYABLE_STATUS_CODES = {429, 500, 502, 503, 504}
+
+
+class PockloClient:
+    def __init__(self, settings: PockloSettings, *, timeout: float = 30.0) -> None:
+        self.settings = settings
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def _headers(self, *, include_auth: bool = True) -> Dict[str, str]:
+        headers: Dict[str, str] = {}
+        if include_auth and self.settings.token:
+            headers["Token"] = self.settings.token
+        return headers
+
+    def _unwrap_response(self, response: requests.Response) -> Any:
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise PockloAPIError(
+                f"Server returned a non-JSON response (HTTP {response.status_code})."
+            ) from exc
+
+        return self._unwrap_payload(payload, status_code=response.status_code)
+
+    @staticmethod
+    def _unwrap_payload(payload: Any, *, status_code: Optional[int] = None) -> Any:
+        if not isinstance(payload, dict) or "code" not in payload:
+            return payload
+
+        if payload.get("code") != 0:
+            raise PockloAPIError(
+                payload.get("msg") or "The Pocklo API request failed.",
+                status_code=status_code,
+                identifier=payload.get("identifier"),
+                debug_msg=payload.get("debug_msg"),
+            )
+
+        return payload.get("body")
+
+    @staticmethod
+    def _retry_delay(attempt: int) -> float:
+        return min(0.5 * (2 ** (attempt - 1)), 4.0)
+
+    @staticmethod
+    def _should_retry_api_error(error: PockloAPIError) -> bool:
+        return error.status_code in RETRYABLE_STATUS_CODES
+
+    def _request_once(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+        include_auth: bool = True,
+    ) -> Any:
+        response = self.session.request(
+            method=method.upper(),
+            url=url,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            headers=self._headers(include_auth=include_auth),
+            timeout=self.timeout,
+        )
+        return self._unwrap_response(response)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        absolute_url: Optional[str] = None,
+        include_auth: bool = True,
+        data: Optional[Dict[str, Any]] = None,
+        files: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        url = absolute_url or urljoin(f"{self.settings.backend_url}/", path.lstrip("/"))
+        last_error: Optional[Exception] = None
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                return self._request_once(
+                    method,
+                    url,
+                    params=params,
+                    json=json,
+                    data=data,
+                    files=files,
+                    include_auth=include_auth,
+                )
+            except PockloAPIError as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES or not self._should_retry_api_error(exc):
+                    raise
+            except requests.RequestException as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES:
+                    raise PockloAPIError(
+                        f"Request failed after {MAX_RETRIES} attempts: {exc}"
+                    ) from exc
+            time.sleep(self._retry_delay(attempt))
+
+        if isinstance(last_error, PockloAPIError):
+            raise last_error
+        raise PockloAPIError(f"Request failed after {MAX_RETRIES} attempts.")
+
+    def exchange_code(self, code: str) -> Dict[str, Any]:
+        body = self.request(
+            "GET",
+            "/api/oauth/qtb/callback",
+            params={"code": code},
+            include_auth=False,
+        )
+        if not isinstance(body, dict) or "token" not in body:
+            raise PockloAPIError("OAuth callback did not return a login token.")
+        self.settings.token = body["token"]
+        return body
+
+    def get_current_user(self) -> Dict[str, Any]:
+        body = self.request("GET", "/api/user/")
+        if not isinstance(body, dict):
+            raise PockloAPIError("User endpoint returned an unexpected payload.")
+        return body
+
+    def get_resource(self, res_str_id: str, visit_key: Optional[str] = None) -> Dict[str, Any]:
+        params = {"visit_key": visit_key} if visit_key else None
+        body = self.request("GET", f"/api/res/{res_str_id}", params=params)
+        if not isinstance(body, dict):
+            raise PockloAPIError("Resource endpoint returned an unexpected payload.")
+        return body
+
+    def get_selector(self, res_str_id: str) -> Dict[str, Any]:
+        body = self.request("GET", f"/api/res/{res_str_id}/selector")
+        if not isinstance(body, dict):
+            raise PockloAPIError("Selector endpoint returned an unexpected payload.")
+        return body
+
+    def get_path(self, res_str_id: str) -> list[str]:
+        body = self.request("GET", f"/api/res/{res_str_id}/path")
+        if not isinstance(body, list):
+            raise PockloAPIError("Path endpoint returned an unexpected payload.")
+        return [str(item) for item in body]
+
+    def create_folder(self, parent_id: str, folder_name: str) -> Dict[str, Any]:
+        body = self.request(
+            "POST",
+            f"/api/res/{parent_id}/folder",
+            json={"folder_name": folder_name},
+        )
+        if not isinstance(body, dict):
+            raise PockloAPIError("Create-folder endpoint returned an unexpected payload.")
+        return body
+
+    def create_link(self, parent_id: str, link_name: str, link: str) -> Dict[str, Any]:
+        body = self.request(
+            "POST",
+            f"/api/res/{parent_id}/link",
+            json={"link_name": link_name, "link": link},
+        )
+        if not isinstance(body, dict):
+            raise PockloAPIError("Create-link endpoint returned an unexpected payload.")
+        return body
+
+    def update_resource(
+        self,
+        res_str_id: str,
+        *,
+        rname: Optional[str] = None,
+        status: Optional[int] = None,
+        description: Optional[str] = None,
+        visit_key: Optional[str] = None,
+        right_bubble: Optional[bool] = None,
+        parent_str_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body = self.request(
+            "PUT",
+            f"/api/res/{res_str_id}",
+            json={
+                "rname": rname,
+                "status": status,
+                "description": description,
+                "visit_key": visit_key,
+                "right_bubble": right_bubble,
+                "parent_str_id": parent_str_id,
+            },
+        )
+        if not isinstance(body, dict):
+            raise PockloAPIError("Update-resource endpoint returned an unexpected payload.")
+        return body
+
+    def delete_resource(self, res_str_id: str) -> None:
+        self.request("DELETE", f"/api/res/{res_str_id}")
+
+    def _is_backend_json_api_response(
+        self,
+        response: requests.Response,
+        *,
+        requested_url: str,
+    ) -> bool:
+        content_type = response.headers.get("content-type", "").lower()
+        if "application/json" not in content_type:
+            return False
+
+        content_disposition = response.headers.get("content-disposition", "").lower()
+        if "attachment" in content_disposition or "filename=" in content_disposition:
+            return False
+
+        final_url = urlparse(response.url)
+        backend_url = urlparse(self.settings.backend_url)
+        requested = urlparse(requested_url)
+        if (final_url.scheme, final_url.netloc) != (backend_url.scheme, backend_url.netloc):
+            return False
+        return final_url.path.rstrip("/") == requested.path.rstrip("/")
+
+    def download_resource(
+        self,
+        res_str_id: str,
+        destination: Path,
+        *,
+        progress_callback: Optional[ProgressCallback] = None,
+    ) -> str:
+        url = urljoin(f"{self.settings.backend_url}/", f"/api/res/{res_str_id}/dl".lstrip("/"))
+        last_error: Optional[Exception] = None
+        for attempt in range(1, MAX_RETRIES + 1):
+            response: Optional[requests.Response] = None
+            try:
+                response = self.session.get(
+                    url,
+                    params={"token": self.settings.token or ""},
+                    headers={},
+                    timeout=self.timeout,
+                    stream=True,
+                    allow_redirects=True,
+                )
+                try:
+                    response.raise_for_status()
+                except requests.HTTPError as exc:
+                    raise PockloAPIError(
+                        f"Download failed with HTTP {response.status_code}.",
+                        status_code=response.status_code,
+                    ) from exc
+
+                if self._is_backend_json_api_response(response, requested_url=url):
+                    self._unwrap_response(response)
+                    raise PockloAPIError(
+                        "Download endpoint returned JSON metadata instead of file content."
+                    )
+
+                total_header = response.headers.get("content-length")
+                total = int(total_header) if total_header and total_header.isdigit() else None
+                if progress_callback:
+                    progress_callback(0, total)
+
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                transferred = 0
+                with destination.open("wb") as handle:
+                    for chunk in response.iter_content(chunk_size=1024 * 128):
+                        if chunk:
+                            handle.write(chunk)
+                            transferred += len(chunk)
+                            if progress_callback:
+                                progress_callback(transferred, total)
+                return response.url
+            except PockloAPIError as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES or not self._should_retry_api_error(exc):
+                    raise
+            except requests.RequestException as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES:
+                    raise PockloAPIError(
+                        f"Download failed after {MAX_RETRIES} attempts: {exc}"
+                    ) from exc
+            finally:
+                if response is not None:
+                    response.close()
+            time.sleep(self._retry_delay(attempt))
+
+        if isinstance(last_error, PockloAPIError):
+            raise last_error
+        raise PockloAPIError(f"Download failed after {MAX_RETRIES} attempts.")
+
+    def get_upload_token(self, parent_id: str, filename: str) -> UploadToken:
+        body = self.request(
+            "GET",
+            f"/api/res/{parent_id}/token",
+            params={"filename": filename},
+        )
+        if not isinstance(body, dict):
+            raise PockloAPIError("Upload-token endpoint returned an unexpected payload.")
+        return UploadToken(key=body["key"], upload_token=body["upload_token"])
+
+    def upload_file(
+        self,
+        upload: UploadToken,
+        local_path: Path,
+        *,
+        progress_callback: Optional[ProgressCallback] = None,
+        phase_callback: Optional[UploadPhaseCallback] = None,
+    ) -> Dict[str, Any]:
+        last_error: Optional[Exception] = None
+        file_size = local_path.stat().st_size
+        bucket_name = Auth.get_bucket_name(upload.upload_token)
+        if not bucket_name:
+            raise PockloAPIError("Upload token does not contain a valid bucket name.")
+
+        for attempt in range(1, MAX_RETRIES + 1):
+            try:
+                self.settings.upload_record_dir.mkdir(parents=True, exist_ok=True)
+                recorder = UploadProgressRecorder(str(self.settings.upload_record_dir))
+                uploader = ResumeUploaderV2(
+                    bucket_name,
+                    part_size=4 * 1024 * 1024,
+                    progress_handler=progress_callback,
+                    upload_progress_recorder=recorder,
+                )
+
+                context, resp = uploader.initial_parts(
+                    up_token=upload.upload_token,
+                    key=upload.key,
+                    file_path=str(local_path),
+                    file_name=local_path.name,
+                )
+                if resp is not None and not resp.ok():
+                    raise PockloAPIError(
+                        f"Failed to initialize multipart upload: {resp.error}",
+                        status_code=resp.status_code,
+                        debug_msg=resp.text_body,
+                    )
+
+                with local_path.open("rb") as file_handle:
+                    _, resp = uploader.upload_parts(
+                        up_token=upload.upload_token,
+                        data=file_handle,
+                        data_size=file_size,
+                        context=context,
+                        key=upload.key,
+                        file_name=local_path.name,
+                    )
+                if resp is not None and not resp.ok():
+                    raise PockloAPIError(
+                        f"Failed while uploading file parts: {resp.error}",
+                        status_code=resp.status_code,
+                        debug_msg=resp.text_body,
+                    )
+
+                if phase_callback:
+                    phase_callback("finalizing")
+
+                body, resp = uploader.complete_parts(
+                    up_token=upload.upload_token,
+                    data_size=file_size,
+                    context=context,
+                    key=upload.key,
+                    file_name=local_path.name,
+                )
+                if resp is not None and not resp.ok():
+                    raise PockloAPIError(
+                        f"Failed to finalize multipart upload: {resp.error}",
+                        status_code=resp.status_code,
+                        debug_msg=resp.text_body,
+                    )
+                body = self._unwrap_payload(body, status_code=resp.status_code if resp is not None else None)
+                if not isinstance(body, dict):
+                    raise PockloAPIError("Upload endpoint returned an unexpected payload.")
+                return body
+            except PockloAPIError as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES or not self._should_retry_api_error(exc):
+                    raise
+            except requests.RequestException as exc:
+                last_error = exc
+                if attempt >= MAX_RETRIES:
+                    raise PockloAPIError(
+                        f"Upload failed after {MAX_RETRIES} attempts: {exc}"
+                    ) from exc
+            time.sleep(self._retry_delay(attempt))
+
+        if isinstance(last_error, PockloAPIError):
+            raise last_error
+        raise PockloAPIError(f"Upload failed after {MAX_RETRIES} attempts.")