pardesline 0.1.0__py3-none-any.whl

pardesline/__init__.py

@@ -0,0 +1,173 @@
+"""PardesLine — transfer files between accounts in a few lines.
+
+    import pardesline as pl
+    pl.login()
+    obj = pl.upload("scan.ply")
+    pl.share(obj, to="bob@lab.org")
+
+    # bob:
+    pl.read("alice@lab.org/scan.ply").download("scan.ply")
+
+The module-level helpers use a default client built lazily from the stored
+credentials (PARDESLINE_API_KEY or ~/.pardesline/token). For explicit control,
+use the Client class.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__version__ = "0.1.0"
+
+from .client import Client
+from .errors import (
+    AuthError,
+    Conflict,
+    Forbidden,
+    GpuAddonRequired,
+    NotFound,
+    PardesLineError,
+    PlatformLocked,
+    QuotaExceeded,
+    RateLimited,
+    TooLarge,
+    TransferError,
+)
+from .objects import RemoteObject
+
+__all__ = [
+    "AuthError",
+    "Client",
+    "Conflict",
+    "Forbidden",
+    "GpuAddonRequired",
+    "NotFound",
+    "PardesLineError",
+    "PlatformLocked",
+    "QuotaExceeded",
+    "RateLimited",
+    "RemoteObject",
+    "TooLarge",
+    "TransferError",
+    "delete",
+    "download",
+    "gpu",
+    "inbox",
+    "list_files",
+    "login",
+    "logout",
+    "me",
+    "np",
+    "o3d",
+    "pv",
+    "read",
+    "send",
+    "share",
+    "sitk",
+    "upload",
+    "upload_bytes",
+    "view",
+    "view_registration",
+    "whoami",
+]
+
+_default: Optional[Client] = None
+
+
+def _client() -> Client:
+    global _default
+    if _default is None:
+        _default = Client()
+    return _default
+
+
+def login(token: Optional[str] = None, *, email: Optional[str] = None, save: bool = True) -> Client:
+    """Log in (terminal email+code flow, or with a pl_ key). Returns the client."""
+    global _default
+    _default = Client(token=token) if token else Client()
+    return _default.login(token=token, email=email, save=save)
+
+
+def logout() -> None:
+    _client().logout()
+
+
+def whoami() -> Optional[str]:
+    return _client().whoami()
+
+
+def me():
+    return _client().me()
+
+
+def upload(path, *, name=None, project=None, workspace=None) -> RemoteObject:
+    return _client().upload(path, name=name, project=project, workspace=workspace)
+
+
+def upload_bytes(data: bytes, name: str, *, project=None) -> RemoteObject:
+    return _client().upload_bytes(data, name, project=project)
+
+
+def send(path, to: str, *, name=None, message=None) -> RemoteObject:
+    """Upload a local file and hand it to another account in one call."""
+    return _client().send(path, to=to, name=name, message=message)
+
+
+def read(ref: str) -> RemoteObject:
+    return _client().read(ref)
+
+
+def download(ref: str, path=None, *, extract: bool = False):
+    return _client().download(ref, path, extract=extract)
+
+
+def share(obj, *, to: str, message: Optional[str] = None):
+    return _client().share(obj, to=to, message=message)
+
+
+def inbox(*, limit: int = 50):
+    return _client().inbox(limit=limit)
+
+
+def list_files(scope: str = "mine", *, limit: int = 50):
+    return _client().list(scope, limit=limit)
+
+
+def delete(obj) -> None:
+    _client().delete(obj)
+
+
+def view(*objs):
+    return _client().view(*objs)
+
+
+def view_registration(fixed, moving=None, *, method: str = "rigid"):
+    return _client().view_registration(fixed, moving, method=method)
+
+
+class _GpuProxy:
+    def __getattr__(self, name):
+        return getattr(_client().gpu, name)
+
+
+gpu = _GpuProxy()
+
+
+class _LibProxy:
+    """Module-level pl.o3d / pl.pv / pl.sitk / pl.np — the faithful, server-side
+    mirrors of open3d / pyvista / SimpleITK / numpy (bound to the default client)."""
+
+    def __init__(self, attr: str):
+        self._attr = attr
+
+    def __getattr__(self, name: str):
+        return getattr(getattr(_client(), self._attr), name)
+
+    def __call__(self, *args, **kwargs):
+        return getattr(_client(), self._attr)(*args, **kwargs)
+
+
+o3d = _LibProxy("o3d")
+pv = _LibProxy("pv")
+sitk = _LibProxy("sitk")
+np = _LibProxy("np")

pardesline/_auth.py

@@ -0,0 +1,89 @@
+"""Credential resolution and the terminal login flow.
+
+Precedence (highest first):
+  1. an explicit token passed to Client(token=...) / login(token=...)
+  2. the PARDESLINE_API_KEY environment variable (CI, notebooks)
+  3. the key saved at ~/.pardesline/token (mode 0600) by a previous login()
+
+login() with no argument is the Hugging-Face-style terminal flow: email →
+6-digit code → the SDK mints a long-lived pl_ key with that short session and
+stores it; the session token is discarded.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import stat
+from pathlib import Path
+from typing import Optional
+
+ENV_VAR = "PARDESLINE_API_KEY"
+ENV_BASE_URL = "PARDESLINE_BASE_URL"
+DEFAULT_BASE_URL = "https://appbeta.pardesline.com"
+
+
+def token_path() -> Path:
+    override = os.environ.get("PARDESLINE_TOKEN_PATH")
+    if override:
+        return Path(override)
+    return Path.home() / ".pardesline" / "token"
+
+
+def load_saved_token() -> Optional[str]:
+    p = token_path()
+    try:
+        if p.exists():
+            tok = p.read_text(encoding="utf-8").strip()
+            return tok or None
+    except OSError:
+        pass
+    return None
+
+
+def save_token(token: str) -> Path:
+    p = token_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(token.strip() + "\n", encoding="utf-8")
+    try:
+        os.chmod(p, stat.S_IRUSR | stat.S_IWUSR)  # 0600 (best-effort on Windows)
+    except OSError:
+        pass
+    return p
+
+
+def clear_saved_token() -> None:
+    try:
+        token_path().unlink(missing_ok=True)  # type: ignore[call-arg]
+    except TypeError:  # Python 3.7/3.8 have no missing_ok
+        try:
+            token_path().unlink()
+        except OSError:
+            pass
+    except OSError:
+        pass
+
+
+def resolve_token(explicit: Optional[str] = None) -> Optional[str]:
+    if explicit:
+        return explicit.strip()
+    env = os.environ.get(ENV_VAR)
+    if env:
+        return env.strip()
+    return load_saved_token()
+
+
+def resolve_base_url(explicit: Optional[str] = None) -> str:
+    return (explicit or os.environ.get(ENV_BASE_URL) or DEFAULT_BASE_URL).rstrip("/")
+
+
+def default_key_name() -> str:
+    try:
+        host = socket.gethostname() or "device"
+    except Exception:
+        host = "device"
+    return f"{host} (pardesline-python)"
+
+
+def prompt(msg: str) -> str:
+    return input(msg).strip()

