pytruenas 0.0.0__tar.gz

pytruenas-0.0.0/.gitignore

@@ -0,0 +1,43 @@
+# Agent configs / private notes — never tracked in this repo
+.agents
+*.local.md
+CLAUDE*
+.claude/
+
+# Virtualenvs
+.venv*/
+venv/
+env/
+.env/
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Docs site build
+/site
+docs/_build/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Local pytruenas config / generated typings
+pytruenas.yaml
+/typings/

pytruenas-0.0.0/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.0] - 2026-07-22
+
+Initial release.
+
+Earlier version numbers appear in this project's git history but were never
+tagged or published, so there is no upgrade path to describe -- everything
+below is simply what the package contains.
+
+### Fixed
+- **`ws://` and `wss://` URLs no longer parse as port 0.** No system services
+  database has an entry for the websocket schemes, so `getservbyname("wss")`
+  failed -- and those are the schemes this client uses most. Port resolution now
+  goes through `netimps`, whose scheme table is consulted before the system
+  database.
+
+### Added
+- **`pytruenas call <method>` command.** Invoke any middleware method by its
+  dotted name (`system.info`, `core.ping`, `pool.dataset.details`) — not just
+  the queryable `<namespace>.query` methods `query` covers. Parameters are JSON
+  values via `-p/--param` (repeatable).
+
+### Changed
+- **CLI targets are now trailing positional arguments, not `-t/--target`.**
+  A command's own positionals come first, then the target host(s):
+  `pytruenas query user nas1 nas2`, `pytruenas dump-api nas1,nas2`. Comma lists
+  and `[A-Z]`/`[0-9]` range patterns still expand; no target means `localhost`.
+  The `-t`/`--target` flag has been removed.
+
+- Dependency floors raised to the validated versions: `duho>=0.3.2` (CLI parser
+  fixes — a global option before a subcommand is no longer shadowed; a literal
+  `%` in a `Cmd` docstring no longer breaks parser build) and the `ssh` extra's
+  `pathlib_next[sftp-async]>=0.8.3` (SFTP default concurrency raised 8→16).
+
+### Fixed
+- **API calls no longer silently return `None` on a dropped connection.** The
+  namespace call retry loop fell through and returned `None` after a single
+  `ECONNABORTED` — which `_get` read as "record missing", turning an `_upsert`
+  into a spurious create (possible duplicate rows). It now retries then raises,
+  and never returns `None` on a connection error.
+- **Long-running jobs no longer spuriously time out.** `core.job_wait` (waited
+  on after uploads/downloads and mutating `_upsert`/`_update` calls) is now
+  issued with no client-side timeout, so a job lasting longer than the 60s
+  default no longer raises `CallTimeout` while it is still running server-side.
+  `Client.call(timeout=None)` now means "wait indefinitely".
+- `client.run()` with a `str` `input` together with a text `encoding`/`errors`
+  no longer crashes. It used to pre-encode the string to bytes *and* hand the
+  encoding to `subprocess.run`, which then tried to `.encode()` the already-bytes
+  input (`AttributeError`). Now text mode keeps `str` input as-is (and decodes
+  `bytes` input), binary mode encodes. Found by live testing on TrueNAS 26.0.
+
+- `ops.template.TemplateTarget.apply_template` no longer crashes on a plain
+  string template (`issubclass()` was called on a non-type); a `str` is now
+  treated as literal template content and a path-like is read as file content.
+- `namespace.ioerror` only maps a middleware error to `OSError` when the
+  bracketed prefix names a real POSIX errno; previously an unrecognised prefix
+  produced `IOError(None, msg)`, discarding the original exception type.
+
+### Internal
+- `jsonrpc.Client.call` narrows the compatibility kwargs it ignores and logs any
+  other unexpected keyword at debug level instead of silently swallowing it;
+  `_ioerror` is no longer forwarded into the upload/download paths.
+- `Namespace` child lookups use a per-instance dict instead of `functools.cache`
+  on the methods, so namespaces are garbage-collected with their client instead
+  of being pinned for the process lifetime (relevant to long-lived embeddings).
+- The `pytruenas.ops` subpackage (systemd/midclt host-config helpers) is
+  **experimental** and exercised only by unit tests, not against a live host.
+
+### Added
+- Packaged as `pytruenas` (src layout, hatchling, `pytruenas` console script,
+  `py.typed`). Python 3.9+.
+- Lean in-house JSON-RPC 2.0 client (`pytruenas.jsonrpc`) speaking the middleware
+  protocol over `wss://`/`ws://` and the local `ws+unix://` socket, with
+  extended-JSON (datetime/date/time/set/IP) round-tripping and
+  `ClientException`/`ValidationErrors` mapping. Verified against a live host.
+- Attribute-style API namespace (`client.api.<namespace>.<method>(...)`) with
+  `_get`/`_query`/`_create`/`_update`/`_upsert` convenience helpers.
+- Filesystem paths on `pathlib_next`: `client.path()` returns a `LocalPath`
+  (local) or `TruenasPath` (remote — SFTP-preferred via pathlib_next's `SftpPath`,
+  falling back to the middleware `filesystem.*` websocket API for
+  delete/rename/symlink).
+- Typings generator (`generate-typings`): produces `.pyi` stubs for the whole
+  API, validated to parse across every version of a real v26 dump (780 methods).
+- CLI (`dump-api`, `query`, `generate-typings`) on `duho` with multi-target
+  fan-out (`-t/--target`, `--parallel`) and optional YAML config.
+- Optional extras: `ssh`, `config`, `codegen`, `host`.
+- Test suite green on Python 3.9 and 3.13/3.14.
+
+### Notes
+- Runtime CLI/logging/qualname/text come from `duho` (>=0.3.0); path types from
+  `pathlib_next` (>=0.8.2). Both are on PyPI.
+- Remote shell command execution (`client.run` over SSH) uses `asyncssh` (the
+  `ssh` extra); the middleware API has no command-exec method. SFTP is handled by
+  `pathlib_next`.
+
+[Unreleased]: https://github.com/jose-pr/pytruenas/compare/v0.0.0...HEAD
+[0.0.0]: https://github.com/jose-pr/pytruenas/releases/tag/v0.0.0

