Skip to main content

Python client for the reactive backend-as-a-service Convex.

Project description


The official Python client for Convex.

PyPI GitHub

Write and read data from a Convex backend with queries, mutations, and actions. Get up and running at


pip install convex

Basic usage:

>>> from convex import ConvexClient
>>> client = ConvexClient('')
>>> messages = client.query("messages:list")
>>> from pprint import pprint
>>> pprint(messages)
[{'_creationTime': 1668107495676.2854,
  '_id': '2sh2c7pn6nyvkexbdsfj66vd9h5q3hg',
  'author': 'Tom',
  'body': 'Have you tried Convex?'},
 {'_creationTime': 1668107497732.2295,
  '_id': '1f053fgh2tt2fc93mw3sn2x09h5bj08',
  'author': 'Sarah',
  'body': "Yeah, it's working pretty well for me."}]
>>> client.mutation("sendMessage", dict(author="Me", body="Hello!"))

To find the url of your convex backend, open the deployment you want to work with in the appropriate project in the Convex dashboard and click "Settings" where the Deployment URL should be visible. To find out which queries, mutations, and actions are available check the Functions pane in the dashboard.

To see logs emitted from Convex functions, set the debug mode to True.

>>> client.set_debug(True)

To provide authentication for function execution, call set_auth().

>>> client.set_auth("token-from-authetication-flow")

Join us on Discord to get your questions answered or share what you're doing with Convex. If you're just getting started, see to see how to quickly spin up a backend that does everything you need in the Convex cloud.

Convex types

Convex backend functions are written in JavaScript, so arguments passed to Convex RPC functions in Python are serialized, sent over the network, and deserialized into JavaScript objects. To learn about Convex's supported types see

In order to call a function that expects a JavaScript type, use the corresponding Python type or any other type that coerces to it. Values returned from Convex will be of the corresponding Python type.

JavaScript Type Python Type Example Other Python Types that Convert
null None None
bigint ConvexInt64 (see below) ConvexInt64(2**60)
number float or int 3.1, 10
boolean bool True, False
string str 'abc'
ArrayBuffer bytes b'abc' ArrayBuffer
Array list [1, 3.2, "abc"] tuple,
object dict {a: "abc"}

Ints and Floats

While Convex supports storing Int64s and Float64s, idiomatic JavaScript pervasively uses the (floating point) Number type. In Python floats are often understood to contain the ints: the float type annotation is generally understood as Union[int, float].

Therefore, the Python Convex client converts Python's floats and ints to a Float64 in Convex.

To specify a JavaScript BigInt, use the ConvexInt64 class. Functions which return JavaScript BigInts will return ConvexInt64 instances.

Convex Errors

The Python client supports the ConvexError type to hold application errors that are propagated from your Convex functions. To learn about how to throw ConvexErrors see

On the Python client, ConvexErrors are Exceptions with a data field that contains some ConvexValue. Handling application errors from the Python client might look something like this:

import convex
client = convex.ConvexClient('')

    client.mutation("messages:sendMessage", {body: "hi", author: "anjan"})
except convex.ConvexError as err:
    if isinstance(, dict):
        if "code" in and["code"] == 1:
            # do something
            # do something else
    elif isinstance(, str):
except Exception as err:
    # log internally


Paginated queries are queries that accept pagination options as an argument and can be called repeatedly to produce additional "pages" of results.

For a paginated query like this:

import { query } from "./_generated/server";

export default query(async ({ db }, { paginationOpts }) => {
  return await db.query("messages").order("desc").paginate(paginationOpts);

and returning all results 5 at a time in Python looks like this:

import convex
client = convex.ConvexClient('')

done = False
cursor = None
data = []

while not done:
    result = client.query('listMessages', {"paginationOpts": {"numItems": 5, "cursor": cursor}})
    cursor = result['continueCursor']
    done = result["isDone"]
    print('got', len(result['page']), 'results')

print('collected', len(data), 'results')


While we are pre-1.0.0, we'll update the minor version for large changes, and the patch version for small bugfixes. We may make backwards incompatible changes to the python client's API, but we will limit those to minor version bumps.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

convex-0.6.0.tar.gz (185.0 kB view hashes)

Uploaded Source

Built Distributions

convex-0.6.0-cp39-abi3-win_amd64.whl (846.5 kB view hashes)

Uploaded CPython 3.9+ Windows x86-64

convex-0.6.0-cp39-abi3-win32.whl (834.3 kB view hashes)

Uploaded CPython 3.9+ Windows x86

convex-0.6.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (27.8 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ x86-64

convex-0.6.0-cp39-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (29.5 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ s390x

convex-0.6.0-cp39-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (26.6 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ ppc64le

convex-0.6.0-cp39-abi3-manylinux_2_17_i686.manylinux2014_i686.whl (26.9 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ i686

convex-0.6.0-cp39-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (20.8 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ ARMv7l

convex-0.6.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (27.0 MB view hashes)

Uploaded CPython 3.9+ manylinux: glibc 2.17+ ARM64

convex-0.6.0-cp39-abi3-macosx_11_0_arm64.whl (1.2 MB view hashes)

Uploaded CPython 3.9+ macOS 11.0+ ARM64

convex-0.6.0-cp39-abi3-macosx_10_12_x86_64.whl (1.2 MB view hashes)

Uploaded CPython 3.9+ macOS 10.12+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page