kcfinder-client 0.2.0__tar.gz

kcfinder_client-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Typecheck
+        run: uv run pyrefly check
+
+      - name: Test
+        run: uv run pytest -v

kcfinder_client-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Typecheck
+        run: uv run pyrefly check
+
+      - name: Test
+        run: uv run pytest -v
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

kcfinder_client-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+.venv/
+.pyrefly/
+.ruff_cache/
+*.whl
+*.tar.gz
+.pytest_cache/
+.coverage
+.idea
+htmlcov/
+docs/superpowers/
+.env

kcfinder_client-0.2.0/.markdownlint.rb

@@ -0,0 +1,8 @@
+# https://github.com/markdownlint/markdownlint/blob/main/docs/creating_styles.md
+# https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
+all
+rule 'MD007', :indent => 3
+rule 'MD013', :ignore_code_blocks => true, :tables => false
+rule 'MD029', :style => :ordered
+exclude_rule 'MD033'
+exclude_rule 'MD034'

kcfinder_client-0.2.0/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## Project Overview
+
+A standalone Python client library for KCFinder, a PHP web file manager.
+Wraps KCFinder's HTTP action-dispatch API (`browse.php?act=<action>`) into a
+clean Python interface with both sync and async clients. Designed to work with
+any KCFinder instance, with built-in support for the HarmonySite auth
+extension.
+
+## Build & Development
+
+Python package managed with `uv` and `pyproject.toml`. Requires Python 3.14+.
+
+```bash
+uv sync                    # Install dependencies
+uv run pytest              # Run all tests
+uv run pytest tests/test_client.py::test_list_files  # Run a single test
+uv run pytest -x           # Stop on first failure
+```
+
+### Invoke Tasks
+
+```bash
+inv test       # Run pytest
+inv lint       # Run ruff linter
+inv format     # Run ruff formatter
+inv tc         # Run pyrefly type checker
+inv mdlint     # Run markdownlint on docs (requires Docker)
+inv check      # Lint + format + typecheck + mdlint (run this frequently)
+inv scan       # Security scan (bandit + pip-audit)
+inv build      # Build package with uv
+```
+
+### Live Testing
+
+Atomic live tests for every client method against a real KCFinder server.
+Requires env vars (see `live.py` for details). Credentials are loaded via
+`python-dotenv` from a `.env` file.
+
+```bash
+inv live.auth          # Authenticate, confirm session
+inv live.list          # List files in root (--dir for subdirs)
+inv live.tree          # Root directory node with immediate subdirs
+inv live.expand        # List subdirectories (--dir for subdirs)
+inv live.upload        # Upload a test JPEG
+inv live.download      # Upload, download, verify bytes match
+inv live.thumb         # Upload image, get thumbnail
+inv live.rename        # Upload, rename, verify
+inv live.delete        # Upload, delete, verify gone
+inv live.mkdir         # Create test directory
+inv live.list-dir      # Create dir with file, list contents
+inv live.rename-dir    # Create dir, rename, verify
+inv live.delete-dir    # Create dir, delete, verify gone
+inv live.copy          # Upload, copy to dest dir
+inv live.move          # Upload, move to dest dir
+inv live.bulk-delete   # Upload 2 files, bulk delete
+inv live.download-dir  # Download dir as ZIP
+inv live.download-sel  # Download selected files as ZIP
+inv live.cleanup       # Remove all _test_* artifacts
+inv live.all           # Run all tests in order
+```
+
+## Package Structure
+
+```text
+src/kcfinder_client/
+├── __init__.py          # Public exports
+├── _core.py             # Shared request building, response parsing, error checking
+├── async_client.py      # AsyncKCFinderClient (httpx.AsyncClient)
+├── client.py            # KCFinderClient (httpx.Client, sync)
+├── auth.py              # BaseAuth, HarmonySiteAuth, SessionAuth, harmonysite_auth_from_env
+├── models.py            # FileInfo, DirTree, SyncResult dataclasses
+├── exceptions.py        # KCFinderError hierarchy
+└── sync.py              # SyncManager, SyncManagerSync (one-way push)
+
+live.py                  # Live test tasks (inv live.*)
+tasks.py                 # Invoke task definitions + live namespace registration
+```
+
+## Architecture
+
+### Dual Client Pattern
+
+Two client classes share core logic via private helpers in `_core.py`:
+
+- **`AsyncKCFinderClient`** — async methods, uses `httpx.AsyncClient`
+- **`KCFinderClient`** — sync methods, uses `httpx.Client`
+
+Both are context managers that handle auth and cleanup. All request building,
+response parsing, and error detection lives in `_core.py`.
+
+### KCFinder Protocol
+
+All operations POST to `browse.php?act=<action>` with form data (`dir`,
+`file`, `files[]`). Key protocol details:
+
+- **Session-based auth**: `PHPSESSID` cookie from login step
+- **Required headers**: `Referer` (full browse URL) and
+  `X-Requested-With: XMLHttpRequest`
+- **Auth query params**: HarmonySite's fork requires `bros_config` and
+  `brosseccheck` as query params on every request, not just the session init.
+  This is handled by `BaseAuth.get_query_params()`.
+- **Dir param type prefix**: All `dir` params must include the file type
+  prefix (e.g., `images/subfolder`). The client handles this internally via
+  `prefix_dir()` — callers pass bare paths like `"subfolder"`.
+- **Error handling**: KCFinder returns HTTP 200 even on errors — response body
+  must be inspected. Success is `{}` for mutating actions, JSON for queries.
+  Bulk action errors are arrays joined with `"; "`.
+- **Thumbnail via GET**: `act=thumb` uses GET query params (dir, file), not
+  POST form data.
+- **File scoping**: The `type=images` param scopes to `images/` under
+  `uploadDir` — this is the filesystem ceiling
+
+### Auth Strategy Pattern
+
+Auth is pluggable via `BaseAuth` subclasses. Each strategy implements
+`authenticate(session)`, `authenticate_sync(session)`, `get_referer()`, and
+optionally `get_query_params()`.
+
+- **`HarmonySiteAuth`**: Logs in via `dbaction.php`, then initializes KCFinder
+  session with `bros_config`/`brosseccheck` query params. These params are
+  also sent on every subsequent request via `get_query_params()`.
+- **`SessionAuth`**: For standard KCFinder installs where the session is
+  pre-established
+- **`harmonysite_auth_from_env()`**: Factory that reads credentials from
+  environment variables
+
+### SyncManager
+
+One-way push sync on top of the client. Compares local vs remote files by
+name + size. Supports dry run. Available in both async (`SyncManager`) and
+sync (`SyncManagerSync`) variants.
+
+## Design Principles
+
+- Dual sync/async clients sharing logic via `_core.py` (same pattern as
+  anthropic/openai SDKs)
+- Auth classes take explicit args — no credential sourcing; consumers handle
+  that
+- `harmonysite_auth_from_env()` factory for deployment contexts (n8n, CI)
+- Primary consumer is the `witnessmusic` project via local path dependency
+  (`uv` source)

kcfinder_client-0.2.0/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.

kcfinder_client-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,154 @@
+# 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