Skip to content
OpenVireoDeveloper
GitHub

Python

The openvireo package: install, sign in, vaults, sync, errors.

The openvireo package is the Python binding of the core: accounts, vaults, sync, share links and .kdbx files, on the same Rust code as the iOS, desktop and web apps. UniFFI generates the openvireo._core module from bindings/ov-ffi, and openvireo.hosts adds ready-made platform parts, so a script needs no glue.

  • Python 3.10 or later, on macOS (arm64, x86_64), Linux (manylinux 2.28 x86_64 and aarch64, musllinux x86_64) and Windows x64.
  • One wheel per platform (py3-none-<platform>) covers every Python version, because the library is loaded through ctypes rather than the CPython ABI.
  • Every call that touches the network or storage is an asyncio coroutine.
  • The package is typed (py.typed and stubs): mypy and pyright see every signature as it runs.

The package source and its developer notes are in bindings/python.

The package isn’t on PyPI yet. Wheels are attached to each core release on GitHub, and pip reads them from the release’s asset list:

Terminal window
pip install "openvireo==X.Y.Z" \
--find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z

Use the expanded_assets URL. It’s the HTML fragment that lists the release’s files, which pip can read. The releases/tag/vX.Y.Z page loads its asset list with JavaScript, so pip finds nothing there. Pin the version (==X.Y.Z): pip also searches PyPI, and the pin stops it picking up something else named openvireo.

Two optional extras. Their dependencies come from PyPI, so pass --find-links as well:

Terminal window
# async HTTP on httpx (otherwise urllib runs in a worker thread)
pip install "openvireo[httpx]==X.Y.Z" --find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z
# keep sessions and trusted Secret Keys in the OS keychain
pip install "openvireo[keyring]==X.Y.Z" --find-links https://github.com/openvireo/openvireo-core/releases/expanded_assets/vX.Y.Z

Each wheel has a GPG signature (.asc) next to it on the release page.

Check the install:

import openvireo as ov
print(ov.__version__, ov.sha256(b"abc").hex()[:8]) # X.Y.Z ba7816bf

An OvClient needs a ClientConfig (this device) and a Host (the platform parts the core calls: HTTP, secure store, offline cache, clock, log sink). default_host() builds the Host for you:

import openvireo as ov
from openvireo.hosts import default_host
client = ov.OvClient(
ov.ClientConfig(
device=ov.DeviceInfo(id=None, name="backup script", platform=ov.Platform.CLI),
offline=False,
server=None,
),
default_host(),
)
  • device.name is what the account’s device list shows. Scripts use Platform.CLI.
  • offline=True keeps the offline cache: unlock, list and open vaults without the network, and keep edits until they upload. It needs a persistent cache: pass cache_dir= to default_host.
  • server is a discovery document to use instead of fetching one. Leave it None.

default_host() with no arguments keeps everything in memory, so each run is a new device: it signs in from scratch and needs the Secret Key every time. To keep the session and the trusted Secret Key between runs, give it a persistent store:

from openvireo.hosts import KeyringStore, default_host
host = default_host(store=KeyringStore(), cache_dir="~/.cache/openvireo")
import asyncio
import getpass
import openvireo as ov
from openvireo.hosts import KeyringStore, default_host
async def sign_in(client: ov.OvClient, email: str) -> ov.Account:
account = await client.connect("https://accounts.openvireo.com")
password = getpass.getpass("Master password: ").encode()
if account.is_signed_in():
# A stored session (persistent store): unlock it, no OPAQUE round trip.
await account.unlock(password, None)
return account
login = ov.LoginInput(email=email, password=password, secret_key=None, totp=None, trust_device=True)
try:
step = await account.login(login)
except ov.OvError as e:
if e.code != ov.OvErrorCode.INVALID_SECRET_KEY:
raise
# A new device: the Secret Key isn't stored here yet.
login.secret_key = getpass.getpass("Secret Key: ").encode()
step = await account.login(login)
while isinstance(step, ov.LoginStep.NEEDS_TOTP):
try:
step = await account.submit_totp(step.challenge, input("Two-step code: "))
except ov.OvError as e:
if e.code != ov.OvErrorCode.INVALID_MFA:
raise # mfa_expired: start the sign-in again
print("Wrong code, try again")
return account
  • connect fetches the server’s discovery document and loads a stored session if there is one. The account is then signed in but locked, and unlock opens it with the master password.
  • A device that has never seen the account doesn’t have the Secret Key. login without one fails with invalid_secret_key. Ask for the key and try again. With trust_device=True the core stores the key, so the next sign-in on this device doesn’t need it.
  • A wrong password, or an email with no account, is unauthorized (401). A wrong Secret Key is also unauthorized; details tells them apart (see Errors).
  • An account with two-step sign-in returns LoginStep.NEEDS_TOTP. Send the code with submit_totp. A wrong code is invalid_mfa and the same challenge can be used again (challenge.attempt() counts the tries). After the fifth wrong code, or once the challenge expires, the result is mfa_expired and the sign-in starts again. If you already have the code, pass totp="123456" in LoginInput to skip that step.
  • LoginStep.UNLOCKED carries unlocked (offline, deletion_scheduled_for).