pardesline/_catalog.py

@@ -0,0 +1,136 @@
+"""Bind module methods onto the remote object classes from the live catalog.
+
+The platform's /api/v1/modules lists every module, its methods and which input
+geometry it accepts. We expose each method_id as a Python method on the object
+type it applies to (a point-cloud method on PointCloud, a volume method on
+Volume, …) plus a set of curated friendly aliases. Everything ultimately calls
+obj.run(module_id, method_id, **params).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple
+
+if TYPE_CHECKING:
+    from .client import Client
+
+# Curated, human-friendly aliases → (module_id, method_id). Keep small and
+# obvious; anything else is reachable via obj.run(...) or the generated names.
+ALIASES: Dict[str, Tuple[str, str]] = {
+    # point cloud
+    "downsample": ("point_cloud_processing", "voxel_downsample"),
+    "remove_outliers": ("point_cloud_processing", "statistical_outlier_removal"),
+    "poisson": ("point_cloud_reconstruction", "poisson"),
+    "ball_pivoting": ("point_cloud_reconstruction", "ball_pivoting"),
+    "normals": ("features_extraction", "normal_estimation"),
+    "icp": ("registration", "icp_refinement"),
+    "ransac": ("registration", "ransac_global"),
+    # mesh
+    "decimate": ("pyvista_mesh_processing", "pv_decimate"),
+    "smooth": ("pyvista_mesh_processing", "pv_smooth_laplacian"),
+    "to_points": ("mesh_processing", "mesh_to_pcd_poisson_disk"),
+    # volume / medical (dual-input handled positionally)
+    "register": ("simpleitk_registration", "rigid"),
+    "segment": ("simpleitk_segmentation", "otsu_threshold"),
+}
+
+
+class Catalog:
+    """Loaded once per client from /api/v1/modules."""
+
+    def __init__(self, modules: List[dict]):
+        self.modules = modules
+        # method_id -> list of (module_id, accepted_extensions, dual_input)
+        # We gate by the file EXTENSION against the module's input_formats (like
+        # the server), NOT by coarse geometry: a .ply may be a mesh or a point
+        # cloud, and a module accepting .ply applies to both.
+        self._by_method: Dict[str, List[Tuple[str, frozenset, bool]]] = {}
+        # (module_id, method_id) -> [param schema dicts] and -> display name
+        self._params: Dict[Tuple[str, str], List[dict]] = {}
+        self._method_name: Dict[Tuple[str, str], str] = {}
+        for m in modules:
+            exts = frozenset((e or "").lower() for e in (m.get("input_formats") or []))
+            for meth in m.get("methods", []):
+                self._by_method.setdefault(meth["id"], []).append(
+                    (m["id"], exts, bool(meth.get("dual_input") or m.get("dual_input"))))
+                self._params[(m["id"], meth["id"])] = list(meth.get("parameters") or [])
+                self._method_name[(m["id"], meth["id"])] = meth.get("name") or meth["id"]
+
+    def params(self, module_id: str, method_id: str) -> List[dict]:
+        """The parameter schema (name/type/default/min/max/description) for a
+        method — every knob the algorithm accepts, all optional."""
+        return self._params.get((module_id, method_id), [])
+
+    def validate_params(self, module_id: str, method_id: str, params: dict) -> None:
+        """Raise a helpful ValueError if a param name isn't accepted by this
+        method. No-op when the method is unknown to the catalog (forward-compat)."""
+        key = (module_id, method_id)
+        if key not in self._params:
+            return
+        known = {p.get("name") for p in self._params[key]}
+        unknown = [k for k in params if k not in known]
+        if not unknown:
+            return
+        if known:
+            hint = "Accepted: " + ", ".join(sorted(n for n in known if n)) + "."
+        else:
+            hint = "This method takes no parameters."
+        raise ValueError(
+            f"{module_id}.{method_id}: unknown parameter(s) {', '.join(unknown)}. {hint} "
+            f"See obj.describe({method_id!r}).")
+
+    def describe(self, module_id: str, method_id: str) -> str:
+        """A human-readable listing of every parameter + default + range."""
+        rows = self._params.get((module_id, method_id))
+        title = f"{module_id}.{method_id}  ({self._method_name.get((module_id, method_id), method_id)})"
+        if not rows:
+            return f"{title}\n  (no tunable parameters)"
+        lines = [title]
+        for p in rows:
+            name = p.get("name", "?")
+            typ = p.get("type", "")
+            dflt = p.get("default")
+            rng = ""
+            if p.get("min") is not None or p.get("max") is not None:
+                rng = f" [{p.get('min')}..{p.get('max')}]"
+            opts = f" {{{', '.join(map(str, p['options']))}}}" if p.get("options") else ""
+            desc = p.get("description", "")
+            lines.append(f"  {name}: {typ}={dflt!r}{rng}{opts}  {desc}".rstrip())
+        return "\n".join(lines)
+
+    def resolve(self, method_id: str, extension: Optional[str]) -> Optional[Tuple[str, bool]]:
+        """(module_id, dual_input) for a method whose module accepts `extension`,
+        else None."""
+        candidates = self._by_method.get(method_id)
+        if not candidates:
+            return None
+        ext = (extension or "").lower()
+        if ext:
+            for module_id, exts, dual in candidates:
+                if not exts or ext in exts:
+                    return module_id, dual
+            return None
+        module_id, _exts, dual = candidates[0]
+        return module_id, dual
+
+    def methods_for(self, extension: Optional[str]) -> List[str]:
+        ext = (extension or "").lower()
+        names = set()
+        for method_id, entries in self._by_method.items():
+            for _module_id, exts, _dual in entries:
+                if not ext or not exts or ext in exts:
+                    names.add(method_id)
+                    break
+        return sorted(names)
+
+
+_cache: Dict[str, Catalog] = {}
+
+
+def get_catalog(client: Client) -> Catalog:
+    key = client.base_url
+    cat = _cache.get(key)
+    if cat is None:
+        cat = Catalog([m.model_dump() if hasattr(m, "model_dump") else m for m in client.modules.list()])
+        _cache[key] = cat
+    return cat

pardesline/_http.py

@@ -0,0 +1,126 @@
+"""Thin httpx transport: auth header, retries with backoff, error mapping.
+
+A single place that turns HTTP failures into the typed errors in errors.py and
+retries idempotent calls on 429/5xx. Used by every resource.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import httpx
+
+from . import __version__
+from .errors import PardesLineError, TransferError, from_response
+
+USER_AGENT = f"pardesline-python/{__version__}"
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+class Transport:
+    def __init__(self, base_url: str, token: Optional[str], *, timeout: float = 60.0,
+                 max_retries: int = 3):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.max_retries = max_retries
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if token:
+            headers["X-API-Key"] = token
+        self._client = httpx.Client(base_url=self.base_url, headers=headers, timeout=timeout,
+                                    follow_redirects=True)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def set_token(self, token: Optional[str]) -> None:
+        self.token = token
+        if token:
+            self._client.headers["X-API-Key"] = token
+        else:
+            self._client.headers.pop("X-API-Key", None)
+
+    def request(self, method: str, path: str, *, json: Any = None, params: Any = None,
+                auth: bool = True, timeout: Optional[float] = None) -> Any:
+        """Call an /api endpoint, return the parsed JSON, raise a typed error.
+        `timeout` (seconds) overrides the default for this call (GPU calls need
+        a long read timeout for cold starts)."""
+        headers = {}
+        if not auth:
+            headers["X-API-Key"] = ""  # override the client default for public routes
+        kwargs = {"json": json, "params": params, "headers": headers or None}
+        if timeout is not None:
+            kwargs["timeout"] = httpx.Timeout(connect=30.0, read=float(timeout), write=60.0, pool=30.0)
+        # GPU calls are long single attempts — don't retry a partial compute.
+        retries = 0 if timeout and timeout > 120 else self.max_retries
+        for attempt in range(retries + 1):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+            except httpx.HTTPError as e:
+                if attempt < retries:
+                    time.sleep(0.5 * (2 ** attempt))
+                    continue
+                raise TransferError(f"Network error calling {path}: {e}") from e
+            if resp.status_code in _RETRY_STATUS and attempt < retries:
+                time.sleep(float(resp.headers.get("Retry-After", 0)) or 0.5 * (2 ** attempt))
+                continue
+            if resp.status_code >= 400:
+                try:
+                    body = resp.json()
+                except Exception:
+                    body = {"detail": resp.text}
+                raise from_response(resp.status_code, body)
+            if resp.status_code == 204 or not resp.content:
+                return None
+            return resp.json()
+        raise PardesLineError("request failed after retries")
+
+    # ── raw bytes to/from a storage/API URL (no auth header for signed URLs) ──
+
+    def put_bytes(self, url: str, data, *, headers: Optional[dict] = None, timeout: float = 900.0) -> None:
+        absolute = url if url.startswith("http") else f"{self.base_url}{url}"
+        h = dict(headers or {})
+        # A signed bucket URL must NOT receive our API key; the API fallback
+        # route (relative path) needs it.
+        if not url.startswith("http") and self.token:
+            h["X-API-Key"] = self.token
+        try:
+            with httpx.Client(timeout=timeout) as c:
+                resp = c.put(absolute, content=data, headers=h)
+        except httpx.HTTPError as e:
+            raise TransferError(f"Upload failed: {e}") from e
+        if resp.status_code >= 400:
+            raise TransferError(f"Upload rejected by storage ({resp.status_code}): {resp.text[:200]}")
+
+    def get_bytes(self, url: str, *, timeout: float = 900.0):
+        absolute = url if url.startswith("http") else f"{self.base_url}{url}"
+        h = {}
+        if not url.startswith("http") and self.token:
+            h["X-API-Key"] = self.token
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as c:
+                resp = c.get(absolute, headers=h)
+        except httpx.HTTPError as e:
+            raise TransferError(f"Download failed: {e}") from e
+        if resp.status_code >= 400:
+            raise TransferError(f"Download failed ({resp.status_code}): {resp.text[:200]}")
+        return resp.content
+
+    def stream_to_file(self, url: str, dest, *, timeout: float = 900.0) -> int:
+        absolute = url if url.startswith("http") else f"{self.base_url}{url}"
+        h = {}
+        if not url.startswith("http") and self.token:
+            h["X-API-Key"] = self.token
+        total = 0
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as c:
+                with c.stream("GET", absolute, headers=h) as resp:
+                    if resp.status_code >= 400:
+                        raise TransferError(f"Download failed ({resp.status_code})")
+                    with open(dest, "wb") as f:
+                        for chunk in resp.iter_bytes(chunk_size=1024 * 1024):
+                            f.write(chunk)
+                            total += len(chunk)
+        except httpx.HTTPError as e:
+            raise TransferError(f"Download failed: {e}") from e
+        return total

