# TursoPy
A lightweight, dependency-minimal Python client for Turso databases. Born out of frustration with dependency issues in existing solutions, TursoPy provides a straightforward way to interact with Turso databases without the complexity.
> **Note**: This project isn't meant to compete with libsql-experimental or suggest it's any better or worse. It's simply an alternative born from experiencing dependency issues with existing solutions. While TursoPy might not be as feature-rich as libsql-experimental, it gets the job done with minimal fuss. As a solo developer without corporate backing, I created this to solve my own frustrations and share it with others who might face similar challenges.
## Features
- Simple CRUD operations
- Batch processing support
- Advanced query capabilities including JOINs
- Minimal dependencies (just `requests` and `python-dotenv`)
- Straightforward error handling
- Database creation utilities
## Installation
```
pip install turso-python
```
If pip install doesn't work, clone the project or download the zip from the realease section
## Quick Start
1. Set up your environment variables:
```env
TURSO_DATABASE_URL="https://your_database_url"
TURSO_AUTH_TOKEN="your_auth_token"
```
When you use the turso dashboard to generate urls and auth token, the url will be libsql: change that to https:
> libsql://database-organisation.turso.io --> https://database-organisation.turso.io
2. Basic usage:
```python
from turso_python.connection import TursoConnection
from turso_python.crud import TursoCRUD
# Initialize connection
connection = TursoConnection()
crud = TursoCRUD(connection)
# Insert data
data = {"name": "John Doe", "age": 30}
crud.create("users", data)
# Read data
result = crud.read("users", "name = ?", [{"type": "text", "value": "John Doe"}])
```
## Detailed Usage Guide
### Connection Management
The `TursoConnection` class handles all communication with the Turso API:
```python
from turso_python.connection import TursoConnection
# Using environment variables
connection = TursoConnection()
# Or explicit credentials
connection = TursoConnection(
database_url="your_database_url",
auth_token="your_auth_token"
)
```
### CRUD Operations
#### Create
```python
crud = TursoCRUD(connection)
# Single insert
user_data = {
"name": "Jane Smith",
"email": "jane@example.com",
"age": 25
}
crud.create("users", user_data)
```
#### Read
```python
# Fetch all records
all_users = crud.read("users")
# Fetch with conditions
young_users = crud.read(
table="users",
where="age < ?",
args=[{"type": "integer", "value": "30"}]
)
```
#### Update
```python
update_data = {"age": 31}
crud.update(
table="users",
data=update_data,
where="name = ?",
args=[{"type": "text", "value": "Jane Smith"}]
)
```
#### Delete
```python
crud.delete(
table="users",
where="name = ?",
args=[{"type": "text", "value": "Jane Smith"}]
)
```
### Batch Operations
For bulk operations, use the `TursoBatch` class:
```python
from turso_python.batch import TursoBatch
batch = TursoBatch(connection)
users = [
{"name": "User 1", "age": 25},
{"name": "User 2", "age": 30},
{"name": "User 3", "age": 35}
]
batch.batch_insert("users", users)
```
### Advanced Queries
The `TursoAdvancedQueries` class handles complex operations:
```python
from turso_python.advanced_queries import TursoAdvancedQueries
advanced = TursoAdvancedQueries(connection)
# Perform a JOIN operation
result = advanced.join_query(
base_table="users",
join_table="orders",
join_condition="users.id = orders.user_id",
select_columns="users.name, orders.order_date",
where="orders.amount > 100"
)
```
### Schema Management
The `TursoSchemaManager` helps with table operations:
```python
from turso_python.crud import TursoSchemaManager
schema_manager = TursoSchemaManager(connection)
# Create a new table
schema = {
"id": "INTEGER PRIMARY KEY",
"name": "TEXT NOT NULL",
"email": "TEXT UNIQUE",
"created_at": "TIMESTAMP DEFAULT CURRENT_TIMESTAMP"
}
schema_manager.create_table("users", schema)
# Drop a table
schema_manager.drop_table("old_table")
```
### Database Creation
```python
from turso_python.crud import TursoClient
client = TursoClient()
# Create a new database
client.create_database(
org_name="your_org",
db_name="new_database",
group_name="default",
api_token="your_api_token"
)
```
## Error Handling
TursoPy includes basic error handling for common scenarios:
```python
try:
result = crud.read("non_existent_table")
except Exception as e:
print(f"An error occurred: {e}")
```
## Best Practices
1. Always use environment variables for sensitive credentials
2. Use batch operations for bulk inserts/updates
3. Close connections when done (handled automatically in most cases)
4. Use proper type hints in query arguments
5. Handle errors appropriately in production code
## Contributing
Contributions are welcome! As a solo developer project, I appreciate any help in improving TursoPy. Please feel free to:
- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation
## License
Apache 2.0 License
## Support
For issues, questions, or suggestions, please open an issue on GitHub. As a solo developer, I'll do my best to respond in a timely manner.
---
Remember: TursoPy is designed to be simple and straightforward. While it might not have all the bells and whistles of other clients, it focuses on reliability and ease of use. Sometimes, simpler is better!
**Note for 2024-11-24, I literally built this yesterday so I'm still tweaking some stuff and fixing some stuff**
Raw data
{
"_id": null,
"home_page": "https://github.com/marcus-peterson/tursopy",
"name": "turso-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Marcus Peterson",
"author_email": "Marcus Peterson <marcus.peterson.tech@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/6a/50/df0019f99f422bbc1e9db8822c6603c40235250908b5d6f2ca1bd322dd89/turso_python-1.6.tar.gz",
"platform": null,
"description": "# TursoPy\r\n\r\nA lightweight, dependency-minimal Python client for Turso databases. Born out of frustration with dependency issues in existing solutions, TursoPy provides a straightforward way to interact with Turso databases without the complexity.\r\n\r\n> **Note**: This project isn't meant to compete with libsql-experimental or suggest it's any better or worse. It's simply an alternative born from experiencing dependency issues with existing solutions. While TursoPy might not be as feature-rich as libsql-experimental, it gets the job done with minimal fuss. As a solo developer without corporate backing, I created this to solve my own frustrations and share it with others who might face similar challenges.\r\n\r\n## Features\r\n\r\n- Simple CRUD operations\r\n- Batch processing support\r\n- Advanced query capabilities including JOINs\r\n- Minimal dependencies (just `requests` and `python-dotenv`)\r\n- Straightforward error handling\r\n- Database creation utilities\r\n\r\n## Installation\r\n```\r\npip install turso-python\r\n```\r\nIf pip install doesn't work, clone the project or download the zip from the realease section\r\n\r\n## Quick Start\r\n\r\n1. Set up your environment variables:\r\n\r\n```env\r\nTURSO_DATABASE_URL=\"https://your_database_url\"\r\nTURSO_AUTH_TOKEN=\"your_auth_token\"\r\n```\r\nWhen you use the turso dashboard to generate urls and auth token, the url will be libsql: change that to https:\r\n> libsql://database-organisation.turso.io --> https://database-organisation.turso.io\r\n\r\n\r\n2. Basic usage:\r\n\r\n```python\r\nfrom turso_python.connection import TursoConnection\r\nfrom turso_python.crud import TursoCRUD\r\n\r\n# Initialize connection\r\nconnection = TursoConnection()\r\ncrud = TursoCRUD(connection)\r\n\r\n# Insert data\r\ndata = {\"name\": \"John Doe\", \"age\": 30}\r\ncrud.create(\"users\", data)\r\n\r\n# Read data\r\nresult = crud.read(\"users\", \"name = ?\", [{\"type\": \"text\", \"value\": \"John Doe\"}])\r\n```\r\n\r\n## Detailed Usage Guide\r\n\r\n### Connection Management\r\n\r\nThe `TursoConnection` class handles all communication with the Turso API:\r\n\r\n```python\r\nfrom turso_python.connection import TursoConnection\r\n\r\n# Using environment variables\r\nconnection = TursoConnection()\r\n\r\n# Or explicit credentials\r\nconnection = TursoConnection(\r\n database_url=\"your_database_url\",\r\n auth_token=\"your_auth_token\"\r\n)\r\n```\r\n\r\n### CRUD Operations\r\n\r\n#### Create\r\n\r\n```python\r\ncrud = TursoCRUD(connection)\r\n\r\n# Single insert\r\nuser_data = {\r\n \"name\": \"Jane Smith\",\r\n \"email\": \"jane@example.com\",\r\n \"age\": 25\r\n}\r\ncrud.create(\"users\", user_data)\r\n```\r\n\r\n#### Read\r\n\r\n```python\r\n# Fetch all records\r\nall_users = crud.read(\"users\")\r\n\r\n# Fetch with conditions\r\nyoung_users = crud.read(\r\n table=\"users\",\r\n where=\"age < ?\",\r\n args=[{\"type\": \"integer\", \"value\": \"30\"}]\r\n)\r\n```\r\n\r\n#### Update\r\n\r\n```python\r\nupdate_data = {\"age\": 31}\r\ncrud.update(\r\n table=\"users\",\r\n data=update_data,\r\n where=\"name = ?\",\r\n args=[{\"type\": \"text\", \"value\": \"Jane Smith\"}]\r\n)\r\n```\r\n\r\n#### Delete\r\n\r\n```python\r\ncrud.delete(\r\n table=\"users\",\r\n where=\"name = ?\",\r\n args=[{\"type\": \"text\", \"value\": \"Jane Smith\"}]\r\n)\r\n```\r\n\r\n### Batch Operations\r\n\r\nFor bulk operations, use the `TursoBatch` class:\r\n\r\n```python\r\nfrom turso_python.batch import TursoBatch\r\n\r\nbatch = TursoBatch(connection)\r\n\r\nusers = [\r\n {\"name\": \"User 1\", \"age\": 25},\r\n {\"name\": \"User 2\", \"age\": 30},\r\n {\"name\": \"User 3\", \"age\": 35}\r\n]\r\n\r\nbatch.batch_insert(\"users\", users)\r\n```\r\n\r\n### Advanced Queries\r\n\r\nThe `TursoAdvancedQueries` class handles complex operations:\r\n\r\n```python\r\nfrom turso_python.advanced_queries import TursoAdvancedQueries\r\n\r\nadvanced = TursoAdvancedQueries(connection)\r\n\r\n# Perform a JOIN operation\r\nresult = advanced.join_query(\r\n base_table=\"users\",\r\n join_table=\"orders\",\r\n join_condition=\"users.id = orders.user_id\",\r\n select_columns=\"users.name, orders.order_date\",\r\n where=\"orders.amount > 100\"\r\n)\r\n```\r\n\r\n### Schema Management\r\n\r\nThe `TursoSchemaManager` helps with table operations:\r\n\r\n```python\r\nfrom turso_python.crud import TursoSchemaManager\r\n\r\nschema_manager = TursoSchemaManager(connection)\r\n\r\n# Create a new table\r\nschema = {\r\n \"id\": \"INTEGER PRIMARY KEY\",\r\n \"name\": \"TEXT NOT NULL\",\r\n \"email\": \"TEXT UNIQUE\",\r\n \"created_at\": \"TIMESTAMP DEFAULT CURRENT_TIMESTAMP\"\r\n}\r\nschema_manager.create_table(\"users\", schema)\r\n\r\n# Drop a table\r\nschema_manager.drop_table(\"old_table\")\r\n```\r\n\r\n### Database Creation\r\n\r\n```python\r\nfrom turso_python.crud import TursoClient\r\n\r\nclient = TursoClient()\r\n\r\n# Create a new database\r\nclient.create_database(\r\n org_name=\"your_org\",\r\n db_name=\"new_database\",\r\n group_name=\"default\",\r\n api_token=\"your_api_token\"\r\n)\r\n```\r\n\r\n## Error Handling\r\n\r\nTursoPy includes basic error handling for common scenarios:\r\n\r\n```python\r\ntry:\r\n result = crud.read(\"non_existent_table\")\r\nexcept Exception as e:\r\n print(f\"An error occurred: {e}\")\r\n```\r\n\r\n## Best Practices\r\n\r\n1. Always use environment variables for sensitive credentials\r\n2. Use batch operations for bulk inserts/updates\r\n3. Close connections when done (handled automatically in most cases)\r\n4. Use proper type hints in query arguments\r\n5. Handle errors appropriately in production code\r\n\r\n## Contributing\r\n\r\nContributions are welcome! As a solo developer project, I appreciate any help in improving TursoPy. Please feel free to:\r\n\r\n- Report bugs\r\n- Suggest features\r\n- Submit pull requests\r\n- Improve documentation\r\n\r\n## License\r\n\r\nApache 2.0 License\r\n\r\n## Support\r\n\r\nFor issues, questions, or suggestions, please open an issue on GitHub. As a solo developer, I'll do my best to respond in a timely manner.\r\n\r\n---\r\n\r\nRemember: TursoPy is designed to be simple and straightforward. While it might not have all the bells and whistles of other clients, it focuses on reliability and ease of use. Sometimes, simpler is better!\r\n\r\n**Note for 2024-11-24, I literally built this yesterday so I'm still tweaking some stuff and fixing some stuff**\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Turso ORM for Python",
"version": "1.6",
"project_urls": {
"Homepage": "https://github.com/Marcus-Peterson/tursopy",
"Issues": "https://github.com/Marcus-Peterson/tursopy/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ec569cfe684f587be13b1633ad12bcada10a7d1254c3b99478f5a2fd01e5876f",
"md5": "32a3eb8c790551d22a8c6a129712f1a9",
"sha256": "ac15df864f0f874d597e00354855abe635209c7541f799d7a649b72f98f382ee"
},
"downloads": -1,
"filename": "turso_python-1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32a3eb8c790551d22a8c6a129712f1a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 14578,
"upload_time": "2024-11-25T16:28:44",
"upload_time_iso_8601": "2024-11-25T16:28:44.590780Z",
"url": "https://files.pythonhosted.org/packages/ec/56/9cfe684f587be13b1633ad12bcada10a7d1254c3b99478f5a2fd01e5876f/turso_python-1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a50df0019f99f422bbc1e9db8822c6603c40235250908b5d6f2ca1bd322dd89",
"md5": "715a0bd13fdfe447c73af8ffa1d5aa23",
"sha256": "173cce4456a2b22f1ab6a4aaf8b3f92a9f5beccefabb03a3747201cdbe05421e"
},
"downloads": -1,
"filename": "turso_python-1.6.tar.gz",
"has_sig": false,
"md5_digest": "715a0bd13fdfe447c73af8ffa1d5aa23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 14789,
"upload_time": "2024-11-25T16:28:45",
"upload_time_iso_8601": "2024-11-25T16:28:45.628807Z",
"url": "https://files.pythonhosted.org/packages/6a/50/df0019f99f422bbc1e9db8822c6603c40235250908b5d6f2ca1bd322dd89/turso_python-1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 16:28:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "marcus-peterson",
"github_project": "tursopy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "turso-python"
}
JSON