await account.sign_out(False) ends the session and deletes this device’s offline cache, including edits that haven’t synced. sign_out(True) also forgets the stored Secret Key and device id.

for info in await account.vaults():
vault = await account.open_vault(info.id)
for entry in vault.entries(False): # False: leave out the Recycle Bin
print(info.name, "/", "/".join(entry.group_path), entry.title, entry.username)

vaults() returns VaultInfo records (id, name, role, org_id, …). open_vault downloads and decrypts one. After that, reading and editing a Vault is local and synchronous:

  • entries(include_recycle_bin) gives EntrySummary records (id, title, username, url, group_path, tags, …). They have no field values.
  • entry(id) gives the full EntryRecord. Its fields are FieldRecord(name, value, protected), and every value is bytes (UTF-8 for text).
  • find("ov://Personal/Servers/Router") looks an entry up by reference: ov://<vault>/[<group>/...]<entry>, where <entry> is a UUID or a unique title. read_field("ov://Personal/Servers/Router/Password") reads one field.
rec = vault.entry(entry.id)
password = next(f.value for f in rec.fields if f.name == "Password").decode()
entry_id = vault.add_entry(
vault.root_group_id(), # or vault.ensure_group("Servers/Prod")
ov.EntryInput(
fields=[
ov.FieldInput(name="Title", value=b"Router", protected=None),
ov.FieldInput(name="UserName", value=b"admin", protected=None),
ov.FieldInput(name="Password", value=b"correct horse", protected=None),
],
remove_fields=[],
tags=None,
icon_id=None,
expiry=ov.EntryExpiry.KEEP(),
),
)
report = await vault.sync(ov.SyncOptions(local_changed=True))
print(report.outcome) # SyncOutcome.UPLOADED, PULLED, ...

Edits stay in the local copy until sync. SyncOptions(local_changed=True) uploads them. It first merges in whatever other devices uploaded, with the same three-way merge as the other apps. local_changed=False only pulls. edit_entry(id, EntryInput(...)) changes an entry: it sets the fields you pass, removes the names in remove_fields, and leaves the rest alone. delete_entry moves an entry to the Recycle Bin.

account.create_vault("Name", None) creates a vault. The second argument is an organisation id.

A share link gives one entry, or some text, to someone without an account. The key is in the URL’s #fragment, so the server never sees it.

rec = vault.entry(entry_id)
payload = ov.item_share_payload(rec, ov.default_share_fields(), None) # UserName, Password, URL
created = await account.create_share(
payload,
ov.ShareOptions(expires_in=3600, max_opens=1, passcode=None, vault_id=vault.id(), entry_id=entry_id),
)
print(created.url.decode()) # https://share.openvireo.com/s/...#...

created.url is bytes, because it holds the key. ov.text_share_payload(b"text", "Title", None) shares plain text. account.list_shares() and account.revoke_share(id) manage your links.

Opening a link needs no account, only a client:

api = account.server_config().api # e.g. https://accounts.openvireo.com/api/v1
share_id = ov.parse_share_link(link).id
info = await client.share_info(api, share_id) # expires_at, opens_left, kdf (passcode needed?)
opened = await client.open_share(api, link.encode(), None, info)
for f in opened.payload.fields:
print(f.label, f.value.decode()) # f.k: "username", "password", "url", "notes", "text", ...

