🐍
Python SDK
StableThe official TrueEntropy Python client. Supports sync and async, full type hints, automatic retries, and direct access to QuBitLang metadata.
Installation
Terminal
pip install trueentropy
Requires Python 3.9+. For async support, aiohttp is installed automatically.
Quick Start
quickstart.py
from trueentropy import TrueEntropy
client = TrueEntropy(api_key="te_live_YOUR_KEY")
# Generate quantum random integers
result = client.integers(count=10, min=1, max=100)
print(result.values)
# [42, 87, 13, 65, 91, 28, 74, 3, 56, 49]
# Access QuBitLang provenance metadata
print(result.metadata.qubitlang_circuit) # qrng_hadamard_v2.3
print(result.metadata.quantum_backend) # ibm_fez
print(result.metadata.nist_verified) # True
Configuration
config.py
from trueentropy import TrueEntropy
# Full configuration
client = TrueEntropy(
api_key="te_live_YOUR_KEY",
base_url="https://api.trueentropy.net", # default
timeout=30, # seconds
max_retries=3, # automatic retries
sandbox=False, # set True for sandbox
)
# Or use environment variable
# export TRUEENTROPY_API_KEY=te_live_YOUR_KEY
client = TrueEntropy() # auto-reads from env
Endpoint Methods
Integers
integers.py
result = client.integers(count=5, min=1, max=1000)
print(result.values) # [472, 829, 134, 567, 291]
print(result.count) # 5
Floats
floats.py
result = client.floats(count=5, precision=10)
print(result.values) # [0.4721937482, 0.8291053847, ...]
Bytes
bytes.py
result = client.bytes(count=32, encoding="hex")
print(result.bytes) # "a7f2b9c4d8e1..."
result = client.bytes(count=32, encoding="base64")
print(result.bytes) # "p/K5xNjh..."
UUID
uuid.py
result = client.uuid(count=3)
for uid in result.uuids:
print(uid)
# a7f2b9c4-d8e1-4f3a-b5c7-d9e2f4a6b8c0
Bitstring
bitstring.py
result = client.bitstring(length=256)
print(result.bits) # "10110100111010010110..."
print(len(result.bits)) # 256
Shuffle
shuffle.py
deck = [f"{r}{s}" for s in "SHDC" for r in "A23456789TJQK"]
result = client.shuffle(items=deck)
print(result.shuffled[:5]) # ["7H", "KS", "3D", "AC", "9S"]
Batch
batch.py
result = client.batch(
type="integers",
count=100000,
params={"min": 1, "max": 1000000}
)
print(len(result.values)) # 100000
print(result.metadata.processing_time_ms) # 342
Certificate
certificate.py
cert = client.certificate(id="cert_a7f2b9c4d8e1")
print(cert.provenance.qubitlang_circuit) # qrng_hadamard_v2.3
print(cert.verification.nist_sp800_22) # 7/7 passed
print(cert.verify_url) # https://trueentropy.net/verify/?id=...
Async Support
async_example.py
import asyncio
from trueentropy import TrueEntropy
async def main():
async with TrueEntropy.async_client(api_key="te_live_YOUR_KEY") as client:
# Concurrent requests
ints, floats, uuids = await asyncio.gather(
client.integers(count=10),
client.floats(count=10),
client.uuid(count=5),
)
print(ints.values, floats.values, uuids.uuids)
asyncio.run(main())
Error Handling
errors.py
from trueentropy import TrueEntropy
from trueentropy.exceptions import (
AuthenticationError,
RateLimitError,
ValidationError,
TrueEntropyError,
)
client = TrueEntropy(api_key="te_live_YOUR_KEY")
try:
result = client.integers(count=10)
except AuthenticationError as e:
print(f"Invalid API key: {e}")
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
except ValidationError as e:
print(f"Invalid params: {e.code}")
except TrueEntropyError as e:
print(f"API error: {e.status_code} - {e.message}")
Features
| Feature | Details |
|---|---|
| Type hints | Full mypy compatible type annotations on all methods and responses |
| Async | Native async/await via TrueEntropy.async_client() |
| Retries | Exponential backoff with configurable max_retries |
| Connection pooling | Persistent HTTP connections for high-throughput use |
| Sandbox | Toggle sandbox=True for testing without consuming quota |
| Certificates | Built-in client.certificate() for provenance retrieval |
| QuBitLang metadata | Typed access to circuit, version, backend info on every response |