altcodepro-polydb-python 2.5.18__tar.gz → 2.5.19__tar.gz

{altcodepro_polydb_python-2.5.18/src/altcodepro_polydb_python.egg-info → altcodepro_polydb_python-2.5.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.5.18
+Version: 2.5.19
 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

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "altcodepro-polydb-python"
-version = "2.5.18"
+version = "2.5.19"
 description = "Production-ready multi-cloud database abstraction layer with connection pooling, retry logic, and thread safety"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19/src/altcodepro_polydb_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: altcodepro-polydb-python
-Version: 2.5.18
+Version: 2.5.19
 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

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/altcodepro_polydb_python.egg-info/SOURCES.txt

@@ -115,6 +115,7 @@ tests/test_postgresql.py
 tests/test_postgresql_deserialize_row.py
 tests/test_queue_extend_delay_cancel.py
 tests/test_rabbitmq.py
+tests/test_read_projection.py
 tests/test_redis_kv.py
 tests/test_schema_ddl_injection.py
 tests/test_secrets_aws.py

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/polydb/PolyDB.py

@@ -158,6 +158,8 @@ class PolyDB:
         cache_ttl: Optional[int] = None,
         include_deleted: bool = False,
         engine_override: Optional[EngineOverride] = None,
+        fields: Optional[List[str]] = None,
+        omit: Optional[List[str]] = None,
     ) -> List[JsonDict]:
         return self.db.read(
             model,
@@ -168,6 +170,8 @@ class PolyDB:
             cache_ttl=cache_ttl,
             include_deleted=include_deleted,
             engine_override=engine_override,
+            fields=fields,
+            omit=omit,
         )
 
     def read_one(

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/polydb/adapters/AzureTableStorageAdapter.py

@@ -633,9 +633,35 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
                 return None
             raise NoSQLError(f"Azure Table get failed: {str(e)}")
 
+    # `fields` / `omit` are sent to Azure as `$select`, so unrequested properties never leave the service.
+    SUPPORTS_SELECT_PUSHDOWN = True
+
+    def _select_properties(self, select: Optional[List[str]]) -> Optional[List[str]]:
+        """The Azure property names to `$select` for the requested field names -- the requested ones, plus what `_unpack_entity`
+        needs to rebuild a row (the keys, the model tag, and the sanitized-name map). A per-property blob overflow is stored in
+        the property itself, so selecting the property is enough for `_restore_overflow_properties`. None = no pushdown: if any
+        requested name is rewritten by `_sanitize_prop_name` (so its stored name could carry a collision suffix), the whole row is
+        fetched and trimmed afterwards instead of risking a silently missing column."""
+        if not select:
+            return None
+        props: List[str] = []
+        for name in select:
+            safe = self._sanitize_prop_name(name)
+            if safe != str(name):
+                return None
+            props.append(safe)
+        for needed in ("PartitionKey", "RowKey", _MODEL_FIELD, "__keymap__"):
+            if needed not in props:
+                props.append(needed)
+        return props
+
     @retry(max_attempts=3, delay=1.0, exceptions=(NoSQLError,))
     def _query_raw(
-        self, model: type, filters: Dict[str, Any], limit: Optional[int]
+        self,
+        model: type,
+        filters: Dict[str, Any],
+        limit: Optional[int],
+        select: Optional[List[str]] = None,
     ) -> List[JsonDict]:
         try:
             table_client = self._get_table_client(model)
@@ -685,7 +711,11 @@ class AzureTableStorageAdapter(NoSQLKVAdapter):
             else:
                 query_filter = " and ".join(parts)
 
-            entities = table_client.query_entities(query_filter=query_filter)
+            props = self._select_properties(select)
+            if props is None:
+                entities = table_client.query_entities(query_filter=query_filter)
+            else:
+                entities = table_client.query_entities(query_filter=query_filter, select=props)
 
             results: List[JsonDict] = []
             count = 0

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/polydb/adapters/PostgreSQLAdapter.py

@@ -487,8 +487,12 @@ class PostgreSQLAdapter:
         tx: Optional[Any] = None,
         *,
         session_vars: Optional[Dict[str, str]] = None,
+        fields: Optional[List[str]] = None,
     ) -> List[JsonDict]:
         table = validate_table_name(table)
+        if fields:
+            for f in fields:
+                validate_column_name(f)
         conn = tx
         own_conn = False
         if not conn:
@@ -498,7 +502,7 @@ class PostgreSQLAdapter:
         try:
             self._apply_session_vars(conn, session_vars)
             cursor = conn.cursor()
-            sql = f"SELECT * FROM {table}"
+            sql = f"SELECT {', '.join(fields)} FROM {table}" if fields else f"SELECT * FROM {table}"
             params: List[Any] = []
 
             if query:

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/polydb/base/NoSQLKVAdapter.py

