NativeHTMLKit — Python SDK
An independent Python SDK (import nativehtmlkit) for the NativeHTMLKit Core
host: native HTML/CSS desktop windows, DOM/form/node operations, events, live bitmaps and desktop
services. No browser, JavaScript, web server, PyO3 extension or Rust compiler is needed by users of a
platform wheel: the wheel embeds one prebuilt, SHA-256-pinned Core host. Pure standard library; Python ≥ 3.10.
Version 0.1.1 — bundles NativeHTMLKit Core 1.0.3. Wire protocol v1 is the stable wire contract (1.0)
since Core 1.0.3. This SDK version relies on Core 1.0.3 behaviour (backend output relayed at every diagnostics
level, out-of-order document.load replies, notification backpressure counters); a host given through
NATIVEHTMLKIT_HOST_BINARY should be 1.0.3 or later. Qualification record:
docs/QUALIFICATION.md. Releases: https://github.com/nativehtmlkit/nativehtmlkit-python/releases.
Install
python -m pip install nativehtmlkit
Only two platform wheels are published (there is no source distribution on PyPI):
| Platform | Wheel tag | Requirement |
|---|---|---|
| Linux x86-64 | manylinux_2_39_x86_64 |
glibc ≥ 2.39 (e.g. Ubuntu 24.04+, Debian 13, Fedora 40+) and a desktop session (Wayland/X11) |
| Windows x64 | win_amd64 |
Windows 10/11 or Server 2022, interactive desktop |
CPython 3.10–3.14. On any other platform (macOS, ARM, 32-bit, older glibc) pip finds no compatible
distribution and reports that no matching distribution was found; nothing is built from source. A downloaded
release wheel installs offline with python -m pip install --no-index ./nativehtmlkit-0.1.1-py3-none-<tag>.whl.
nativehtmlkit-python version shows the bundled host, its SHA-256 and whether it matches the pinned manifest.
Run an app
from nativehtmlkit import Application
def main():
with Application.start(name="Hello NativeHTMLKit") as app:
window = app.open_html('<button id="hello">Hello</button><p id="status"></p>')
window.document.on("click", lambda _: window.document.set_text("status", "Hi"), element="hello")
app.run()
if __name__ == "__main__":
main()
python app.py starts the native host, which re-runs the same command as its supervised backend
(two processes: top-level code before Application.start() runs twice; keep side effects inside main).
The host-first runner avoids that:
python -m nativehtmlkit run mypackage.app:main --name MyApp # or: nativehtmlkit-python run ...
main(app) runs only in the backend; it creates windows and subscribes to events, then the runner calls
app.run(). It may be async def; it then runs under asyncio.run() and may await app.async_adapter().run().
Installed commands: nativehtmlkit-python (runner, doctor, version, support), nativehtmlkit-python-host
(forwards to the bundled host, e.g. nativehtmlkit-python-host run --app app.toml), nativehtmlkit-new
(project scaffold) and nativehtmlkit-skill (agent skill installer). The SDK never installs a nativehtmlkit
executable: that name belongs to the Rust CLI.
Host resolution (every launch path: Application.start(), run, doctor, nativehtmlkit-python-host):
NATIVEHTMLKIT_HOST_BINARY— explicit development override, used as given (not verified);- the wheel's bundled host — verified against the SHA-256 in its
HOST-MANIFEST.jsonbefore every launch; a missing/unreadable manifest or a mismatch raisesHostVerificationErrorand nothing is executed; - only with
NATIVEHTMLKIT_ALLOW_PATH_HOST=1: the firstnativehtmlkit-hostin an absolutePATHentry (never the current directory or a relative entry, also on Windows); unpinned, so a warning is printed on stderr and recorded. Without the opt-in there is no PATH fallback.
version prints SDK/protocol versions, the host path, its SHA-256 and whether it matches the manifest. The
verification hashes the file before it is started; an attacker who can rewrite files inside the installed
package between that check and the start is out of scope (they could equally replace the SDK's Python code).
Public API (summary)
| Object | Purpose |
|---|---|
Application |
start(), from_environment(), open_html()/open_file()/create_window(), run(), close(), request_quit(), on_window_event(), on_shutdown(), on_before_quit(), capabilities(), clipboard and desktop services, async_adapter(), low-level rpc |
Window |
load_html()/load_file(), set()/state(), request_close(), on_before_close(), native dialogs open_files()/save_file()/choose_folder() (wait=False returns a cancellable future) |
Document |
generation-bound DOM API: text/value/checked/attributes/classes/HTML, query()/query_nodes()/node(), forms (form_data, request_submit, validity), focus/selection/editing, styles, scrolling, dialogs/popovers, register_resources(), create_bitmap(), command(op, **fields) for every Core op, on(event, cb, element=...) → unsubscribe function |
Node |
opaque node references (incl. elements without ids) and node mutations |
LiveBitmap |
bounded RGBA8 frames for <img src="ui4me-bitmap://ID"> |
RpcClient |
low-level wire-v1 client (call, call_async → concurrent.futures.Future, notify, on_request, on_notification) |
AsyncApplication, AsyncRpcClient, EventDispatcher |
asyncio adapter over the same connection |
export_support_bundle(), diagnostics_session_id |
local, explicit, sanitized support ZIP |
Threading, asyncio and blocking
- One connection: a reader and a writer thread own the socket/pipe; application callbacks never run on
them. Document/window notifications are delivered in order on one event worker; host requests
(
window.before_close,app.before_quit) are answered by a small worker pool so a slow event callback does not block close/quit policy. - A sync callback may call any sync API (including RPCs). A failing handler is reported (stderr + diagnostics)
and does not stop the other handlers of the same event; unsubscribing a handler from another handler of
the same event takes effect immediately.
SystemExit/KeyboardInterruptraised in an event callback is reported and event delivery continues (callclose()/request_quit()to end the app). - Host requests (
window.before_close,app.before_quit) are always answered: a handler exception of any kind yields error -32603 with only the exception type (never its text).SystemExit/KeyboardInterruptin such a handler is answered first, then the SDK sendsapp.request_quitfor an orderly shutdown. - Futures returned by
RpcClient.call_async()andWindow.open_files/save_file/choose_folder(wait=False)complete on the dedicatednativehtmlkit-completionsthread, never on the transport reader; their done-callbacks may call synchronous RPCs (a done-callback that blocks delays later completions). - Sync calls block the calling thread (default deadline 15 s,
document.load30 s, native dialogs none). Calling a blocking API on a running asyncio loop emits aRuntimeWarning(once) and a diagnostic record. AsyncRpcClient.call()awaitsasyncio.wrap_futureof the transport future (never.result()on the loop).AsyncApplication.on_document_event()runs plain orasynccallbacks FIFO on the owning loop; the returned function disposes the subscription — no invocation starts afterwards, even for events already queued. A full dispatcher queue drops the event and incrementsdispatcher.dropped.await AsyncApplication.run()returns after orderly shutdown; cancelling it closes the connection and finishes promptly (the worker polls every 0.1 s; tested < 2 s), leaving no stuck thread.await AsyncApplication.close()may be called from inside a dispatched handler (with or withoutrun()): the dispatcher then finishes after the current callback instead of waiting for itself.- After
app.shutdown,create_window()/open_html()/load_*()raiseApplicationShutdownError.
Errors
All SDK errors derive from NativeHTMLKitError (classification, code, operation, request_id, session_id,
outcome_unknown). classification is the stable NHK-… category on every error. For compatibility code
equals classification everywhere except RpcError, where code is the numeric wire code (int) and
classification is NHK-HOST-RPC (ClientBusyError: NHK-CLIENT-BUSY); error_id is kept as an alias.
| Error | When | Notes |
|---|---|---|
RpcError |
the host returned an error | .code is the numeric v1 code (-32004 closed/stale id, -32005 busy, -32008 invalid state, …); never parse .message |
ClientBusyError (RpcError, local=True) |
SDK refused to queue (128 pending / 8 MiB outgoing) | nothing was sent |
RpcTimeoutError (TimeoutError) |
local deadline expired (sync and asyncio) | cancellation requested; outcome_unknown=True — no rollback |
DisconnectedError (ConnectionError) |
connection ended | every pending call fails with operation, request_id, pending_failed, __cause__; outcome_unknown=True |
ProtocolError |
the host sent a malformed frame/JSON, duplicate keys or an invalid response; bad token shape; protocol ≠ 1 | fatal for the session |
LocalRequestError (ValueError) |
the caller's request is not JSON-encodable (NaN, lone surrogate, non-string keys, objects) or exceeds 2 MiB | nothing was sent; the session continues |
StaleDocumentError (StaleHandleError, RuntimeError) |
handle of a replaced/unloaded document or closed window | raised locally before any RPC |
ApplicationShutdownError (StaleHandleError, RuntimeError) |
window/document creation after app.shutdown |
raised locally |
HostVerificationError (FileNotFoundError) |
bundled host missing its manifest or not matching its pinned SHA-256 | nothing executed |
StartupError (RuntimeError) |
direct start cannot launch or connect (incl. arguments/paths containing {app_dir}, which the host would substitute) |
Application.run() returns after orderly shutdown or after this process called close(); it raises
DisconnectedError if the host connection was lost. On app.shutdown the SDK first delivers the events
already received, then marks every window and document handle stale (protocol v1 §7: shutdown implies
all windows closed; the host sends no closed event for the last window), then runs on_shutdown hooks.
Diagnostics and support bundles
NATIVEHTMLKIT_DIAGNOSTICS=trace python app.py # or: python -m nativehtmlkit --diagnostics trace run pkg.app:main
python -m nativehtmlkit support ./support.zip # explicit; latest recorded session (or --session ID)
- Levels
off|normal|debug|trace(shared with Core and passed to the host unchanged). Applicationprint()output and tracebacks are relayed at every level, includingoff(Core ≥ 1.0.3; with a Core 1.0.2 host given throughNATIVEHTMLKIT_HOST_BINARYthey are lost atoff, NHK-CROSS-0007). normalkeeps a bounded in-memory history only;debug/tracealso writepython-<session>-<pid>.jsonl(0600) underNATIVEHTMLKIT_DIAGNOSTICS_DIR(default~/.local/state/nativehtmlkit/diagnostics, Windows%LOCALAPPDATA%\NativeHTMLKit\diagnostics).NATIVEHTMLKIT_DIAGNOSTIC_SESSION_ID([A-Za-z0-9._:-]{1,128}; generated if absent/invalid) is exported to the host and backend; Core ≥ 1.0.2 tags its stderr records with it (diagnostic_session_id).- Trace records correlate a host notification (
host.notification,event_seq, event type, element id) →document.dispatch(handlers / matched) →callback.started/completed/failed→rpc.started(cause_seq,document.commandop name) →rpc.completed(duration, error code). This pinpoints e.g. "Submit did nothing" (event arrived,matched: 0). - Records never contain RPC params/results, form values, typed text, tokens, URLs or file paths.
methodandopare allow-listed against the pinned contract (anything else becomesunknown-method/unknown-op); fields named like messages, titles, labels, paths, values etc. are always[REDACTED]; other strings must be short identifiers. Element ids and event types are recorded attrace(author-chosen markup ids). Ring eviction (history_evicted), writer-queue loss (dropped) and I/O errors are counted and exported. - The support ZIP is created 0600 through an exclusive random temporary file and never replaces an existing
file unless
--force/overwrite=Trueis given. - The support ZIP contains only
manifest.jsonand re-sanitizedtimeline.jsonl; never environment variables, raw host stderr or screenshots.NATIVEHTMLKIT_HOST_LOG=PATH/run --host-log PATHopt in to a raw host stderr capture (0600): sensitive (may contain backend output), never bundled.
Wire compatibility
Protocol v1 launch variables UI4ME_ENDPOINT, UI4ME_TOKEN, UI4ME_APP_ID, UI4ME_PROTOCOL_VERSION are kept
(they are the v1 contract). The SDK validates the token shape, removes all four (and its own
UI4ME_DIRECT_START) from os.environ right after connecting — also on failure — and never logs them.
contracts/core-v1-method-matrix.json is a byte-identical, SHA-pinned copy of Core's protocol/v1/method-matrix.json;
a test checks every method/op the SDK sends exists in it.
Known limitations and host-version notes
-
Linux wheels are tagged
manylinux_<glibc floor>_x86_64from the embedded host (Core 1.0.3: glibc ≥ 2.39, e.g. Ubuntu 24.04+/Debian 13); installers refuse older systems. Each wheel records the host's source identity (--version --verbose), cross-checked against the Core release manifest when packaging and bynativehtmlkit-python versionon the target.scripts/package-local.pyoutput is reproducible (fixedSOURCE_DATE_EPOCH, normalised archives). The sdist contains no host: installing it fails with an explanation unlessNATIVEHTMLKIT_DEV_SOURCE_ONLY=1(then setNATIVEHTMLKIT_HOST_BINARY). -
Core ≥ 1.0.2: a backend
request_closeof a non-last window beforeapp.readycloses only that window, so anopen_html()/open_file()load failure during startup raises a catchable error. Closing the last window (or a user close) beforeapp.readystill cancels startup. With Core 1.0.1 any early close cancelled startup. -
Closing the last window shuts down without a
window.eventclosedfor it (documented v1 behaviour); rely onapp.shutdown/on_shutdown, after which all handles are stale. -
Live bitmaps: only the transport path returned by the host is used (Core 1.0.3: a private runtime directory on Linux,
%TEMP%\nativehtmlkit-bitmaps\on Windows); allocations beyond 64 MiB per document or 256 MiB per host are refused withRpcErrorcode -32005 (local=False). -
Core ≥ 1.0.3 answers
document.loadwithpath/asset_rootwhen the file read finishes, so replies to later requests can arrive first; the SDK correlates strictly by request id (sync and asyncio). -
Core ≥ 1.0.3 drops
window.event/document.eventnotifications (counted inhost.diagnosticsdropped_notifications) if a backend stops reading. The SDK's reader never runs application code, so this stays 0; events the SDK itself drops because a callback blocks its own 128-event queue are counted inrpc.dropped_notifications. Both counters are recorded at shutdown (host.notifications_dropped) andApplication.host_diagnostics()returns the host's counters. Do not block event callbacks for long. -
Core ≥ 1.0.3 presents a new window when its first document loads (at the latest after 750 ms); on Windows
observed.visibleinwindow.state()isfalseuntil then. New windows are kept inside the monitor's work area;width/heightstay as requested,physical_size/observed.positionreport the actual geometry. -
Drag/resize regions (
data-ui4me-drag,data-ui4me-resize) work only on frameless windows (decorations=False). -
A callback blocked forever in user code keeps its daemon worker thread;
close()joins callback workers for at most 0.5 s in total, then leaves them and recordscallback.worker_abandoned. -
A blocking SDK call on a running asyncio loop is allowed but warns once (
RuntimeWarning) and recordsrpc.sync_call_on_event_loop. -
Core ≥ 1.0.2 at
traceemits metadata-onlyrpc.received/rpc.completed(same request ids as the SDK'spy-N),notify.sentandrequest.sent, so SDK and host timelines correlate exactly; 1.0.1 hosts emit none and lackdiagnostic_session_id. -
After a protocol violation a desktop (non-headless) host stays in its failure state until the user closes its window.
-
If the connection is lost right after
app.shutdown(force quit, transport failure), events still queued in the SDK are not delivered; an orderly shutdown keeps the connection open long enough to deliver them. -
On Linux the backend's initial environment block (
/proc/<pid>/environ, readable by the same user and root) still showsUI4ME_TOKENafter the SDK removed it fromos.environ; the token is single-use (consumed byhost.hello).
Development and verification
bash scripts/test-local.sh # unit + fake-host suite (PYTHON=... to choose the interpreter)
NATIVEHTMLKIT_HOST_BINARY=/path/nativehtmlkit-host bash scripts/test-local.sh # + real-host integration
python scripts/qualify.py --host HOST --host-sha256 SHA --evidence DIR # PASS/FAIL/BLOCKED results.json
python scripts/package-local.py --out dist --host linux-x64=HOST=SHA --sdist # wheel(s) + sdist + SHA256SUMS
tests/native/qualify-linuxdev.sh HOST SHA EVIDENCE # lab: workstation + KDE Wayland desktop
tests/native/qualify-windev.sh 'F:\...\nativehtmlkit-host.exe' SHA EVIDENCE # lab: Windows SSH + RDP desktop
Builds and tests are local only. The one GitHub Actions workflow, .github/workflows/pypi_publish.yml, is publish-only: on manual dispatch it uploads the wheels of an existing GitHub Release to PyPI after verifying their checksums. No publication without explicit owner approval. See docs/QUALIFICATION.md.
Licence
The SDK's own code is MIT-licensed (LICENSE). Each platform wheel also contains the
prebuilt NativeHTMLKit Core host (MIT) together with its third-party licences and notices (including OFL-1.1 for
the embedded font, MPL-2.0 components and CC-BY-4.0 stylesheets) in nativehtmlkit/_bin/core-licenses/.
Metadata
Release files for nativehtmlkit 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nativehtmlkit-0.1.1-py3-none-win_amd64.whl | Python 3 | none | Windows x86-64 | Details for nativehtmlkit-0.1.1-py3-none-win_amd64.whl |
| nativehtmlkit-0.1.1-py3-none-manylinux_2_39_x86_64.whl | Python 3 | none | Linux glibc 2.39+ x86-64 | Details for nativehtmlkit-0.1.1-py3-none-manylinux_2_39_x86_64.whl |
Total release size: 29.8 MB
Release files / nativehtmlkit-0.1.1-py3-none-win_amd64.whl
| Download URL | nativehtmlkit-0.1.1-py3-none-win_amd64.whl |
|---|---|
| Size | 13.4 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5ac1a1ef67b2f88e3f59630e01f0da8149dd4e4aa6b2fcfc05e8d4e77900cdd5
|
|
BLAKE2b-256 checksum How to use checksums |
51dbf17f12f052a91936e483fcc74ecf49953badc660ffac79ce9cfdde799ed0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / nativehtmlkit-0.1.1-py3-none-manylinux_2_39_x86_64.whl
| Download URL | nativehtmlkit-0.1.1-py3-none-manylinux_2_39_x86_64.whl |
|---|---|
| Size | 16.4 MB |
| Tags | Linux glibc 2.39+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
5478384b9a10a130166e3d8877b25b13c7d5004a23165e0aa62aa686e7acffe4
|
|
BLAKE2b-256 checksum How to use checksums |
a9e6026253d321a0579540f80a9110fab50c6bcebcdb85555864b390290374b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for nativehtmlkit 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for nativehtmlkit-0.1.1-py3-none-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.