 turbopuffer Python Client [](https://github.com/turbopuffer/turbopuffer-python/actions/workflows/ci_test.yml)
=========================
The official Python client for accessing the turbopuffer API.
Usage
-----
1. Install the turbopuffer package and set your API key.
```sh
$ pip install turbopuffer
```
Or if you're able to run C binaries for JSON encoding, use:
```sh
$ pip install turbopuffer[fast]
```
2. Start using the API
```py
import turbopuffer as tpuf
tpuf.api_key = 'your-token' # Alternatively: export=TURBOPUFFER_API_KEY=your-token
# Choose the best region for your data https://turbopuffer.com/docs/regions
tpuf.api_base_url = "https://gcp-us-east4.turbopuffer.com"
# Open a namespace
ns = tpuf.Namespace('hello_world')
# Read namespace metadata
if ns.exists():
print(f'Namespace {ns.name} exists with {ns.dimensions()} dimensions and approximately {ns.approx_count()} vectors.')
# Upsert your dataset
ns.upsert(
ids=[1, 2],
vectors=[[0.1, 0.2], [0.3, 0.4]],
attributes={'name': ['foo', 'foos']},
distance_metric='cosine_distance',
)
# Alternatively, upsert using a row iterator
ns.upsert(
{
'id': id,
'vector': [id/10, id/10],
'attributes': {'name': 'food', 'num': 8}
} for id in range(3, 10),
distance_metric='cosine_distance',
)
# Query your dataset
vectors = ns.query(
vector=[0.15, 0.22],
distance_metric='cosine_distance',
top_k=10,
filters=['And', [
['name', 'Glob', 'foo*'],
['name', 'NotEq', 'food'],
]],
include_attributes=['name'],
include_vectors=True
)
print(vectors)
# [
# VectorRow(id=2, vector=[0.30000001192092896, 0.4000000059604645], attributes={'name': 'foos'}, dist=0.001016080379486084),
# VectorRow(id=1, vector=[0.10000000149011612, 0.20000000298023224], attributes={'name': 'foo'}, dist=0.009067952632904053)
# ]
# List all namespaces
namespaces = tpuf.namespaces()
print('Total namespaces:', len(namespaces))
for namespace in namespaces:
print('Namespace', namespace.name, 'contains approximately', namespace.approx_count(),
'vectors with', namespace.dimensions(), 'dimensions.')
# Delete vectors using the separate delete method
ns.delete([1, 2])
```
Endpoint Documentation
----------------------
For more details on request parameters and query options, check the docs at https://turbopuffer.com/docs
## Development
Run `poetry install --with=test` to set up the project and dependencies.
1. `poetry run pytest`
2. Bump version in `turbopuffer/version.py` and `pyproject.toml`
3. `git tag vX.Y.Z && git push --tags`
3. `poetry build`
4. `poetry publish`
Raw data
{
"_id": null,
"home_page": "https://turbopuffer.com",
"name": "turbopuffer",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "turbopuffer, vector, database, cloud",
"author": "turbopuffer Inc.",
"author_email": "info@turbopuffer.com",
"download_url": "https://files.pythonhosted.org/packages/34/6b/99827c3d6f0a6d0d33c25d38dc87aae971828dfb524afb58955d72d09229/turbopuffer-0.1.26.tar.gz",
"platform": null,
"description": " turbopuffer Python Client [](https://github.com/turbopuffer/turbopuffer-python/actions/workflows/ci_test.yml)\n=========================\n\nThe official Python client for accessing the turbopuffer API.\n\nUsage\n-----\n\n1. Install the turbopuffer package and set your API key.\n```sh\n$ pip install turbopuffer\n```\nOr if you're able to run C binaries for JSON encoding, use:\n```sh\n$ pip install turbopuffer[fast]\n```\n\n2. Start using the API\n```py\nimport turbopuffer as tpuf\ntpuf.api_key = 'your-token' # Alternatively: export=TURBOPUFFER_API_KEY=your-token\n# Choose the best region for your data https://turbopuffer.com/docs/regions\ntpuf.api_base_url = \"https://gcp-us-east4.turbopuffer.com\"\n\n# Open a namespace\nns = tpuf.Namespace('hello_world')\n\n# Read namespace metadata\nif ns.exists():\n print(f'Namespace {ns.name} exists with {ns.dimensions()} dimensions and approximately {ns.approx_count()} vectors.')\n\n# Upsert your dataset\nns.upsert(\n ids=[1, 2],\n vectors=[[0.1, 0.2], [0.3, 0.4]],\n attributes={'name': ['foo', 'foos']},\n distance_metric='cosine_distance',\n)\n\n# Alternatively, upsert using a row iterator\nns.upsert(\n {\n 'id': id,\n 'vector': [id/10, id/10],\n 'attributes': {'name': 'food', 'num': 8}\n } for id in range(3, 10),\n distance_metric='cosine_distance',\n)\n\n# Query your dataset\nvectors = ns.query(\n vector=[0.15, 0.22],\n distance_metric='cosine_distance',\n top_k=10,\n filters=['And', [\n ['name', 'Glob', 'foo*'],\n ['name', 'NotEq', 'food'],\n ]],\n include_attributes=['name'],\n include_vectors=True\n)\nprint(vectors)\n# [\n# VectorRow(id=2, vector=[0.30000001192092896, 0.4000000059604645], attributes={'name': 'foos'}, dist=0.001016080379486084),\n# VectorRow(id=1, vector=[0.10000000149011612, 0.20000000298023224], attributes={'name': 'foo'}, dist=0.009067952632904053)\n# ]\n\n# List all namespaces\nnamespaces = tpuf.namespaces()\nprint('Total namespaces:', len(namespaces))\nfor namespace in namespaces:\n print('Namespace', namespace.name, 'contains approximately', namespace.approx_count(),\n 'vectors with', namespace.dimensions(), 'dimensions.')\n\n# Delete vectors using the separate delete method\nns.delete([1, 2])\n```\n\nEndpoint Documentation\n----------------------\n\nFor more details on request parameters and query options, check the docs at https://turbopuffer.com/docs\n\n## Development\n\nRun `poetry install --with=test` to set up the project and dependencies.\n\n1. `poetry run pytest`\n2. Bump version in `turbopuffer/version.py` and `pyproject.toml`\n3. `git tag vX.Y.Z && git push --tags`\n3. `poetry build`\n4. `poetry publish`\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Client for accessing the turbopuffer API",
"version": "0.1.26",
"project_urls": {
"Documentation": "https://turbopuffer.com/docs",
"Homepage": "https://turbopuffer.com",
"Repository": "https://github.com/turbopuffer/turbopuffer-python"
},
"split_keywords": [
"turbopuffer",
" vector",
" database",
" cloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ffcac695c037c2eb41c9ecdabc29f51b2009d881031d42686114ea9309f327f",
"md5": "955a76b787e7ad5f01dc01571608aa91",
"sha256": "6f4f27b5870b2f745034c2e0c735b2daa17e3feb6c3d53974cb9de732cafa4b2"
},
"downloads": -1,
"filename": "turbopuffer-0.1.26-py3-none-any.whl",
"has_sig": false,
"md5_digest": "955a76b787e7ad5f01dc01571608aa91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 16350,
"upload_time": "2025-01-14T02:34:29",
"upload_time_iso_8601": "2025-01-14T02:34:29.927440Z",
"url": "https://files.pythonhosted.org/packages/0f/fc/ac695c037c2eb41c9ecdabc29f51b2009d881031d42686114ea9309f327f/turbopuffer-0.1.26-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "346b99827c3d6f0a6d0d33c25d38dc87aae971828dfb524afb58955d72d09229",
"md5": "16f05f4ce804dc6842bd1775d3f01a16",
"sha256": "94ddff9e41258dd97ff0ec03262cb2a4f0bef3a11f1d6ffff977b4538ff7a2ae"
},
"downloads": -1,
"filename": "turbopuffer-0.1.26.tar.gz",
"has_sig": false,
"md5_digest": "16f05f4ce804dc6842bd1775d3f01a16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 14475,
"upload_time": "2025-01-14T02:34:32",
"upload_time_iso_8601": "2025-01-14T02:34:32.150550Z",
"url": "https://files.pythonhosted.org/packages/34/6b/99827c3d6f0a6d0d33c25d38dc87aae971828dfb524afb58955d72d09229/turbopuffer-0.1.26.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-14 02:34:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "turbopuffer",
"github_project": "turbopuffer-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "turbopuffer"
}
JSON