@@ -17,9 +17,43 @@ if TYPE_CHECKING:
     from ..models import PartitionConfig
 
 
+def project_rows(
+    rows: List[JsonDict], fields: Optional[List[str]] = None, omit: Optional[List[str]] = None
+) -> List[JsonDict]:
+    """The exact `fields` / `omit` semantics every NoSQL read shares: `fields` keeps only those keys, `omit` drops those keys
+    (`fields` wins if both are given). Applied by the base `query()` AFTER overflow rehydration, so it is correct for every
+    adapter whether or not it also pushes the projection down to the store."""
+    if fields:
+        keep = set(fields)
+        return [{k: v for k, v in r.items() if k in keep} for r in rows]
+    if omit:
+        drop = set(omit)
+        return [{k: v for k, v in r.items() if k not in drop} for r in rows]
+    return rows
+
+
+def select_columns(
+    fields: Optional[List[str]], omit: Optional[List[str]], columns: Optional[List[str]]
+) -> Optional[List[str]]:
+    """The column list a store can be asked for: `fields` as given, or -- for `omit` -- the model's known `columns` minus the
+    omitted ones. None means "no column list can be derived" (no projection, or `omit` on a model whose columns are unknown):
+    the read then fetches whole rows and `project_rows` trims them."""
+    if fields:
+        return list(fields)
+    if omit and columns:
+        drop = set(omit)
+        return [c for c in columns if c not in drop]
+    return None
+
+
 class NoSQLKVAdapter:
     """Base with auto-overflow and LINQ support"""
 
+    # An adapter sets this True when its `_query_raw` accepts `select=[property names]` and really sends it to the store (Azure
+    # Table's `$select`). False (the default) means `fields`/`omit` are applied after the rows come back -- same result, no
+    # network saving. Opt in per adapter only once the adapter's own rehydration is proven to survive a narrowed row.
+    SUPPORTS_SELECT_PUSHDOWN = False
+
     def __init__(
         self,
         partition_config: Optional[PartitionConfig] = None,
@@ -242,9 +276,15 @@ class NoSQLKVAdapter:
         limit: Optional[int] = None,
         no_cache: bool = False,
         cache_ttl: Optional[int] = None,
+        fields: Optional[List[str]] = None,
+        omit: Optional[List[str]] = None,
     ) -> List[JsonDict]:
-        results = self._query_raw(model, query or {}, limit)
-        return [self._retrieve_overflow(r) for r in results]
+        select = select_columns(fields, omit, getattr(model, "__polydb__", {}).get("columns"))
+        if select is not None and self.SUPPORTS_SELECT_PUSHDOWN:
+            results = self._query_raw(model, query or {}, limit, select=select)
+        else:
+            results = self._query_raw(model, query or {}, limit)
+        return project_rows([self._retrieve_overflow(r) for r in results], fields, omit)
 
     def query_page(
         self, model: type, query: Lookup, page_size: int, continuation_token: Optional[str] = None

{altcodepro_polydb_python-2.5.18 → altcodepro_polydb_python-2.5.19}/src/polydb/databaseFactory.py

@@ -24,7 +24,7 @@ from tenacity import retry, stop_after_attempt, wait_exponential
 from .adapters.PostgreSQLAdapter import PostgreSQLAdapter
 from .audit.context import AuditContext
 from .audit.manager import AuditManager
-from .base.NoSQLKVAdapter import NoSQLKVAdapter
+from .base.NoSQLKVAdapter import NoSQLKVAdapter, project_rows, select_columns
 from .batch import BatchOperations
 from .cache import CacheWarmer, RedisCacheEngine
 from .cloudDatabaseFactory import CloudDatabaseFactory
@@ -453,30 +453,53 @@ class DatabaseFactory:
         include_deleted: bool = False,
         engine_override: Optional[EngineOverride] = None,
         session_vars: Optional[Dict[str, str]] = None,
+        fields: Optional[List[str]] = None,
+        omit: Optional[List[str]] = None,
     ) -> List[JsonDict]:
+        """`fields` returns only those keys; `omit` returns every key except those (`fields` wins if both are given). SQL
+        names the columns in the SELECT; NoSQL adapters that can ($select on Azure Table) send the property list to the store,
+        the rest trim the rows after the read -- same result either way. `omit` needs the model's `__polydb__["columns"]` to
+        be turned into a column list for the store; without it the whole row is fetched and trimmed. A projected read never
+        goes through the external cache (its key does not include the projection)."""
         name = _model_name(model)
         meta = _extract_meta(model)
