Skip to main content

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).

requirements.txt
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.

main.py (FastAPI)
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)
app.py (Streamlit)
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​

JavaScriptPython
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, listBucketscreate_signed_url, get_public_url, list_buckets
jobTitle, groupIds, hasRole, inGroupjob_title, group_ids, has_role, in_group
{ data, error } (storage)Returns data, raises TcError

tc.auth​

MethodReturns
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.

ParameterTypeDescription
querystrSQL with %s placeholders
paramsiterableValues
dataframebool | NoneNone (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):

MemberDescription
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​

ExportDescription
Client(env=None, http=None)Build a client with a custom env mapping or httpx.Client (tests)
TcErrorcode, reason, fix, status, details, request, connect_url
UserThe user dict class
user_token(request), share_id(url), rows_to_objects(values), encode_storage_path(path)Helpers
Was this page helpful?