Skip to content

Library API

qrtransfer can be used as a Python library. The stable surface lives in qrtransfer.api; the individual modules (qrtransfer.server, qrtransfer.network, ...) are also importable, but their interfaces may change between releases.

Table of Contents

Install

pip install qrtransfer-lite

Serve a file

from qrtransfer.api import Session, start, stop

session = Session(
    token="an-unguessable-token",  # build your own, or use secrets.token_urlsafe(8)
    ip="0.0.0.0",  # advertised IP (informational)
    port=0,  # 0 lets the OS pick a free port
    file_path="/home/me/photo.jpg",
    filename="photo.jpg",
    directory="/home/me",
    max_downloads=1,  # stop after one download (None = keep serving)
)

server = start(session)  # binds and serves in a background thread
print(f"Download from http://{session.ip}:{server.server_address[1]}/{session.token}")
# ... do other work ...
stop(server)  # shutdown() + server_close()

For a fixed port, pass port=8080; if that port is already in use the server will fail to bind and start raises OSError.

Serve a directory or zip

Set file_path/filename/directory to point at an archive (or any file). zip_content creates a temporary zip from files or directories:

from qrtransfer.api import Session, zip_content, start, stop

zip_path = zip_content(["/home/me/docs", "/home/me/a.pdf"])

session = Session(
    token="tok-zip",
    ip="0.0.0.0",
    port=0,
    file_path=zip_path,
    filename=zip_path.rsplit("/", 1)[-1],
    directory=zip_path.rsplit("/", 1)[0],
)
server = start(session)
stop(server)

Receive files

Set mode="receive" and provide directory/downloads_dir; POSTs to the token URL are streamed to that directory:

from qrtransfer.api import Session, start, stop

session = Session(
    token="tok-recv",
    ip="0.0.0.0",
    port=0,
    mode="receive",
    directory="/tmp/inbox",
    downloads_dir="/tmp/inbox",
    max_upload_size=200 * (1 << 20),  # bytes (default is 1 GiB)
)
server = start(session)
stop(server)

TLS

Set scheme="https" and pass a certificate/key to start (or omit them to auto-generate a self-signed certificate, which requires the tls extra):

session = Session(..., scheme="https")
server = start(session)  # auto-generates a cert
# or:
server = start(session, cert="server.crt", key="server.key")

Reference

qrtransfer.api exports:

Symbol Origin Purpose
Session qrtransfer.session Mutable dataclass holding token, limits, expiry, paths, mode.
start(session, cert=None, key=None) this module Bind and serve session in a background thread; returns the running TransferServer.
stop(server) this module shutdown() + server_close() on a server from start.
create_server(session) qrtransfer.server Build a TransferServer without starting it.
TransferServer qrtransfer.server ThreadingHTTPServer subclass (bound in start).
tls_context(cert, key, ip) qrtransfer.tls Build an ssl.SSLContext (auto-generates a cert when cert/key are None).
get_ip(interface=None, ipv6=False) qrtransfer.network Detect the LAN IP for an interface (or the default route).
list_interfaces() qrtransfer.network List Interface(name, ip, ipv6, up) objects.
find_free_port(preferred=None) qrtransfer.network Return a free TCP port (or preferred if it is free).
zip_content(paths) qrtransfer.zipper Zip files/dirs into a temp archive; returns the path.
draw(url) qrtransfer.qr Print an ANSI QR code for url to stdout.
load_config() / save_config(data) qrtransfer.config Read/write the persisted interface/port JSON config.
add_entry(entry) / load_history() qrtransfer.history Append/read transfer-history entries (kept to 200).

Session fields you will usually set

Field Meaning
token URL path token; checked against every request (404 on mismatch).
ip / port Advertised address; port=0 requests an ephemeral port.
mode "send" (default) or "receive".
file_path / filename / directory What to serve in send mode.
downloads_dir Where uploads land in receive mode.
password / expire Gate access (URL param ?passed= or X-Password header).
max_downloads / max_clients / max_upload_size Limits.
scheme "http" (default) or "https".

Security notes for embedders

  • Tokens should come from secrets.token_urlsafe; the server does not generate one for you.
  • max_downloads=None means the server runs until stop() is called, the link expires, or the process exits — shut it down explicitly.
  • Receive mode sanitizes filenames and enforces max_upload_size, but does not authenticate callers beyond the token/password flow described in architecture.md.

Back to README