Every failure is an ov.OvError, with these fields:

Field
code an ov.OvErrorCode (UNAUTHORIZED, NETWORK_ERROR, PLAN_LIMIT, …)
wire_code the stable string ("unauthorized"). It’s the server’s own code when that isn’t one of OvErrorCode. Match on this in UI code.
message English text for logs
status the HTTP status, for server errors
retry_after seconds, for RATE_LIMITED
details a JSON object string with camelCase keys, or None
server_code the server’s code when it isn’t one of OvErrorCode
import json
try:
step = await account.login(login)
except ov.OvError as e:
if e.code == ov.OvErrorCode.UNAUTHORIZED:
reason = json.loads(e.details or "{}").get("reason")
print("wrong Secret Key" if reason == "keyset_unwrap_failed" else "wrong email or password")
elif e.code == ov.OvErrorCode.NETWORK_ERROR:
print("can't reach the server:", e.message)
elif e.code == ov.OvErrorCode.RATE_LIMITED:
print(f"try again in {e.retry_after}s")
else:
raise

The codes are the TypeScript SDK’s OpenVireoErrorCodes, one for one, plus internal. The SDK’s error list says what each one means. ov.error_code_wire(code) and ov.error_code_from_wire("plan_limit") convert between a code and its string.

The crypto functions raise OvError too, for example decryption_failed from ov.aead_decrypt.

  • Any loop. A core call is a coroutine: await it from asyncio.run(...), an existing loop, or a framework built on asyncio (FastAPI, aiohttp). trio and curio aren’t supported.
  • Your Host’s coroutines run on the loop that awaits the core call. The core starts no threads, and every call stays on that loop. The shipped parts send blocking work (urllib, files, the keyring) through asyncio.to_thread, so the loop isn’t blocked.
  • Threads. Objects (OvClient, Account, Vault, …) are thread-safe handles. Each thread that calls the core needs its own running loop. ov.uniffi_set_event_loop(loop) forces one loop for every call, which you only need if you call the core from a thread with no running loop.
  • Synchronous calls (Vault.entries, add_entry, the crypto functions) do CPU work in the core and block the loop while they run. For a very large vault, use asyncio.to_thread.
  • Several asyncio.run calls in one script are fine. HttpxTransport keeps one httpx client per loop.

Two ways:

  • Cancel the task. task.cancel() raises CancelledError in the awaiting code. It drops the core’s future, and with it the Host call in progress (an HTTP request, for example).
  • A CancelToken. Every async method takes an optional cancel= (typed CancelToken | None = None, so type checkers accept a call without it). Calling token.cancel(), from any thread, makes each call that holds the token fail with OvError code ABORTED. One token can be shared by several calls, to cancel them as a group. Once cancelled, a token stays cancelled.
token = ov.CancelToken()
task = asyncio.create_task(vault.sync(ov.SyncOptions(local_changed=True), cancel=token))
...
token.cancel()
try:
await task
except ov.OvError as e:
assert e.code == ov.OvErrorCode.ABORTED

account.subscribe() opens the server’s event stream (server-sent events, parsed in the core):

stream = await account.subscribe()
while (event := await stream.next()) is not None:
if isinstance(event, ov.AccountEvent.VAULT_CHANGED):
await (await account.open_vault(event.vault_id)).sync(ov.SyncOptions(local_changed=False))
elif isinstance(event, ov.AccountEvent.VAULTS_CHANGED):
print("vault list or access changed")
elif isinstance(event, ov.AccountEvent.SESSION_ENDED):
break

stream.close() ends it, from any thread, and a pending next() then returns None.

openvireo.hosts has a ready-made part for each Host interface:

Interface Parts default_host() uses
HttpTransport HttpxTransport (async, openvireo[httpx]), UrllibTransport (stdlib, in a worker thread) httpx if it’s installed, else urllib
SecureStore MemoryStore, KeyringStore(service="openvireo") (openvireo[keyring]) MemoryStore
BlobCache FileCache(dir), MemoryCache FileCache(cache_dir) if cache_dir= is given, else MemoryCache
Clock SystemClock SystemClock
LogSink LoggingSink(logger=None), which logs to logging.getLogger("openvireo") LoggingSink

