swiftpy-framework 0.1.0__py3-none-any.whl

swiftpy/support/redis_config.py

@@ -0,0 +1,223 @@
+"""
+Centralized Redis connection configuration resolver.
+
+Guarantees single-source-of-truth configuration resolution through Config,
+with proper URL-encoding of user credentials and consistent defaults.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from swiftpy.core.config import Config
+
+
+def _first_not_none(*values: Any) -> Any:
+    """Return the first value that is not None."""
+    for val in values:
+        if val is not None:
+            return val
+    return None
+
+
+def _resolve_section_dict(cfg: Config, section: str) -> dict[str, Any]:
+    """Retrieve dictionary for the given section or known subsystem fallback."""
+    # Subsystem-specific structures
+    if section in ("cache", "cache.redis", "cache.stores.redis"):
+        stores = cfg.get("cache.stores")
+        if isinstance(stores, dict):
+            redis_store = stores.get("redis")
+            if isinstance(redis_store, dict):
+                return {str(k): v for k, v in redis_store.items()}
+        cache_redis = cfg.get("cache.redis")
+        if isinstance(cache_redis, dict):
+            return {str(k): v for k, v in cache_redis.items()}
+
+    if section in ("queue", "queue.redis", "queue.connections.redis"):
+        connections = cfg.get("queue.connections")
+        if isinstance(connections, dict):
+            redis_conn = connections.get("redis")
+            if isinstance(redis_conn, dict):
+                return {str(k): v for k, v in redis_conn.items()}
+        queue_redis = cfg.get("queue.redis")
+        if isinstance(queue_redis, dict):
+            return {str(k): v for k, v in queue_redis.items()}
+
+    if section in ("events", "events.redis"):
+        events_redis = cfg.get("events.redis")
+        if isinstance(events_redis, dict):
+            return {str(k): v for k, v in events_redis.items()}
+
+    val = cfg.get(section)
+    if isinstance(val, dict):
+        val_redis = val.get("redis")
+        if isinstance(val_redis, dict):
+            return {str(k): v for k, v in val_redis.items()}
+        return {str(k): v for k, v in val.items()}
+
+    return {}
+
+
+def resolve_redis_params(
+    config: Config | None = None,
+    section: str = "redis",
+    *,
+    host: str | None = None,
+    port: int | None = None,
+    password: str | None = None,
+    database: int | None = None,
+    username: str | None = None,
+    ssl: bool | None = None,
+) -> dict[str, Any]:
+    """
+    Resolve Redis connection parameters from Config and keyword overrides.
+
+    Reads only through Config (never raw os.getenv in runtime callers),
+    ensuring deterministic precedence and environment variable integration.
+    """
+    if config is None:
+        try:
+            cfg = Config.get_instance()
+        except (RuntimeError, ValueError):
+            cfg = Config()
+    else:
+        cfg = config
+
+    # Check for direct URL in section or sub-path
+    section_dict = _resolve_section_dict(cfg, section)
+    explicit_url = _first_not_none(
+        section_dict.get("url"),
+        cfg.get(f"{section}.url"),
+        cfg.get(f"{section}.redis_url"),
+        cfg.get("redis.url"),
+        cfg.get("redis_url"),
+    )
+
+    # Resolve individual components
+    cfg_host = _first_not_none(
+        section_dict.get("host"),
+        cfg.get(f"{section}.host"),
+        cfg.get("redis.host"),
+        cfg.get("redis_host"),
+    )
+    cfg_port = _first_not_none(
+        section_dict.get("port"),
+        cfg.get(f"{section}.port"),
+        cfg.get("redis.port"),
+        cfg.get("redis_port"),
+    )
+    cfg_password = (
+        section_dict.get("password")
+        if "password" in section_dict
+        else _first_not_none(
+            cfg.get(f"{section}.password"),
+            cfg.get("redis.password"),
+            cfg.get("redis_password"),
+        )
+    )
+
+    # Per-subsystem database fallback
+    subsystem_db = None
+    if section in ("queue", "queue.redis", "queue.connections.redis"):
+        subsystem_db = _first_not_none(cfg.get("redis_queue_db"), cfg.get("redis.queue_db"))
+    elif section in ("cache", "cache.redis", "cache.stores.redis"):
+        subsystem_db = _first_not_none(cfg.get("redis_cache_db"), cfg.get("redis.cache_db"))
+    elif section in ("events", "events.redis"):
+        subsystem_db = _first_not_none(cfg.get("redis_events_db"), cfg.get("redis.events_db"))
+
+    cfg_database = (
+        section_dict.get("database")
+        if "database" in section_dict
+        else _first_not_none(
+            subsystem_db,
+            cfg.get(f"{section}.database"),
+            cfg.get("redis.database"),
+            cfg.get("redis_db"),
+        )
+    )
+
+    cfg_username = _first_not_none(
+        section_dict.get("username"),
+        cfg.get(f"{section}.username"),
+        cfg.get("redis.username"),
+    )
+    cfg_ssl = (
+        section_dict.get("ssl")
+        if "ssl" in section_dict
+        else _first_not_none(cfg.get(f"{section}.ssl"), cfg.get("redis.ssl"))
+    )
+
+    # Apply overrides over config
+    final_host = host if host is not None else (str(cfg_host) if cfg_host is not None else "127.0.0.1")
+    final_port = port if port is not None else (int(cfg_port) if cfg_port is not None else 6379)
+    final_password = password if password is not None else (str(cfg_password) if cfg_password is not None else None)
+    final_database = database if database is not None else (int(cfg_database) if cfg_database is not None else 0)
+    final_username = username if username is not None else (str(cfg_username) if cfg_username is not None else None)
+    final_ssl = ssl if ssl is not None else (bool(cfg_ssl) if cfg_ssl is not None else False)
+
+    # If an explicit URL was configured and no individual component override was provided, use it
+    has_overrides = any(
+        arg is not None
+        for arg in (host, port, password, database, username, ssl)
+    )
+    if explicit_url and not has_overrides:
+        return {
+            "host": final_host,
+            "port": final_port,
+            "password": final_password,
+            "database": final_database,
+            "username": final_username,
+            "ssl": final_ssl,
+            "url": str(explicit_url),
+        }
+
+    # Construct the percent-encoded URL
+    scheme = "rediss" if final_ssl else "redis"
+    userinfo = ""
+    if final_username is not None and final_password is not None:
+        userinfo = f"{quote(final_username, safe='')}:{quote(final_password, safe='')}@"
+    elif final_password is not None:
+        userinfo = f":{quote(final_password, safe='')}@"
+    elif final_username is not None:
+        userinfo = f"{quote(final_username, safe='')}@"
+
+    url = f"{scheme}://{userinfo}{final_host}:{final_port}/{final_database}"
+
+    return {
+        "host": final_host,
+        "port": final_port,
+        "password": final_password,
+        "database": final_database,
+        "username": final_username,
+        "ssl": final_ssl,
+        "url": url,
+    }
+
+
+def build_redis_url(
+    config: Config | None = None,
+    section: str = "redis",
+    *,
+    host: str | None = None,
+    port: int | None = None,
+    password: str | None = None,
+    database: int | None = None,
+    username: str | None = None,
+    ssl: bool | None = None,
+) -> str:
+    """Build a sanitized and credential-encoded Redis connection URL."""
+    params = resolve_redis_params(
+        config=config,
+        section=section,
+        host=host,
+        port=port,
+        password=password,
+        database=database,
+        username=username,
+        ssl=ssl,
+    )
+    return str(params["url"])
+
+
+__all__ = ["build_redis_url", "resolve_redis_params"]

swiftpy/support/strings.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import re
+
+_UNCOUNTABLES = {
+    "aircraft",
+    "deer",
+    "equipment",
+    "fish",
+    "information",
+    "money",
+    "police",
+    "rice",
+    "series",
+    "sheep",
+    "species",
+}
+
+_IRREGULARS = {
+    "child": "children",
+    "foot": "feet",
+    "goose": "geese",
+    "man": "men",
+    "mouse": "mice",
+    "ox": "oxen",
+    "person": "people",
+    "quiz": "quizzes",
+    "tooth": "teeth",
+    "woman": "women",
+}
+
+_PLURAL_RULES: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"(quiz)$", re.IGNORECASE), r"\1zes"),
+    (re.compile(r"^(ox)$", re.IGNORECASE), r"\1en"),
+    (re.compile(r"([ml])ouse$", re.IGNORECASE), r"\1ice"),
+    (re.compile(r"(matr|vert|ind)(?:ix|ex)$", re.IGNORECASE), r"\1ices"),
+    (re.compile(r"(ax|test)is$", re.IGNORECASE), r"\1es"),
+    (re.compile(r"sis$", re.IGNORECASE), "ses"),
+    (re.compile(r"(x|ch|ss|sh)$", re.IGNORECASE), r"\1es"),
+    (re.compile(r"([^aeiouy]|qu)y$", re.IGNORECASE), r"\1ies"),
+    (re.compile(r"(?:([^f])fe|([lr])f)$", re.IGNORECASE), r"\1\2ves"),
+    (re.compile(r"([ti])um$", re.IGNORECASE), r"\1a"),
+    (re.compile(r"(buffal|tomat)o$", re.IGNORECASE), r"\1oes"),
+    (re.compile(r"(bu)s$", re.IGNORECASE), r"\1ses"),
+    (re.compile(r"(alias|status)$", re.IGNORECASE), r"\1es"),
+    (re.compile(r"(octop|vir)us$", re.IGNORECASE), r"\1uses"),
+    (re.compile(r"s$", re.IGNORECASE), "s"),
+    (re.compile(r"$"), "s"),
+]
+
+
+def snake_case(name: str) -> str:
+    """
+    Convert PascalCase, camelCase, or mixed acronyms to snake_case.
+
+    Examples:
+        snake_case("UserProfile") -> "user_profile"
+        snake_case("APIKey") -> "api_key"
+        snake_case("HTTPServer") -> "http_server"
+        snake_case("HTTPRequest") -> "http_request"
+        snake_case("UserAPIKey") -> "user_api_key"
+        snake_case("Oauth2Client") -> "oauth2_client"
+    """
+    if not name:
+        return name
+
+    # 1. Separate consecutive uppercase runs followed by titlecase/lowercase
+    # e.g., 'APIKey' -> 'API_Key', 'HTTPRequest' -> 'HTTP_Request'
+    s1 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)
+
+    # 2. Separate lowercase/digit followed by uppercase
+    # e.g., 'UserAPI_Key' -> 'User_API_Key', 'oauth2Client' -> 'oauth2_Client'
+    s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)
+
+    return s2.lower()
+
+
+def pluralize(word: str) -> str:
+    """Pluralize an English word or snake_cased identifier, preserving capitalization."""
+    if not word:
+        return word
+
+    parts = word.split("_")
+    last = parts[-1]
+    last_lower = last.lower()
+
+    if last_lower in _UNCOUNTABLES:
+        plural_last = last
+    elif last_lower in _IRREGULARS:
+        replacement = _IRREGULARS[last_lower]
+        if last.isupper():
+            plural_last = replacement.upper()
+        elif last.istitle():
+            plural_last = replacement.title()
+        else:
+            plural_last = replacement
+    else:
+        for pattern, replacement in _PLURAL_RULES:
+            if pattern.search(last):
+                plural_last = pattern.sub(replacement, last)
+                break
+        else:
+            plural_last = last + "s"
+
+        if last.isupper():
+            plural_last = plural_last.upper()
+        elif last.istitle():
+            plural_last = plural_last[0].upper() + plural_last[1:]
+
+    parts[-1] = plural_last
+    return "_".join(parts)
+
+
+__all__ = ["pluralize", "snake_case"]

swiftpy/testing/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from swiftpy.testing.fakes.ai_fake import AIFake, FakeCall
+from swiftpy.testing.fakes.vectorstore_fake import VectorStoreCall, VectorStoreFake
+from swiftpy.testing.fixtures import db_transaction, transactional_test
+from swiftpy.testing.http_client import TestClient, TestResponse, WebSocketTestSession
+from swiftpy.testing.test_case import TestCase
+
+__all__ = [
+    "AIFake",
+    "FakeCall",
+    "TestCase",
+    "TestClient",
+    "TestResponse",
+    "VectorStoreCall",
+    "VectorStoreFake",
+    "WebSocketTestSession",
+    "db_transaction",
+    "transactional_test",
+]

swiftpy/testing/fakes/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from swiftpy.testing.fakes.ai_fake import AIFake, FakeCall
+from swiftpy.testing.fakes.vectorstore_fake import VectorStoreCall, VectorStoreFake
+
+__all__ = [
+    "AIFake",
+    "FakeCall",
+    "VectorStoreCall",
+    "VectorStoreFake",
+]

swiftpy/testing/fakes/ai_fake.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from swiftpy.ai._deterministic import (
+    generate_deterministic_embedding as _deterministic_fake_vector,
+)
+from swiftpy.ai._fake import (
+    AIFake,
+    FakeCall,
+    FakeEmbeddingCall,
+    FixtureType,
+    _task_fake_stack,
+)
+
+__all__ = [
+    "AIFake",
+    "FakeCall",
+    "FakeEmbeddingCall",
+    "FixtureType",
+    "_deterministic_fake_vector",
+    "_task_fake_stack",
+]

swiftpy/testing/fakes/vectorstore_fake.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from swiftpy.ai.vectorstore.base import SearchResult, VectorRecord
+from swiftpy.ai.vectorstore.in_memory_adapter import InMemoryVectorStore
+
+
+@dataclass(frozen=True, slots=True)
+class VectorStoreCall:
+    """Recorded invocation made against a VectorStoreFake."""
+
+    method: str
+    collection: str
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+class VectorStoreFake(InMemoryVectorStore):
+    """
+    In-memory vector store test fake that records operations for assertions.
+    """
+
+    def __init__(
+        self,
+        collection_name: str = "default",
+        dimensions: int | None = None,
+        metric: str = "cosine",
+        *,
+        max_records: int | None = 100_000,
+    ) -> None:
+        super().__init__(
+            collection_name=collection_name,
+            dimensions=dimensions,
+            metric=metric,
+            max_records=max_records,
+        )
+        self.calls: list[VectorStoreCall] = []
+
+    def reset(self) -> None:
+        """Clear all stored vectors and recorded calls."""
+        self.calls.clear()
+        self._collections.clear()
+
+    def recorded(self, method: str | None = None) -> list[VectorStoreCall]:
+        """Return recorded invocations, optionally filtered by method name."""
+        if method is None:
+            return list(self.calls)
+        return [call for call in self.calls if call.method == method]
+
+    def assert_called(self, method: str, *, times: int | None = None) -> None:
+        """Assert that `method` was invoked (and optionally how many times)."""
+        matched = self.recorded(method)
+        if not matched and (times is None or times > 0):
+            raise AssertionError(f"Expected VectorStore method '{method}' to be called.")
+        if times is not None and len(matched) != times:
+            raise AssertionError(
+                f"Expected VectorStore method '{method}' to be called {times} time(s), got {len(matched)}."
+            )
+
+    def assert_upserted(self, record_id: str | None = None) -> None:
+        """Assert that an upsert/upsert_batch occurred (optionally for a specific id)."""
+        upserts = [
+            call for call in self.calls if call.method in ("upsert", "upsert_batch")
+        ]
+        if not upserts:
+            raise AssertionError("Expected at least one vectorstore upsert call.")
+        if record_id is not None:
+            found = any(
+                call.args.get("id") == record_id
+                or record_id in call.args.get("ids", ())
+                for call in upserts
+            )
+            if not found:
+                raise AssertionError(
+                    f"Expected record id '{record_id}' to be upserted, got {upserts!r}."
+                )
+
+    def assert_searched(self, *, times: int | None = None) -> None:
+        """Assert that search() was invoked."""
+        self.assert_called("search", times=times)
+
+    async def create_collection(
+        self,
+        name: str,
+        dimensions: int,
+        metric: str = "cosine",
+    ) -> None:
+        await super().create_collection(name, dimensions, metric=metric)
+        self.calls.append(
+            VectorStoreCall(
+                method="create_collection",
+                collection=name,
+                args={"name": name, "dimensions": dimensions, "metric": metric},
+            )
+        )
+
+    async def upsert(
+        self,
+        id: str,
+        vector: list[float],
+        metadata: dict[str, Any] | None = None,
+        content: str = "",
+    ) -> None:
+        await super().upsert(id, vector, metadata=metadata, content=content)
+        self.calls.append(
+            VectorStoreCall(
+                method="upsert",
+                collection=self._current_collection,
+                args={"id": id, "dimensions": len(vector), "metadata": metadata},
+            )
+        )
+
+    async def upsert_batch(
+        self,
+        records: Sequence[
+            VectorRecord
+            | dict[str, Any]
+            | tuple[str, list[float], dict[str, Any] | None]
+            | tuple[str, list[float], dict[str, Any] | None, str]
+        ],
+    ) -> None:
+        ids: list[str] = []
+        for rec in records:
+            if isinstance(rec, VectorRecord):
+                ids.append(rec.id)
+            elif isinstance(rec, dict):
+                ids.append(str(rec.get("id", "")))
+            elif isinstance(rec, tuple) and rec:
+                ids.append(str(rec[0]))
+        await super().upsert_batch(records)
+        self.calls.append(
+            VectorStoreCall(
+                method="upsert_batch",
+                collection=self._current_collection,
+                args={"count": len(records), "ids": tuple(ids)},
+            )
+        )
+
+    async def search(
+        self,
+        vector: list[float],
+        limit: int = 10,
+        filter: dict[str, Any] | None = None,
+    ) -> list[SearchResult]:
+        results = await super().search(vector, limit=limit, filter=filter)
+        self.calls.append(
+            VectorStoreCall(
+                method="search",
+                collection=self._current_collection,
+                args={
+                    "limit": limit,
+                    "filter": filter,
+                    "result_count": len(results),
+                },
+            )
+        )
+        return results
+
+    async def delete(self, id: str) -> bool:
+        deleted = await super().delete(id)
+        self.calls.append(
+            VectorStoreCall(
+                method="delete",
+                collection=self._current_collection,
+                args={"id": id, "deleted": deleted},
+            )
+        )
+        return deleted
+
+    async def delete_batch(self, ids: Sequence[str]) -> int:
+        count = await super().delete_batch(ids)
+        self.calls.append(
+            VectorStoreCall(
+                method="delete_batch",
+                collection=self._current_collection,
+                args={"ids": tuple(ids), "deleted_count": count},
+            )
+        )
+        return count
+
+    async def drop_collection(self, name: str) -> None:
+        await super().drop_collection(name)
+        self.calls.append(
+            VectorStoreCall(
+                method="drop_collection",
+                collection=name,
+                args={"name": name},
+            )
+        )
+
+
+__all__ = ["VectorStoreCall", "VectorStoreFake"]