| Name | cursordata-sdk JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | SDK for interacting with Cursor editor's local SQLite usage data database |
| upload_time | 2025-10-30 22:52:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
analytics
cursor
sdk
sqlite
usage-data
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CursorData SDK
[](https://github.com/shaun3141/CursorData-SDK/actions/workflows/test.yml)
[](https://badge.fury.io/py/cursordata-sdk)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://codecov.io/gh/shaun3141/CursorData-SDK)
> **⚠️ Disclaimer:** This is an unofficial project not connected with or endorsed by AnySphere (Cursor). This SDK is developed independently and provided as-is. Use at your own risk. The Cursor editor and its database structure are property of AnySphere.
A well-documented Python SDK for interacting with the local SQLite database that contains all Cursor editor usage data on your computer.
## Features
- 🔍 **Strongly Typed**: Full type hints and dataclasses for all data models
- 📊 **Comprehensive Access**: Query AI code tracking, composer sessions, bubble conversations, and more
- 🎯 **Platform Support**: Automatically detects database location on macOS, Windows, and Linux
- 📚 **Well Documented**: Auto-generated API documentation with Sphinx
- 🔒 **Type Safe**: Full mypy type checking support
## Installation
Install from PyPI:
```bash
pip install cursordata-sdk
```
Or using `uv`:
```bash
uv pip install cursordata-sdk
```
📦 **Available on PyPI**: [https://pypi.org/project/cursordata-sdk/](https://pypi.org/project/cursordata-sdk/)
## Quick Start
```python
from cursordata import CursorDataClient
from datetime import datetime, timedelta
# Initialize the client (automatically finds the database)
with CursorDataClient() as client:
# Get usage statistics
stats = client.get_usage_stats()
print(f"Total tracking entries: {stats.total_tracking_entries}")
print(f"Total scored commits: {stats.total_scored_commits}")
print(f"Composer sessions: {stats.composer_sessions}")
# Query data using the query builder (primary API)
# Get recent bubbles with code changes
week_ago = datetime.now() - timedelta(days=7)
bubbles = (
client.query()
.bubbles()
.where(created_after=week_ago, has_code_blocks=True)
.limit(10)
.execute()
)
print(f"Found {len(bubbles)} recent bubbles with code changes")
# Get composer sessions for Python files
sessions = (
client.query()
.composer_sessions()
.where(file_extension=".py")
.execute()
)
for session in sessions:
print(f"Session {session.composer_id}: {session.entries_count} entries")
print(f" Files: {len(session.files_modified)}")
print(f" Extensions: {', '.join(session.file_extensions)}")
# Get database info
info = client.get_database_info()
print(f"Database path: {info.path}")
print(f"ItemTable entries: {info.item_table_count}")
print(f"CursorDiskKV entries: {info.cursor_disk_kv_count}")
```
## Data Models
The SDK provides strongly-typed data models:
### UsageStats
Aggregated usage statistics including total tracking entries, scored commits, and file extension usage.
### AICodeTrackingEntry
Individual AI code tracking entries with metadata about source, composer ID, file extension, and file name.
### ComposerSession
Composer sessions grouped by session ID with associated files and code entries.
### BubbleConversation
Bubble conversations stored in the database.
### DatabaseInfo
Information about the database file including counts and last modified time.
## API Reference
See the [full API documentation](docs/_build/html/index.html) (generated with Sphinx) for detailed information about all classes and methods.
## Examples
### Analyzing File Extension Usage
```python
from cursordata import CursorDataClient
with CursorDataClient() as client:
stats = client.get_usage_stats()
# Get most used file extensions
extensions = sorted(
stats.most_used_file_extensions.items(),
key=lambda x: x[1],
reverse=True
)
print("Most used file extensions:")
for ext, count in extensions[:10]:
print(f" {ext}: {count} entries")
```
### Finding Files Modified by Composer
```python
from cursordata import CursorDataClient
with CursorDataClient() as client:
sessions = client.get_composer_sessions()
# Collect all unique files
all_files = set()
for session in sessions:
all_files.update(session.files_modified)
print(f"Total unique files modified: {len(all_files)}")
for file_path in sorted(all_files)[:20]:
print(f" {file_path}")
```
### Querying with Filters
```python
from datetime import datetime, timedelta
from cursordata import CursorDataClient
with CursorDataClient() as client:
# Query bubbles from last week
week_ago = datetime.now() - timedelta(days=7)
recent_bubbles = (
client.query()
.bubbles()
.where(created_after=week_ago, has_code_blocks=True)
.limit(10)
.execute()
)
print(f"Found {len(recent_bubbles)} recent bubbles with code changes")
# Query composer sessions for Python files
python_sessions = (
client.query()
.composer_sessions()
.where(file_extension=".py")
.execute()
)
print(f"Found {len(python_sessions)} Python composer sessions")
```
## Development
### Setup
```bash
# Install development dependencies
uv pip install -e ".[dev,docs]"
# Or with pip
pip install -e ".[dev,docs]"
```
### Running Tests
```bash
pytest
```
### Building Documentation
```bash
cd docs
make html
# Documentation will be in docs/_build/html/
```
### Code Quality
```bash
# Format code
black src/
# Lint
ruff check src/
# Type check
mypy src/
```
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Raw data
{
"_id": null,
"home_page": null,
"name": "cursordata-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "analytics, cursor, sdk, sqlite, usage-data",
"author": null,
"author_email": "Shaun VanWeelden <shaun.t.vanweelden@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/be/e9/82d98fcc124927cdffe91e0c5eac24bd691fec109ba3dbe6dbfb19bdacd2/cursordata_sdk-0.2.1.tar.gz",
"platform": null,
"description": "# CursorData SDK\n\n[](https://github.com/shaun3141/CursorData-SDK/actions/workflows/test.yml)\n[](https://badge.fury.io/py/cursordata-sdk)\n[](https://www.python.org/downloads/)\n[](LICENSE)\n[](https://codecov.io/gh/shaun3141/CursorData-SDK)\n\n> **\u26a0\ufe0f Disclaimer:** This is an unofficial project not connected with or endorsed by AnySphere (Cursor). This SDK is developed independently and provided as-is. Use at your own risk. The Cursor editor and its database structure are property of AnySphere.\n\nA well-documented Python SDK for interacting with the local SQLite database that contains all Cursor editor usage data on your computer.\n\n## Features\n\n- \ud83d\udd0d **Strongly Typed**: Full type hints and dataclasses for all data models\n- \ud83d\udcca **Comprehensive Access**: Query AI code tracking, composer sessions, bubble conversations, and more\n- \ud83c\udfaf **Platform Support**: Automatically detects database location on macOS, Windows, and Linux\n- \ud83d\udcda **Well Documented**: Auto-generated API documentation with Sphinx\n- \ud83d\udd12 **Type Safe**: Full mypy type checking support\n\n## Installation\n\nInstall from PyPI:\n\n```bash\npip install cursordata-sdk\n```\n\nOr using `uv`:\n\n```bash\nuv pip install cursordata-sdk\n```\n\n\ud83d\udce6 **Available on PyPI**: [https://pypi.org/project/cursordata-sdk/](https://pypi.org/project/cursordata-sdk/)\n\n## Quick Start\n\n```python\nfrom cursordata import CursorDataClient\nfrom datetime import datetime, timedelta\n\n# Initialize the client (automatically finds the database)\nwith CursorDataClient() as client:\n # Get usage statistics\n stats = client.get_usage_stats()\n print(f\"Total tracking entries: {stats.total_tracking_entries}\")\n print(f\"Total scored commits: {stats.total_scored_commits}\")\n print(f\"Composer sessions: {stats.composer_sessions}\")\n \n # Query data using the query builder (primary API)\n # Get recent bubbles with code changes\n week_ago = datetime.now() - timedelta(days=7)\n bubbles = (\n client.query()\n .bubbles()\n .where(created_after=week_ago, has_code_blocks=True)\n .limit(10)\n .execute()\n )\n print(f\"Found {len(bubbles)} recent bubbles with code changes\")\n \n # Get composer sessions for Python files\n sessions = (\n client.query()\n .composer_sessions()\n .where(file_extension=\".py\")\n .execute()\n )\n for session in sessions:\n print(f\"Session {session.composer_id}: {session.entries_count} entries\")\n print(f\" Files: {len(session.files_modified)}\")\n print(f\" Extensions: {', '.join(session.file_extensions)}\")\n \n # Get database info\n info = client.get_database_info()\n print(f\"Database path: {info.path}\")\n print(f\"ItemTable entries: {info.item_table_count}\")\n print(f\"CursorDiskKV entries: {info.cursor_disk_kv_count}\")\n```\n\n## Data Models\n\nThe SDK provides strongly-typed data models:\n\n### UsageStats\nAggregated usage statistics including total tracking entries, scored commits, and file extension usage.\n\n### AICodeTrackingEntry\nIndividual AI code tracking entries with metadata about source, composer ID, file extension, and file name.\n\n### ComposerSession\nComposer sessions grouped by session ID with associated files and code entries.\n\n### BubbleConversation\nBubble conversations stored in the database.\n\n### DatabaseInfo\nInformation about the database file including counts and last modified time.\n\n## API Reference\n\nSee the [full API documentation](docs/_build/html/index.html) (generated with Sphinx) for detailed information about all classes and methods.\n\n## Examples\n\n### Analyzing File Extension Usage\n\n```python\nfrom cursordata import CursorDataClient\n\nwith CursorDataClient() as client:\n stats = client.get_usage_stats()\n \n # Get most used file extensions\n extensions = sorted(\n stats.most_used_file_extensions.items(),\n key=lambda x: x[1],\n reverse=True\n )\n \n print(\"Most used file extensions:\")\n for ext, count in extensions[:10]:\n print(f\" {ext}: {count} entries\")\n```\n\n### Finding Files Modified by Composer\n\n```python\nfrom cursordata import CursorDataClient\n\nwith CursorDataClient() as client:\n sessions = client.get_composer_sessions()\n \n # Collect all unique files\n all_files = set()\n for session in sessions:\n all_files.update(session.files_modified)\n \n print(f\"Total unique files modified: {len(all_files)}\")\n for file_path in sorted(all_files)[:20]:\n print(f\" {file_path}\")\n```\n\n### Querying with Filters\n\n```python\nfrom datetime import datetime, timedelta\nfrom cursordata import CursorDataClient\n\nwith CursorDataClient() as client:\n # Query bubbles from last week\n week_ago = datetime.now() - timedelta(days=7)\n recent_bubbles = (\n client.query()\n .bubbles()\n .where(created_after=week_ago, has_code_blocks=True)\n .limit(10)\n .execute()\n )\n print(f\"Found {len(recent_bubbles)} recent bubbles with code changes\")\n \n # Query composer sessions for Python files\n python_sessions = (\n client.query()\n .composer_sessions()\n .where(file_extension=\".py\")\n .execute()\n )\n print(f\"Found {len(python_sessions)} Python composer sessions\")\n```\n\n## Development\n\n### Setup\n\n```bash\n# Install development dependencies\nuv pip install -e \".[dev,docs]\"\n\n# Or with pip\npip install -e \".[dev,docs]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Building Documentation\n\n```bash\ncd docs\nmake html\n# Documentation will be in docs/_build/html/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/\n\n# Lint\nruff check src/\n\n# Type check\nmypy src/\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "SDK for interacting with Cursor editor's local SQLite usage data database",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/shaun3141/CursorData-SDK/tree/main/docs/_build/html",
"Homepage": "https://github.com/shaun3141/CursorData-SDK",
"Issues": "https://github.com/shaun3141/CursorData-SDK/issues",
"Repository": "https://github.com/shaun3141/CursorData-SDK"
},
"split_keywords": [
"analytics",
" cursor",
" sdk",
" sqlite",
" usage-data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e866a160e24f4a39283ce2311b8bbd595f5a3d38ac36f86ea54c5f05860f2966",
"md5": "ba3691d55b39380e1fdea9d3e3e464fa",
"sha256": "6044e2b57d30ea796eb52382dba031a4ca09a068407570ad9bad8b6ba80d0201"
},
"downloads": -1,
"filename": "cursordata_sdk-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba3691d55b39380e1fdea9d3e3e464fa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25964,
"upload_time": "2025-10-30T22:52:09",
"upload_time_iso_8601": "2025-10-30T22:52:09.664808Z",
"url": "https://files.pythonhosted.org/packages/e8/66/a160e24f4a39283ce2311b8bbd595f5a3d38ac36f86ea54c5f05860f2966/cursordata_sdk-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bee982d98fcc124927cdffe91e0c5eac24bd691fec109ba3dbe6dbfb19bdacd2",
"md5": "50fb35b4f0804bc5f5056e25d40f6bee",
"sha256": "68674d40f92a24ec8351902f68b3010244c4936d74e4ce1e37fae1109492ad46"
},
"downloads": -1,
"filename": "cursordata_sdk-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "50fb35b4f0804bc5f5056e25d40f6bee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 56466,
"upload_time": "2025-10-30T22:52:10",
"upload_time_iso_8601": "2025-10-30T22:52:10.620352Z",
"url": "https://files.pythonhosted.org/packages/be/e9/82d98fcc124927cdffe91e0c5eac24bd691fec109ba3dbe6dbfb19bdacd2/cursordata_sdk-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 22:52:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shaun3141",
"github_project": "CursorData-SDK",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "cursordata-sdk"
}
