SheetSandbox SDK for Python

A simple and easy-to-understand Python SDK for SheetSandbox - Turn Google Sheets into your production-ready database.

🎯 Features

• ✅ Simple & Clean - Easy to understand code without complex parts
• ✅ Basic CRUD Operations - Get, GetById, Post, and Token Verification
• ✅ Pythonic API - Follows Python conventions and best practices
• ✅ Lightweight - Minimal dependencies
• ✅ Ready to Extend - Clean architecture for future enhancements

📦 Installation

pip install sheetsandbox

🚀 Quick Start

from sheetsandbox import SheetSandbox

# Initialize the client
client = SheetSandbox('your-api-token')

# Verify your token
result = client.verify_token()
print(result)

# Create a record
result = client.post('UserFeedback', {
    'Subject': 'John Doe',
    'Message': 'john@example.com',
    'type': 'active'
})

# Get all records
result = client.get('UserFeedback')

# Get a specific record
result = client.get_by_id('UserFeedback', 1)

📖 API Reference

Constructor

client = SheetSandbox(token, base_url=None, timeout=30)

Parameters:

• token (str, required) - Your SheetSandbox API token
• base_url (str, optional) - API base URL (default: 'http://localhost:3001/api')
• timeout (int, optional) - Request timeout in seconds (default: 30)

Methods

verify_token()

Verify if your API token is valid.

result = client.verify_token()

if result['success']:
    print("Token is valid!")
else:
    print(f"Error: {result['error']}")

Returns: dict

• success (bool) - Operation status
• data (dict) - Verification response data
• status (str) - 'success' or 'error'
• error (str) - Error message (if failed)

---

get(table_name)

Get all records from a table.

result = client.get('UserFeedback')

if result['success']:
    for record in result['data']:
        print(record)

Returns: dict

• success (bool) - Operation status
• data (list) - Array of records
• status (str) - 'success' or 'error'
• error (str) - Error message (if failed)

---

get_by_id(table_name, record_id)

Get a specific record by ID.

result = client.get_by_id('UserFeedback', 1)

if result['success']:
    print(result['data'])  # Single record

Parameters:

• table_name (str) - Name of the table
• record_id (int|str) - Record ID (1-based index)

Returns: dict

• success (bool) - Operation status
• data (dict) - Record data
• status (str) - 'success' or 'error'
• error (str) - Error message (if failed)

---

post(table_name, data)

Create a new record.

result = client.post('UserFeedback', {
    'Subject': 'Feature Request',
    'Message': 'Add dark mode support',
    'type': 'feature'
})

if result['success']:
    print('Record created!')

Parameters:

• table_name (str) - Name of the table
• data (dict) - Record data to create

Returns: dict

• success (bool) - Operation status
• data (dict) - Created record data
• status (str) - 'success' or 'error'
• error (str) - Error message (if failed)

---

set_token(new_token)

Update the API token.

client.set_token('new-api-token')

---

set_base_url(new_base_url)

Update the base URL.

client.set_base_url('https://api.sheetsandbox.com')

---

get_config()

Get current configuration.

config = client.get_config()
print(config)
# {'base_url': '...', 'timeout': 30, 'has_token': True}

💡 Examples

Waitlist Signup

from sheetsandbox import SheetSandbox
from datetime import datetime

client = SheetSandbox('your-api-token')

def add_to_waitlist(email, name):
    result = client.post('Waitlist', {
        'email': email,
        'name': name,
        'timestamp': datetime.now().isoformat()
    })
    
    if result['success']:
        print('✅ Added to waitlist!')
    else:
        print(f"❌ Error: {result['error']}")

add_to_waitlist('user@example.com', 'Jane Doe')

Feedback Form

def submit_feedback(feedback):
    result = client.post('Feedback', {
        'message': feedback['message'],
        'rating': feedback['rating'],
        'email': feedback['email'],
        'submitted_at': datetime.now().isoformat()
    })
    
    return result['success']

# Usage
feedback_data = {
    'message': 'Great product!',
    'rating': 5,
    'email': 'happy@customer.com'
}

if submit_feedback(feedback_data):
    print('Feedback submitted successfully!')

Get User Feedback List

def get_feedback_list():
    result = client.get('UserFeedback')
    
    if result['success']:
        for feedback in result['data']:
            print(f"{feedback['Subject']} - {feedback['Message']}")
    else:
        print(f"Error: {result['error']}")

get_feedback_list()

Token Verification

def check_token():
    result = client.verify_token()
    
    if result['success']:
        print('✅ Token is valid and working!')
        print(f"API Response: {result['data']}")
    else:
        print(f"❌ Token verification failed: {result['error']}")

check_token()

Complete CRUD Example

from sheetsandbox import SheetSandbox

client = SheetSandbox('your-api-token')

# Verify token first
if not client.verify_token()['success']:
    print("Invalid token!")
    exit()

# Create a new user
new_user = client.post('Users', {
    'name': 'Alice Johnson',
    'email': 'alice@example.com',
    'role': 'developer'
})

if new_user['success']:
    print(f"Created user: {new_user['data']}")

# Get all users
all_users = client.get('Users')
if all_users['success']:
    print(f"Total users: {len(all_users['data'])}")

# Get specific user
user = client.get_by_id('Users', 1)
if user['success']:
    print(f"First user: {user['data']}")

🔧 Error Handling

All methods return a consistent response format:

result = client.get('Users')

if result['success']:
    # Operation succeeded
    print(result['data'])
else:
    # Operation failed
    print(result['error'])

Exception Handling

try:
    result = client.post('Users', {
        'name': 'Test User',
        'email': 'test@example.com'
    })
    
    if result['success']:
        print('Success!')
    else:
        print(f"API Error: {result['error']}")
        
except Exception as e:
    print(f"Unexpected error: {str(e)}")

🛣️ Roadmap

This is a simplified version designed to be easy to understand and extend. Future enhancements may include:

• Async/await support with asyncio
• Batch operations (create multiple records at once)
• Advanced filtering and sorting
• Duplicate prevention
• Update and delete operations
• Pagination support
• Retry logic with exponential backoff
• Type hints and better IDE support
• Data validation

📝 License

MIT

🔗 Links

• Website
• Documentation
• GitHub
• PyPI Package

💬 Support

For issues and questions, please visit our GitHub Issues.

🐍 Python Version Support

• Python 3.7+
• Tested on Python 3.8, 3.9, 3.10, 3.11, and 3.12

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request