scanii-python

Python SDK for the Scanii content security API.

Installation

pip install scanii-python

Distribution name is scanii-python; import as from scanii import ScaniiClient.

SDK Principles

1. Light. Zero runtime dependencies, stdlib only.
2. Up to date. Always current with the latest Scanii API.
3. Integration-only. Wraps the REST API — retries, concurrency, and batching are the caller's responsibility.

Quickstart

from scanii import ScaniiClient, ScaniiTarget

client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.US1)
result = client.process_file("./document.pdf")
print(result.findings)  # [] when clean

Streaming

Pass any IO-like object (anything with read(n) -> bytes) to process() directly — no temp file needed:

import io

# Scan bytes already in memory
result = client.process(io.BytesIO(my_bytes), filename="upload.bin")

# Scan content from an open file handle
with open("./large.pdf", "rb") as f:
    result = client.process(f, filename="large.pdf")

API Reference

Constructor

ScaniiClient(
    *,
    key: str | None = None,
    secret: str | None = None,
    token: str | None = None,
    target: ScaniiTarget,
    timeout: float = 60.0,
)

Supply either key + secret (HTTP Basic Auth) or token (auth-token authentication). Mixing both raises ValueError. target is required — see Regional Endpoints.

File scanning

delete() and delete_trace() act on independent resources: deleting a scan result leaves its trace readable, and deleting a trace leaves the result readable. To erase a scan entirely, call both.

Auth tokens

Health check

Regional Endpoints

Choose a regional target explicitly. Six regional constants are available: US1, EU1, EU2, AP1, AP2, CA1. Latency-based routing (AUTO in other Scanii SDKs) is intentionally not provided — chain-of-custody and data-residency compliance require an explicit regional choice. For local testing against scanii-cli, construct a target with an arbitrary URL: ScaniiTarget("http://localhost:4000").

client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.EU1)

Error Handling

from scanii import ScaniiClient, ScaniiTarget, ScaniiError, ScaniiAuthError, ScaniiRateLimitError
import time

client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.US1)

try:
    result = client.process_file("./document.pdf")
except ScaniiAuthError:
    print("Invalid credentials")
except ScaniiRateLimitError as e:
    if e.retry_after:
        time.sleep(e.retry_after)
except ScaniiError as e:
    print(f"API error {e.status_code}: {e}")

Network-level failures (urllib.error.URLError) propagate unwrapped — retries are the caller's responsibility per SDK Principle 3.

Local Testing with scanii-cli

All integration tests run against a locally-hosted scanii-cli mock server — no real credentials needed.

docker run -d --name scanii-cli -p 4000:4000 ghcr.io/scanii/scanii-cli:latest server

# Run tests
pip install -e ".[dev]"
pytest

client = ScaniiClient(key="key", secret="secret", target=ScaniiTarget("http://localhost:4000"))
result = client.ping()  # True

Contributing

Pull requests welcome. Please open an issue first for substantial changes.

License

Apache 2.0 — see LICENSE.