kcfinder-client 0.2.0__py3-none-any.whl

kcfinder_client/__init__.py

@@ -0,0 +1,42 @@
+"""Python client library for KCFinder file manager."""
+
+from kcfinder_client.async_client import AsyncKCFinderClient
+from kcfinder_client.auth import (
+    BaseAuth,
+    HarmonySiteAuth,
+    SessionAuth,
+    harmonysite_auth_from_env,
+)
+from kcfinder_client.client import KCFinderClient
+from kcfinder_client.exceptions import (
+    ActionError,
+    AuthError,
+    DirectoryOperationError,
+    FileOperationError,
+    KCFinderError,
+    PermissionDeniedError,
+    UploadError,
+)
+from kcfinder_client.models import DirTree, FileInfo, SyncResult
+from kcfinder_client.sync import SyncManager, SyncManagerSync
+
+__all__ = [
+    "ActionError",
+    "AsyncKCFinderClient",
+    "AuthError",
+    "BaseAuth",
+    "DirTree",
+    "DirectoryOperationError",
+    "FileInfo",
+    "FileOperationError",
+    "HarmonySiteAuth",
+    "KCFinderClient",
+    "KCFinderError",
+    "PermissionDeniedError",
+    "SessionAuth",
+    "SyncManager",
+    "SyncManagerSync",
+    "SyncResult",
+    "UploadError",
+    "harmonysite_auth_from_env",
+]

kcfinder_client/_core.py

@@ -0,0 +1,177 @@
+"""Shared request-building and response-parsing logic for KCFinder clients."""
+
+import json
+from datetime import datetime, timezone
+from urllib.parse import urlencode
+
+from kcfinder_client.exceptions import classify_error
+from kcfinder_client.models import DirTree, FileInfo
+
+
+def prefix_dir(file_type: str, dir: str) -> str:
+    """Build a type-prefixed directory path for KCFinder.
+
+    KCFinder expects all ``dir`` parameters to start with the file type
+    (e.g., ``images/subfolder``).  The PHP constructor validates this prefix
+    via ``checkInputDir`` and strips it before resolving the filesystem path.
+    """
+    if dir:
+        return f"{file_type}/{dir}"
+    return file_type
+
+
+def prefix_file_paths(file_type: str, paths: list[str]) -> list[str]:
+    """Prepend the file type to each path for bulk clipboard operations.
+
+    Bulk actions (cp_cbd, mv_cbd, rm_cbd) expect each file entry to be a
+    type-prefixed path like ``images/subfolder/photo.jpg``.
+    """
+    return [f"{file_type}/{p}" for p in paths]
+
+
+def build_action_url(
+    browse_url: str,
+    action: str,
+    file_type: str | None,
+    extra_params: dict[str, str] | None = None,
+) -> str:
+    """Build the full URL for a KCFinder action."""
+    params: dict[str, str] = {}
+    if extra_params:
+        params.update(extra_params)
+    params["act"] = action
+    if file_type is not None:
+        params["type"] = file_type
+    return f"{browse_url}?{urlencode(params)}"
+
+
+def build_headers(referer: str) -> dict[str, str]:
+    """Build the required headers for a KCFinder request."""
+    return {
+        "X-Requested-With": "XMLHttpRequest",
+        "Referer": referer,
+    }
+
+
+def build_form_data(
+    *,
+    dir: str | None = None,
+    file: str | None = None,
+    new_name: str | None = None,
+    new_dir: str | None = None,
+    files: list[str] | None = None,
+) -> dict[str, str | list[str]]:
+    """Build the form data dict for a KCFinder action."""
+    data: dict[str, str | list[str]] = {}
+    if dir is not None:
+        data["dir"] = dir
+    if file is not None:
+        data["file"] = file
+    if new_name is not None:
+        data["newName"] = new_name
+    if new_dir is not None:
+        data["newDir"] = new_dir
+    if files is not None:
+        data["files[]"] = files
+    return data
+
+
+def parse_file_list(raw: dict) -> list[FileInfo]:
+    """Parse a file list from a KCFinder response into FileInfo objects."""
+    writable = raw.get("dirWritable", False)
+    return [
+        FileInfo(
+            name=f["name"],
+            size=f["size"],
+            mtime=datetime.fromtimestamp(f["mtime"], tz=timezone.utc),  # noqa: UP017
+            is_writable=f.get("writable", writable),
+        )
+        for f in raw.get("files", [])
+    ]
+
+
+def parse_dir_tree(raw: dict) -> DirTree:
+    """Parse a KCFinder init response into a DirTree.
+
+    The init response wraps the tree in a "tree" key at the top level.
+    Files are siblings of "tree", not nested under it.
+    """
+    tree = raw.get("tree", raw)
+    files = parse_file_list(raw) if "files" in raw else []
+    return _parse_tree_node(tree, files)
+
+
+def _parse_tree_node(node: dict, files: list[FileInfo] | None = None) -> DirTree:
+    """Parse a single tree node recursively."""
+    return DirTree(
+        name=node["name"],
+        is_writable=node.get("writable", False),
+        has_subdirs=node.get("hasDirs", False),
+        children=[_parse_tree_node(child) for child in node.get("dirs", [])],
+        files=files if files is not None else [],
+    )
+
+
+def check_upload_response(response_text: str) -> None:
+    """Check an upload response for errors.
+
+    Upload responses differ from other actions: success returns the
+    uploaded filename prefixed with "/" (e.g., "/photo.jpg"). Errors
+    return "filename: error message". Multiple files produce one line
+    per file.
+    """
+    for line in response_text.strip().splitlines():
+        line = line.strip()
+        if not line or line.startswith("/"):
+            continue  # success — uploaded filename
+        raise classify_error(action="upload", message=line)
+
+
+def check_action_error(action: str, response_body: str | dict) -> None:
+    """Check a KCFinder response body for errors and raise if found.
+
+    KCFinder returns HTTP 200 even on errors.  Successful mutating actions
+    return the string ``{}`` (PHP echoes ``{}`` when the handler returns
+    ``true``).  Query actions return valid JSON.  Errors come as plain
+    strings or ``{"error": "message"}`` dicts.  Bulk clipboard actions
+    return ``{"error": ["msg1", "msg2"]}`` with a list of per-file errors.
+    """
+    if isinstance(response_body, dict):
+        if "error" in response_body:
+            err = response_body["error"]
+            msg = "; ".join(err) if isinstance(err, list) else str(err)
+            raise classify_error(action=action, message=msg)
+        return  # empty dict or success dict without "error" key
+    if isinstance(response_body, str):
+        stripped = response_body.strip()
+        if stripped == "" or stripped == "{}":
+            return
+        # Try to parse as JSON — some actions return JSON error strings
+        try:
+            parsed = json.loads(stripped)
+            if isinstance(parsed, dict) and "error" in parsed:
+                err = parsed["error"]
+                msg = "; ".join(err) if isinstance(err, list) else str(err)
+                raise classify_error(action=action, message=msg)
+            return  # valid JSON without "error" key
+        except json.JSONDecodeError:
+            pass
+        raise classify_error(action=action, message=stripped)
+
+
+def parse_expand_response(raw: dict) -> list[DirTree]:
+    """Parse a KCFinder expand response into a list of DirTree nodes.
+
+    The expand action returns ``{"dirs": [{name, writable, hasDirs, ...}]}``.
+    Each entry describes a direct subdirectory (no nested children).
+    """
+    return [
+        DirTree(
+            name=d["name"],
+            is_writable=d.get("writable", False),
+            has_subdirs=d.get("hasDirs", False),
+            children=[],
+            files=[],
+        )
+        for d in raw.get("dirs", [])
+    ]

