hfsapi 0.1.0__py3-none-any.whl

hfsapi/__init__.py

@@ -0,0 +1,21 @@
+"""HFS (HTTP File Server) Python API 客户端 - https://github.com/rejetto/hfs"""
+
+from hfsapi.client import HFSClient
+from hfsapi.models import (
+    DirEntry,
+    FileListResponse,
+    entry_created,
+    entry_modified,
+    entry_permissions,
+    entry_size,
+)
+
+__all__ = [
+    "HFSClient",
+    "DirEntry",
+    "FileListResponse",
+    "entry_size",
+    "entry_created",
+    "entry_modified",
+    "entry_permissions",
+]

hfsapi/client.py

@@ -0,0 +1,324 @@
+"""
+HFS (HTTP File Server) Python API 客户端。
+
+基于 https://github.com/rejetto/hfs 的 OpenAPI 与前端行为实现，
+支持登录、文件列表、上传、配置及权限相关操作。
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any, BinaryIO
+from urllib.parse import urlencode
+
+import httpx
+
+from hfsapi.models import DirEntry, FileListResponse
+
+# POST 请求需携带的防 CSRF 头（HFS OpenAPI 要求）
+HFS_ANTI_CSRF_HEADER = "x-hfs-anti-csrf"
+HFS_ANTI_CSRF_VALUE = "1"
+
+
+class HFSClient:
+    """
+    HFS 服务器 API 客户端。
+
+    认证方式：使用 Basic HTTP 认证或首次请求带 ?login=用户名:密码 建立会话。
+    测试示例： base_url="http://127.0.0.1:8280", username="abct", password="abc123"
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        timeout: float = 30.0,
+        verify: bool = True,
+    ):
+        """
+        :param base_url: 服务器根地址，如 http://127.0.0.1:8280（不要带末尾 /data/）
+        :param username: 登录用户名，如 abct
+        :param password: 登录密码，如 abc123
+        :param timeout: 请求超时秒数
+        :param verify: 是否验证 HTTPS 证书
+        """
+        self.base_url = base_url.rstrip("/")
+        self.username = username
+        self.password = password
+        self.timeout = timeout
+        self.verify = verify
+        self._api_base = f"{self.base_url}/~/api"
+        self._client: httpx.Client | None = None
+
+    def _get_client(self) -> httpx.Client:
+        if self._client is None or self._client.is_closed:
+            auth = None
+            if self.username is not None and self.password is not None:
+                auth = (self.username, self.password)
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                auth=auth,
+                timeout=self.timeout,
+                verify=self.verify,
+                follow_redirects=True,
+            )
+        return self._client
+
+    def _post_headers(self) -> dict[str, str]:
+        return {HFS_ANTI_CSRF_HEADER: HFS_ANTI_CSRF_VALUE}
+
+    def close(self) -> None:
+        """关闭底层 HTTP 客户端。"""
+        if self._client and not self._client.is_closed:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> HFSClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ------------------------- 登录与会话 -------------------------
+
+    def login(self) -> bool:
+        """
+        使用 URL 参数方式建立登录会话（可选）。
+        若已使用 Basic 认证构造客户端，则无需单独调用。
+        返回是否请求成功（不保证服务端一定接受凭证）。
+        """
+        if self.username is None or self.password is None:
+            return False
+        url = f"{self.base_url}/?login={self.username}:{self.password}"
+        try:
+            r = self._get_client().get(url)
+            return r.is_success
+        except Exception:
+            return False
+
+    # ------------------------- 文件列表（对应图片中的「谁可以访问列表」等） -------------------------
+
+    def get_file_list(
+        self,
+        uri: str = "/",
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+        search: str | None = None,
+        request_c_and_m: bool = False,
+    ) -> FileListResponse:
+        """
+        获取指定目录下的文件/文件夹列表（含权限与元数据）。
+
+        对应前端「谁可以访问列表」：有权限时才能拿到 list；列表中每项包含：
+        - 名称、创建/修改时间、大小
+        - 权限缩写 p（r/R/l/L/d 等，仅在与父级不同时返回）
+
+        :param uri: 目录路径，如 "/" 或 "/data"
+        :param offset: 跳过条数
+        :param limit: 最多返回条数
+        :param search: 搜索关键词（含子目录）
+        :param request_c_and_m: 是否同时请求 c（创建）和 m（修改）时间
+        :return: 含 can_archive, can_upload, can_delete, can_comment, list 等字段
+        """
+        params: dict[str, Any] = {"uri": uri}
+        if offset is not None:
+            params["offset"] = offset
+        if limit is not None:
+            params["limit"] = limit
+        if search:
+            params["search"] = search
+        if request_c_and_m:
+            params["c"] = "1"
+        r = self._get_client().get(f"{self._api_base}/get_file_list", params=params)
+        r.raise_for_status()
+        return r.json()
+
+    def list_entries(self, uri: str = "/", **kwargs: Any) -> list[DirEntry]:
+        """便捷方法：只返回 get_file_list 的 list 数组。"""
+        data = self.get_file_list(uri, **kwargs)
+        return data.get("list", [])
+
+    # ------------------------- 下载（对应「谁可以下载」） -------------------------
+
+    def download_file(
+        self,
+        path: str,
+        save_to: str | None = None,
+    ) -> bytes:
+        """
+        下载文件。GET 指定路径，返回内容；若提供 save_to 则写入该路径。
+
+        :param path: 远程路径，如 "/data/Welcome.md" 或 "share/foo.txt"
+        :param save_to: 本地保存路径，若提供则写入文件
+        :return: 文件内容（bytes）
+        """
+        path = path.strip("/")
+        # 使用相对路径，避免带 base_url 的 client 将完整 URL 再拼一次
+        url = f"/{path}" if path else "/"
+        r = self._get_client().get(url)
+        r.raise_for_status()
+        content = r.content
+        if save_to:
+            from pathlib import Path
+
+            Path(save_to).parent.mkdir(parents=True, exist_ok=True)
+            Path(save_to).write_bytes(content)
+        return content
+
+    # ------------------------- 上传（对应「谁可以上传」） -------------------------
+
+    def upload_file(
+        self,
+        folder: str,
+        file_content: BinaryIO | bytes,
+        filename: str | None = None,
+        *,
+        use_put: bool = False,
+        put_params: dict[str, str] | None = None,
+        use_session_for_put: bool = False,
+    ) -> httpx.Response:
+        """
+        上传文件到指定目录。
+
+        :param folder: 目录路径，如 "" 或 "share" 或 "share/sub"
+        :param file_content: 文件内容（文件对象或 bytes）
+        :param filename: 使用 PUT 时的文件名；POST 时由服务端从 multipart 解析
+        :param use_put: True 时用 PUT /{folder}/{filename}，否则用 POST /{folder} multipart
+        :param put_params: PUT 时附加的 query 参数（与前端一致时可传 resume=0! 等）
+        :param use_session_for_put: True 时用仅 session（无 Basic）发 PUT，与浏览器一致，需先 login()
+        :return: 响应对象，可检查 .status_code 与 .json()
+        """
+        folder = folder.strip("/")
+        if use_put:
+            if not filename:
+                raise ValueError("use_put=True 时必须提供 filename")
+            # 使用相对路径，避免带 base_url 的 client 将 URL 重复拼接（与 download_file 一致）
+            path = f"{folder}/{filename}".replace("//", "/") if folder else filename
+            url = f"/{path}" if path else "/"
+            if isinstance(file_content, bytes):
+                body = file_content
+            else:
+                body = file_content.read()
+            if put_params:
+                url = f"{url}?{urlencode(put_params)}"
+            # 与 HFS 前端一致：Referer 为当前目录 URL
+            referer = f"{self.base_url}/{folder}/".replace("//", "/") if folder else f"{self.base_url}/"
+            headers = {**self._post_headers(), "Referer": referer}
+            if use_session_for_put and self.username and self.password:
+                session_client = httpx.Client(
+                    base_url=self.base_url,
+                    timeout=self.timeout,
+                    verify=self.verify,
+                    follow_redirects=True,
+                )
+                try:
+                    session_client.get(f"/?login={self.username}:{self.password}")
+                    if folder:
+                        session_client.get(f"/{folder}/")
+                    r = session_client.put(url, content=body, headers=headers)
+                    # HFS roots：若 host 映射到 root（如 /data），需发 PUT /filename 相对 root
+                    if r.status_code == 404 and folder:
+                        url_rel = f"/{filename}?{urlencode(put_params)}" if put_params else f"/{filename}"
+                        r = session_client.put(url_rel, content=body, headers=headers)
+                    return r
+                finally:
+                    session_client.close()
+            return self._get_client().put(url, content=body, headers=headers)
+        # POST multipart：HFS 文档写的是 curl -F upload=@FILE FOLDER/，字段名用 upload
+        url = f"{self.base_url}/{folder}".replace("//", "/") if folder else self.base_url
+        if isinstance(file_content, bytes):
+            file_content = io.BytesIO(file_content)
+        files = {"upload": (filename or "file", file_content, "application/octet-stream")}
+        return self._get_client().post(
+            url,
+            files=files,
+            headers=self._post_headers(),
+        )
+
+    # ------------------------- 删除（对应「谁可以删除」） -------------------------
+
+    def delete_file(self, folder: str, filename: str) -> httpx.Response:
+        """
+        删除指定目录下的文件。
+
+        HFS 3：对文件路径发 DELETE 请求（path 即要删除的文件）；需当前用户有 can_delete 权限。
+
+        :param folder: 目录路径，如 "share" 或 "share/sub"
+        :param filename: 要删除的文件名（仅文件名，不含路径）
+        :return: 响应对象，可检查 .status_code
+        """
+        folder = folder.strip("/")
+        path = f"{folder}/{filename}".replace("//", "/") if folder else filename
+        url = f"/{path}" if path else "/"
+        return self._get_client().delete(url)
+
+    # ------------------------- 配置（权限、VFS、Serve as web-page 等） -------------------------
+
+    def get_config(
+        self,
+        only: list[str] | None = None,
+        omit: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """
+        获取服务器配置（含 VFS、权限等）。
+
+        :param only: 只返回这些键
+        :param omit: 返回除这些键外的所有键
+        """
+        params: dict[str, Any] = {}
+        if only is not None:
+            params["only"] = only
+        if omit is not None:
+            params["omit"] = omit
+        r = self._get_client().get(f"{self._api_base}/get_config", params=params)
+        r.raise_for_status()
+        return r.json()
+
+    def set_config(self, values: dict[str, Any]) -> httpx.Response:
+        """
+        设置配置项。可用于修改 VFS 节点权限（can_read, can_see, can_upload 等）
+        以及「如果找到 index.html 则作为网页提供」等选项（对应 default 等）。
+
+        与界面权限对应关系：
+        - can_read: 谁可以下载
+        - can_archive: 谁可以压缩
+        - can_list: 谁可以访问列表
+        - can_delete: 谁可以删除
+        - can_upload: 谁可以上传
+        - can_see: 谁可以查看
+        - default: 如 "index.html" 表示该文件夹「作为网页提供」
+
+        :param values: 配置键值，参见 HFS config.md
+        """
+        return self._get_client().post(
+            f"{self._api_base}/set_config",
+            json={"values": values},
+            headers=self._post_headers(),
+        )
+
+    def get_vfs(self) -> Any:
+        """获取当前 VFS 配置（文件/文件夹树及权限）。"""
+        return self.get_config(only=["vfs"]).get("vfs", [])
+
+    # ------------------------- 账户（可选，管理员接口） -------------------------
+
+    def get_accounts(self) -> list[dict[str, Any]]:
+        """获取账户列表（需管理员权限）。"""
+        r = self._get_client().get(f"{self._api_base}/get_accounts")
+        r.raise_for_status()
+        return r.json().get("list", [])
+
+    def get_usernames(self) -> list[str]:
+        """获取用户名列表。"""
+        r = self._get_client().get(f"{self._api_base}/get_usernames")
+        r.raise_for_status()
+        return r.json().get("list", [])
+
+    def get_account(self, username: str) -> dict[str, Any]:
+        """获取单个账户信息。"""
+        r = self._get_client().get(f"{self._api_base}/get_account", params={"username": username})
+        r.raise_for_status()
+        return r.json()

hfsapi/models.py

@@ -0,0 +1,39 @@
+"""
+HFS API 数据模型（与 OpenAPI / 前端一致）。
+
+与界面「谁可以下载/压缩/访问列表/删除/上传/查看」对应：
+- 列表项中的 p：权限缩写，仅在与父级不同时返回。
+  - r: 不可下载  R: 仅其他凭证可下载
+  - l: 不可列目录  L: 仅其他凭证可列目录
+  - d: 可删除
+- 修改这些权限需通过 set_config 修改 VFS 节点上的 can_read / can_archive / can_list / can_delete / can_upload / can_see。
+"""
+
+from typing import Any
+
+# DirEntry：get_file_list 返回的 list 中每一项
+# n=名称, c=创建时间, m=修改时间, s=大小(字节), p=权限缩写, comment=注释
+DirEntry = dict[str, Any]
+
+# get_file_list 响应：can_archive, can_upload, can_delete, can_comment, list
+FileListResponse = dict[str, Any]
+
+
+def entry_size(entry: DirEntry) -> int:
+    """条目大小（字节），文件夹可为 0 或未提供。"""
+    return int(entry.get("s") or 0)
+
+
+def entry_created(entry: DirEntry) -> str | None:
+    """条目创建时间（ISO 字符串）。"""
+    return entry.get("c")
+
+
+def entry_modified(entry: DirEntry) -> str | None:
+    """条目修改时间（ISO 字符串）。"""
+    return entry.get("m")
+
+
+def entry_permissions(entry: DirEntry) -> str:
+    """权限字符串，如 'rLd'；仅在与父级不同时存在。"""
+    return entry.get("p") or ""

hfsapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: hfsapi
+Version: 0.1.0
+Summary: HFS (HTTP File Server) Python API 客户端
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+
+# hfsapi
+
+[HFS (HTTP File Server)](https://github.com/rejetto/hfs) 的 Python API 客户端，支持登录、文件列表、上传、配置与权限相关操作。
+
+## 安装
+
+```bash
+uv sync
+# 或
+pip install -e .
+```
+
+## 快速开始
+
+```python
+from hfsapi import HFSClient, entry_size, entry_created, entry_modified
+
+with HFSClient("http://127.0.0.1:8280", username="abct", password="abc123") as client:
+    data = client.get_file_list(uri="/data")
+    for e in data.get("list", []):
+        print(e["n"], entry_size(e), entry_created(e), entry_modified(e))
+
+    # 上传
+    client.upload_file("data", b"content", filename="hello.txt", use_put=True)
+```
+
+## 核心 API
+
+| 方法 / 函数 | 说明 |
+|-------------|------|
+| **HFSClient**(base_url, username, password, timeout) | 客户端；建议用 `with` 或显式 `close()`。 |
+| **login()** | 使用 URL 参数建立会话（与 Basic 二选一或配合使用）。 |
+| **get_file_list**(uri, offset, limit, search, request_c_and_m) | 获取目录列表及当前用户在该目录的权限、条目元数据。 |
+| **list_entries**(uri, ...) | 仅返回 `get_file_list` 的 `list` 数组。 |
+| **upload_file**(folder, file_content, filename, use_put, put_params, use_session_for_put) | 上传文件到指定目录。 |
+| **delete_file**(folder, filename) | 删除指定目录下的文件。 |
+| **get_config**(only, omit) / **set_config**(values) | 读取/写入 HFS 配置；可改 VFS 与权限等。 |
+| **get_vfs()** | 获取当前 VFS 树（含权限结构）。 |
+| **entry_size**(e) / **entry_created**(e) / **entry_modified**(e) / **entry_permissions**(e) | 列表项元数据与权限缩写解析。 |
+
+列表响应中：`n` 名称、`s` 大小、`c`/`m` 创建/修改时间；`can_archive`、`can_upload`、`can_delete` 等表示当前用户在该目录的权限。
+
+更多说明（权限对应、测试、发布、上传方式与 roots 等）见 **[HELP.md](HELP.md)**。

hfsapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+hfsapi/__init__.py,sha256=hTZfQrPh9TzCAcXt9BBUNntzL2JPauKnadUVhnDkEns,422
+hfsapi/client.py,sha256=rpgVGnI35azOY0r4s9hqWdrLFrTWEkrGRuhzD3MCApI,12799
+hfsapi/models.py,sha256=DFGng0mHc0UyUtEwpq5XQX8zL8sTE5qZMVBE3PQi7dM,1353
+hfsapi-0.1.0.dist-info/METADATA,sha256=Bd3g0lbIEjEr-2eIJ98-OK9WIC5jSrAt4bv0fcsDLAE,2206
+hfsapi-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+hfsapi-0.1.0.dist-info/top_level.txt,sha256=W7sHdemBjJ6XhEileCvntDqiAa9kNqV8Lt0drPKDMtk,7
+hfsapi-0.1.0.dist-info/RECORD,,

hfsapi-0.1.0.dist-info/WHEEL

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

hfsapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hfsapi