Python SDK
tenantcloud is the Python twin of the JavaScript SDK: same namespaces, Python naming. It's synchronous and server-side only (there is no browser).
tenantcloud
# or, to get DataFrames from tc.db.sql and Excel tables:
tenantcloud[pandas]
Requires Python 3.10+. Dependencies: httpx, PyJWT[crypto], psycopg[binary], postgrest (and optionally pandas).
The request
Every per-user call takes request=: a FastAPI/Starlette Request, a Flask request, a dict of headers, or the raw token. In Streamlit, st.context.headers works as the request.
from fastapi import FastAPI, Request
from tenantcloud import tc, TcError
app = FastAPI()
@app.get("/api/me")
def me(request: Request):
return tc.auth.user(request)
import streamlit as st
from tenantcloud import tc
user = tc.auth.user(st.context.headers)
st.write(f"Hello {user.name}")
There is no middleware: pass the request each time.
Naming differences
| JavaScript | Python |
|---|---|
tc.db.from(t) (browser) / tc.db.asUser(req).from(t) | tc.db.as_user(request).from_(t) (also .table(t)) |
tc.db.sql`… ${x}` | tc.db.sql("… %s", [x]) |
{ request: req } | request=request |
{ as: 'project' } | as_="project" |
from (mail) | from_ |
tc.storage.from(b) | tc.storage.from_(b) |
createSignedUrl, getPublicUrl, listBuckets | create_signed_url, get_public_url, list_buckets |
jobTitle, groupIds, hasRole, inGroup | job_title, group_ids, has_role, in_group |
{ data, error } (storage) | Returns data, raises TcError |
tc.auth
| Method | Returns |
|---|---|
tc.auth.user(request) | User, a dict with attribute access: id, name, email, department, job_title, groups, group_ids, roles, project, plus has_role(r) and in_group(g) |
tc.auth.token(request) | The raw X-TC-User token, or None |
Raises UNAUTHENTICATED, BAD_IDENTITY, NOT_CONFIGURED.
tc.db
tc.db.sql(query, params=None, dataframe=None)
SQL as the project's service role (bypasses row-level security). Use %s placeholders.
| Parameter | Type | Description |
|---|---|---|
query | str | SQL with %s placeholders |
params | iterable | Values |
dataframe | bool | None | None (default): a DataFrame if pandas is installed, else a list of dicts. False forces a list. |
rows = tc.db.sql("select * from purchase_requests where status = %s", ["open"], dataframe=False)
Raises DB_ERROR (with details["sqlstate"]) or NOT_CONFIGURED. Each thread keeps one connection.
tc.db.as_user(request)
Returns a user-scoped client (row-level security applies):
| Member | Description |
|---|---|
from_(table) / table(table) | A postgrest-py builder; end the chain with .execute() |
rpc(fn, params) | Call a Postgres function |
sql(query, params=None, dataframe=None) | SQL as the user |
res = tc.db.as_user(request).from_("purchase_requests").select("*").eq("status", "open").execute()
print(res.data)
Raises NO_REQUEST if the request carries no user.
tc.storage
bucket = tc.storage.from_("receipts", request=request) # request/as_ apply to every call
bucket.upload(path, data, content_type="application/pdf", upsert=False)
bucket.update(path, data, content_type=None)
bucket.download(path) # -> bytes
bucket.list("2026/", search=None) # -> list of dicts, folders first (id None)
bucket.remove([path1, path2]) # -> removed entries
bucket.create_signed_url(path, 300, download=False) # -> {"signedUrl", "path", "expiresAt"}
bucket.get_public_url(path, download=False) # -> str (app-public buckets only)
tc.storage.list_buckets(request=request)
upload accepts bytes, str (uploaded as text, not read as a file name), a file object or an os.PathLike path. Every method except get_public_url also takes request= and as_=. Errors raise TcError with the storage codes.
tc.m365
wb = tc.m365.excel(url, request=request, sheet=None, as_=None)
wb.info(); wb.tables()
wb.table("Actuals").rows() # list of dicts
wb.table("Actuals").values() # 2-D list
wb.table("Actuals").columns()
wb.table("Actuals").dataframe() # needs pandas
wb.range("Summary!A1:B6").values()
tc.m365.list(site_url, "Vendors", request=request).items(top=100)
tc.m365.mail.send(to="a@contoso.com", subject="Report", html=html, cc=None, request=request)
tc.int and tc.teams
tc.int.salesforce.get("/query", {"q": "SELECT Id FROM Case"}, request=request)
tc.int.erp.post("/query", {"sql": "select 1"}, request=request)
tc.int["my-system"].get("/items", request=request)
tc.teams.notify(to="role:approver", text="New request", card=None, request=request)
Methods: get(path, query=None), post(path, body=None), patch, put, delete(path); each takes request= and as_=. tc.teams.notify takes request= only (no as_=). There is no connect() in Python: per-user OAuth consent happens in the browser.
Not in the Python SDK
createSignedUrls, getUsage, worksheets(), a limit on list, middleware and the browser-only helpers exist only in JavaScript.
Other exports
| Export | Description |
|---|---|
Client(env=None, http=None) | Build a client with a custom env mapping or httpx.Client (tests) |
TcError | code, reason, fix, status, details, request, connect_url |
User | The user dict class |
user_token(request), share_id(url), rows_to_objects(values), encode_storage_path(path) | Helpers |