pytruenas-0.0.0/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to pytruenas
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/jose-pr/pytruenas.git
+cd pytruenas
+
+# Create a virtual environment (project targets Python 3.9+)
+python -m venv .venv39
+.venv39/Scripts/activate      # Windows; on Unix: source .venv39/bin/activate
+
+# Install in development mode with the test dependencies
+pip install -e ".[dev]"
+```
+
+The `ssh`, `config`, `codegen`, and `host` extras enable optional features; add
+the ones whose tests you want to run (e.g. `-e ".[dev,ssh]"`).
+
+## Running Tests
+
+```bash
+pytest -q
+```
+
+With coverage:
+
+```bash
+pytest -q --cov=pytruenas --cov-report=term-missing
+```
+
+Some `client.run()` tests require a POSIX shell and skip on Windows; they run on
+Linux/macOS (and on a real NAS). "0 failures" with those skipped is expected on
+Windows — run `pytest -rs` to see skip reasons.
+
+## Running Benchmarks
+
+```bash
+python benchmarks/run.py            # print summary
+python benchmarks/run.py --save     # write benchmarks/results/<name>.json
+```
+
+See [`benchmarks/README.md`](benchmarks/README.md) for the schema and what the
+numbers mean.
+
+## Docs
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve            # live preview at http://127.0.0.1:8000
+mkdocs build --strict   # what CI gates on
+```
+
+## Code Style
+
+- Follow PEP 8; use type hints.
+- `from __future__ import annotations` in any module using `X | Y` unions at
+  runtime — the project supports Python 3.9.
+- Keep the vendored-free, minimal-dependency posture: guard optional imports and
+  degrade gracefully rather than hard-crashing on a missing extra.
+
+## Commit Guidelines
+
+Format: `type: description`
+
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation
+- `test:` tests
+- `chore:` build, CI, deps, or tooling
+
+Keep commits logical and separate (a feature and its tests together; docs/config
+apart from behavior changes).
+
+## Pull Request Process
+
+1. Branch: `git checkout -b feat/my-feature`
+2. Make changes and add tests.
+3. `pytest -q` green; `mkdocs build --strict` clean if docs changed.
+4. Commit with a clear message and open a PR.
+
+## Reporting Issues
+
+Include your Python version, pytruenas version, the TrueNAS version, a minimal
+reproducer, and expected vs. actual behavior.