+        columns = (getattr(model, "__polydb__", None) or {}).get("columns") if isinstance(model, type) else None
+        projected = bool(fields or omit)
+        sql_columns = select_columns(fields, omit, columns)
 
         if self._soft_delete and not include_deleted:
             query = self._apply_soft_delete_filter(query)
 
         adapters = self._adapters_for(model, meta, engine_override)
-        use_external_cache = self._enable_cache and self._cache and getattr(meta, "cache", False)
+        use_external_cache = (
+            self._enable_cache and self._cache and getattr(meta, "cache", False) and not projected
+        )
         encrypted_fields = getattr(meta, "encrypted_fields", [])
 
         def _op() -> List[JsonDict]:
             if self._is_sql(meta, engine_override):
-                raw = adapters.sql.select(
-                    meta.table, query, limit=limit, offset=offset, session_vars=session_vars
-                )
+                if sql_columns is not None:
+                    raw = adapters.sql.select(
+                        meta.table, query, limit=limit, offset=offset,
+                        session_vars=session_vars, fields=sql_columns,
+                    )
+                else:
+                    raw = adapters.sql.select(
+                        meta.table, query, limit=limit, offset=offset, session_vars=session_vars
+                    )
+                    raw = project_rows(raw, fields, omit)
             else:
                 cls = (
                     model
                     if isinstance(model, type)
                     else type(name, (), {"__polydb__": meta.__dict__})
                 )
+                nosql_kwargs: Dict[str, Any] = {}
+                if projected:
+                    nosql_kwargs = {"fields": fields, "omit": omit}
                 raw = adapters.nosql.query(
-                    cls, query=query, limit=limit, no_cache=no_cache or bool(use_external_cache)
+                    cls, query=query, limit=limit, no_cache=no_cache or bool(use_external_cache),
+                    **nosql_kwargs,
                 )
             if self.encryption and encrypted_fields:
                 raw = [self.encryption.decrypt_fields(r, encrypted_fields) for r in raw]

altcodepro_polydb_python-2.5.19/tests/test_read_projection.py

