{"id":28372265,"url":"https://github.com/clockworklabs/spacetimedb-python-sdk","last_synced_at":"2025-08-18T16:04:51.623Z","repository":{"id":171727551,"uuid":"637995429","full_name":"clockworklabs/spacetimedb-python-sdk","owner":"clockworklabs","description":"The SpacetimeDB SDK for Python clients","archived":false,"fork":false,"pushed_at":"2024-05-02T22:11:58.000Z","size":168,"stargazers_count":29,"open_issues_count":2,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-18T05:50:05.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://spacetimedb.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clockworklabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-08T21:26:53.000Z","updated_at":"2025-08-08T04:11:55.000Z","dependencies_parsed_at":"2023-12-09T02:44:58.220Z","dependency_job_id":null,"html_url":"https://github.com/clockworklabs/spacetimedb-python-sdk","commit_stats":null,"previous_names":["clockworklabs/spacetimedb-python-sdk"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/clockworklabs/spacetimedb-python-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clockworklabs%2Fspacetimedb-python-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clockworklabs%2Fspacetimedb-python-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clockworklabs%2Fspacetimedb-python-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clockworklabs%2Fspacetimedb-python-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clockworklabs","download_url":"https://codeload.github.com/clockworklabs/spacetimedb-python-sdk/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clockworklabs%2Fspacetimedb-python-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271019393,"owners_count":24685678,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-29T13:42:48.478Z","updated_at":"2025-08-18T16:04:51.615Z","avatar_url":"https://github.com/clockworklabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Notice: Seeking Maintainers\r\n\r\nDue to resource constraints, we are not actively maintaining the SpacetimeDB Python SDK at this time. Official Python SDK support will return in the future when Python modules are also supported.\r\n\r\nFor now, help wanted! We believe in the importance of open-source collaboration and want to ensure that SpacetimeDB continues to thrive. Therefore, we are seeking individuals or organizations who are interested in taking over the maintenance and development of the Python SDK.\r\n\r\nIf you are passionate about SpacetimeDB and have the time and expertise to contribute, we welcome you to step forward and become a maintainer. Your contributions will be highly valued by the community and will help ensure the longevity and sustainability of this project.\r\n\r\n# SpacetimeDB SDK for Python\r\n\r\n## Overview\r\n\r\nThis repository contains the [Python](https://python.org/) SDK for SpacetimeDB. The SDK allows to interact with the database server and is prepared to work with code generated from a SpacetimeDB backend code.\r\n\r\n## Documentation\r\n\r\nThe Python SDK has a [Quick Start](https://spacetimedb.com/docs/client-languages/python/python-sdk-quickstart-guide) guide and a [Reference](https://spacetimedb.com/docs/client-languages/python/python-sdk-reference).\r\n\r\n## Installation\r\n\r\nThe SDK is available as a [PyPi package](https://pypi.org/project/spacetimedb-sdk/). To install it, run the following command:\r\n\r\n```bash\r\npip install spacetimedb-sdk\r\n```\r\n\r\n## Usage\r\n\r\nThe Python SpacetimeDB SDK utilizes a client that uses the `asyncio` package to provide an event driven interface. \r\n\r\n### Connecting to SpacetimeDB\r\n\r\nTo connect to SpacetimeDB, you first need to create a `SpacetimeDBAsyncClient` instance. The `SpacetimeDBAsyncClient` constructor takes the `module_bindings` folder that contains the auto-generated files as a parameter. The `module_bindings` folder is generated by the CLI generate command.\r\n\r\n```python\r\nfrom spacetimedb_sdk.spacetimedb_async_client import SpacetimeDBAsyncClient\r\n\r\nspacetime_client = SpacetimeDBAsyncClient(module_bindings)\r\n```\r\n\r\nTo connect to SpacetimeDB, you need to call the `run` method on the `SpacetimeDBAsyncClient` instance. The `run` method takes the following parameters:\r\n\r\n- `auth_token`: The authentication token to use to connect to SpacetimeDB. This token is generated by the backend code and is used to authenticate the client.\r\n- `host_name`: The hostname of the SpacetimeDB server. This hostname should also contain the port number. For example: `http://localhost:3000`.\r\n- `module_address`: The address of the module to connect to. This is the same address that you use to connect to the SpacetimeDB web interface.\r\n- `ssl_enabled`: Whether to use SSL to connect to SpacetimeDB. `True` if connecting to SpacetimeDB Cloud.\r\n- `on_connect`: A callback that is called when the client connects to SpacetimeDB.\r\n- `queries`: A list of queries to subscribe to. The queries are the same queries that you use to subscribe to tables in the SpacetimeDB web interface.\r\n\r\nExample:\r\n\r\n```python\r\nimport asyncio\r\n\r\nasyncio.run(\r\n    spacetime_client.run(\r\n        local_config.get_string(\"auth_token\"),\r\n        \"http://localhost:3000\",\r\n        \"chatqs\",\r\n        on_connect,\r\n        [\"SELECT * FROM User\", \"SELECT * FROM Message\"],\r\n    )\r\n)\r\n```\r\n\r\n### Listening to events\r\n\r\nTo listen to events, you need to register callbacks on the `SpacetimeDBAsyncClient` instance. The following callbacks are available:\r\n\r\n- `on_subscription_applied`: Called when the client receives the initial data from SpacetimeDB after subscribing to tables.\r\n- scheduled events: You can schedule events to be called at a later time. The `schedule_event` method takes the following parameters:\r\n  - `delay`: The delay in seconds before the event is called.\r\n  - `callback`: The callback to call when the event is called.\r\n\r\nYou can register for row update events on a table. To do this, you need to register callbacks on the auto-generated table class. The following callbacks are available:\r\n\r\n- `register_row_update`: Called when a row is inserted, updated, or deleted from the table. The callback takes the following parameters:\r\n  - `row_op`: The operation that was performed on the row. Can be `insert`, `update`, or `delete`.\r\n  - `row_old`: The old row value. `None` if the operation is `insert`.\r\n  - `row`: The new row value. `None` if the operation is `delete`.\r\n  - `reducer_event`: The reducer event that caused the row update. `None` if the row update was not caused by a reducer event.\r\n\r\nExample:\r\n    \r\n```python\r\ndef on_message_row_update(row_op, message_old, message, reducer_event):\r\n    if reducer_event is not None and row_op == \"insert\":\r\n        print_message(message)\r\n\r\nMessage.register_row_update(on_message_row_update)\r\n```\r\n\r\nYou can register for reducer call updates as well.\r\n\r\n- `register_on_REDUCER`: Called when a reducer call is received from SpacetimeDB. (If a) you are subscribed to the table that the reducer modifies or b) You called the reducer and it failed)\r\n\r\nExample:\r\n\r\n```python\r\ndef on_send_message_reducer(sender, status, message, msg):\r\n    if sender == local_identity:\r\n        if status == \"failed\":\r\n            print(f\"Failed to send message: {message}\")\r\n\r\nsend_message_reducer.register_on_send_message(on_send_message_reducer)\r\n```\r\n\r\n### Accessing the client cache\r\n\r\nThe client cache is a local cache of the data that the client has received from SpacetimeDB. The client cache is automatically updated when the client receives updates from SpacetimeDB. \r\n\r\nWhen you run the CLI generate command, SpacetimeDB will automatically generate a class for each table in your database. \r\n\r\n- `filter_by_COLUMN`: Filters the table by the specified column value.\r\n- `iter`: Returns an iterator over the table.\r\n\r\nExample:\r\n\r\n```python\r\nfrom module_bindings.user import User\r\n\r\nmy_user = User.filter_by_identity(local_identity)\r\n\r\nfor user in User.iter():\r\n    print(user.name)\r\n```\r\n\r\n### Calling Reducers\r\n\r\nTo call a reducer, you need to call the autogenerated method in the auto-generated reducer file. \r\n\r\nExample:\r\n\r\n```python\r\nimport module_bindings.send_message_reducer as send_message_reducer\r\n\r\nsend_message_reducer.send_message(\"Hello World!\")\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclockworklabs%2Fspacetimedb-python-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclockworklabs%2Fspacetimedb-python-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclockworklabs%2Fspacetimedb-python-sdk/lists"}