Convex

Convex的官方Python客户端。

使用查询、变更和操作从Convex后端写入和读取数据。在docs.convex.dev上开始使用。

安装

pip install convex

基本用法

>>> from convex import ConvexClient
>>> client = ConvexClient('https://example-lion-123.convex.cloud')
>>> 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!"))

要找到您的凸后端URL，请打开您想要在相应项目中工作的部署，在Convex仪表板中点击“设置”，在那里可以找到部署URL。要了解哪些查询、突变和操作可用，请检查仪表板中的“函数”面板。

要查看从Convex函数发出的日志，请将调试模式设置为True。

>>> client.set_debug(True)

为了对函数执行提供认证，请调用set_auth()。

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

加入我们Discord以获取您的疑问解答或分享您使用Convex的进展。如果您是初学者，请访问https://docs.convex.dev了解如何在Convex云中快速启动一个能够满足您所需一切的后端。

Convex类型

Convex后端函数是用JavaScript编写的，因此传递给Convex RPC函数的Python参数将被序列化，通过网络发送，并反序列化为JavaScript对象。要了解Convex支持的类型，请参阅https://docs.convex.dev/using/types。

为了调用期望JavaScript类型的函数，请使用相应的Python类型或任何可以转换为它的类型。Convex返回的值将是相应的Python类型。

整数和浮点数

虽然Convex支持存储Int64s和Float64s，但惯用的JavaScript广泛使用（浮点数）Number类型。在Python中，float通常被认为包含int：float类型注解通常理解为Union[int, float]。

因此，Python Convex客户端将Python的float和int转换为Convex中的Float64。

要指定JavaScript BigInt，请使用ConvexInt64类。返回JavaScript BigInt的函数将返回ConvexInt64实例。

Convex错误

Python客户端支持ConvexError类型来持有从您的Convex函数传播的应用程序错误。有关如何抛出ConvexError的说明，请参阅https://docs.convex.dev/functions/error-handling/application-errors。

在Python客户端上，ConvexError是带有包含一些ConvexValue的data字段的异常。处理Python客户端的应用程序错误可能看起来像这样

import convex
client = convex.ConvexClient('https://happy-animal-123.convex.cloud')

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

分页

分页查询是接受分页选项作为参数的查询，可以重复调用以产生额外的“页面”结果。

对于此类分页查询

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

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

在Python中以每次返回5个结果的方式返回所有结果如下所示

import convex
client = convex.ConvexClient('https://happy-animal-123.convex.cloud')

done = False
cursor = None
data = []

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

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

版本控制

虽然我们处于预1.0.0版本，但我们将对大更改更新次要版本，对小错误修复更新补丁版本。我们可能会对Python客户端的API进行向后不兼容的更改，但我们将在次要版本升级中限制这些更改。