velocity-python 0.1.81__tar.gz → 0.1.85__tar.gz

{velocity_python-0.1.81 → velocity_python-0.1.85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.81
+Version: 0.1.85
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT
@@ -39,6 +39,16 @@ Provides-Extra: http
 Requires-Dist: requests>=2.32.0; extra == "http"
 Provides-Extra: mysql
 Requires-Dist: mysql-connector-python>=9.0.0; extra == "mysql"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0.0; extra == "redis"
+Provides-Extra: mongodb
+Requires-Dist: pymongo>=4.6.0; extra == "mongodb"
+Provides-Extra: elasticsearch
+Requires-Dist: elasticsearch>=8.13.0; extra == "elasticsearch"
+Provides-Extra: cassandra
+Requires-Dist: cassandra-driver>=3.29.0; extra == "cassandra"
+Provides-Extra: couchbase
+Requires-Dist: couchbase>=4.2.0; extra == "couchbase"
 Provides-Extra: sqlserver
 Requires-Dist: python-tds>=1.15.0; extra == "sqlserver"
 Provides-Extra: postgres
@@ -70,6 +80,11 @@ Requires-Dist: braintree>=4.30.0; extra == "test"
 Requires-Dist: xmltodict>=0.13.0; extra == "test"
 Requires-Dist: authorizenet>=1.1.3; extra == "test"
 Requires-Dist: openpyxl>=3.1.0; extra == "test"
+Requires-Dist: redis>=5.0.0; extra == "test"
+Requires-Dist: fakeredis>=2.23.0; extra == "test"
+Requires-Dist: pymongo>=4.6.0; extra == "test"
+Requires-Dist: mongomock>=4.1.0; extra == "test"
+Requires-Dist: moto[dynamodb]>=5.0.0; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=8.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
@@ -234,6 +249,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |

{velocity_python-0.1.81 → velocity_python-0.1.85}/README.md

@@ -157,6 +157,7 @@ Full documentation is included in the `docs/` directory of the source distributi
 | Async Support | `docs/async.md` | AsyncTransaction, AsyncTable, AsyncResult, parallel queries with gather() |
 | Configuration Reference | `docs/configuration.md` | All environment variables, engine options, and connection settings |
 | AWS Lambda Handlers | `docs/aws-handlers.md` | LambdaHandler, SqsHandler, auth modes, per-record transactions |
+| NoSQL Adapters | `docs/nosql.md` | Redis, DynamoDB, MongoDB, Elasticsearch, Cassandra, Couchbase behind one capability-honest contract |
 | Payment Processing | `docs/payment.md` | Stripe and Braintree adapters, payment lifecycle |
 | Utilities | `docs/utilities.md` | Excel export, data conversion, formatting, timers, email parsing |
 | Testing Guide | `docs/TESTING.md` | Running tests, markers, coverage |

{velocity_python-0.1.81 → velocity_python-0.1.85}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.81"
+version = "0.1.85"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]
@@ -63,6 +63,21 @@ http = [
 mysql = [
   "mysql-connector-python>=9.0.0",
 ]
+redis = [
+  "redis>=5.0.0",
+]
+mongodb = [
+  "pymongo>=4.6.0",
+]
+elasticsearch = [
+  "elasticsearch>=8.13.0",
+]
+cassandra = [
+  "cassandra-driver>=3.29.0",
+]
+couchbase = [
+  "couchbase>=4.2.0",
+]
 sqlserver = [
   "python-tds>=1.15.0",
 ]
@@ -102,6 +117,14 @@ test = [
   "xmltodict>=0.13.0",
   "authorizenet>=1.1.3",
   "openpyxl>=3.1.0",
+  # NoSQL adapter unit tests run against in-process fakes (real clients for
+  # the wire formats, fakes for the servers). ES/Cassandra/Couchbase have
+  # translation-only unit tests and need no driver here.
+  "redis>=5.0.0",
+  "fakeredis>=2.23.0",
+  "pymongo>=4.6.0",
+  "mongomock>=4.1.0",
+  "moto[dynamodb]>=5.0.0",
 ]
 docs = [
   "sphinx>=8.0.0",

{velocity_python-0.1.81 → velocity_python-0.1.85}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.81"
+__version__ = version = "0.1.85"
 
 import importlib as _importlib
 

{velocity_python-0.1.81 → velocity_python-0.1.85}/src/velocity/aws/amplify_build.py

@@ -294,7 +294,54 @@ def _normalize_policy_document(policy_document: Any) -> Any:
         return json.loads(policy_document)
 
 
+def _canonical_statement(statement: Mapping[str, Any]) -> str:
+    """Canonical form for statement identity: scalar Action/Resource and their
+    list equivalents compare equal, action order is ignored."""
+    normalized: Dict[str, Any] = {}
+    for key, value in statement.items():
+        if key in ("Action", "NotAction", "Resource", "NotResource"):
+            items = value if isinstance(value, list) else [value]
+            normalized[key] = sorted(str(item) for item in items)
+        else:
+            normalized[key] = value
+    return json.dumps(normalized, sort_keys=True)
+
+
+def _merge_policy_statements(
+    current_document: Mapping[str, Any], desired_document: Mapping[str, Any]
+) -> Dict[str, Any]:
+    """Additive union of policy statements.
+
+    Every statement already on the policy is kept (manually-added grants and
+    other apps' statements survive); desired statements not already present are
+    appended. Statements are never removed here — remove manually when needed.
+    """
+    current_statements = list(current_document.get("Statement", []))
+    seen = {_canonical_statement(statement) for statement in current_statements}
+    merged = list(current_statements)
+    for statement in desired_document.get("Statement", []):
+        key = _canonical_statement(statement)
+        if key not in seen:
+            merged.append(statement)
+            seen.add(key)
+    merged_document = dict(current_document)
+    if "Version" not in merged_document and "Version" in desired_document:
+        merged_document["Version"] = desired_document["Version"]
+    merged_document["Statement"] = merged
+    return merged_document
+
+
 def _sync_managed_policy_document(iam_client, policy_arn: str, policy_document: Any) -> None:
+    """Ensure the managed policy contains every desired statement (additive).
+
+    The policy document is the union of what is already on the policy and the
+    desired statements; existing statements are never dropped. This keeps a
+    shared policy (e.g. lambda-vpc-execution, attached by every app's build)
+    stable across builds of apps with differing extra statements, and preserves
+    grants added out-of-band. Note: IAM managed policies cap at 6144 chars —
+    if the union outgrows that, create_policy_version raises and the surplus
+    must be pruned manually.
+    """
     policy = retryable_call(iam_client.get_policy, PolicyArn=policy_arn)["Policy"]
     current_version = retryable_call(
         iam_client.get_policy_version,
@@ -303,7 +350,9 @@ def _sync_managed_policy_document(iam_client, policy_arn: str, policy_document:
     )["PolicyVersion"]
 
     current_document = _normalize_policy_document(current_version["Document"])
-    desired_document = _normalize_policy_document(policy_document)
+    desired_document = _merge_policy_statements(
+        current_document, _normalize_policy_document(policy_document)
+    )
     if json.dumps(current_document, sort_keys=True) == json.dumps(desired_document, sort_keys=True):
         return
 

velocity_python-0.1.85/src/velocity/nosql/__init__.py

@@ -0,0 +1,20 @@
+"""
+velocity.nosql — a thin, capability-honest layer over NoSQL backends.
+
+Same idiom as velocity.db: collections are just names, documents are just
+dicts, where-dicts use the familiar operator-prefix convention. Unlike
+velocity.db there is no transaction contract — see docs/nosql.md.
+
+Usage:
+    from velocity.nosql.servers import redis
+    store = redis.initialize()
+    col = store.collection("sessions")
+    col.put("abc", {"user": "paul"}, ttl=3600)
+    col.get("abc")
+"""
+
+from velocity.nosql.core.capabilities import Capabilities
+from velocity.nosql.core.store import KEY_FIELD, Collection, Store
+from velocity.nosql import exceptions
+
+__all__ = ["Capabilities", "Collection", "Store", "KEY_FIELD", "exceptions"]

velocity_python-0.1.85/src/velocity/nosql/core/capabilities.py

@@ -0,0 +1,45 @@
+"""
+Capability declaration for NoSQL adapters.
+
+Every adapter declares what it can do; shared code checks the flags and the
+Collection base class enforces them, so unsupported operations fail loudly
+with NoSqlUnsupportedOperationError instead of degrading silently.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Capabilities:
+    """What a NoSQL adapter supports.
+
+    Attributes:
+        name: Adapter identifier ("memory", "redis", "dynamodb", ...).
+        query: ``find()`` with a where-dict is supported at all.
+        indexed_query: ad-hoc where-dicts are served efficiently without an
+            explicit index (Mongo/ES/Couchbase style). When False, ``find()``
+            beyond a key lookup requires ``allow_scan=True``.
+        scan: full-collection scans are possible (with ``allow_scan=True``).
+        ttl: per-document time-to-live on ``put()``.
+        lazy_ttl: expired documents may still exist physically and are
+            filtered out client-side on read (DynamoDB-style lazy expiry).
+        conditional_put: ``put_if_absent()`` supported.
+        cas: compare-and-swap via ``get_versioned()`` / ``cas()``.
+        transactions: backend has some atomic multi-write construct exposed
+            through the adapter's native handle (never through the shared
+            contract).
+        search: full-text relevance search via an adapter extension.
+        sort: server-side sort in ``find()``.
+    """
+
+    name: str
+    query: bool = False
+    indexed_query: bool = False
+    scan: bool = False
+    ttl: bool = False
+    lazy_ttl: bool = False
+    conditional_put: bool = False
+    cas: bool = False
+    transactions: bool = False
+    search: bool = False
+    sort: bool = False

velocity_python-0.1.85/src/velocity/nosql/core/store.py

@@ -0,0 +1,328 @@
+"""
+Store / Collection — the shared NoSQL contract.
+
+Deliberately *not* part of velocity.db's transactional world: there is no
+``tx`` here, and the shared contract makes no atomicity promises beyond the
+single operation. Backends with atomic multi-write constructs expose them
+via ``store.native`` only.
+
+Tiered contract:
+    Tier 1 (every adapter): get / put / delete / exists / put_if_absent,
+        plus get_versioned / cas where Capabilities.cas is set.
+    Tier 2 (Capabilities.query): find(where) using velocity's where-dict
+        convention (operator prefixes: {">=age": 21}, {"%name": "Smi%"}).
+    Tier 3: store/collection ``.native`` and adapter-specific extensions.
+
+Honesty rules enforced here, not left to adapters:
+    - Operations a backend can't support raise NoSqlUnsupportedOperationError.
+    - On backends without efficient ad-hoc queries (Capabilities.indexed_query
+      False), a find() beyond key lookups raises NoSqlUnindexedQueryError
+      unless the caller passes allow_scan=True.
+"""
+
+import os
+from abc import ABC, abstractmethod
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from velocity.nosql.core.capabilities import Capabilities
+from velocity.nosql.core.where import EQ, IN, Condition, parse_where
+from velocity.nosql.exceptions import (
+    NoSqlInvalidKeyError,
+    NoSqlSchemaLockedError,
+    NoSqlUnindexedQueryError,
+    NoSqlUnsupportedOperationError,
+)
+
+# Reserved field carrying the document key in find() results.
+KEY_FIELD = "_key"
+# Internal version field used by adapters that emulate CAS.
+VERSION_FIELD = "_vel_version"
+# Internal expiry marker used by adapters with lazy TTL (DynamoDB, Mongo).
+EXPIRES_FIELD = "_expires_at"
+
+MAX_KEY_LENGTH = 1024
+
+SortSpec = Union[str, List[str], None]
+
+
+def _schema_locked_from_env() -> bool:
+    return os.environ.get("VELOCITY_SCHEMA_LOCKED", "").lower() in ("true", "1", "yes")
+
+
+def apply_sort(
+    results: List[Dict[str, Any]], sort: List[Tuple[str, bool]]
+) -> List[Dict[str, Any]]:
+    """Client-side sort used by adapters that filter in Python (memory,
+    Redis/Cassandra scans). None sorts last in both directions; stable sorts
+    applied in reverse order keep earlier sort keys dominant."""
+    for field, ascending in reversed(sort):
+        nulls = [d for d in results if d.get(field) is None]
+        rest = [d for d in results if d.get(field) is not None]
+        rest.sort(key=lambda d, f=field: d.get(f), reverse=not ascending)
+        results = rest + nulls
+    return results
+
+
+def parse_sort(sort: SortSpec) -> List[Tuple[str, bool]]:
+    """Normalize a sort spec into [(field, ascending), ...].
+
+    Accepts "field", "-field" (descending), or a list of those.
+    """
+    if not sort:
+        return []
+    if isinstance(sort, str):
+        sort = [sort]
+    result = []
+    for item in sort:
+        item = item.strip()
+        if item.startswith("-"):
+            result.append((item[1:].strip(), False))
+        else:
+            result.append((item, True))
+    return result
+
+
+class Store(ABC):
+    """A connection to one NoSQL backend; hands out Collections."""
+
+    capabilities: Capabilities
+
+    def __init__(self, schema_locked: bool = False):
+        self.schema_locked = schema_locked or _schema_locked_from_env()
+        self._collections: Dict[str, "Collection"] = {}
+
+    def collection(self, name: str) -> "Collection":
+        if not isinstance(name, str) or not name.strip():
+            raise NoSqlInvalidKeyError(
+                f"Collection name must be a non-empty string: {name!r}"
+            )
+        name = name.strip()
+        if name not in self._collections:
+            self._collections[name] = self._make_collection(name)
+        return self._collections[name]
+
+    def ensure_collection(self, name: str, **options) -> None:
+        """Create the backing object (table/index/...) if missing. Idempotent.
+
+        Honors VELOCITY_SCHEMA_LOCKED, mirroring velocity.db schema locking.
+        """
+        if self.schema_locked:
+            raise NoSqlSchemaLockedError(
+                f"Cannot ensure collection {name!r}: schema is locked"
+            )
+        self._ensure_collection(name, **options)
+
+    def drop_collection(self, name: str) -> None:
+        if self.schema_locked:
+            raise NoSqlSchemaLockedError(
+                f"Cannot drop collection {name!r}: schema is locked"
+            )
+        self._drop_collection(name)
+        self._collections.pop(name, None)
+
+    def close(self) -> None:
+        """Release backend resources. Default: no-op."""
+
+    @property
+    def native(self) -> Any:
+        """The raw backend client, for Tier-3 use. Never required for Tier 1/2."""
+        raise NoSqlUnsupportedOperationError(
+            f"{self.capabilities.name} store does not expose a native client"
+        )
+
+    @abstractmethod
+    def _make_collection(self, name: str) -> "Collection": ...
+
+    @abstractmethod
+    def _ensure_collection(self, name: str, **options) -> None: ...
+
+    @abstractmethod
+    def _drop_collection(self, name: str) -> None: ...
+
+
+class Collection(ABC):
+    """One named document collection. Documents are dicts; keys are strings."""
+
+    def __init__(self, store: Store, name: str):
+        self.store = store
+        self.name = name
+
+    # ------------------------------------------------------------------ Tier 1
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        """Return the document, or None if absent (or expired)."""
+        return self._get(self._check_key(key))
+
+    def put(self, key: str, doc: Dict[str, Any], ttl: Optional[int] = None) -> None:
+        """Write (create or replace) the document. ``ttl`` is seconds."""
+        self._put(self._check_key(key), self._check_doc(doc), self._check_ttl(ttl))
+
+    def put_if_absent(
+        self, key: str, doc: Dict[str, Any], ttl: Optional[int] = None
+    ) -> bool:
+        """Atomically create the document only if the key is absent.
+
+        Returns True if this call created it. This is the locking primitive.
+        """
+        self._require(self.store.capabilities.conditional_put, "put_if_absent")
+        return self._put_if_absent(
+            self._check_key(key), self._check_doc(doc), self._check_ttl(ttl)
+        )
+
+    def get_versioned(self, key: str) -> Tuple[Optional[Dict[str, Any]], Optional[Any]]:
+        """Return (document, version-token) for use with cas(). (None, None) if absent."""
+        self._require(self.store.capabilities.cas, "get_versioned")
+        return self._get_versioned(self._check_key(key))
+
+    def cas(
+        self, key: str, doc: Dict[str, Any], version: Any, ttl: Optional[int] = None
+    ) -> bool:
+        """Replace the document only if it still carries ``version``.
+
+        Returns True on success, False if the document changed (or vanished)
+        since ``get_versioned``. The version token is adapter-opaque.
+        """
+        self._require(self.store.capabilities.cas, "cas")
+        if version is None:
+            return False
+        return self._cas(
+            self._check_key(key), self._check_doc(doc), version, self._check_ttl(ttl)
+        )
+
+    def delete(self, key: str) -> bool:
+        """Delete the document. Returns True if it existed."""
+        return self._delete(self._check_key(key))
+
+    def exists(self, key: str) -> bool:
+        return self._exists(self._check_key(key))
+
+    # ------------------------------------------------------------------ Tier 2
+
+    def find(
+        self,
+        where: Optional[Dict[str, Any]] = None,
+        limit: Optional[int] = None,
+        sort: SortSpec = None,
+        allow_scan: bool = False,
+    ) -> List[Dict[str, Any]]:
+        """Query the collection with a velocity where-dict.
+
+        Returned documents include their key under ``_key``. Conditions are
+        AND-combined. ``sort`` is "field" / "-field" / a list of those.
+        """
+        conditions = self._gate_query(where, allow_scan)
+        sort_spec = parse_sort(sort)
+        if sort_spec:
+            self._require(self.store.capabilities.sort, "sort")
+        return self._find(conditions, limit, sort_spec)
+
+    def count(
+        self, where: Optional[Dict[str, Any]] = None, allow_scan: bool = False
+    ) -> int:
+        conditions = self._gate_query(where, allow_scan)
+        return self._count(conditions)
+
+    # ------------------------------------------------------------------ Tier 3
+
+    @property
+    def native(self) -> Any:
+        """The adapter's native handle for this collection (falls back to the store's)."""
+        return self.store.native
+
+    # ---------------------------------------------------------------- plumbing
+
+    def _gate_query(
+        self, where: Optional[Dict[str, Any]], allow_scan: bool
+    ) -> List[Condition]:
+        caps = self.store.capabilities
+        if not caps.query and not caps.scan:
+            raise NoSqlUnsupportedOperationError(
+                f"{caps.name} does not support find()/count()"
+            )
+        conditions = parse_where(where)
+        key_only = all(
+            c.field == KEY_FIELD and c.op in (EQ, IN) for c in conditions
+        ) and bool(conditions)
+        needs_scan = not caps.indexed_query and not key_only
+        if needs_scan and not caps.scan:
+            raise NoSqlUnsupportedOperationError(
+                f"{caps.name} can only query by {KEY_FIELD}"
+            )
+        if needs_scan and not allow_scan:
+            raise NoSqlUnindexedQueryError(
+                f"This query is a full scan on {caps.name}. Pass allow_scan=True "
+                f"to accept the cost, or restructure the query around {KEY_FIELD}."
+            )
+        return conditions
+
+    def _require(self, flag: bool, operation: str) -> None:
+        if not flag:
+            raise NoSqlUnsupportedOperationError(
+                f"{self.store.capabilities.name} does not support {operation}"
+            )
+
+    @staticmethod
+    def _check_key(key: str) -> str:
+        if not isinstance(key, str) or not key or len(key) > MAX_KEY_LENGTH:
+            raise NoSqlInvalidKeyError(
+                f"Keys must be non-empty strings up to {MAX_KEY_LENGTH} chars, got: {key!r}"
+            )
+        return key
+
+    @staticmethod
+    def _check_doc(doc: Dict[str, Any]) -> Dict[str, Any]:
+        if not isinstance(doc, dict):
+            raise TypeError(f"Documents must be dicts, got {type(doc)}")
+        # Reserved fields never round-trip into storage.
+        return {
+            k: v
+            for k, v in doc.items()
+            if k not in (KEY_FIELD, VERSION_FIELD, EXPIRES_FIELD)
+        }
+
+    def _check_ttl(self, ttl: Optional[int]) -> Optional[int]:
+        if ttl is None:
+            return None
+        self._require(self.store.capabilities.ttl, "ttl")
+        ttl = int(ttl)
+        if ttl <= 0:
+            raise ValueError(f"ttl must be a positive number of seconds, got {ttl}")
+        return ttl
+
+    # ------------------------------------------------------- adapter interface
+
+    @abstractmethod
+    def _get(self, key: str) -> Optional[Dict[str, Any]]: ...
+
+    @abstractmethod
+    def _put(self, key: str, doc: Dict[str, Any], ttl: Optional[int]) -> None: ...
+
+    def _put_if_absent(self, key: str, doc: Dict[str, Any], ttl: Optional[int]) -> bool:
+        raise NoSqlUnsupportedOperationError("put_if_absent not implemented")
+
+    def _get_versioned(
+        self, key: str
+    ) -> Tuple[Optional[Dict[str, Any]], Optional[Any]]:
+        raise NoSqlUnsupportedOperationError("get_versioned not implemented")
+
+    def _cas(
+        self, key: str, doc: Dict[str, Any], version: Any, ttl: Optional[int]
+    ) -> bool:
+        raise NoSqlUnsupportedOperationError("cas not implemented")
+
+    @abstractmethod
+    def _delete(self, key: str) -> bool: ...
+
+    def _exists(self, key: str) -> bool:
+        return self._get(key) is not None
+
+    def _find(
+        self,
+        conditions: List[Condition],
+        limit: Optional[int],
+        sort: List[Tuple[str, bool]],
+    ) -> List[Dict[str, Any]]:
+        raise NoSqlUnsupportedOperationError("find not implemented")
+
+    def _count(self, conditions: List[Condition]) -> int:
+        return len(self._find(conditions, None, []))