ripv-py 1.0.0

Python SDK for PersonalVault - secure API key retrieval

PersonalVault Python SDK

Secure API key retrieval for Python backend applications.

Installation

pip install personalvault

Quick Start

Environment Variables

export PV_API_KEY="pvault_bk_..."       # Required - your backend key
export PV_API_URL="https://pv.example.com"  # Optional - defaults to http://localhost:8923
export PV_CACHE_TTL="3600"              # Optional - cache TTL in seconds (default: 3600)

Synchronous (Django, Flask)

from personalvault import init, pv

# Initialize once at startup
init()

# Retrieve keys instantly from cache
openai_key = pv("OPENAI_API_KEY")
db_password = pv("DB_PASS")

Asynchronous (FastAPI, AIOHTTP)

from personalvault import pv_async

# Auto-initializes on first call, then serves from cache
openai_key = await pv_async("OPENAI_API_KEY")
db_password = await pv_async("DB_PASS")

API Reference

init() -> None

Synchronously fetch and cache all allowed keys. Blocks until complete.

pv(key_name: str) -> str

Synchronous cache lookup. Raises PVNotInitializedError if init() hasn't been called or cache has expired.

pv_async(key_name: str) -> str

Async key retrieval. Automatically initializes/refreshes the cache when needed.

Exceptions

Exception	When
PVAuthError	PV_API_KEY missing, invalid, or expired
PVDeniedError	Server rejected request (IP allowlist, etc.)
PVKeyNotFoundError	Key not in vault or not allowed for this backend key
PVNotInitializedError	pv() called before init() or cache expired

Framework Examples

FastAPI

from contextlib import asynccontextmanager
from fastapi import FastAPI
from personalvault import pv_async, pv

@asynccontextmanager
async def lifespan(app: FastAPI):
    await pv_async("DB_URL")  # warm the cache
    yield

app = FastAPI(lifespan=lifespan)

@app.get("/")
async def root():
    return {"db": pv("DB_URL")}

Flask

from flask import Flask
from personalvault import init, pv

app = Flask(__name__)
init()  # fetch keys at import time

@app.route("/")
def index():
    return {"db": pv("DB_URL")}

Django (settings.py)

from personalvault import init, pv

init()

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "PASSWORD": pv("DB_PASS"),
    }
}