default_host(http=..., store=..., cache=..., clock=..., log=..., cache_dir=...) replaces any of them. The transports take timeout=. UrllibTransport also takes ssl_context= and proxies=. By default it uses the HTTPS_PROXY environment variables. HttpxTransport takes client= or other httpx.AsyncClient options.

The cache holds only ciphertext and public data (vault blobs encrypted under the vault key, the wrapped keyset, the discovery document). FileCache writes files 0600 in folders 0700.

Subclass the interface. HttpTransport, SecureStore and BlobCache have async methods. Clock.now_unix_ms and LogSink.log are plain methods, and the core may call log from any thread.

A transport wrapper that logs each request’s method and URL:

from openvireo.hosts import UrllibTransport
class LoggedTransport(ov.HttpTransport):
def __init__(self, inner: ov.HttpTransport) -> None:
self.inner = inner
async def send(self, req: ov.HttpRequest) -> ov.HttpResponse:
res = await self.inner.send(req)
print(req.method.name, req.url, res.status) # never log req.headers: they hold tokens
return res
async def open_stream(self, req: ov.HttpRequest) -> ov.OpenedStream:
return await self.inner.open_stream(req)
host = default_host(http=LoggedTransport(UrllibTransport()))

The rules:

  • A transport must not follow redirects, must not store or send cookies, must send the core’s headers as given, and must return every HTTP status as a response (a 404 or a 500 is not an exception). It raises ov.TransportError (Offline(), Timeout(), Tls(message), Other(message)) only when there is no response. open_stream returns ov.OpenedStream(stream=...) over a ByteStream subclass (status(), async next_chunk() returning None at the end, and close()).
  • A store or cache returns None for a missing key. It raises ov.make_ov_error(ov.OvErrorCode.INTERNAL, "why") when it can’t read or write, so the core can tell a failure from a missing value.
  • Any other exception from a Host method reaches the core as network_error (from a transport) or internal, with the exception’s repr in the message. UniFFI also prints the traceback to stderr.

Passwords, Secret Keys, field values and stored session tokens are plain bytes when they cross into Python. Python can’t wipe bytes, and copies may stay in memory until the garbage collector reuses it. The core zeroizes its own copies. If that matters for your program, keep secrets in Python for as short a time as you can, and don’t log the records: their __str__ prints field values.

Your own OpenVireo account server. Pass its issuer URL to connect:

account = await client.connect("https://accounts.example.com")

The issuer must be https://. The exception is loopback (http://localhost:8000, for a local stack). Any other http:// URL fails with insecure_url. The core reads the API, sync and share URLs from the issuer’s discovery document.

A standalone sync server (no account, .kdbx files synced between paired devices): pair once with a code from a device that is already paired, then sync the database’s bytes:

sh = await ov.SelfHosted.pair(client, "https://sync.example.com", "ABCD-1234", "backup script")
# Later runs, with the same persistent store:
sh = await ov.restore_self_hosted(client, "https://sync.example.com")
creds = ov.KdbxCredentials(password=b"database password", key_file=None)
result = await sh.sync_database("passwords", kdbx_bytes, creds)

The pairing token is kept in the Host’s SecureStore and the sync state in its BlobCache, so use a persistent store (KeyringStore) and cache_dir=. result.kdbx is the merged database: save it as the local file.

Service accounts (an ov_sa_... token, for CI): await ov.ServiceAccount.from_token(client, token). Then vaults(refresh), read("ov://Vault/Entry/Field"), write(...) and inject(template). close() wipes its keys and cached vaults from memory, and later calls fail with signed_out.

No account is needed:

creds = ov.KdbxCredentials(password=b"pw", key_file=None)
vault = await client.open_local(open("db.kdbx", "rb").read(), creds)
...
open("db.kdbx", "wb").write(await vault.save_local())

client.create_local("Name", creds) makes a new database. account.import_kdbx(data, creds, mode) turns one into a vault.

The samples on this page run as tests/test_docs.py in bindings/python, against the in-memory servers (cargo xtask python --smoke).