| Name | sas-cosmosdb JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | A comprehensive Python library for working with Azure Cosmos DB using both MongoDB and SQL APIs |
| upload_time | 2025-07-17 00:35:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
azure
cosmosdb
mongodb
sql
database
sas
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CosmosDB Helper for Python
## Overview
This repository provides a **comprehensive Python library** for working with Azure Cosmos DB using both MongoDB and SQL APIs. Built with enterprise-grade architecture and modern Python best practices, this library offers a unified, type-safe interface that simplifies database operations while maintaining optimal performance and scalability.
### **๐ฏ What This Library Solves**
**Azure Cosmos DB Complexity**: While Azure Cosmos DB is incredibly powerful, it can be complex to work with effectively. Developers often struggle with:
- Managing different API patterns (SQL vs MongoDB)
- Writing optimal queries and handling partition keys correctly
- Implementing proper error handling and retry logic
- Maintaining type safety across database operations
- Following enterprise patterns for scalable applications
**This library eliminates these challenges** by providing a clean, intuitive abstraction layer that handles the complexity behind the scenes while giving you full control when needed.
### **๐ข Enterprise-Grade Solution**
This isn't just another database wrapper - it's an **enterprise-grade solution** designed for production applications:
- โ
**Type-Safe Architecture** - Full Pydantic validation with compile-time error detection
- โ
**Performance Optimized** - Automatic partition key handling and connection pooling
- โ
**Enterprise Patterns** - Repository pattern, Domain-Driven Design, async/await architecture
- โ
**Comprehensive Testing** - Extensive test suite with 63+ test scenarios
- โ
**Cosmos DB Best Practices** - Follows Microsoft's recommended patterns and optimizations
- โ
**Security First** - Built-in support for Azure AD authentication (SQL API)
### **๐ฅ Who This Library Is For**
- **Enterprise Developers** building scalable applications that need reliable database operations with minimal boilerplate code
- **Data Engineers** who want type-safe database interactions without sacrificing the flexibility to write complex queries when needed
- **DevOps Teams** seeking standardized database patterns that work consistently across different Cosmos DB API types
- **Python Developers** who value clean architecture, comprehensive type hints, and developer experience with full IDE support
### **โญ Key Features**
- **๏ฟฝ Dual API Support**: Seamlessly switch between MongoDB and SQL APIs or use both simultaneously
- **๐ฏ Zero SQL Knowledge Required**: Use intuitive Python dictionaries for 90% of your queries
- **โก Smart Query Optimization**: Automatic predicate-to-SQL conversion with partition key optimization
- **๐ Automatic Partition Key Management**: Intelligent handling for both data distribution and query optimization (SQL API)
- **๐ก๏ธ Comprehensive Error Handling**: Built-in retry logic, connection resilience, and detailed error reporting
- **๏ฟฝ Developer Experience First**: Full IntelliSense, type checking, and extensive documentation
*The library is packaged under the `sas` namespace and provides a unified interface for database operations.*
## ๐ Quick Start
๏ฟฝ๐ง **Ready to start coding?** Check out the [**Hands-On Guide**](HANDS_ON_GUIDE.md) for step-by-step instructions, real code examples, and practical tutorials.
๐ **Need detailed API documentation?** Choose your API:
- **[API Overview](API_REFERENCE.md)** - Quick comparison and getting started guide
- **[SQL API Reference](API_REFERENCE_SQL.md)** - Complete documentation for SQL (Core) API
- **[MongoDB API Reference](API_REFERENCE_MONGO.md)** - Complete documentation for MongoDB API
## ๐๏ธ Architecture Overview
This library implements the **Repository Pattern**, a proven architectural approach that separates data access logic from business logic, making your applications more maintainable, testable, and scalable.
### **Core Components**
- **๐ Entities** - Domain objects that represent your data models with business logic and validation
- **๐ Repositories** - Data access objects that handle CRUD operations and queries
- **๐ Unified Interface** - Consistent patterns that work across both MongoDB and SQL APIs
### **Repository Pattern Benefits**
- **๐๏ธ Separation of Concerns** - Business logic stays in entities, data access logic in repositories
- **๐ Database Agnostic** - Switch between SQL/MongoDB APIs without changing business logic
- **๐งช Testability** - Mock repositories easily for comprehensive unit testing
- **๐ก๏ธ Type Safety** - Full Pydantic validation and type hints throughout the entire stack
- **โก Performance** - Optimized queries and intelligent partition key handling
- **๐ Consistency** - Standardized patterns across all data operations
## ๐จ Essential: Type Variable Usage
**Critical Rule for All Entity Classes:**
Every `RootEntityBase` class **MUST** be defined with type variables:
```python
# โ
CORRECT - Always specify both entity type and key type
class Customer(RootEntityBase["Customer", str]): pass
# โ WRONG - Missing type variables
class Customer(RootEntityBase): pass
```
**Why This Pattern Is Essential:**
- **๐ฏ Type Safety** - Enables compile-time error checking and IDE autocompletion
- **๏ฟฝ Repository Integration** - Allows the repository to know exactly what entity type it manages
- **โก Performance** - Enables runtime optimizations and early error detection
- **๐ก๏ธ Production Reliability** - Prevents type-related bugs before deployment
**The Pattern:** `RootEntityBase["EntityClassName", KeyType]`
This leverages [Python Generics](https://typing.python.org/en/latest/reference/generics.html) to provide type safety throughout your application.
## ๐ก Simple Example
Here's how easy it is to get started:
```python
from sas.cosmosdb.sql import RootEntityBase, RepositoryBase
from typing import Optional
# 1. Define your entity
class Customer(RootEntityBase["Customer", str]):
name: str
email: str
is_active: bool = True
# 2. Create a repository
class CustomerRepository(RepositoryBase[Customer, str]):
def __init__(self, connection_string: str, database_name: str):
super().__init__(
connection_string=connection_string,
database_name=database_name,
container_name="customers"
)
# 3. Use it in your application
async def main():
repo = CustomerRepository("your-connection-string", "mydb")
async with repo:
# Create and save a customer
customer = Customer(
id="cust-001",
name="John Doe",
email="john@example.com"
)
await repo.add_async(customer)
# Find customers with simple predicates
active_customers = await repo.find_async({"is_active": True})
# Get a specific customer
found = await repo.get_async("cust-001")
```
## ๐ Query Operations
The library eliminates the need to write complex SQL queries for most database operations. Instead, use intuitive Python dictionaries and let the library handle query optimization automatically.
### **Simple Predicate Queries**
```python
# Simple field matching - no SQL required
customers = await repo.find_async({"name": "John Doe"})
# Range queries with operators
young_adults = await repo.find_async({"age": {"$gte": 18, "$lt": 30}})
# Multiple conditions
active_customers = await repo.find_async({
"is_active": True,
"registration_date": {"$gte": "2024-01-01"}
})
# Nested field queries
seattle_customers = await repo.find_async({
"address.city": "Seattle",
"address.state": "WA"
})
# Array operations
tagged_customers = await repo.find_async({
"tags": {"$in": ["premium", "vip"]}
})
```
### **Supported Query Operators**
The library provides intuitive operators that work across both APIs:
```python
# Comparison operators (Both APIs)
{"age": {"$gt": 25}} # Greater than
{"age": {"$gte": 25}} # Greater than or equal
{"age": {"$lt": 65}} # Less than
{"age": {"$lte": 65}} # Less than or equal
{"status": {"$ne": "inactive"}} # Not equal
# Array and inclusion operators
{"category": {"$in": ["A", "B", "C"]}} # Value in list (Both APIs)
{"tags": {"$nin": ["deprecated", "old"]}} # Value not in list (MongoDB only)
# Text operations
{"name": {"$regex": ".*John.*"}} # Pattern matching (MongoDB)
{"name": {"$contains": "John"}} # Substring matching (SQL API)
{"phone": {"$exists": True}} # Field exists (MongoDB only)
```
### **Raw SQL for Complex Operations**
When you need complex aggregations or joins, drop down to raw SQL:
```python
class CustomerRepository(RepositoryBase[Customer, str]):
async def get_customer_statistics(self) -> List[dict]:
"""Complex analytics using raw SQL"""
query = """
SELECT
c.address.region as region,
COUNT(*) as total_customers,
AVG(c.age) as average_age
FROM customers c
WHERE c.is_active = true
GROUP BY c.address.region
"""
return await self.query_raw_dynamic_cursor_async(query)
```
### **Type-Safe Operations**
All operations are fully type-safe with IDE support:
```python
# Type-safe entity creation with validation
customer = Customer(
name="John Smith", # String - validated
age=35, # Integer - validated
email="john@example.com", # Email format - validated
is_active=True # Boolean - type-checked
)
# Type-safe repository operations with return type hints
await repo.add_async(customer) # Returns: None
found = await repo.get_async("cust-123") # Returns: Customer | None
all_active = await repo.find_async({ # Returns: List[Customer]
"is_active": True
})
```
*Ready to dive deeper? Check out the [**Hands-On Guide**](HANDS_ON_GUIDE.md) for complete tutorials and the [**API References**](API_REFERENCE.md) for detailed documentation.*
Raw data
{
"_id": null,
"home_page": null,
"name": "sas-cosmosdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "azure, cosmosdb, mongodb, sql, database, sas",
"author": null,
"author_email": "DB Lee <db.lee@microsoft.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/74/d4ea92bf3dec9544e17145cab876784d9fa3de81acbcc8c6e1a047f393ba/sas_cosmosdb-0.1.4.tar.gz",
"platform": null,
"description": "# CosmosDB Helper for Python\n\n## Overview\n\nThis repository provides a **comprehensive Python library** for working with Azure Cosmos DB using both MongoDB and SQL APIs. Built with enterprise-grade architecture and modern Python best practices, this library offers a unified, type-safe interface that simplifies database operations while maintaining optimal performance and scalability.\n\n### **\ud83c\udfaf What This Library Solves**\n\n**Azure Cosmos DB Complexity**: While Azure Cosmos DB is incredibly powerful, it can be complex to work with effectively. Developers often struggle with:\n\n- Managing different API patterns (SQL vs MongoDB)\n- Writing optimal queries and handling partition keys correctly\n- Implementing proper error handling and retry logic\n- Maintaining type safety across database operations\n- Following enterprise patterns for scalable applications\n\n**This library eliminates these challenges** by providing a clean, intuitive abstraction layer that handles the complexity behind the scenes while giving you full control when needed.\n\n### **\ud83c\udfe2 Enterprise-Grade Solution**\n\nThis isn't just another database wrapper - it's an **enterprise-grade solution** designed for production applications:\n\n- \u2705 **Type-Safe Architecture** - Full Pydantic validation with compile-time error detection\n- \u2705 **Performance Optimized** - Automatic partition key handling and connection pooling\n- \u2705 **Enterprise Patterns** - Repository pattern, Domain-Driven Design, async/await architecture\n- \u2705 **Comprehensive Testing** - Extensive test suite with 63+ test scenarios\n- \u2705 **Cosmos DB Best Practices** - Follows Microsoft's recommended patterns and optimizations\n- \u2705 **Security First** - Built-in support for Azure AD authentication (SQL API)\n\n### **\ud83d\udc65 Who This Library Is For**\n\n- **Enterprise Developers** building scalable applications that need reliable database operations with minimal boilerplate code\n- **Data Engineers** who want type-safe database interactions without sacrificing the flexibility to write complex queries when needed \n- **DevOps Teams** seeking standardized database patterns that work consistently across different Cosmos DB API types\n- **Python Developers** who value clean architecture, comprehensive type hints, and developer experience with full IDE support\n\n### **\u2b50 Key Features**\n\n- **\ufffd Dual API Support**: Seamlessly switch between MongoDB and SQL APIs or use both simultaneously\n- **\ud83c\udfaf Zero SQL Knowledge Required**: Use intuitive Python dictionaries for 90% of your queries\n- **\u26a1 Smart Query Optimization**: Automatic predicate-to-SQL conversion with partition key optimization\n- **\ud83d\udd11 Automatic Partition Key Management**: Intelligent handling for both data distribution and query optimization (SQL API)\n- **\ud83d\udee1\ufe0f Comprehensive Error Handling**: Built-in retry logic, connection resilience, and detailed error reporting\n- **\ufffd Developer Experience First**: Full IntelliSense, type checking, and extensive documentation\n\n*The library is packaged under the `sas` namespace and provides a unified interface for database operations.*\n\n## \ud83d\ude80 Quick Start\n\n\ufffd\ud83d\udd27 **Ready to start coding?** Check out the [**Hands-On Guide**](HANDS_ON_GUIDE.md) for step-by-step instructions, real code examples, and practical tutorials.\n\n\ud83d\udcda **Need detailed API documentation?** Choose your API:\n\n- **[API Overview](API_REFERENCE.md)** - Quick comparison and getting started guide\n- **[SQL API Reference](API_REFERENCE_SQL.md)** - Complete documentation for SQL (Core) API\n- **[MongoDB API Reference](API_REFERENCE_MONGO.md)** - Complete documentation for MongoDB API\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\nThis library implements the **Repository Pattern**, a proven architectural approach that separates data access logic from business logic, making your applications more maintainable, testable, and scalable.\n\n### **Core Components**\n\n- **\ud83c\udfe0 Entities** - Domain objects that represent your data models with business logic and validation\n- **\ud83d\udcda Repositories** - Data access objects that handle CRUD operations and queries\n- **\ud83d\udd04 Unified Interface** - Consistent patterns that work across both MongoDB and SQL APIs\n\n### **Repository Pattern Benefits**\n\n- **\ud83c\udfd7\ufe0f Separation of Concerns** - Business logic stays in entities, data access logic in repositories\n- **\ud83d\udd04 Database Agnostic** - Switch between SQL/MongoDB APIs without changing business logic\n- **\ud83e\uddea Testability** - Mock repositories easily for comprehensive unit testing\n- **\ud83d\udee1\ufe0f Type Safety** - Full Pydantic validation and type hints throughout the entire stack\n- **\u26a1 Performance** - Optimized queries and intelligent partition key handling\n- **\ud83d\udcd0 Consistency** - Standardized patterns across all data operations\n\n## \ud83d\udea8 Essential: Type Variable Usage\n\n**Critical Rule for All Entity Classes:**\n\nEvery `RootEntityBase` class **MUST** be defined with type variables:\n\n```python\n# \u2705 CORRECT - Always specify both entity type and key type\nclass Customer(RootEntityBase[\"Customer\", str]): pass\n\n# \u274c WRONG - Missing type variables\nclass Customer(RootEntityBase): pass\n```\n\n**Why This Pattern Is Essential:**\n\n- **\ud83c\udfaf Type Safety** - Enables compile-time error checking and IDE autocompletion\n- **\ufffd Repository Integration** - Allows the repository to know exactly what entity type it manages\n- **\u26a1 Performance** - Enables runtime optimizations and early error detection\n- **\ud83d\udee1\ufe0f Production Reliability** - Prevents type-related bugs before deployment\n\n**The Pattern:** `RootEntityBase[\"EntityClassName\", KeyType]`\n\nThis leverages [Python Generics](https://typing.python.org/en/latest/reference/generics.html) to provide type safety throughout your application.\n\n## \ud83d\udca1 Simple Example\n\nHere's how easy it is to get started:\n\n```python\nfrom sas.cosmosdb.sql import RootEntityBase, RepositoryBase\nfrom typing import Optional\n\n# 1. Define your entity\nclass Customer(RootEntityBase[\"Customer\", str]):\n name: str\n email: str\n is_active: bool = True\n\n# 2. Create a repository\nclass CustomerRepository(RepositoryBase[Customer, str]):\n def __init__(self, connection_string: str, database_name: str):\n super().__init__(\n connection_string=connection_string,\n database_name=database_name,\n container_name=\"customers\"\n )\n\n# 3. Use it in your application\nasync def main():\n repo = CustomerRepository(\"your-connection-string\", \"mydb\")\n \n async with repo:\n # Create and save a customer\n customer = Customer(\n id=\"cust-001\",\n name=\"John Doe\", \n email=\"john@example.com\"\n )\n await repo.add_async(customer)\n \n # Find customers with simple predicates\n active_customers = await repo.find_async({\"is_active\": True})\n \n # Get a specific customer \n found = await repo.get_async(\"cust-001\")\n```\n\n## \ud83d\udd0d Query Operations\n\nThe library eliminates the need to write complex SQL queries for most database operations. Instead, use intuitive Python dictionaries and let the library handle query optimization automatically.\n\n### **Simple Predicate Queries**\n\n```python\n# Simple field matching - no SQL required\ncustomers = await repo.find_async({\"name\": \"John Doe\"})\n\n# Range queries with operators \nyoung_adults = await repo.find_async({\"age\": {\"$gte\": 18, \"$lt\": 30}})\n\n# Multiple conditions\nactive_customers = await repo.find_async({\n \"is_active\": True,\n \"registration_date\": {\"$gte\": \"2024-01-01\"}\n})\n\n# Nested field queries\nseattle_customers = await repo.find_async({\n \"address.city\": \"Seattle\",\n \"address.state\": \"WA\" \n})\n\n# Array operations\ntagged_customers = await repo.find_async({\n \"tags\": {\"$in\": [\"premium\", \"vip\"]}\n})\n```\n\n### **Supported Query Operators**\n\nThe library provides intuitive operators that work across both APIs:\n\n```python\n# Comparison operators (Both APIs)\n{\"age\": {\"$gt\": 25}} # Greater than\n{\"age\": {\"$gte\": 25}} # Greater than or equal\n{\"age\": {\"$lt\": 65}} # Less than\n{\"age\": {\"$lte\": 65}} # Less than or equal\n{\"status\": {\"$ne\": \"inactive\"}} # Not equal\n\n# Array and inclusion operators\n{\"category\": {\"$in\": [\"A\", \"B\", \"C\"]}} # Value in list (Both APIs)\n{\"tags\": {\"$nin\": [\"deprecated\", \"old\"]}} # Value not in list (MongoDB only)\n\n# Text operations\n{\"name\": {\"$regex\": \".*John.*\"}} # Pattern matching (MongoDB)\n{\"name\": {\"$contains\": \"John\"}} # Substring matching (SQL API)\n{\"phone\": {\"$exists\": True}} # Field exists (MongoDB only)\n```\n\n### **Raw SQL for Complex Operations**\n\nWhen you need complex aggregations or joins, drop down to raw SQL:\n\n```python\nclass CustomerRepository(RepositoryBase[Customer, str]):\n \n async def get_customer_statistics(self) -> List[dict]:\n \"\"\"Complex analytics using raw SQL\"\"\"\n query = \"\"\"\n SELECT \n c.address.region as region,\n COUNT(*) as total_customers,\n AVG(c.age) as average_age\n FROM customers c \n WHERE c.is_active = true\n GROUP BY c.address.region\n \"\"\"\n return await self.query_raw_dynamic_cursor_async(query)\n```\n\n### **Type-Safe Operations**\n\nAll operations are fully type-safe with IDE support:\n\n```python\n# Type-safe entity creation with validation\ncustomer = Customer(\n name=\"John Smith\", # String - validated\n age=35, # Integer - validated \n email=\"john@example.com\", # Email format - validated\n is_active=True # Boolean - type-checked\n)\n\n# Type-safe repository operations with return type hints\nawait repo.add_async(customer) # Returns: None\nfound = await repo.get_async(\"cust-123\") # Returns: Customer | None\nall_active = await repo.find_async({ # Returns: List[Customer]\n \"is_active\": True\n})\n```\n\n*Ready to dive deeper? Check out the [**Hands-On Guide**](HANDS_ON_GUIDE.md) for complete tutorials and the [**API References**](API_REFERENCE.md) for detailed documentation.*\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python library for working with Azure Cosmos DB using both MongoDB and SQL APIs",
"version": "0.1.4",
"project_urls": {
"Changelog": "https://github.com/mcaps-microsoft/python_cosmosdb_helper/releases",
"Documentation": "https://github.com/mcaps-microsoft/python_cosmosdb_helper/blob/main/README.md",
"Homepage": "https://github.com/mcaps-microsoft/python_cosmosdb_helper",
"Issues": "https://github.com/mcaps-microsoft/python_cosmosdb_helper/issues",
"Repository": "https://github.com/mcaps-microsoft/python_cosmosdb_helper"
},
"split_keywords": [
"azure",
" cosmosdb",
" mongodb",
" sql",
" database",
" sas"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e06f08c3d3d40cc453afd3d12ec6042c257c4bba379b85202e2be5ebdeab296b",
"md5": "0e30ff5b00a39347c30cd1b7da62a1c4",
"sha256": "e95918494b2cb7774fba059cebbc005adcc7ebae951b252b1b28eac610f11f23"
},
"downloads": -1,
"filename": "sas_cosmosdb-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e30ff5b00a39347c30cd1b7da62a1c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 36683,
"upload_time": "2025-07-17T00:35:40",
"upload_time_iso_8601": "2025-07-17T00:35:40.132440Z",
"url": "https://files.pythonhosted.org/packages/e0/6f/08c3d3d40cc453afd3d12ec6042c257c4bba379b85202e2be5ebdeab296b/sas_cosmosdb-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c374d4ea92bf3dec9544e17145cab876784d9fa3de81acbcc8c6e1a047f393ba",
"md5": "e2124a259c6c89ede2bb20d1f0100830",
"sha256": "0291296cd38e6e957522726ff519c50559c91820c656fe2af4e4ce79bf4f0cc2"
},
"downloads": -1,
"filename": "sas_cosmosdb-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "e2124a259c6c89ede2bb20d1f0100830",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 58058,
"upload_time": "2025-07-17T00:35:43",
"upload_time_iso_8601": "2025-07-17T00:35:43.368236Z",
"url": "https://files.pythonhosted.org/packages/c3/74/d4ea92bf3dec9544e17145cab876784d9fa3de81acbcc8c6e1a047f393ba/sas_cosmosdb-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 00:35:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mcaps-microsoft",
"github_project": "python_cosmosdb_helper",
"github_not_found": true,
"lcname": "sas-cosmosdb"
}