pytruenas-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+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.

pytruenas-0.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pytruenas
+Version: 0.0.0
+Summary: A typed, Pythonic client and CLI for the TrueNAS middleware API
+Project-URL: Homepage, https://github.com/jose-pr/pytruenas/
+Project-URL: Issues, https://github.com/jose-pr/pytruenas/issues
+Project-URL: Repository, https://github.com/jose-pr/pytruenas
+Author: Jose A.
+License: MIT License
+        
+        Copyright (c) 2026 Jose A.
+        
+        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.
+License-File: LICENSE
+Keywords: cli,jsonrpc,middleware,sysadmin,truenas,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: duho>=0.3.2
+Requires-Dist: netimps>=0.0.1
+Requires-Dist: pathlib-next[uri]>=0.8.2
+Requires-Dist: requests
+Requires-Dist: websocket-client
+Provides-Extra: codegen
+Requires-Dist: jinja2; extra == 'codegen'
+Provides-Extra: config
+Requires-Dist: pyyaml; extra == 'config'
+Provides-Extra: dev
+Requires-Dist: asyncssh; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: jinja2; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: host
+Requires-Dist: ifaddr; extra == 'host'
+Provides-Extra: ssh
+Requires-Dist: asyncssh; extra == 'ssh'
+Requires-Dist: pathlib-next[sftp-async]>=0.8.3; extra == 'ssh'
+Description-Content-Type: text/markdown
+
+# pytruenas
+
+[![PyPI version](https://img.shields.io/pypi/v/pytruenas.svg)](https://pypi.org/project/pytruenas/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pytruenas.svg)](https://pypi.org/project/pytruenas/)
+[![Documentation](https://img.shields.io/badge/docs-jose--pr.github.io%2Fpytruenas-blue.svg)](https://jose-pr.github.io/pytruenas/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/pytruenas/blob/main/LICENSE)
+
+A typed, Pythonic client and CLI for the [TrueNAS](https://www.truenas.com/)
+middleware API.
+
+`pytruenas` speaks the middleware's JSON-RPC 2.0 websocket protocol directly —
+over `wss://`/`ws://` to a remote host, or over the local unix socket
+(`ws+unix://`) when running on the NAS itself. It exposes the whole API surface
+through an attribute-style namespace, adds convenience helpers for the common
+create/update/upsert patterns, a remote-filesystem abstraction, an optional
+typings generator, and a small CLI for scripting host configuration.
+
+## Install
+
+```sh
+pip install pytruenas          # once published to PyPI
+# or, from a checkout:
+pip install .
+```
+
+Optional extras:
+
+| Extra | Enables |
+| ----- | ------- |
+| `pytruenas[ssh]` | Remote shell + SFTP filesystem backend (`asyncssh`) |
+| `pytruenas[config]` | YAML config/targets file for the CLI (`pyyaml`) |
+| `pytruenas[codegen]` | `generate-typings` command (`jinja2`) |
+| `pytruenas[host]` | Local network-adapter / packaging helpers (`ifaddr`) |
+
+## Quickstart
+
+```python
+from pytruenas import TrueNASClient
+
+# Remote host (api key, or "user:password", or a token)
+client = TrueNASClient("nas.example.com", "1-<64-char-api-key>", sslverify=False)
+
+# Attribute-style access to any API namespace/method:
+for user in client.api.user.query():
+    print(user["username"])
+
+# Convenience helpers for common DB patterns:
+client.api.user._upsert("username", username="svc", full_name="Service", group_create=True)
+
+# Running on the NAS itself talks to the local unix socket, no auth:
+local = TrueNASClient()            # ws+unix:///var/run/middleware/middlewared.sock
+print(local.api.system.info())
+```
+
+### Credentials
+
+`TrueNASClient(target, creds)` accepts, for `creds`:
+
+- an **API key** string `"<id>-<64 chars>"`,
+- `"user:password"` (optionally `"user:password\n<otp>"`),
+- a **token** string,
+- a `(user, password)` tuple,
+- `None` / omitted → local socket auth.
+
+`Credentials.from_env()` reads `TN_CREDS`.
+
+## CLI
+
+```sh
+pytruenas --help
+pytruenas query user -f username=root nas.example.com
+pytruenas call system.info nas.example.com          # any method by dotted name
+pytruenas dump-api nas.example.com > api.json
+pytruenas generate-typings --path typings --api-version v26.0.0 nas.example.com
+```
+
+The target host(s) are the **trailing positional arguments** — a command's own
+positionals (like `query`'s namespace) come first, then the hosts. Each target
+may be comma-separated and supports `[A-Z]`/`[0-9]` range expansion (e.g.
+`'nas[1-3].example.com'`); with no target the command runs against `localhost`.
+`--parallel N` runs several targets concurrently. Filter `query` with
+`-f/--filter KEY=VALUE` (repeatable).
+
+## Typings generator
+
+`generate-typings` turns a host's API definition into a package of `.pyi` stubs
+so editors and type checkers understand `client.api.<namespace>.<method>(...)`.
+It is validated against the full real API (every version in a live dump).
+
+```sh
+pytruenas generate-typings --path truenasapi_typings/current nas.example.com
+```
+
+## Development
+
+```sh
+py -3.14 -m venv .venv
+.venv/Scripts/python -m pip install -e .[dev]
+.venv/Scripts/python -m pytest
+```
+
+Supports Python 3.9+.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pytruenas-0.0.0/README.md

@@ -0,0 +1,106 @@
+# pytruenas
+
+[![PyPI version](https://img.shields.io/pypi/v/pytruenas.svg)](https://pypi.org/project/pytruenas/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pytruenas.svg)](https://pypi.org/project/pytruenas/)
+[![Documentation](https://img.shields.io/badge/docs-jose--pr.github.io%2Fpytruenas-blue.svg)](https://jose-pr.github.io/pytruenas/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/pytruenas/blob/main/LICENSE)
+
+A typed, Pythonic client and CLI for the [TrueNAS](https://www.truenas.com/)
+middleware API.
+
+`pytruenas` speaks the middleware's JSON-RPC 2.0 websocket protocol directly —
+over `wss://`/`ws://` to a remote host, or over the local unix socket
+(`ws+unix://`) when running on the NAS itself. It exposes the whole API surface
+through an attribute-style namespace, adds convenience helpers for the common
+create/update/upsert patterns, a remote-filesystem abstraction, an optional
+typings generator, and a small CLI for scripting host configuration.
+
+## Install
+
+```sh
+pip install pytruenas          # once published to PyPI
+# or, from a checkout:
+pip install .
+```
+
+Optional extras:
+
+| Extra | Enables |
+| ----- | ------- |
+| `pytruenas[ssh]` | Remote shell + SFTP filesystem backend (`asyncssh`) |
+| `pytruenas[config]` | YAML config/targets file for the CLI (`pyyaml`) |
+| `pytruenas[codegen]` | `generate-typings` command (`jinja2`) |
+| `pytruenas[host]` | Local network-adapter / packaging helpers (`ifaddr`) |
+
+## Quickstart
+
+```python
+from pytruenas import TrueNASClient
+
+# Remote host (api key, or "user:password", or a token)
+client = TrueNASClient("nas.example.com", "1-<64-char-api-key>", sslverify=False)
+
+# Attribute-style access to any API namespace/method:
+for user in client.api.user.query():
+    print(user["username"])
+
+# Convenience helpers for common DB patterns:
+client.api.user._upsert("username", username="svc", full_name="Service", group_create=True)
+
+# Running on the NAS itself talks to the local unix socket, no auth:
+local = TrueNASClient()            # ws+unix:///var/run/middleware/middlewared.sock
+print(local.api.system.info())
+```
+
+### Credentials
+
+`TrueNASClient(target, creds)` accepts, for `creds`:
+
+- an **API key** string `"<id>-<64 chars>"`,
+- `"user:password"` (optionally `"user:password\n<otp>"`),
+- a **token** string,
+- a `(user, password)` tuple,
+- `None` / omitted → local socket auth.
+
+`Credentials.from_env()` reads `TN_CREDS`.
+
+## CLI
+
+```sh
+pytruenas --help
+pytruenas query user -f username=root nas.example.com
+pytruenas call system.info nas.example.com          # any method by dotted name
+pytruenas dump-api nas.example.com > api.json
+pytruenas generate-typings --path typings --api-version v26.0.0 nas.example.com
+```
+
+The target host(s) are the **trailing positional arguments** — a command's own
+positionals (like `query`'s namespace) come first, then the hosts. Each target
+may be comma-separated and supports `[A-Z]`/`[0-9]` range expansion (e.g.
+`'nas[1-3].example.com'`); with no target the command runs against `localhost`.
+`--parallel N` runs several targets concurrently. Filter `query` with
+`-f/--filter KEY=VALUE` (repeatable).
+
+## Typings generator
+
+`generate-typings` turns a host's API definition into a package of `.pyi` stubs
+so editors and type checkers understand `client.api.<namespace>.<method>(...)`.
+It is validated against the full real API (every version in a live dump).
+
+```sh
+pytruenas generate-typings --path truenasapi_typings/current nas.example.com
+```
+
+## Development
+
+```sh
+py -3.14 -m venv .venv
+.venv/Scripts/python -m pip install -e .[dev]
+.venv/Scripts/python -m pytest
+```
+
+Supports Python 3.9+.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

pytruenas-0.0.0/RELEASENOTES.md

@@ -0,0 +1,73 @@
+# Release Notes
+
+Detailed notes per release: the narrative, the performance story, and the
+validation evidence behind each version. `CHANGELOG.md` stays terse and
+user-facing; this file is the durable record.
+
+---
+
+## [Unreleased]
+
+### What changed
+
+- **`client.run()` text-mode input fix.** `str` input together with a text
+  `encoding`/`errors` used to be pre-encoded to bytes *and* handed to
+  `subprocess.run` with the encoding, which then tried to `.encode()` bytes and
+  crashed. Text mode now keeps `str` as-is (and decodes `bytes` input); binary
+  mode encodes. Found by live testing against a real TrueNAS 26.0 host — the
+  unit tests mock `subprocess.run`, so only a real POSIX run exercised it.
+- **`pytruenas.__version__`** now exposed (resolved from installed metadata).
+- **Dependency floors** raised to the tested versions: `duho>=0.3.2` (CLI parser
+  fixes) and the `ssh` extra's `pathlib_next[sftp-async]>=0.8.3` (SFTP
+  concurrency 8→16).
+- **Repo brought to standard:** benchmark suite (`benchmarks/run.py`), docs site
+  (`mkdocs.yml` + `docs/`), `CONTRIBUTING.md`, and this file.
+
+### Performance
+
+First benchmark baseline (see `benchmarks/results/`). These are **local**
+numbers (Intel i7-1065G7 class, Windows) for regression-catching, not a CI
+figure. The suite measures pure-CPU hot paths — no network.
+
+| metric | py3.9 median (ms/call) | py3.14 median (ms/call) |
+| --- | --- | --- |
+| `ejson.dumps.plain` (20-row response) | 0.048 | 0.045 |
+| `ejson.loads.plain` | 0.048 | 0.050 |
+| `ejson.dumps.extended` | 0.020 | 0.021 |
+| `ejson.loads.extended` | 0.020 | 0.020 |
+| `namespace.methodname` | 0.004 | 0.004 |
+| `query.filter_from_kwargs` | 0.003 | 0.002 |
+
+**Hot-path analysis:** the ejson encode/decode paths dominate and are already
+near stdlib-optimal. Two candidate micro-optimizations were measured and
+**rejected** (each ~1.02x, within noise): swapping `json.dumps(cls=Encoder)` for
+`default=func` (Python's `json` uses the pure-Python encoder whenever any custom
+type handling is present, regardless), and a fast-path bail in `_object_hook`
+(real response dicts are multi-key, already short-circuited). The client's cost
+is I/O-bound; there is no pending CPU speedup. This baseline exists to catch a
+future regression.
+
+**Performance target for the next release:** no regression on the medians above
+(compare same machine + interpreter).
+
+### Validation evidence
+
+- Tests: **113 passed / 5 skipped** on Windows Python 3.9; **118 passed / 0
+  skipped** on Python 3.13 on a real TrueNAS 26.0 host (the POSIX-shell-gated
+  `run()` tests that skip on Windows run there).
+- Live integration on TrueNAS 26.0.0-BETA.1 via the local middleware socket:
+  `system.info`, `user.query`, `pool.dataset.query`, `_get`, fs `Path`
+  exists/read, `client.run()` shell paths, and the `dump-api` / `query` /
+  `generate-typings` CLI subcommands (129 valid `.pyi` stubs generated).
+- Build: `python -m build` + `twine check` PASS; wheel carries `py.typed`, no
+  agent-file leakage.
+- Docs: `mkdocs build --strict` clean.
+- Coverage: TOTAL 70% (client 62%, namespace 79%, jsonrpc 84%, main 80%).
+
+### Publication state
+
+Prepared and merged to `main`. **Not tagged/published** — a `v0.1.0` release is
+user-gated and requires PyPI trusted-publishing + GitHub Pages setup by the repo
+owner.
+
+---

pytruenas-0.0.0/benchmarks/README.md

@@ -0,0 +1,58 @@
+# pytruenas benchmarks
+
+Micro-benchmarks for the pure-CPU hot paths hit on every middleware call —
+extended-JSON (ejson) encode/decode, API namespace method-name building, and
+query-filter construction. **No network or server is involved**; these measure
+per-call CPU cost, not the round-trip latency that dominates real use.
+
+## Running
+
+```bash
+# print summary only
+PYTHONPATH=src .venv39/Scripts/python benchmarks/run.py
+
+# also write benchmarks/results/pytruenas-<ver>-py<ver>.json
+PYTHONPATH=src .venv39/Scripts/python benchmarks/run.py --save
+PYTHONPATH=src .venv314/Scripts/python benchmarks/run.py --save
+```
+
+Run without `--save` to just print. `--name <x>` overrides the filename stem.
+Compare files only across the **same machine + interpreter**, or the numbers
+aren't meaningful.
+
+## Schema
+
+Each `results/<name>.json`: `name`, `pytruenas_version`, `python`, `platform`,
+`processor`, `timestamp` (UTC), `iterations` (inner counts + `repeat`), and
+`metrics`. Each metric reports `min_ms`/`median_ms`/`max_ms` **per call**,
+sampled `repeat` times — compare on `median_ms`; min/max show run-to-run noise.
+
+Metrics:
+- `ejson.dumps.plain` / `ejson.loads.plain` — a 20-row `user.query`-shaped
+  response with no extended types (the common case).
+- `ejson.dumps.extended` / `ejson.loads.extended` — a payload exercising every
+  extended type (datetime/date/time/set/IPv4Interface).
+- `namespace.methodname` — building `pool.dataset.snapshot` from an attribute
+  walk (fresh chain each call, so the `@cache` hit is not what's measured).
+- `query.filter_from_kwargs` — turning `username="root", uid=GT(0), locked=False`
+  into middleware filter tuples.
+
+## Findings (2026-07-19, baseline)
+
+The ejson paths dominate (~0.02–0.05 ms/call) and are **already near
+stdlib-optimal**. Two candidate optimizations were measured and rejected:
+
+- Swapping `json.dumps(cls=Encoder)` for `json.dumps(default=func)` to avoid
+  re-instantiating the encoder: **~1.02x**, within noise. Python's `json` drops
+  to the pure-Python `iterencode` whenever any custom type handling is present,
+  regardless of `cls=` vs `default=`, so there's no C-encoder fast path to
+  recover here.
+- A fast-path bail in `_object_hook` for single-key dicts whose key doesn't
+  start with `$`: **~1.02x**. Real response dicts are multi-key, so the existing
+  `len(obj) == 1` guard already short-circuits them.
+
+Conclusion: the client's CPU hot paths are not a bottleneck worth
+micro-optimizing; real-world cost is I/O-bound (network round-trips). This
+baseline exists to catch a future *regression*, not because a speedup is
+pending. The per-release before/after narrative lives in the repo-root
+`RELEASENOTES.md`.