# WoosCloud Storage - Python Client
Simple, powerful, and scalable cloud storage for Python applications.
## 🚀 Features
- **Simple API** - Store and retrieve data with just a few lines of code
- **Type Safe** - Full type hints support
- **Fast** - Optimized for performance
- **Secure** - API key authentication
- **Free Tier** - 500MB storage + 10,000 API calls/month
## 📦 Installation
```bash
pip install wooscloud
```
## 🔑 Get Your API Key
1. Sign up at [woos-ai.com](https://woos-ai.com)
2. Create an API key from your dashboard
3. Copy your API key (starts with `wai_`)
## 🎯 Quick Start
```python
from wooscloud import WoosStorage
# Initialize with your API key
storage = WoosStorage(api_key="wai_your_api_key_here")
# Save data
data_id = storage.save("users", {
"name": "John Doe",
"email": "john@example.com",
"age": 30
})
print(f"Saved with ID: {data_id}")
# Find data
users = storage.find("users")
for user in users:
print(user.data)
# Find by ID
user = storage.find_one(data_id)
print(user.data)
# Update data
storage.update(data_id, {
"name": "John Doe",
"email": "john@example.com",
"age": 31 # Updated age
})
# Delete data
storage.delete(data_id)
# Get statistics
stats = storage.stats()
print(f"Storage used: {stats.storage_used_mb} MB")
print(f"API calls: {stats.api_calls_count}")
```
## 📚 Examples
### E-commerce Product Management
```python
from wooscloud import WoosStorage
storage = WoosStorage(api_key="wai_your_api_key")
# Add products
laptop_id = storage.save("products", {
"name": "MacBook Pro M3",
"price": 2500000,
"category": "laptop",
"stock": 15
})
phone_id = storage.save("products", {
"name": "iPhone 15 Pro",
"price": 1550000,
"category": "smartphone",
"stock": 30
})
# Get all products
products = storage.find("products")
print(f"Total products: {len(products)}")
# Get product count
count = storage.count("products")
print(f"Product count: {count}")
```
### User Profile Management
```python
from wooscloud import WoosStorage
storage = WoosStorage(api_key="wai_your_api_key")
# Create user profile
user_id = storage.save("users", {
"username": "john_doe",
"email": "john@example.com",
"profile": {
"age": 30,
"city": "Seoul",
"interests": ["technology", "reading", "travel"]
}
})
# Update profile
storage.update(user_id, {
"username": "john_doe",
"email": "john@example.com",
"profile": {
"age": 31, # Birthday!
"city": "Seoul",
"interests": ["technology", "reading", "travel", "photography"]
}
})
```
### Blog System
```python
from wooscloud import WoosStorage
from datetime import datetime
storage = WoosStorage(api_key="wai_your_api_key")
# Create blog post
post_id = storage.save("posts", {
"title": "Getting Started with WoosCloud",
"content": "WoosCloud is a simple cloud storage...",
"author": "John Doe",
"tags": ["cloud", "storage", "tutorial"],
"published_at": datetime.now().isoformat()
})
# Get all posts
posts = storage.find("posts", limit=10)
for post in posts:
print(f"Title: {post.data['title']}")
print(f"Author: {post.data['author']}")
```
## 🔧 API Reference
### WoosStorage
Main class for interacting with WoosCloud Storage.
#### `__init__(api_key: str, base_url: str = "https://wooscloud.up.railway.app")`
Initialize WoosStorage client.
**Parameters:**
- `api_key` (str): Your WoosCloud API key
- `base_url` (str, optional): API base URL
#### `save(collection: str, data: Dict[str, Any]) -> str`
Save data to a collection.
**Parameters:**
- `collection` (str): Collection name
- `data` (dict): Data to save
**Returns:**
- str: Data ID
#### `find(collection: str, limit: int = 100, skip: int = 0) -> List[StorageData]`
Find data in a collection.
**Parameters:**
- `collection` (str): Collection name
- `limit` (int): Maximum results (1-1000)
- `skip` (int): Number to skip (pagination)
**Returns:**
- List[StorageData]: List of data objects
#### `find_one(data_id: str) -> StorageData`
Find data by ID.
**Parameters:**
- `data_id` (str): Data ID
**Returns:**
- StorageData: Data object
#### `update(data_id: str, data: Dict[str, Any]) -> bool`
Update data by ID.
**Parameters:**
- `data_id` (str): Data ID
- `data` (dict): New data
**Returns:**
- bool: True if successful
#### `delete(data_id: str) -> bool`
Delete data by ID.
**Parameters:**
- `data_id` (str): Data ID
**Returns:**
- bool: True if successful
#### `stats() -> StorageStats`
Get storage usage statistics.
**Returns:**
- StorageStats: Statistics object
#### `collections() -> List[Collection]`
List all collections.
**Returns:**
- List[Collection]: List of collections
#### `count(collection: str) -> int`
Count items in a collection.
**Parameters:**
- `collection` (str): Collection name
**Returns:**
- int: Number of items
## 🛡️ Error Handling
```python
from wooscloud import WoosStorage
from wooscloud import (
AuthenticationError,
QuotaExceededError,
NotFoundError,
ValidationError
)
storage = WoosStorage(api_key="wai_your_api_key")
try:
data = storage.find_one("invalid_id")
except NotFoundError:
print("Data not found")
except AuthenticationError:
print("Invalid API key")
except QuotaExceededError:
print("Storage quota exceeded")
except ValidationError as e:
print(f"Validation error: {e.message}")
```
## 📊 Pricing
### FREE Plan
- **Storage:** 500 MB
- **API Calls:** 10,000/month
- **Price:** $0
### STARTER Plan
- **Storage:** 5 GB
- **API Calls:** Unlimited
- **Price:** $9/month
### PRO Plan
- **Storage:** 50 GB
- **API Calls:** Unlimited
- **Price:** $29/month
## 🔗 Links
- **Website:** [woos-ai.com](https://woos-ai.com)
- **Documentation:** [woos-ai.com/docs](https://woos-ai.com/docs)
- **API Reference:** [woos-ai.com/api](https://woos-ai.com/api)
- **GitHub:** [github.com/wooscloud](https://github.com/wooscloud)
## 📝 License
MIT License - see LICENSE file for details
## 🤝 Support
- Email: support@woos-ai.com
- Discord: [Join our community](https://discord.gg/wooscloud)
- GitHub Issues: [Report bugs](https://github.com/wooscloud/python-client/issues)
## 🌟 Contributing
Contributions are welcome! Please read our contributing guidelines.
---
Made with ❤️ by WoosCloud Team
Raw data
{
"_id": null,
"home_page": "https://github.com/sisi010/wooscloud-storage",
"name": "wooscloud",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cloud storage database api rest wooscloud",
"author": "WoosCloud Team",
"author_email": "support@woos-ai.com",
"download_url": "https://files.pythonhosted.org/packages/63/46/0223693761051ff15f0d5f22788357e59ce26b34ccd53219aea38e865525/wooscloud-1.0.0.tar.gz",
"platform": null,
"description": "# WoosCloud Storage - Python Client\r\n\r\nSimple, powerful, and scalable cloud storage for Python applications.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Simple API** - Store and retrieve data with just a few lines of code\r\n- **Type Safe** - Full type hints support\r\n- **Fast** - Optimized for performance\r\n- **Secure** - API key authentication\r\n- **Free Tier** - 500MB storage + 10,000 API calls/month\r\n\r\n## \ud83d\udce6 Installation\r\n```bash\r\npip install wooscloud\r\n```\r\n\r\n## \ud83d\udd11 Get Your API Key\r\n\r\n1. Sign up at [woos-ai.com](https://woos-ai.com)\r\n2. Create an API key from your dashboard\r\n3. Copy your API key (starts with `wai_`)\r\n\r\n## \ud83c\udfaf Quick Start\r\n```python\r\nfrom wooscloud import WoosStorage\r\n\r\n# Initialize with your API key\r\nstorage = WoosStorage(api_key=\"wai_your_api_key_here\")\r\n\r\n# Save data\r\ndata_id = storage.save(\"users\", {\r\n \"name\": \"John Doe\",\r\n \"email\": \"john@example.com\",\r\n \"age\": 30\r\n})\r\nprint(f\"Saved with ID: {data_id}\")\r\n\r\n# Find data\r\nusers = storage.find(\"users\")\r\nfor user in users:\r\n print(user.data)\r\n\r\n# Find by ID\r\nuser = storage.find_one(data_id)\r\nprint(user.data)\r\n\r\n# Update data\r\nstorage.update(data_id, {\r\n \"name\": \"John Doe\",\r\n \"email\": \"john@example.com\",\r\n \"age\": 31 # Updated age\r\n})\r\n\r\n# Delete data\r\nstorage.delete(data_id)\r\n\r\n# Get statistics\r\nstats = storage.stats()\r\nprint(f\"Storage used: {stats.storage_used_mb} MB\")\r\nprint(f\"API calls: {stats.api_calls_count}\")\r\n```\r\n\r\n## \ud83d\udcda Examples\r\n\r\n### E-commerce Product Management\r\n```python\r\nfrom wooscloud import WoosStorage\r\n\r\nstorage = WoosStorage(api_key=\"wai_your_api_key\")\r\n\r\n# Add products\r\nlaptop_id = storage.save(\"products\", {\r\n \"name\": \"MacBook Pro M3\",\r\n \"price\": 2500000,\r\n \"category\": \"laptop\",\r\n \"stock\": 15\r\n})\r\n\r\nphone_id = storage.save(\"products\", {\r\n \"name\": \"iPhone 15 Pro\",\r\n \"price\": 1550000,\r\n \"category\": \"smartphone\",\r\n \"stock\": 30\r\n})\r\n\r\n# Get all products\r\nproducts = storage.find(\"products\")\r\nprint(f\"Total products: {len(products)}\")\r\n\r\n# Get product count\r\ncount = storage.count(\"products\")\r\nprint(f\"Product count: {count}\")\r\n```\r\n\r\n### User Profile Management\r\n```python\r\nfrom wooscloud import WoosStorage\r\n\r\nstorage = WoosStorage(api_key=\"wai_your_api_key\")\r\n\r\n# Create user profile\r\nuser_id = storage.save(\"users\", {\r\n \"username\": \"john_doe\",\r\n \"email\": \"john@example.com\",\r\n \"profile\": {\r\n \"age\": 30,\r\n \"city\": \"Seoul\",\r\n \"interests\": [\"technology\", \"reading\", \"travel\"]\r\n }\r\n})\r\n\r\n# Update profile\r\nstorage.update(user_id, {\r\n \"username\": \"john_doe\",\r\n \"email\": \"john@example.com\",\r\n \"profile\": {\r\n \"age\": 31, # Birthday!\r\n \"city\": \"Seoul\",\r\n \"interests\": [\"technology\", \"reading\", \"travel\", \"photography\"]\r\n }\r\n})\r\n```\r\n\r\n### Blog System\r\n```python\r\nfrom wooscloud import WoosStorage\r\nfrom datetime import datetime\r\n\r\nstorage = WoosStorage(api_key=\"wai_your_api_key\")\r\n\r\n# Create blog post\r\npost_id = storage.save(\"posts\", {\r\n \"title\": \"Getting Started with WoosCloud\",\r\n \"content\": \"WoosCloud is a simple cloud storage...\",\r\n \"author\": \"John Doe\",\r\n \"tags\": [\"cloud\", \"storage\", \"tutorial\"],\r\n \"published_at\": datetime.now().isoformat()\r\n})\r\n\r\n# Get all posts\r\nposts = storage.find(\"posts\", limit=10)\r\nfor post in posts:\r\n print(f\"Title: {post.data['title']}\")\r\n print(f\"Author: {post.data['author']}\")\r\n```\r\n\r\n## \ud83d\udd27 API Reference\r\n\r\n### WoosStorage\r\n\r\nMain class for interacting with WoosCloud Storage.\r\n\r\n#### `__init__(api_key: str, base_url: str = \"https://wooscloud.up.railway.app\")`\r\n\r\nInitialize WoosStorage client.\r\n\r\n**Parameters:**\r\n- `api_key` (str): Your WoosCloud API key\r\n- `base_url` (str, optional): API base URL\r\n\r\n#### `save(collection: str, data: Dict[str, Any]) -> str`\r\n\r\nSave data to a collection.\r\n\r\n**Parameters:**\r\n- `collection` (str): Collection name\r\n- `data` (dict): Data to save\r\n\r\n**Returns:**\r\n- str: Data ID\r\n\r\n#### `find(collection: str, limit: int = 100, skip: int = 0) -> List[StorageData]`\r\n\r\nFind data in a collection.\r\n\r\n**Parameters:**\r\n- `collection` (str): Collection name\r\n- `limit` (int): Maximum results (1-1000)\r\n- `skip` (int): Number to skip (pagination)\r\n\r\n**Returns:**\r\n- List[StorageData]: List of data objects\r\n\r\n#### `find_one(data_id: str) -> StorageData`\r\n\r\nFind data by ID.\r\n\r\n**Parameters:**\r\n- `data_id` (str): Data ID\r\n\r\n**Returns:**\r\n- StorageData: Data object\r\n\r\n#### `update(data_id: str, data: Dict[str, Any]) -> bool`\r\n\r\nUpdate data by ID.\r\n\r\n**Parameters:**\r\n- `data_id` (str): Data ID\r\n- `data` (dict): New data\r\n\r\n**Returns:**\r\n- bool: True if successful\r\n\r\n#### `delete(data_id: str) -> bool`\r\n\r\nDelete data by ID.\r\n\r\n**Parameters:**\r\n- `data_id` (str): Data ID\r\n\r\n**Returns:**\r\n- bool: True if successful\r\n\r\n#### `stats() -> StorageStats`\r\n\r\nGet storage usage statistics.\r\n\r\n**Returns:**\r\n- StorageStats: Statistics object\r\n\r\n#### `collections() -> List[Collection]`\r\n\r\nList all collections.\r\n\r\n**Returns:**\r\n- List[Collection]: List of collections\r\n\r\n#### `count(collection: str) -> int`\r\n\r\nCount items in a collection.\r\n\r\n**Parameters:**\r\n- `collection` (str): Collection name\r\n\r\n**Returns:**\r\n- int: Number of items\r\n\r\n## \ud83d\udee1\ufe0f Error Handling\r\n```python\r\nfrom wooscloud import WoosStorage\r\nfrom wooscloud import (\r\n AuthenticationError,\r\n QuotaExceededError,\r\n NotFoundError,\r\n ValidationError\r\n)\r\n\r\nstorage = WoosStorage(api_key=\"wai_your_api_key\")\r\n\r\ntry:\r\n data = storage.find_one(\"invalid_id\")\r\nexcept NotFoundError:\r\n print(\"Data not found\")\r\nexcept AuthenticationError:\r\n print(\"Invalid API key\")\r\nexcept QuotaExceededError:\r\n print(\"Storage quota exceeded\")\r\nexcept ValidationError as e:\r\n print(f\"Validation error: {e.message}\")\r\n```\r\n\r\n## \ud83d\udcca Pricing\r\n\r\n### FREE Plan\r\n- **Storage:** 500 MB\r\n- **API Calls:** 10,000/month\r\n- **Price:** $0\r\n\r\n### STARTER Plan\r\n- **Storage:** 5 GB\r\n- **API Calls:** Unlimited\r\n- **Price:** $9/month\r\n\r\n### PRO Plan\r\n- **Storage:** 50 GB\r\n- **API Calls:** Unlimited\r\n- **Price:** $29/month\r\n\r\n## \ud83d\udd17 Links\r\n\r\n- **Website:** [woos-ai.com](https://woos-ai.com)\r\n- **Documentation:** [woos-ai.com/docs](https://woos-ai.com/docs)\r\n- **API Reference:** [woos-ai.com/api](https://woos-ai.com/api)\r\n- **GitHub:** [github.com/wooscloud](https://github.com/wooscloud)\r\n\r\n## \ud83d\udcdd License\r\n\r\nMIT License - see LICENSE file for details\r\n\r\n## \ud83e\udd1d Support\r\n\r\n- Email: support@woos-ai.com\r\n- Discord: [Join our community](https://discord.gg/wooscloud)\r\n- GitHub Issues: [Report bugs](https://github.com/wooscloud/python-client/issues)\r\n\r\n## \ud83c\udf1f Contributing\r\n\r\nContributions are welcome! Please read our contributing guidelines.\r\n\r\n---\r\n\r\nMade with \u2764\ufe0f by WoosCloud Team\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Simple, powerful, and scalable cloud storage for Python applications",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/sisi010/wooscloud-storage/issues",
"Documentation": "https://wooscloud-storage-production.up.railway.app/api/docs",
"Homepage": "https://github.com/sisi010/wooscloud-storage",
"Source": "https://github.com/sisi010/wooscloud-storage"
},
"split_keywords": [
"cloud",
"storage",
"database",
"api",
"rest",
"wooscloud"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5df94288ac49de9b2e4c00c193f06ee9e25ad8f6831e35d9feaf73caf2d91b52",
"md5": "3053979adb9ccc2596fe0ba57353527b",
"sha256": "e078b1f7edc3822b4afc059ce264e2628a6a2d4adef40340d074b45e5f731813"
},
"downloads": -1,
"filename": "wooscloud-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3053979adb9ccc2596fe0ba57353527b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8428,
"upload_time": "2025-10-30T06:02:13",
"upload_time_iso_8601": "2025-10-30T06:02:13.479660Z",
"url": "https://files.pythonhosted.org/packages/5d/f9/4288ac49de9b2e4c00c193f06ee9e25ad8f6831e35d9feaf73caf2d91b52/wooscloud-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "63460223693761051ff15f0d5f22788357e59ce26b34ccd53219aea38e865525",
"md5": "9942a3576f8032186186fc3bdc042ab0",
"sha256": "fa06b82636d5f06cd29764627537e49c2f0551f7de8f6cd2d39d337cc3aa3877"
},
"downloads": -1,
"filename": "wooscloud-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "9942a3576f8032186186fc3bdc042ab0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9077,
"upload_time": "2025-10-30T06:02:14",
"upload_time_iso_8601": "2025-10-30T06:02:14.731042Z",
"url": "https://files.pythonhosted.org/packages/63/46/0223693761051ff15f0d5f22788357e59ce26b34ccd53219aea38e865525/wooscloud-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 06:02:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sisi010",
"github_project": "wooscloud-storage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wooscloud"
}
JSON
