altcodepro-polydb-python 2.1.0__tar.gz

altcodepro_polydb_python-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AltCodePro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

altcodepro_polydb_python-2.1.0/MANIFEST.in

@@ -0,0 +1,17 @@
+# Include documentation
+include README.md
+include LICENSE
+include pyproject.toml
+
+# Include requirements files
+include requirements*.txt
+
+# Include examples
+include example_usage.py
+
+# Exclude unnecessary files
+exclude .gitignore
+exclude .env*
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store

altcodepro_polydb_python-2.1.0/PKG-INFO

@@ -0,0 +1,378 @@
+Metadata-Version: 2.4
+Name: altcodepro-polydb-python
+Version: 2.1.0
+Summary: Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety
+Author: AltCodePro
+Project-URL: Homepage, https://github.com/altcodepro/polydb-python
+Project-URL: Documentation, https://github.com/altcodepro/polydb-python#readme
+Project-URL: Repository, https://github.com/altcodepro/polydb-python
+Project-URL: Bug Tracker, https://github.com/altcodepro/polydb-python/issues
+Keywords: database,cloud,multi-cloud,aws,azure,gcp,abstraction,nosql,sql,postgres,mongodb,dynamodb,s3
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg2-binary>=2.9.11
+Requires-Dist: tenacity>=9.1.4
+Provides-Extra: aws
+Requires-Dist: boto3>=1.42.47; extra == "aws"
+Requires-Dist: botocore>=1.42.47; extra == "aws"
+Provides-Extra: azure
+Requires-Dist: azure-core>=1.38.1; extra == "azure"
+Requires-Dist: azure-data-tables>=12.7.0; extra == "azure"
+Requires-Dist: azure-storage-blob>=12.28.0; extra == "azure"
+Requires-Dist: azure-storage-file-share>=12.24.0; extra == "azure"
+Requires-Dist: azure-storage-queue>=12.15.0; extra == "azure"
+Provides-Extra: gcp
+Requires-Dist: google-api-core>=2.29.0; extra == "gcp"
+Requires-Dist: google-auth>=2.48.0; extra == "gcp"
+Requires-Dist: google-cloud-core>=2.5.0; extra == "gcp"
+Requires-Dist: google-cloud-firestore>=2.23.0; extra == "gcp"
+Requires-Dist: google-cloud-pubsub>=2.35.0; extra == "gcp"
+Requires-Dist: google-cloud-storage>=3.9.0; extra == "gcp"
+Provides-Extra: mongodb
+Requires-Dist: pymongo>=4.16.0; extra == "mongodb"
+Provides-Extra: rabbitmq
+Requires-Dist: pika>=1.3.2; extra == "rabbitmq"
+Provides-Extra: vercel
+Requires-Dist: requests>=2.32.5; extra == "vercel"
+Provides-Extra: generic
+Requires-Dist: pymongo>=4.16.0; extra == "generic"
+Requires-Dist: pika>=1.3.2; extra == "generic"
+Requires-Dist: boto3>=1.42.47; extra == "generic"
+Provides-Extra: all
+Requires-Dist: boto3>=1.42.47; extra == "all"
+Requires-Dist: botocore>=1.42.47; extra == "all"
+Requires-Dist: azure-core>=1.38.1; extra == "all"
+Requires-Dist: azure-data-tables>=12.7.0; extra == "all"
+Requires-Dist: azure-storage-blob>=12.28.0; extra == "all"
+Requires-Dist: azure-storage-file-share>=12.24.0; extra == "all"
+Requires-Dist: azure-storage-queue>=12.15.0; extra == "all"
+Requires-Dist: google-cloud-firestore>=2.23.0; extra == "all"
+Requires-Dist: google-cloud-pubsub>=2.35.0; extra == "all"
+Requires-Dist: google-cloud-storage>=3.9.0; extra == "all"
+Requires-Dist: pymongo>=4.16.0; extra == "all"
+Requires-Dist: pika>=1.3.2; extra == "all"
+Requires-Dist: requests>=2.32.5; extra == "all"
+Requires-Dist: redis>=6.4.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: black>=26.1.0; extra == "dev"
+Requires-Dist: flake8>=7.3.0; extra == "dev"
+Requires-Dist: isort>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.19.1; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=9.0.2; extra == "test"
+Requires-Dist: pytest-cov>=7.0.0; extra == "test"
+Requires-Dist: pytest-mock>=3.15.1; extra == "test"
+Requires-Dist: moto>=5.1.21; extra == "test"
+Dynamic: license-file
+
+# PolyDB v3.0 - Enterprise Database Abstraction Layer
+
+**Production-ready, cloud-independent database abstraction with full LINQ support, field-level audit, cache, and overflow storage**
+
+## Features
+
+✅ **LINQ-Style Queries** - All SQL clauses: WHERE, ORDER BY, SELECT, GROUP BY, DISTINCT, COUNT  
+✅ **Multi-Cloud** - Azure, AWS, GCP, Vercel, MongoDB, PostgreSQL  
+✅ **Automatic Overflow** - Large NoSQL records → Object Storage (transparent)  
+✅ **Enterprise Audit** - Cryptographic hash chain, field-level changes, strict ordering  
+✅ **Cache Engine** - In-memory with TTL, automatic invalidation  
+✅ **Soft Delete** - Optional logical deletion with audit trail  
+✅ **Auto-Inject** - Tenant ID, audit fields (created_at, updated_by, etc.)  
+✅ **Thread-Safe** - Connection pooling, distributed-safe hash chaining  
+✅ **Retry Logic** - Exponential backoff, configurable  
+✅ **Type-Safe** - Protocol-based adapters, full type hints  
+
+## Quick Start
+
+```python
+from polydb import DatabaseFactory, polydb_model, QueryBuilder, Operator, AuditContext
+
+# 1. Define model
+@polydb_model
+class User:
+    __polydb__ = {
+        "storage": "sql",
+        "table": "users",
+        "cache": True,
+        "cache_ttl": 600,
+    }
+
+# 2. Initialize
+db = DatabaseFactory(
+    enable_audit=True,
+    enable_cache=True,
+    soft_delete=True,
+)
+
+# 3. Set context (per-request)
+AuditContext.set(
+    actor_id="user_123",
+    roles=["admin"],
+    tenant_id="tenant_abc",
+)
+
+# 4. CRUD with auto-audit
+user = db.create(User, {"name": "John", "email": "john@example.com"})
+# Auto-injects: tenant_id, created_at, created_by, updated_at, updated_by
+
+# 5. LINQ queries
+query = (
+    QueryBuilder()
+    .where("role", Operator.EQ, "admin")
+    .where("age", Operator.GTE, 18)
+    .order_by("created_at", descending=True)
+    .skip(10)
+    .take(20)
+    .select("id", "name", "email")
+)
+
+admins = db.query_linq(User, query)
+```
+
+## LINQ Operations
+
+### Filters
+```python
+builder.where("field", Operator.EQ, value)      # ==
+builder.where("field", Operator.NE, value)      # !=
+builder.where("field", Operator.GT, value)      # >
+builder.where("field", Operator.GTE, value)     # >=
+builder.where("field", Operator.LT, value)      # <
+builder.where("field", Operator.LTE, value)     # <=
+builder.where("field", Operator.IN, [1,2,3])    # IN
+builder.where("field", Operator.CONTAINS, "text") # LIKE
+builder.where("field", Operator.STARTS_WITH, "prefix")
+builder.where("field", Operator.ENDS_WITH, "suffix")
+```
+
+### Ordering & Pagination
+```python
+builder.order_by("field", descending=True)
+builder.skip(10)
+builder.take(20)
+```
+
+### Projection
+```python
+builder.select("id", "name", "email")
+```
+
+### Aggregation
+```python
+builder.count()
+builder.distinct_on()
+builder.group_by("role", "department")
+```
+
+## NoSQL Overflow Storage
+
+Records >1MB automatically stored in object storage:
+
+```python
+@polydb_model
+class Product:
+    __polydb__ = {
+        "storage": "nosql",
+        "collection": "products",
+    }
+
+# Large data automatically overflows
+product = db.create(Product, {
+    "data": {"huge": "payload"} * 100000
+})
+
+# Transparent retrieval
+retrieved = db.read_one(Product, {"id": product["id"]})
+# User never knows it came from blob storage
+```
+
+## Enterprise Audit Trail
+
+### Automatic Tracking
+- **Who**: actor_id, roles
+- **What**: action, model, entity_id, changed_fields
+- **When**: timestamp (microsecond precision)
+- **Where**: tenant_id, ip_address, user_agent
+- **Context**: trace_id, request_id
+- **Integrity**: cryptographic hash chain
+
+### Field-Level Changes
+```python
+db.update(User, user_id, {"email": "new@example.com"})
+# Audit log shows: changed_fields = ["email", "updated_at", "updated_by"]
+```
+
+### Verify Chain
+```python
+from polydb.audit.storage import AuditStorage
+
+audit = AuditStorage()
+is_valid = audit.verify_chain(tenant_id="tenant_abc")
+```
+
+## Cache Engine
+
+```python
+# Auto-cache from model metadata
+@polydb_model
+class User:
+    __polydb__ = {
+        "storage": "sql",
+        "table": "users",
+        "cache": True,
+        "cache_ttl": 600,  # 10 minutes
+    }
+
+# Cached read
+users = db.read(User, {"role": "admin"})
+
+# Bypass cache
+users = db.read(User, {"role": "admin"}, no_cache=True)
+
+# Manual invalidation
+from polydb.cache import CacheEngine
+cache = CacheEngine()
+cache.invalidate("User")
+cache.clear()
+```
+
+## Soft Delete
+
+```python
+db = DatabaseFactory(soft_delete=True)
+
+# Soft delete (sets deleted_at, deleted_by)
+db.delete(User, user_id)
+
+# Hard delete
+db.delete(User, user_id, hard=True)
+
+# Include deleted in queries
+all_users = db.read(User, {}, include_deleted=True)
+```
+
+## Pagination
+
+```python
+page1, next_token = db.read_page(User, {"role": "admin"}, page_size=50)
+page2, token2 = db.read_page(User, {"role": "admin"}, page_size=50, continuation_token=next_token)
+```
+
+## Multi-Tenant
+
+```python
+# Auto-inject tenant_id from context
+AuditContext.set(tenant_id="tenant_123", actor_id="user_456", roles=["admin"])
+
+user = db.create(User, {"name": "John"})
+# Result: {"name": "John", "tenant_id": "tenant_123", "created_by": "user_456", ...}
+
+# Filter by tenant (automatic)
+users = db.read(User, {})  # Only returns tenant_123 records
+```
+
+## Environment Variables
+
+```bash
+# Provider selection (optional, auto-detected)
+CLOUD_PROVIDER=aws|azure|gcp|vercel|mongodb|postgresql
+
+# PostgreSQL
+POSTGRES_CONNECTION_STRING=postgresql://user:pass@host:5432/db
+POSTGRES_MIN_CONNECTIONS=2
+POSTGRES_MAX_CONNECTIONS=20
+
+# AWS
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+DYNAMODB_TABLE_NAME=...
+S3_BUCKET_NAME=...
+
+# Azure
+AZURE_STORAGE_CONNECTION_STRING=...
+AZURE_TABLE_NAME=...
+AZURE_CONTAINER_NAME=...
+
+# GCP
+GOOGLE_CLOUD_PROJECT=...
+FIRESTORE_COLLECTION=...
+GCS_BUCKET_NAME=...
+
+# MongoDB
+MONGODB_URI=mongodb://...
+MONGODB_DATABASE=...
+MONGODB_COLLECTION=...
+
+# Vercel
+KV_URL=...
+KV_REST_API_TOKEN=...
+BLOB_READ_WRITE_TOKEN=...
+```
+
+## Model Metadata
+
+```python
+@polydb_model
+class Entity:
+    __polydb__ = {
+        # Required
+        "storage": "sql" | "nosql",
+        
+        # SQL
+        "table": "table_name",
+        
+        # NoSQL
+        "collection": "collection_name",
+        "pk_field": "partition_key_field",
+        "rk_field": "row_key_field",
+        
+        # Cache
+        "cache": True,
+        "cache_ttl": 300,  # seconds
+        
+        # Optional
+        "provider": "aws",  # Override auto-detection
+    }
+```
+
+## Thread Safety
+
+- Connection pooling with locks
+- Distributed-safe audit hash chaining
+- Cache with thread-safe operations
+- Retry logic with exponential backoff
+
+## Performance
+
+- **SQL**: Connection pooling (min=2, max=20)
+- **NoSQL**: Client reuse, overflow storage
+- **Cache**: In-memory with automatic invalidation
+- **Retry**: Configurable backoff (0.5s-6s)
+
+## Production Checklist
+
+✅ Set `CLOUD_PROVIDER` explicitly  
+✅ Configure connection pool sizes  
+✅ Enable audit (`enable_audit=True`)  
+✅ Set cache TTL per model  
+✅ Use soft delete for compliance  
+✅ Set audit context per request  
+✅ Monitor audit chain integrity  
+✅ Configure retry attempts  
+
+## License
+
+MIT