@@ -0,0 +1,169 @@
+"""`fields` / `omit` on read: SQL names the columns, Azure Table sends `$select`, every other NoSQL adapter trims after the read.
+
+Unit level (no Azurite / Postgres): fake table client, fake cursor.
+"""
+
+import pytest
+
+from polydb.base.NoSQLKVAdapter import NoSQLKVAdapter, project_rows, select_columns
+
+
+# ---------------- pure helpers -------------------------------------------------------------------------------------------
+
+def test_project_rows_fields_omit_and_fields_wins():
+    rows = [{"id": "1", "a": 1, "b": 2, "big": "x" * 10}]
+    assert project_rows(rows, ["id", "a"], None) == [{"id": "1", "a": 1}]
+    assert project_rows(rows, None, ["big"]) == [{"id": "1", "a": 1, "b": 2}]
+    assert project_rows(rows, ["a"], ["a"]) == [{"a": 1}]
+    assert project_rows(rows, None, None) is rows
+
+
+def test_select_columns_from_fields_or_columns_minus_omit():
+    cols = ["id", "a", "b", "big"]
+    assert select_columns(["a"], None, cols) == ["a"]
+    assert select_columns(None, ["big"], cols) == ["id", "a", "b"]
+    assert select_columns(None, ["big"], None) is None  # columns unknown: cannot derive a list, fetch whole rows
+    assert select_columns(None, None, cols) is None
+
+
+# ---------------- base adapter: pushdown flag ----------------------------------------------------------------------------
+
+class _Adapter(NoSQLKVAdapter):
+    def __init__(self, pushdown):
+        super().__init__()
+        self.SUPPORTS_SELECT_PUSHDOWN = pushdown
+        self.calls = []
+    def _query_raw(self, model, filters, limit, select=None):
+        self.calls.append(select)
+        return [{"id": "1", "a": 1, "b": 2, "big": "zzz"}]
+
+
+class _M:
+    __polydb__ = {"columns": ["id", "a", "b", "big"]}
+
+
+def test_without_pushdown_rows_are_trimmed_after_the_read():
+    a = _Adapter(False)
+    assert a.query(_M, {"x": 1}, fields=["id", "a"]) == [{"id": "1", "a": 1}]
+    assert a.calls == [None]  # the store was asked for whole rows
+
+
+def test_with_pushdown_the_select_list_reaches_the_store_and_result_is_still_exact():
+    a = _Adapter(True)
+    assert a.query(_M, {}, fields=["a"]) == [{"a": 1}]
+    assert a.query(_M, {}, omit=["big"]) == [{"id": "1", "a": 1, "b": 2}]
+    assert a.calls == [["a"], ["id", "a", "b"]]
+
+
+def test_omit_on_a_model_without_known_columns_is_client_side_only():
+    class _Bare: pass
+    a = _Adapter(True)
+    assert a.query(_Bare, {}, omit=["big"]) == [{"id": "1", "a": 1, "b": 2}]
+    assert a.calls == [None]
+
+
+def test_no_projection_keeps_the_old_call_shape():
+    a = _Adapter(True)
+    assert a.query(_M, {}) == [{"id": "1", "a": 1, "b": 2, "big": "zzz"}]
+    assert a.calls == [None]
+
+
+# ---------------- Azure Table: $select -----------------------------------------------------------------------------------
+
+azure = pytest.importorskip("azure.data.tables")
+from polydb.adapters.AzureTableStorageAdapter import AzureTableStorageAdapter  # noqa: E402
+
+
+class _Model:
+    __name__ = "Artifact"
+    __qualname__ = "Artifact"
+    __polydb__ = {"pk_field": "tenant_id", "rk_field": "id"}
+
+
+class _Client:
+    def __init__(self, entities):
+        self.entities, self.kwargs = entities, []
+    def query_entities(self, query_filter=None, **kw):
+        self.kwargs.append((query_filter, kw)); return list(self.entities)
+
+
+ENT = {"PartitionKey": "t1", "RowKey": "r1", "__polydb_model__": "Artifact", "__keymap__": "{}", "id": "r1",
+       "name": "n", "status": "ok"}
+
+
+def _adp(client):
+    adp = object.__new__(AzureTableStorageAdapter)
+    adp._get_table_client = lambda model: client
+    return adp
+
+
+def test_azure_sends_select_with_the_keys_the_row_needs():
+    c = _Client([ENT])
+    rows = _adp(c).query(_Model, {"tenant_id": "t1"}, fields=["name", "status"])
+    (flt, kw), = c.kwargs
+    assert flt == "tenant_id eq 't1'"
+    assert set(kw["select"]) == {"name", "status", "PartitionKey", "RowKey", "__polydb_model__", "__keymap__"}
+    assert rows == [{"name": "n", "status": "ok"}]  # id / tenant_id added by unpack are trimmed back out
+
+
+def test_azure_omit_becomes_select_of_the_remaining_known_columns():
+    class _M2(_Model):
+        __polydb__ = {"pk_field": "tenant_id", "rk_field": "id", "columns": ["id", "name", "status", "content"]}
+    c = _Client([ENT])
+    rows = _adp(c).query(_M2, {}, omit=["content"])
+    (_, kw), = c.kwargs
+    assert "content" not in kw["select"] and {"id", "name", "status"} <= set(kw["select"])
+    assert rows == [{"id": "r1", "name": "n", "status": "ok", "tenant_id": "t1"}]  # omit drops only what was named
+
+
+def test_azure_no_projection_sends_no_select():
+    c = _Client([ENT])
+    _adp(c).query(_Model, {})
+    assert c.kwargs == [(None, {})]
+
+
+def test_azure_falls_back_to_whole_rows_when_a_name_would_be_rewritten():
+    c = _Client([dict(ENT, f_1x="v")])
+    _adp(c).query(_Model, {}, fields=["1x"])  # "1x" is stored as "f_1x": cannot be selected by its own name
+    assert c.kwargs == [(None, {})]
+
+
+# ---------------- Postgres: named columns --------------------------------------------------------------------------------
+
+from polydb.adapters.PostgreSQLAdapter import PostgreSQLAdapter  # noqa: E402
+
+
+class _Cur:
+    description = [("id",), ("status",)]
+    def fetchall(self): return [("1", "ok")]
+    def close(self): pass
+class _Conn:
+    def cursor(self): return _Cur()
+    def commit(self): pass
+    def rollback(self): pass
+
+
+def _pg(captured):
+    a = object.__new__(PostgreSQLAdapter)
+    a._get_connection = lambda: _Conn()
+    a._return_connection = lambda c: None
+    a._apply_session_vars = lambda c, v: None
+    a._timed_execute = lambda cur, sql, params, **k: captured.append((sql, params))
+    a._serialize_params = lambda p: p
+    a._deserialize_row = lambda r: r
+    return a
+
+
+def test_postgres_select_names_the_columns():
+    cap = []
+    rows = _pg(cap).select("orders", {"tenant_id": "t"}, limit=5, fields=["id", "status"])
+    assert cap[0][0].startswith("SELECT id, status FROM orders WHERE tenant_id = %s")
+    assert rows == [{"id": "1", "status": "ok"}]
+
+
+def test_postgres_select_without_fields_is_unchanged_and_bad_names_are_refused():
+    cap = []
+    _pg(cap).select("orders", {})
+    assert cap[0][0] == "SELECT * FROM orders"
+    with pytest.raises(Exception):
+        _pg([]).select("orders", {}, fields=["id; DROP TABLE orders"])