iis-access

Python auth library for IIS tools ecosystem. Provides optional authentication, provider resolution, managed key retrieval, and usage reporting for Python-based IIS CLI tools (aria, sonar, iris).

Installation

pip install iis-access

Quick Start

from iis_access import resolve_provider, report_usage

# Resolve the best available provider for a task
resolution = await resolve_provider("tts", preferred="elevenlabs")
print(resolution.provider, resolution.method)

# Report usage (fire-and-forget, never raises)
await report_usage("aria", credits=1.5)

report_usage sends the logged-in user's access token. The account service accepts it only for that user's own account and only for local-runtime capabilities (runtimeTag local or local_gpu in the capability registry, e.g. aria, sonar, iris); any other service is refused, and a refused report is logged as a WARNING on the iis_access logger (account#135).

Development

Use uv — do not pip install into an ad-hoc venv, it drifts out of sync with pyproject.toml (missing deps like PyJWT after account#53 added it).

cd packages/access-py
uv sync --locked --extra dev   # creates .venv/, installs the package + dev deps from uv.lock
PYTHONPATH=src uv run pytest tests/ -v

uv sync --locked reads uv.lock (committed) for reproducible resolution and fails if it is stale — the same command CI runs (.github/workflows/test-access-py.yml).

CI pins uv 0.10.10 in .github/workflows/test-access-py.yml; bump it when re-locking with a newer uv.

aioresponses fork (account#69): the dev extra pins aioresponses-ng, not upstream aioresponses. Upstream 0.7.9 (the latest release) does not intercept aiohttp>=3.14 — aiohttp.ClientResponse.__init__() gained a required stream_writer keyword that upstream doesn't pass, so every aioresponses()-mocked test fails with TypeError: ClientResponse.__init__() missing 1 required keyword-only argument: 'stream_writer' instead of intercepting the request. The fix exists as an unmerged upstream PR (pnuckowski/aioresponses#288); aioresponses-ng is a maintained fork that ships it. It installs under the same aioresponses import path, so no test code changes are needed — only the dependency in pyproject.toml. If upstream ever merges and releases the fix, this pin can be dropped back to aioresponses.

Release

No workflow publishes iis-access to PyPI; publishing is a manual step. The Test access-py workflow (.github/workflows/test-access-py.yml, job test) is otherwise informational: develop is unprotected and no job needs: it, so a red run blocks nothing by itself (account#139). The release gate is therefore this check, made by whoever publishes:

The release SHA must have a green Test access-py run. Before building and uploading, run:

SHA=$(git rev-parse HEAD)   # the commit you are about to publish
gh run list --workflow test-access-py.yml --commit "$SHA" --json conclusion,status --jq '.[0]'

Proceed only if it prints {"conclusion":"success","status":"completed"}. Anything else (failure, in_progress, cancelled, or no output) means do not publish.

Empty output is not a pass. The workflow runs only on changes under packages/access-py/** or the workflow file, and a push triggers it for the tip commit only. A release SHA that did not touch the package, or that sat in the middle of a multi-commit push, has no run of its own. Then gate on the newest run whose commit is an ancestor of the release SHA, provided nothing under the package changed between that commit and the release SHA:

RUN=$(gh run list --workflow test-access-py.yml --branch develop --json headSha,conclusion --jq '.[0]')   # use --branch main for a main release
RUN_SHA=$(jq -r .headSha <<<"$RUN")
git merge-base --is-ancestor "$RUN_SHA" "$SHA" \
  && git diff --quiet "$RUN_SHA" "$SHA" -- packages/access-py .github/workflows/test-access-py.yml \
  && jq -r .conclusion <<<"$RUN"   # must print: success

(If $RUN_SHA is not an ancestor, or the diff is non-empty, trigger a run by pushing the change through a PR or branch push and use the first command on that SHA.)

Build into a fresh directory and upload explicit files. packages/access-py/dist/ in the main tree can hold artifacts of earlier releases (iis_access-0.1.1, iistools_access-0.1.1). PyPI filenames can never be reused, so a glob upload would re-send them and fail or mislead. Never run twine upload dist/*. From packages/access-py:

OUT=$(mktemp -d)
uv build --out-dir "$OUT"
twine check "$OUT"/iis_access-<version>.tar.gz "$OUT"/iis_access-<version>-py3-none-any.whl
twine upload "$OUT"/iis_access-<version>.tar.gz "$OUT"/iis_access-<version>-py3-none-any.whl

<version> is the pyproject.toml version (for example 0.2.1); the directory must hold exactly these two files.