altcodepro_polydb_python-2.1.0/README.md

@@ -0,0 +1,298 @@
+# PolyDB v3.0 - Enterprise Database Abstraction Layer
+
+**Production-ready, cloud-independent database abstraction with full LINQ support, field-level audit, cache, and overflow storage**
+
+## Features
+
+✅ **LINQ-Style Queries** - All SQL clauses: WHERE, ORDER BY, SELECT, GROUP BY, DISTINCT, COUNT  
+✅ **Multi-Cloud** - Azure, AWS, GCP, Vercel, MongoDB, PostgreSQL  
+✅ **Automatic Overflow** - Large NoSQL records → Object Storage (transparent)  
+✅ **Enterprise Audit** - Cryptographic hash chain, field-level changes, strict ordering  
+✅ **Cache Engine** - In-memory with TTL, automatic invalidation  
+✅ **Soft Delete** - Optional logical deletion with audit trail  
+✅ **Auto-Inject** - Tenant ID, audit fields (created_at, updated_by, etc.)  
+✅ **Thread-Safe** - Connection pooling, distributed-safe hash chaining  
+✅ **Retry Logic** - Exponential backoff, configurable  
+✅ **Type-Safe** - Protocol-based adapters, full type hints  
+
+## Quick Start
+
+```python
+from polydb import DatabaseFactory, polydb_model, QueryBuilder, Operator, AuditContext
+
+# 1. Define model
+@polydb_model
+class User:
+    __polydb__ = {
+        "storage": "sql",
+        "table": "users",
+        "cache": True,
+        "cache_ttl": 600,
+    }
+
+# 2. Initialize
+db = DatabaseFactory(
+    enable_audit=True,
+    enable_cache=True,
+    soft_delete=True,
+)
+
+# 3. Set context (per-request)
+AuditContext.set(
+    actor_id="user_123",
+    roles=["admin"],
+    tenant_id="tenant_abc",
+)
+
+# 4. CRUD with auto-audit
+user = db.create(User, {"name": "John", "email": "john@example.com"})
+# Auto-injects: tenant_id, created_at, created_by, updated_at, updated_by
+
+# 5. LINQ queries
+query = (
+    QueryBuilder()
+    .where("role", Operator.EQ, "admin")
+    .where("age", Operator.GTE, 18)
+    .order_by("created_at", descending=True)
+    .skip(10)
+    .take(20)
+    .select("id", "name", "email")
+)
+
+admins = db.query_linq(User, query)
+```
+
+## LINQ Operations
+
+### Filters
+```python
+builder.where("field", Operator.EQ, value)      # ==
+builder.where("field", Operator.NE, value)      # !=
+builder.where("field", Operator.GT, value)      # >
+builder.where("field", Operator.GTE, value)     # >=
+builder.where("field", Operator.LT, value)      # <
+builder.where("field", Operator.LTE, value)     # <=
+builder.where("field", Operator.IN, [1,2,3])    # IN
+builder.where("field", Operator.CONTAINS, "text") # LIKE
+builder.where("field", Operator.STARTS_WITH, "prefix")
+builder.where("field", Operator.ENDS_WITH, "suffix")
+```
+
+### Ordering & Pagination
+```python
+builder.order_by("field", descending=True)
+builder.skip(10)
+builder.take(20)
+```
+
+### Projection
+```python
+builder.select("id", "name", "email")
+```
+
+### Aggregation
+```python
+builder.count()
+builder.distinct_on()
+builder.group_by("role", "department")
+```
+
+## NoSQL Overflow Storage
+
+Records >1MB automatically stored in object storage:
+
+```python
+@polydb_model
+class Product:
+    __polydb__ = {
+        "storage": "nosql",
+        "collection": "products",
+    }
+
+# Large data automatically overflows
+product = db.create(Product, {
+    "data": {"huge": "payload"} * 100000
+})
+
+# Transparent retrieval
+retrieved = db.read_one(Product, {"id": product["id"]})
+# User never knows it came from blob storage
+```
+
+## Enterprise Audit Trail
+
+### Automatic Tracking
+- **Who**: actor_id, roles
+- **What**: action, model, entity_id, changed_fields
+- **When**: timestamp (microsecond precision)
+- **Where**: tenant_id, ip_address, user_agent
+- **Context**: trace_id, request_id
+- **Integrity**: cryptographic hash chain
+
+### Field-Level Changes
+```python
+db.update(User, user_id, {"email": "new@example.com"})
+# Audit log shows: changed_fields = ["email", "updated_at", "updated_by"]
+```
+
+### Verify Chain
+```python
+from polydb.audit.storage import AuditStorage
+
+audit = AuditStorage()
+is_valid = audit.verify_chain(tenant_id="tenant_abc")
+```
+
+## Cache Engine
+
+```python
+# Auto-cache from model metadata
+@polydb_model
+class User:
+    __polydb__ = {
+        "storage": "sql",
+        "table": "users",
+        "cache": True,
+        "cache_ttl": 600,  # 10 minutes
+    }
+
+# Cached read
+users = db.read(User, {"role": "admin"})
+
+# Bypass cache
+users = db.read(User, {"role": "admin"}, no_cache=True)
+
+# Manual invalidation
+from polydb.cache import CacheEngine
+cache = CacheEngine()
+cache.invalidate("User")
+cache.clear()
+```
+
+## Soft Delete
+
+```python
+db = DatabaseFactory(soft_delete=True)
+
+# Soft delete (sets deleted_at, deleted_by)
+db.delete(User, user_id)
+
+# Hard delete
+db.delete(User, user_id, hard=True)
+
+# Include deleted in queries
+all_users = db.read(User, {}, include_deleted=True)
+```
+
+## Pagination
+
+```python
+page1, next_token = db.read_page(User, {"role": "admin"}, page_size=50)
+page2, token2 = db.read_page(User, {"role": "admin"}, page_size=50, continuation_token=next_token)
+```
+
+## Multi-Tenant
+
+```python
+# Auto-inject tenant_id from context
+AuditContext.set(tenant_id="tenant_123", actor_id="user_456", roles=["admin"])
+
+user = db.create(User, {"name": "John"})
+# Result: {"name": "John", "tenant_id": "tenant_123", "created_by": "user_456", ...}
+
+# Filter by tenant (automatic)
+users = db.read(User, {})  # Only returns tenant_123 records
+```
+
+## Environment Variables
+
+```bash
+# Provider selection (optional, auto-detected)
+CLOUD_PROVIDER=aws|azure|gcp|vercel|mongodb|postgresql
+
+# PostgreSQL
+POSTGRES_CONNECTION_STRING=postgresql://user:pass@host:5432/db
+POSTGRES_MIN_CONNECTIONS=2
+POSTGRES_MAX_CONNECTIONS=20
+
+# AWS
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+DYNAMODB_TABLE_NAME=...
+S3_BUCKET_NAME=...
+
+# Azure
+AZURE_STORAGE_CONNECTION_STRING=...
+AZURE_TABLE_NAME=...
+AZURE_CONTAINER_NAME=...
+
+# GCP
+GOOGLE_CLOUD_PROJECT=...
+FIRESTORE_COLLECTION=...
+GCS_BUCKET_NAME=...
+
+# MongoDB
+MONGODB_URI=mongodb://...
+MONGODB_DATABASE=...
+MONGODB_COLLECTION=...
+
+# Vercel
+KV_URL=...
+KV_REST_API_TOKEN=...
+BLOB_READ_WRITE_TOKEN=...
+```
+
+## Model Metadata
+
+```python
+@polydb_model
+class Entity:
+    __polydb__ = {
+        # Required
+        "storage": "sql" | "nosql",
+        
+        # SQL
+        "table": "table_name",
+        
+        # NoSQL
+        "collection": "collection_name",
+        "pk_field": "partition_key_field",
+        "rk_field": "row_key_field",
+        
+        # Cache
+        "cache": True,
+        "cache_ttl": 300,  # seconds
+        
+        # Optional
+        "provider": "aws",  # Override auto-detection
+    }
+```
+
+## Thread Safety
+
+- Connection pooling with locks
+- Distributed-safe audit hash chaining
+- Cache with thread-safe operations
+- Retry logic with exponential backoff
+
+## Performance
+
+- **SQL**: Connection pooling (min=2, max=20)
+- **NoSQL**: Client reuse, overflow storage
+- **Cache**: In-memory with automatic invalidation
+- **Retry**: Configurable backoff (0.5s-6s)
+
+## Production Checklist
+
+✅ Set `CLOUD_PROVIDER` explicitly  
+✅ Configure connection pool sizes  
+✅ Enable audit (`enable_audit=True`)  
+✅ Set cache TTL per model  
+✅ Use soft delete for compliance  
+✅ Set audit context per request  
+✅ Monitor audit chain integrity  
+✅ Configure retry attempts  
+
+## License
+
+MIT