kcfinder_client/async_client.py

@@ -0,0 +1,214 @@
+"""Async client for KCFinder file manager operations."""
+
+from pathlib import Path
+from types import TracebackType
+from urllib.parse import urlencode
+
+import httpx
+
+from kcfinder_client._core import (
+    build_action_url,
+    build_form_data,
+    build_headers,
+    check_action_error,
+    check_upload_response,
+    parse_dir_tree,
+    parse_expand_response,
+    parse_file_list,
+    prefix_dir,
+    prefix_file_paths,
+)
+from kcfinder_client.auth import BaseAuth
+from kcfinder_client.models import DirTree, FileInfo
+
+
+class AsyncKCFinderClient:
+    """Async client for KCFinder file manager operations."""
+
+    def __init__(
+        self,
+        browse_url: str,
+        auth: BaseAuth,
+        file_type: str = "images",
+    ) -> None:
+        self._browse_url = browse_url
+        self._auth = auth
+        self._file_type = file_type
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> AsyncKCFinderClient:
+        self._client = httpx.AsyncClient()
+        await self._auth.authenticate(self._client)
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._client:
+            await self._client.aclose()
+
+    def _get_client(self) -> httpx.AsyncClient:
+        """Return the active HTTP client, raising if not initialized."""
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Use 'async with' context manager."
+            )
+        return self._client
+
+    async def _post(self, action: str, data: dict) -> httpx.Response:
+        """Send a POST request to KCFinder."""
+        url = build_action_url(
+            self._browse_url, action, self._file_type, self._auth.get_query_params()
+        )
+        headers = build_headers(self._auth.get_referer())
+        return await self._get_client().post(url, data=data, headers=headers)
+
+    async def list_files(self, dir: str = "") -> list[FileInfo]:
+        """List files in a directory (root by default)."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = await self._post("chDir", data)
+        return parse_file_list(response.json())
+
+    async def upload(self, dir: str, files: Path | list[Path]) -> None:
+        """Upload one or more files to a directory."""
+        if isinstance(files, Path):
+            files = [files]
+        url = build_action_url(
+            self._browse_url, "upload", self._file_type, self._auth.get_query_params()
+        )
+        url += "&" + urlencode({"dir": prefix_dir(self._file_type, dir)})
+        headers = build_headers(self._auth.get_referer())
+        upload_files = [("upload[]", (f.name, f.read_bytes())) for f in files]
+        response = await self._get_client().post(
+            url,
+            files=upload_files,
+            headers=headers,
+        )
+        check_upload_response(response.text)
+
+    async def delete(self, dir: str, file: str) -> None:
+        """Delete a file."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), file=file)
+        response = await self._post("delete", data)
+        check_action_error("delete", response.text)
+
+    async def rename(self, dir: str, file: str, new_name: str) -> None:
+        """Rename a file."""
+        data = build_form_data(
+            dir=prefix_dir(self._file_type, dir),
+            file=file,
+            new_name=new_name,
+        )
+        response = await self._post("rename", data)
+        check_action_error("rename", response.text)
+
+    async def download(self, dir: str, file: str) -> bytes:
+        """Download a file and return its content as bytes."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), file=file)
+        response = await self._post("download", data)
+        return response.content
+
+    async def get_thumbnail(self, dir: str, file: str) -> bytes:
+        """Get the thumbnail for a file as PNG bytes.
+
+        Thumbnails are served via GET parameters (used as ``<img src>``
+        in the browser UI), not POST form data.
+        """
+        params = {
+            **self._auth.get_query_params(),
+            "act": "thumb",
+            "type": self._file_type,
+            "dir": prefix_dir(self._file_type, dir),
+            "file": file,
+        }
+        url = f"{self._browse_url}?{urlencode(params)}"
+        headers = build_headers(self._auth.get_referer())
+        response = await self._get_client().get(url, headers=headers)
+        return response.content
+
+    async def get_tree(self) -> DirTree:
+        """Initialize the browser view and return the root directory node."""
+        url = build_action_url(
+            self._browse_url, "init", self._file_type, self._auth.get_query_params()
+        )
+        headers = build_headers(self._auth.get_referer())
+        response = await self._get_client().post(url, headers=headers)
+        return parse_dir_tree(response.json())
+
+    async def expand(self, dir: str = "") -> list[DirTree]:
+        """Get subdirectory info for a directory (root by default)."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = await self._post("expand", data)
+        return parse_expand_response(response.json())
+
+    async def create_dir(self, dir: str, new_dir: str) -> None:
+        """Create a new subdirectory."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), new_dir=new_dir)
+        response = await self._post("newDir", data)
+        check_action_error("newDir", response.text)
+
+    async def rename_dir(self, dir: str, new_name: str) -> None:
+        """Rename a directory."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), new_name=new_name)
+        response = await self._post("renameDir", data)
+        check_action_error("renameDir", response.text)
+
+    async def delete_dir(self, dir: str) -> None:
+        """Delete a directory and all its contents recursively.
+
+        Removes all files and subdirectories within the target directory
+        before removing the directory itself.
+        """
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = await self._post("deleteDir", data)
+        check_action_error("deleteDir", response.text)
+
+    async def download_dir(self, dir: str) -> bytes:
+        """Download a directory as a ZIP archive."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = await self._post("downloadDir", data)
+        return response.content
+
+    async def _bulk_action(
+        self, action: str, files: list[str], dest: str | None = None
+    ) -> None:
+        """Shared logic for bulk copy/move/delete actions.
+
+        File paths are automatically prefixed with the file type (e.g.,
+        ``images/subdir/file.jpg``) as required by the KCFinder protocol.
+        """
+        prefixed = prefix_file_paths(self._file_type, files)
+        data = build_form_data(files=prefixed)
+        if dest is not None:
+            data["dir"] = prefix_dir(self._file_type, dest)
+        response = await self._post(action, data)
+        check_action_error(action, response.text)
+
+    async def copy(self, files: str | list[str], dest: str) -> None:
+        """Copy files to a destination directory."""
+        if isinstance(files, str):
+            files = [files]
+        await self._bulk_action("cp_cbd", files, dest)
+
+    async def move(self, files: str | list[str], dest: str) -> None:
+        """Move files to a destination directory."""
+        if isinstance(files, str):
+            files = [files]
+        await self._bulk_action("mv_cbd", files, dest)
+
+    async def bulk_delete(self, files: list[str]) -> None:
+        """Delete multiple files."""
+        await self._bulk_action("rm_cbd", files)
+
+    async def download_selected(self, dir: str, files: list[str]) -> bytes:
+        """Download selected files as a ZIP archive.
+
+        Unlike bulk clipboard operations, ``files`` here are plain
+        filenames (basenames) within the specified directory.
+        """
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), files=files)
+        response = await self._post("downloadSelected", data)
+        return response.content

kcfinder_client/auth.py

@@ -0,0 +1,160 @@
+import os
+from abc import ABC, abstractmethod
+from urllib.parse import urlencode
+
+import httpx
+
+from kcfinder_client.exceptions import AuthError
+
+
+class BaseAuth(ABC):
+    """Base class for KCFinder authentication strategies."""
+
+    @abstractmethod
+    async def authenticate(self, session: httpx.AsyncClient) -> None:
+        """Authenticate an async HTTP session."""
+
+    @abstractmethod
+    def authenticate_sync(self, session: httpx.Client) -> None:
+        """Authenticate a sync HTTP session."""
+
+    @abstractmethod
+    def get_referer(self) -> str:
+        """Return the Referer URL required for KCFinder requests."""
+
+    def get_query_params(self) -> dict[str, str]:
+        """Return extra query params to include on every KCFinder request.
+
+        The HarmonySite fork requires ``bros_config`` and ``brosseccheck``
+        on every request URL, not just the session init.  Standard KCFinder
+        installs return an empty dict.
+        """
+        return {}
+
+
+class SessionAuth(BaseAuth):
+    """Auth for standard KCFinder installs with a pre-established session.
+
+    Use this when you already have a valid PHPSESSID cookie value.
+    """
+
+    def __init__(self, session_id: str, referer: str) -> None:
+        self._session_id = session_id
+        self._referer = referer
+
+    async def authenticate(self, session: httpx.AsyncClient) -> None:
+        session.cookies.set("PHPSESSID", self._session_id)
+
+    def authenticate_sync(self, session: httpx.Client) -> None:
+        session.cookies.set("PHPSESSID", self._session_id)
+
+    def get_referer(self) -> str:
+        return self._referer
+
+
+class HarmonySiteAuth(BaseAuth):
+    """Auth for HarmonySite's KCFinder fork.
+
+    Authenticates in two steps:
+    1. POST to login_url with credentials to establish a web session
+    2. GET browse_url with bros_config and brosseccheck to init the KCFinder session
+    """
+
+    def __init__(
+        self,
+        login_url: str,
+        browse_url: str,
+        username: str,
+        password: str,
+        bros_config: str,
+        brosseccheck: str = "Xx-ok-xX",
+    ) -> None:
+        self._login_url = login_url
+        self._browse_url = browse_url
+        self._username = username
+        self._password = password
+        self._bros_config = bros_config
+        self._brosseccheck = brosseccheck
+
+    def _login_data(self) -> dict[str, str]:
+        """Build the HarmonySite login form payload."""
+        return {
+            "dbase": "users",
+            "action": "login",
+            "username": self._username,
+            "password": self._password,
+            "nextpage": self._login_url.rsplit("/", 1)[0],
+            "login": "Log In",
+            "remember": "1",
+        }
+
+    async def authenticate(self, session: httpx.AsyncClient) -> None:
+        login_resp = await session.post(
+            self._login_url,
+            data=self._login_data(),
+            follow_redirects=True,
+        )
+        if login_resp.status_code != 200:
+            raise AuthError(f"Login failed with status {login_resp.status_code}")
+
+        init_resp = await session.get(self._init_url())
+        if init_resp.status_code != 200:
+            raise AuthError(
+                f"KCFinder session init failed with status {init_resp.status_code}"
+            )
+
+    def authenticate_sync(self, session: httpx.Client) -> None:
+        login_resp = session.post(
+            self._login_url,
+            data=self._login_data(),
+            follow_redirects=True,
+        )
+        if login_resp.status_code != 200:
+            raise AuthError(f"Login failed with status {login_resp.status_code}")
+
+        init_resp = session.get(self._init_url())
+        if init_resp.status_code != 200:
+            raise AuthError(
+                f"KCFinder session init failed with status {init_resp.status_code}"
+            )
+
+    def get_referer(self) -> str:
+        return self._init_url()
+
+    def get_query_params(self) -> dict[str, str]:
+        return {
+            "bros_config": self._bros_config,
+            "brosseccheck": self._brosseccheck,
+        }
+
+    def _init_url(self) -> str:
+        params = urlencode(
+            {
+                "bros_config": self._bros_config,
+                "brosseccheck": self._brosseccheck,
+            }
+        )
+        return f"{self._browse_url}?{params}"
+
+
+def harmonysite_auth_from_env() -> HarmonySiteAuth:
+    """Build a HarmonySiteAuth from environment variables.
+
+    Required env vars:
+        KCFINDER_LOGIN_URL: The HarmonySite login URL
+        KCFINDER_BROWSE_URL: The KCFinder browse.php URL
+        KCFINDER_USERNAME: Login username
+        KCFINDER_PASSWORD: Login password
+        KCFINDER_BROS_CONFIG: PHP-serialized bros_config string
+
+    Optional env vars:
+        KCFINDER_BROSSECCHECK: Security check token (default: "Xx-ok-xX")
+    """
+    return HarmonySiteAuth(
+        login_url=os.environ["KCFINDER_LOGIN_URL"],
+        browse_url=os.environ["KCFINDER_BROWSE_URL"],
+        username=os.environ["KCFINDER_USERNAME"],
+        password=os.environ["KCFINDER_PASSWORD"],
+        bros_config=os.environ["KCFINDER_BROS_CONFIG"],
+        brosseccheck=os.environ.get("KCFINDER_BROSSECCHECK", "Xx-ok-xX"),
+    )

kcfinder_client/client.py

@@ -0,0 +1,212 @@
+"""Sync client for KCFinder file manager operations."""
+
+from pathlib import Path
+from types import TracebackType
+from urllib.parse import urlencode
+
+import httpx
+
+from kcfinder_client._core import (
+    build_action_url,
+    build_form_data,
+    build_headers,
+    check_action_error,
+    check_upload_response,
+    parse_dir_tree,
+    parse_expand_response,
+    parse_file_list,
+    prefix_dir,
+    prefix_file_paths,
+)
+from kcfinder_client.auth import BaseAuth
+from kcfinder_client.models import DirTree, FileInfo
+
+
+class KCFinderClient:
+    """Sync client for KCFinder file manager operations."""
+
+    def __init__(
+        self,
+        browse_url: str,
+        auth: BaseAuth,
+        file_type: str = "images",
+    ) -> None:
+        self._browse_url = browse_url
+        self._auth = auth
+        self._file_type = file_type
+        self._client: httpx.Client | None = None
+
+    def __enter__(self) -> KCFinderClient:
+        self._client = httpx.Client()
+        self._auth.authenticate_sync(self._client)
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._client:
+            self._client.close()
+
+    def _get_client(self) -> httpx.Client:
+        """Return the active HTTP client, raising if not initialized."""
+        if self._client is None:
+            raise RuntimeError("Client not initialized. Use 'with' context manager.")
+        return self._client
+
+    def _post(self, action: str, data: dict) -> httpx.Response:
+        """Send a POST request to KCFinder."""
+        url = build_action_url(
+            self._browse_url, action, self._file_type, self._auth.get_query_params()
+        )
+        headers = build_headers(self._auth.get_referer())
+        return self._get_client().post(url, data=data, headers=headers)
+
+    def list_files(self, dir: str = "") -> list[FileInfo]:
+        """List files in a directory (root by default)."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = self._post("chDir", data)
+        return parse_file_list(response.json())
+
+    def upload(self, dir: str, files: Path | list[Path]) -> None:
+        """Upload one or more files to a directory."""
+        if isinstance(files, Path):
+            files = [files]
+        url = build_action_url(
+            self._browse_url, "upload", self._file_type, self._auth.get_query_params()
+        )
+        url += "&" + urlencode({"dir": prefix_dir(self._file_type, dir)})
+        headers = build_headers(self._auth.get_referer())
+        upload_files = [("upload[]", (f.name, f.read_bytes())) for f in files]
+        response = self._get_client().post(
+            url,
+            files=upload_files,
+            headers=headers,
+        )
+        check_upload_response(response.text)
+
+    def delete(self, dir: str, file: str) -> None:
+        """Delete a file."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), file=file)
+        response = self._post("delete", data)
+        check_action_error("delete", response.text)
+
+    def rename(self, dir: str, file: str, new_name: str) -> None:
+        """Rename a file."""
+        data = build_form_data(
+            dir=prefix_dir(self._file_type, dir),
+            file=file,
+            new_name=new_name,
+        )
+        response = self._post("rename", data)
+        check_action_error("rename", response.text)
+
+    def download(self, dir: str, file: str) -> bytes:
+        """Download a file and return its content as bytes."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), file=file)
+        response = self._post("download", data)
+        return response.content
+
+    def get_thumbnail(self, dir: str, file: str) -> bytes:
+        """Get the thumbnail for a file as PNG bytes.
+
+        Thumbnails are served via GET parameters (used as ``<img src>``
+        in the browser UI), not POST form data.
+        """
+        params = {
+            **self._auth.get_query_params(),
+            "act": "thumb",
+            "type": self._file_type,
+            "dir": prefix_dir(self._file_type, dir),
+            "file": file,
+        }
+        url = f"{self._browse_url}?{urlencode(params)}"
+        headers = build_headers(self._auth.get_referer())
+        response = self._get_client().get(url, headers=headers)
+        return response.content
+
+    def get_tree(self) -> DirTree:
+        """Initialize the browser view and return the root directory node."""
+        url = build_action_url(
+            self._browse_url, "init", self._file_type, self._auth.get_query_params()
+        )
+        headers = build_headers(self._auth.get_referer())
+        response = self._get_client().post(url, headers=headers)
+        return parse_dir_tree(response.json())
+
+    def expand(self, dir: str = "") -> list[DirTree]:
+        """Get subdirectory info for a directory (root by default)."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = self._post("expand", data)
+        return parse_expand_response(response.json())
+
+    def create_dir(self, dir: str, new_dir: str) -> None:
+        """Create a new subdirectory."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), new_dir=new_dir)
+        response = self._post("newDir", data)
+        check_action_error("newDir", response.text)
+
+    def rename_dir(self, dir: str, new_name: str) -> None:
+        """Rename a directory."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), new_name=new_name)
+        response = self._post("renameDir", data)
+        check_action_error("renameDir", response.text)
+
+    def delete_dir(self, dir: str) -> None:
+        """Delete a directory and all its contents recursively.
+
+        Removes all files and subdirectories within the target directory
+        before removing the directory itself.
+        """
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = self._post("deleteDir", data)
+        check_action_error("deleteDir", response.text)
+
+    def download_dir(self, dir: str) -> bytes:
+        """Download a directory as a ZIP archive."""
+        data = build_form_data(dir=prefix_dir(self._file_type, dir))
+        response = self._post("downloadDir", data)
+        return response.content
+
+    def _bulk_action(
+        self, action: str, files: list[str], dest: str | None = None
+    ) -> None:
+        """Shared logic for bulk copy/move/delete actions.
+
+        File paths are automatically prefixed with the file type (e.g.,
+        ``images/subdir/file.jpg``) as required by the KCFinder protocol.
+        """
+        prefixed = prefix_file_paths(self._file_type, files)
+        data = build_form_data(files=prefixed)
+        if dest is not None:
+            data["dir"] = prefix_dir(self._file_type, dest)
+        response = self._post(action, data)
+        check_action_error(action, response.text)
+
+    def copy(self, files: str | list[str], dest: str) -> None:
+        """Copy files to a destination directory."""
+        if isinstance(files, str):
+            files = [files]
+        self._bulk_action("cp_cbd", files, dest)
+
+    def move(self, files: str | list[str], dest: str) -> None:
+        """Move files to a destination directory."""
+        if isinstance(files, str):
+            files = [files]
+        self._bulk_action("mv_cbd", files, dest)
+
+    def bulk_delete(self, files: list[str]) -> None:
+        """Delete multiple files."""
+        self._bulk_action("rm_cbd", files)
+
+    def download_selected(self, dir: str, files: list[str]) -> bytes:
+        """Download selected files as a ZIP archive.
+
+        Unlike bulk clipboard operations, ``files`` here are plain
+        filenames (basenames) within the specified directory.
+        """
+        data = build_form_data(dir=prefix_dir(self._file_type, dir), files=files)
+        response = self._post("downloadSelected", data)
+        return response.content

kcfinder_client/exceptions.py

@@ -0,0 +1,96 @@
+"""Exception hierarchy for the KCFinder client."""
+
+import re
+
+
+class KCFinderError(Exception):
+    """Base exception for all KCFinder errors."""
+
+
+class AuthError(KCFinderError):
+    """Authentication or session initialization failed."""
+
+
+class ActionError(KCFinderError):
+    """A KCFinder action returned an error in the response body."""
+
+    def __init__(self, action: str, message: str) -> None:
+        self.action = action
+        self.message = message
+        super().__init__(f"{action}: {message}")
+
+
+class DirectoryOperationError(ActionError):
+    """Directory creation, rename, or deletion failed."""
+
+
+class FileOperationError(ActionError):
+    """File not found, cannot copy/move/delete, name conflict, etc."""
+
+
+class PermissionDeniedError(ActionError):
+    """Operation denied due to insufficient permissions."""
+
+
+class UploadError(ActionError):
+    """One or more files failed to upload."""
+
+
+# ---------------------------------------------------------------------------
+# Error message classification
+# ---------------------------------------------------------------------------
+# Patterns derived from the KCFinder PHP source (sunhater/kcfinder).
+# Order matters within each group; groups are checked permission → directory
+# → file → upload, with ActionError as the fallback.
+# ---------------------------------------------------------------------------
+
+_PERMISSION_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"don't have permissions", re.IGNORECASE),
+    re.compile(r"Cannot access or write to upload folder", re.IGNORECASE),
+]
+
+_DIR_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"Cannot (create .+ |rename the |delete the )folder", re.IGNORECASE),
+    re.compile(r"enter new folder name", re.IGNORECASE),
+    re.compile(r"characters in folder name", re.IGNORECASE),
+    re.compile(r"Folder name shouldn't begins with", re.IGNORECASE),
+    re.compile(r"Failed to delete .+ files/folders", re.IGNORECASE),
+]
+
+_FILE_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"does not exist", re.IGNORECASE),
+    re.compile(r"Cannot (read|copy|move|delete) '", re.IGNORECASE),
+    re.compile(r"cannot rename the extension", re.IGNORECASE),
+    re.compile(r"already exists", re.IGNORECASE),
+    re.compile(r"enter new file name", re.IGNORECASE),
+    re.compile(r"characters in file name", re.IGNORECASE),
+    re.compile(r"File name shouldn't begins with", re.IGNORECASE),
+    re.compile(r"Denied file extension", re.IGNORECASE),
+]
+
+_UPLOAD_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"uploaded file", re.IGNORECASE),
+    re.compile(r"No file was uploaded", re.IGNORECASE),
+    re.compile(r"Missing a temporary folder", re.IGNORECASE),
+    re.compile(r"Failed to write file", re.IGNORECASE),
+    re.compile(r"Cannot move uploaded file", re.IGNORECASE),
+    re.compile(r"too big and/or cannot be resized", re.IGNORECASE),
+    re.compile(r"Non-existing directory type", re.IGNORECASE),
+]
+
+
+def classify_error(action: str, message: str) -> ActionError:
+    """Return the most specific ActionError subclass for a KCFinder error message."""
+    for pattern in _PERMISSION_PATTERNS:
+        if pattern.search(message):
+            return PermissionDeniedError(action=action, message=message)
+    for pattern in _DIR_PATTERNS:
+        if pattern.search(message):
+            return DirectoryOperationError(action=action, message=message)
+    for pattern in _FILE_PATTERNS:
+        if pattern.search(message):
+            return FileOperationError(action=action, message=message)
+    for pattern in _UPLOAD_PATTERNS:
+        if pattern.search(message):
+            return UploadError(action=action, message=message)
+    return ActionError(action=action, message=message)

kcfinder_client/models.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class FileInfo:
+    """A file entry returned by KCFinder."""
+
+    name: str
+    size: int
+    mtime: datetime
+    is_writable: bool
+
+
+@dataclass
+class DirTree:
+    """A directory node from KCFinder's init or expand actions.
+
+    The server returns only one level of subdirectories at a time.
+    Use ``expand()`` to load deeper levels on demand.
+    """
+
+    name: str
+    is_writable: bool
+    has_subdirs: bool
+    children: list[DirTree]
+    files: list[FileInfo]
+
+
+@dataclass
+class SyncResult:
+    """Result of a push sync operation."""
+
+    uploaded: list[str]
+    deleted: list[str]
+    skipped: list[str]

kcfinder_client/sync.py

@@ -0,0 +1,93 @@
+"""One-way push sync: make a remote directory match a local directory."""
+
+from pathlib import Path
+
+from kcfinder_client.async_client import AsyncKCFinderClient
+from kcfinder_client.client import KCFinderClient
+from kcfinder_client.models import FileInfo, SyncResult
+
+
+def _compute_sync_actions(
+    local_files: dict[str, int],
+    remote_files: dict[str, int],
+) -> SyncResult:
+    """Compare local and remote file sets by name and size."""
+    uploaded = []
+    skipped = []
+    deleted = []
+
+    for name, local_size in sorted(local_files.items()):
+        if name in remote_files and remote_files[name] == local_size:
+            skipped.append(name)
+        else:
+            uploaded.append(name)
+
+    for name in sorted(remote_files):
+        if name not in local_files:
+            deleted.append(name)
+
+    return SyncResult(uploaded=uploaded, deleted=deleted, skipped=skipped)
+
+
+def _scan_local_dir(local_dir: Path) -> dict[str, int]:
+    """Scan a local directory and return a dict of filename -> size."""
+    return {f.name: f.stat().st_size for f in local_dir.iterdir() if f.is_file()}
+
+
+def _remote_file_map(files: list[FileInfo]) -> dict[str, int]:
+    """Convert a list of FileInfo to a dict of filename -> size."""
+    return {f.name: f.size for f in files}
+
+
+class SyncManager:
+    """Async one-way push sync manager."""
+
+    def __init__(self, client: AsyncKCFinderClient) -> None:
+        self._client = client
+
+    async def push(
+        self, remote_dir: str, local_dir: Path, *, dry_run: bool = False
+    ) -> SyncResult:
+        """Sync local directory to remote, making remote match local."""
+        remote_files = await self._client.list_files(remote_dir)
+        local_map = _scan_local_dir(local_dir)
+        remote_map = _remote_file_map(remote_files)
+        result = _compute_sync_actions(local_map, remote_map)
+
+        if dry_run:
+            return result
+
+        for name in result.uploaded:
+            await self._client.upload(remote_dir, local_dir / name)
+
+        for name in result.deleted:
+            await self._client.delete(remote_dir, name)
+
+        return result
+
+
+class SyncManagerSync:
+    """Sync (non-async) one-way push sync manager."""
+
+    def __init__(self, client: KCFinderClient) -> None:
+        self._client = client
+
+    def push(
+        self, remote_dir: str, local_dir: Path, *, dry_run: bool = False
+    ) -> SyncResult:
+        """Sync local directory to remote, making remote match local."""
+        remote_files = self._client.list_files(remote_dir)
+        local_map = _scan_local_dir(local_dir)
+        remote_map = _remote_file_map(remote_files)
+        result = _compute_sync_actions(local_map, remote_map)
+
+        if dry_run:
+            return result
+
+        for name in result.uploaded:
+            self._client.upload(remote_dir, local_dir / name)
+
+        for name in result.deleted:
+            self._client.delete(remote_dir, name)
+
+        return result

kcfinder_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: kcfinder-client
+Version: 0.2.0
+Summary: Python client library for KCFinder file manager
+Project-URL: Changelog, https://github.com/cyberops7/kcfinder-client/releases
+Project-URL: Issues, https://github.com/cyberops7/kcfinder-client/issues
+Project-URL: Repository, https://github.com/cyberops7/kcfinder-client
+License-Expression: MIT
+License-File: LICENSE
+Keywords: file-manager,httpx,kcfinder,php
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# kcfinder-client
+
+[![CI](https://github.com/cyberops7/kcfinder-client/actions/workflows/ci.yml/badge.svg)](https://github.com/cyberops7/kcfinder-client/actions/workflows/ci.yml)
+![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+A Python client library for [KCFinder](https://github.com/sunhater/kcfinder),
+a PHP web file manager. Wraps KCFinder's HTTP action-dispatch API into a clean
+Python interface with both async and sync clients.
+
+> [!NOTE]
+> Designed for and tested against HarmonySite's KCFinder fork.
+> May work with other KCFinder instances via `SessionAuth`, but this
+> has not been tested.
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Auth from Environment Variables](#auth-from-environment-variables)
+- [Sync Files with SyncManager](#sync-files-with-syncmanager)
+- [Documentation](#documentation)
+
+## Install
+
+```bash
+# uv
+uv add kcfinder-client
+
+# pip
+pip install kcfinder-client
+```
+
+## Quick Start
+
+### Async (recommended)
+
+```python
+import asyncio
+import os
+from kcfinder_client import AsyncKCFinderClient, HarmonySiteAuth
+
+auth = HarmonySiteAuth(
+    login_url="https://example.harmonysong.com/dbaction.php",
+    browse_url="https://example.harmonysong.com/kcfinder/browse.php",
+    username="admin",
+    password="secret",
+    bros_config=(
+        'a:3:{s:9:"uploadDir";s:6:"files/";'
+        's:9:"thumbsDir";s:14:"files/.thumbs/";'
+        's:9:"uploadURL";s:0:"";}'
+    ),
+)
+
+async def main():
+    browse_url = "https://example.harmonysong.com/kcfinder/browse.php"
+    async with AsyncKCFinderClient(browse_url, auth) as client:
+        files = await client.list_files("banners")
+        for f in files:
+            print(f.name, f.size)
+
+asyncio.run(main())
+```
+
+### Sync
+
+```python
+from kcfinder_client import KCFinderClient, HarmonySiteAuth
+
+auth = HarmonySiteAuth(
+    login_url="https://example.harmonysong.com/dbaction.php",
+    browse_url="https://example.harmonysong.com/kcfinder/browse.php",
+    username="admin",
+    password="secret",
+    bros_config=(
+        'a:3:{s:9:"uploadDir";s:6:"files/";'
+        's:9:"thumbsDir";s:14:"files/.thumbs/";'
+        's:9:"uploadURL";s:0:"";}'
+    ),
+)
+
+browse_url = "https://example.harmonysong.com/kcfinder/browse.php"
+with KCFinderClient(browse_url, auth) as client:
+    files = client.list_files("banners")
+    for f in files:
+        print(f.name, f.size)
+```
+
+## Auth from Environment Variables
+
+Load credentials from the environment rather than hardcoding them:
+
+```bash
+export KCFINDER_LOGIN_URL=https://example.harmonysong.com/dbaction.php
+export KCFINDER_BROWSE_URL=https://example.harmonysong.com/kcfinder/browse.php
+export KCFINDER_USERNAME=admin
+export KCFINDER_PASSWORD=secret
+export KCFINDER_BROS_CONFIG='a:3:{s:9:"uploadDir";s:6:"files/";s:9:"thumbsDir";s:14:"files/.thumbs/";s:9:"uploadURL";s:0:"";}'
+```
+
+```python
+import os
+from kcfinder_client import AsyncKCFinderClient, harmonysite_auth_from_env
+import asyncio
+
+async def main():
+    auth = harmonysite_auth_from_env()
+    browse_url = os.environ["KCFINDER_BROWSE_URL"]
+    async with AsyncKCFinderClient(browse_url, auth) as client:
+        files = await client.list_files()
+        print(f"Found {len(files)} files")
+
+asyncio.run(main())
+```
+
+## Sync Files with SyncManager
+
+One-way push sync to make a remote directory match a local one:
+
+```python
+import os
+from pathlib import Path
+from kcfinder_client import KCFinderClient, SyncManagerSync, harmonysite_auth_from_env
+
+auth = harmonysite_auth_from_env()
+browse_url = os.environ["KCFINDER_BROWSE_URL"]
+
+with KCFinderClient(browse_url, auth) as client:
+    sync = SyncManagerSync(client)
+
+    # Dry run first to preview changes
+    result = sync.push("banners", Path("./banners"), dry_run=True)
+    print(f"Would upload: {result.uploaded}")
+    print(f"Would delete: {result.deleted}")
+    print(f"Would skip:   {result.skipped}")
+
+    # Apply the sync
+    result = sync.push("banners", Path("./banners"))
+```
+
+## Documentation
+
+- [Auth setup](docs/auth.md) — HarmonySiteAuth, SessionAuth, env vars
+- [File operations](docs/files.md) — list, upload, download, delete, rename,
+  thumbnails
+- [Directory operations](docs/directories.md) — tree, expand, create, rename,
+  delete
+- [Bulk operations](docs/bulk.md) — copy, move, bulk delete, download selected
+- [Sync manager](docs/sync.md) — push sync, dry run, SyncResult
+- [Exceptions](docs/exceptions.md) — error handling, exception hierarchy
+
+## License
+
+MIT

kcfinder_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+kcfinder_client/__init__.py,sha256=WJ10BvBqmT5z6P1LpHDHTRp_-0L8BDWJVBvQ9mp__nY,1013
+kcfinder_client/_core.py,sha256=J5DOjXHCqD8MGTbEJE_hoaQgUzfaFvkDVEpPo8GeBq4,6137
+kcfinder_client/async_client.py,sha256=PQ64rKyqGkfv9uzE60aWTOhc_knz0KM9hKji-i7fnoE,8321
+kcfinder_client/auth.py,sha256=-HMW3cn9_zqP6kZnjibKOtcqPX0U723cdcQxtEt3Tg8,5189
+kcfinder_client/client.py,sha256=QlqMhtOeoetn1DKPGg1cn8ZtmX2x-30jibwYvcyIdRo,8020
+kcfinder_client/exceptions.py,sha256=aMEGtAFOr46akKc-Qh2Ey9CFyYIDfBc25lDLWiCptZk,3706
+kcfinder_client/models.py,sha256=HEOOQPNQBLH6e4UOd-SOXdmdZfU6iZegKRlLH4NiSLw,689
+kcfinder_client/sync.py,sha256=eJUnK2CWHSlNi1gkATmqrvPq0KZuXJuQV2B0SrEFzJw,2941
+kcfinder_client-0.2.0.dist-info/METADATA,sha256=5e0nwQOtt0H_ZWlGdbuhomVrU-h3Fvw_4LdYMgSNJPs,5403
+kcfinder_client-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+kcfinder_client-0.2.0.dist-info/licenses/LICENSE,sha256=ynoj1mLUphGX7jiRCgzPXIyhNQRpz5J1oLVumMoFsus,1066
+kcfinder_client-0.2.0.dist-info/RECORD,,

kcfinder_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kcfinder_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cyberops7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.