pardesline/cli.py

@@ -0,0 +1,84 @@
+"""`pardesline` command-line interface — thin wrapper over the client.
+
+    pardesline login
+    pardesline whoami
+    pardesline upload scan.ply
+    pardesline send scan.ply bob@lab.org
+    pardesline inbox
+    pardesline ls
+    pardesline download "alice@lab.org/scan.ply" out.ply
+    pardesline share <file_id> bob@lab.org
+    pardesline logout
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .client import Client
+from .errors import PardesLineError
+
+
+def _fmt_size(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n/1:.0f}{unit}" if False else f"{n:.1f}{unit}"
+        n /= 1024
+    return f"{n:.1f}GB"
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="pardesline", description="Transfer files between PardesLine accounts.")
+    p.add_argument("--version", action="version", version=f"pardesline {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("login", help="Sign in (email + code) and store a key")
+    sub.add_parser("logout", help="Revoke and forget the stored key")
+    sub.add_parser("whoami", help="Show the logged-in account")
+    up = sub.add_parser("upload", help="Upload a file or folder"); up.add_argument("path")
+    se = sub.add_parser("send", help="Upload and share with an email"); se.add_argument("path"); se.add_argument("to")
+    sub.add_parser("inbox", help="Files shared with you")
+    lsp = sub.add_parser("ls", help="Your files"); lsp.add_argument("--scope", default="mine", choices=["mine", "shared", "all"])
+    dl = sub.add_parser("download", help="Download by id or owner@email/name")
+    dl.add_argument("ref"); dl.add_argument("out", nargs="?"); dl.add_argument("--extract", action="store_true")
+    sh = sub.add_parser("share", help="Share one of your files"); sh.add_argument("file_id"); sh.add_argument("to")
+
+    args = p.parse_args(argv)
+    client = Client()
+    try:
+        if args.cmd == "login":
+            client.login(); return 0
+        if args.cmd == "logout":
+            client.logout(); print("Logged out."); return 0
+        if args.cmd == "whoami":
+            print(client.whoami() or "(not logged in)"); return 0
+        if args.cmd == "upload":
+            print(client.upload(args.path)); return 0
+        if args.cmd == "send":
+            obj = client.send(args.path, to=args.to); print(f"Sent {obj.name} to {args.to} (id {obj.id})"); return 0
+        if args.cmd == "inbox":
+            for o in client.inbox():
+                print(f"{o.id}  {o.name:<32} {_fmt_size(o.size_bytes):>9}  from {o.shared_by}")
+            return 0
+        if args.cmd == "ls":
+            for o in client.list(args.scope):
+                print(f"{o.id}  {o.name:<32} {_fmt_size(o.size_bytes):>9}")
+            return 0
+        if args.cmd == "download":
+            dest = client.download(args.ref, args.out, extract=args.extract); print(f"Saved {dest}"); return 0
+        if args.cmd == "share":
+            s = client.share(args.file_id, to=args.to); print(f"Shared with {args.to} ({s.status})"); return 0
+    except PardesLineError as e:
+        print(f"error: {e.message}" + (f"  [{e.code}]" if e.code else ""), file=sys.stderr)
+        if getattr(e, "upgrade_url", None):
+            print(f"  upgrade: {e.upgrade_url}", file=sys.stderr)
+        return 1
+    except (FileNotFoundError, KeyboardInterrupt) as e:
+        print(f"error: {e}", file=sys.stderr); return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())