hfsapi

English | 中文

Python API client for HFS (HTTP File Server): login, file listing, upload, config, and permissions.

Install

Global CLI (recommended) — install so the hfs command is available everywhere:

uv tool install hfsapi
# or (system / user level)
pip install hfsapi

As a project dependency (e.g. for import hfsapi in your code):

pip install hfsapi
# or in a uv-managed project
uv add hfsapi

From source:

uv sync
# or
pip install -e .

Quick start

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))

    # Create folder (same as “New folder” in the web UI)
    client.create_folder("data", "myfolder")

    # Upload
    client.upload_file("data", b"content", filename="hello.txt", use_put=True)

CLI

After installing (e.g. uv tool install hfsapi or pip install hfsapi), the hfs command is available. Log in once to save credentials locally; all other commands then use them (or pass --base-url if not logged in).

hfs login --base-url http://127.0.0.1:8280 -u abct -p abc123
hfs list /data
hfs upload ./local.txt --folder data
hfs upload ./mydir --folder data   # folder: upload contents into --folder (rclone-style)
hfs upload ./file.txt -f data -u -p   # -u print link after upload (resolves server-renamed name), -p progress
hfs mkdir data/myfolder
hfs download data/foo.txt -o ./foo.txt
hfs delete data/foo.txt
hfs config get
hfs vfs
hfs info
hfs logout

Path or URL: For list, upload --folder, download, mkdir, and delete, you can pass either a path (e.g. data/foo.txt) or a full URL (e.g. http://127.0.0.1:8280/data/foo.txt). A URL is parsed to use that server and path for that command.

See hfs --help and hfs <command> --help for options.

Core API

Method / function	Description
HFSClient(base_url, username, password, timeout)	Client; use with or call close() when done.
login()	Establish session via URL params (alternative or complement to Basic auth).
get_file_list(uri, offset, limit, search, request_c_and_m)	Get directory listing, current user permissions, and entry metadata.
list_entries(uri, ...)	Returns only the list array from get_file_list.
upload_file(folder, file_content, filename, use_put, put_params, use_session_for_put)	Upload a file to the given folder.
upload_folder(parent_folder, local_path, on_file_progress, on_progress)	Recursively upload directory contents (rclone-style).
get_resource_url(path, human_readable) / get_uploaded_file_url(folder, filename, response)	Build URL for a path; resolve real filename after upload (e.g. when server renames).
create_folder(parent_folder, new_name, use_put)	Create a new folder under the parent (same as “New folder” in the web UI).
delete_file(folder, filename)	Delete a file under the given folder.
get_config(only, omit) / set_config(values)	Read/write HFS config; e.g. VFS and permissions.
get_vfs()	Get current VFS tree (including permission structure).
entry_size(e) / entry_created(e) / entry_modified(e) / entry_permissions(e)	Helpers for list entry metadata and permission abbreviations.

In list responses: n = name, s = size, c/m = created/modified time; can_archive, can_upload, can_delete, etc. indicate the current user’s permissions for that directory.

More details (permission mapping, testing, publishing, upload options and roots) in HELP.md.

Legal: DISCLAIMER.md — no warranty, no liability, use at your own risk.