plain.postgres 0.110.2__tar.gz → 0.111.0__tar.gz

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.110.2
+Version: 0.111.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,17 @@
 # plain-postgres changelog
 
+## [0.111.0](https://github.com/dropseed/plain/releases/plain-postgres@0.111.0) (2026-06-30)
+
+### What's changed
+
+- Slicing a `QuerySet` now always returns a `QuerySet`, even when its results are already cached — previously, slicing an already-evaluated queryset returned a plain `list`. The returned queryset carries the sliced cache, so iterating it won't re-query, but re-chaining it (adding a `.filter()`, ordering, etc.) drops the cache and applies the slice as SQL `LIMIT`/`OFFSET` so the rows stay correct. ([d60e07d6ad](https://github.com/dropseed/plain/commit/d60e07d6ad))
+- Step slicing (e.g. `qs[::2]`) now raises `ValueError` instead of silently evaluating the queryset and returning a stepped `list`. Negative indexing and negative slice bounds continue to raise, as before. `RawQuerySet` is unaffected — it is always fully materialized, so its slicing keeps plain `list` semantics, where step and negative slicing still work. ([d60e07d6ad](https://github.com/dropseed/plain/commit/d60e07d6ad), [a873a521d4](https://github.com/dropseed/plain/commit/a873a521d4))
+
+### Upgrade instructions
+
+- If you relied on `queryset[a:b]` returning a `list` — for example checking `isinstance(result, list)`, calling list methods like `.append()` on it, or re-slicing it with a step — wrap it in `list(queryset[a:b])` to materialize it explicitly.
+- Replace any step slicing of a queryset (`queryset[::2]`) with a `list(...)` conversion first, since it now raises `ValueError`.
+
 ## [0.110.2](https://github.com/dropseed/plain/releases/plain-postgres@0.110.2) (2026-06-26)
 
 ### What's changed

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/plain/postgres/query.py

@@ -423,38 +423,47 @@ class QuerySet[T: "Model"]:
     def __getitem__(self, k: int) -> T: ...
 
     @overload
-    def __getitem__(self, k: slice) -> QuerySet[T] | list[T]: ...
+    def __getitem__(self, k: slice) -> QuerySet[T]: ...
 
-    def __getitem__(self, k: int | slice) -> T | QuerySet[T] | list[T]:
-        """Retrieve an item or slice from the set of results."""
+    def __getitem__(self, k: int | slice) -> T | QuerySet[T]:
+        """Retrieve an item or slice from the set of results.
+
+        Slicing always returns a QuerySet, even when the results are
+        already cached. The returned QuerySet behaves exactly like one
+        sliced before evaluation — same allowed operations — except it
+        carries the sliced cache so iterating it won't re-query. The slice
+        is also applied as SQL limits, so any operation that re-chains the
+        QuerySet drops the cache and re-queries the correct rows.
+
+        Negative indexing and step slicing both raise.
+        """
         if not isinstance(k, int | slice):
             raise TypeError(
                 f"QuerySet indices must be integers or slices, not {type(k).__name__}."
             )
-        if (isinstance(k, int) and k < 0) or (
-            isinstance(k, slice)
-            and (
-                (k.start is not None and k.start < 0)
-                or (k.stop is not None and k.stop < 0)
-            )
-        ):
-            raise ValueError("Negative indexing is not supported.")
-
-        if self._result_cache is not None:
-            return self._result_cache[k]
 
         if isinstance(k, slice):
+            if (k.start is not None and k.start < 0) or (
+                k.stop is not None and k.stop < 0
+            ):
+                raise ValueError("Negative indexing is not supported.")
+            if k.step is not None:
+                raise ValueError("Step slicing is not supported.")
             qs = self._chain()
-            if k.start is not None:
-                start = int(k.start)
-            else:
-                start = None
-            if k.stop is not None:
-                stop = int(k.stop)
-            else:
-                stop = None
+            start = int(k.start) if k.start is not None else None
+            stop = int(k.stop) if k.stop is not None else None
             qs.sql_query.set_limits(start, stop)
-            return list(qs)[:: k.step] if k.step else qs
+            if self._result_cache is not None:
+                # Carry the sliced cache so the new QuerySet won't re-query on
+                # iteration. The SQL limits above keep it correct if it's later
+                # re-chained, which drops the cache.
+                self._attach_result_cache(qs, self._result_cache[k])
+            return qs
+
+        if k < 0:
+            raise ValueError("Negative indexing is not supported.")
+        if self._result_cache is not None:
+            return self._result_cache[k]
 
         qs = self._chain()
         qs.sql_query.set_limits(k, k + 1)
@@ -1136,9 +1145,8 @@ class QuerySet[T: "Model"]:
         """
         obj = self._chain()
         # Preserve cache since all() doesn't modify the query.
-        # This is important for prefetch_related() to work correctly.
-        obj._result_cache = self._result_cache
-        obj._prefetch_done = self._prefetch_done
+        if self._result_cache is not None:
+            self._attach_result_cache(obj, self._result_cache)
         return obj
 
     def filter(self, *args: Any, **kwargs: Any) -> Self:
@@ -1511,6 +1519,17 @@ class QuerySet[T: "Model"]:
         c._fields = self._fields
         return c
 
+    def _attach_result_cache(self, obj: Self, cache: list[T]) -> None:
+        """Carry a result cache onto a chained QuerySet.
+
+        Whenever a cache is moved onto a new QuerySet, the prefetch state
+        must ride along with it — otherwise prefetch_related() would re-run
+        (or be skipped). Keep both writes together here so callers can't
+        forget the pairing.
+        """
+        obj._result_cache = cache
+        obj._prefetch_done = self._prefetch_done
+
     def _fetch_all(self) -> None:
         if self._result_cache is None:
             self._result_cache = list(self._iterable_class(self))
@@ -1691,6 +1710,9 @@ class RawQuerySet:
         return f"<{self.__class__.__name__}: {self.sql_query}>"
 
     def __getitem__(self, k: int | slice) -> Model | list[Model]:
+        # Unlike QuerySet, a RawQuerySet is always fully materialized — there's
+        # no lazy query to push a slice into — so indexing keeps plain list
+        # semantics: a slice returns a list (and step/negative slicing work).
         return list(self)[k]
 
     @cached_property

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.110.2"
+version = "0.111.0"
 description = "Model your data and store it in a database."
 authors = [{ name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev" }]
 readme = "README.md"

plain_postgres-0.111.0/tests/conftest.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+import pytest
+
+from plain.postgres.connection import DatabaseConnection
+from plain.postgres.db import _db_conn, get_connection
+
+
+@pytest.fixture
+def capture_queries():
+    """Return a context manager that records the SQL run within its block.
+
+        with capture_queries() as queries:
+            list(qs)
+        assert len(queries) == 1
+
+    ``queries`` is populated when the block exits with the executed query
+    dicts (each has a ``"sql"`` key), so inspect it after the ``with``.
+    """
+
+    @contextmanager
+    def _capture():
+        conn = get_connection()
+        previous = conn.force_debug_cursor
+        conn.force_debug_cursor = True
+        conn.queries_log.clear()
+        captured: list[dict] = []
+        try:
+            yield captured
+        finally:
+            captured.extend(conn.queries_log)
+            conn.force_debug_cursor = previous
+
+    return _capture
+
+
+@pytest.fixture
+def _unblock_cursor() -> None:
+    """Restore the real cursor method (blocked by the autouse _db_disabled fixture)."""
+    DatabaseConnection.cursor = getattr(DatabaseConnection, "_enabled_cursor")
+
+
+@pytest.fixture
+def _clean_connection():
+    """Ensure the ContextVar starts empty and clean up any connection afterward."""
+    token = _db_conn.set(None)
+    yield
+    conn = _db_conn.get()
+    if conn is not None:
+        try:
+            conn.close()
+        except Exception:
+            pass
+    _db_conn.reset(token)

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/tests/internal/test_constraint_violation_error.py

@@ -12,7 +12,6 @@ from app.examples.models.constraints import ConstraintExample
 from plain.exceptions import NON_FIELD_ERRORS, ValidationError
 from plain.postgres import CheckConstraint, Q, UniqueConstraint
 from plain.postgres.constraints import BaseConstraint
-from plain.postgres.db import get_connection
 from plain.postgres.expressions import F
 from plain.postgres.forms import ModelForm
 from plain.test import RequestFactory
@@ -172,20 +171,13 @@ def test_save_runs_full_clean_by_default(
     assert ConstraintExample.query.filter(name="bad").count() == 0
 
 
-def test_save_skips_constraint_pre_check_select(db: None) -> None:
+def test_save_skips_constraint_pre_check_select(db: None, capture_queries) -> None:
     """A default save() issues only the INSERT — the per-unique-constraint
     pre-check SELECT is gone. The database enforces the constraint and
     save_base maps any violation."""
-    conn = get_connection()
-    previous = conn.force_debug_cursor
-    conn.force_debug_cursor = True
-    conn.queries_log.clear()
-    try:
+    with capture_queries() as queries:
         ConstraintExample(name="solo", description="row").create()
-        query_count = len(conn.queries_log)
-    finally:
-        conn.force_debug_cursor = previous
-    assert query_count == 1, [q["sql"] for q in conn.queries_log]
+    assert len(queries) == 1, [q["sql"] for q in queries]
 
 
 def test_save_clean_and_validate_false_skips_validation(

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/tests/internal/test_convergence_constraints.py

@@ -1379,7 +1379,9 @@ class TestProbeTableReuse:
     """analyze_model creates the probe temp table once per model and reuses it
     for every round-trip, instead of churning one CREATE/DROP per comparison."""
 
-    def test_analyze_model_shares_one_temp_table_across_round_trips(self, db):
+    def test_analyze_model_shares_one_temp_table_across_round_trips(
+        self, db, capture_queries
+    ):
         from plain.postgres.convergence.analysis import _PROBE_TABLE
 
         # ConstraintExample already has a converged UNIQUE constraint (one
@@ -1398,15 +1400,12 @@ class TestProbeTableReuse:
         )
 
         conn = get_connection()
-        previous = conn.force_debug_cursor
-        conn.force_debug_cursor = True
-        conn.queries_log.clear()
         try:
-            with conn.cursor() as cursor:
-                analyze_model(conn, cursor, ConstraintExample)
-            sqls = [q["sql"] for q in conn.queries_log]
+            with capture_queries() as queries:
+                with conn.cursor() as cursor:
+                    analyze_model(conn, cursor, ConstraintExample)
+            sqls = [q["sql"] for q in queries]
         finally:
-            conn.force_debug_cursor = previous
             ConstraintExample.model_options.constraints = original
             execute(
                 'ALTER TABLE "examples_constraintexample" DROP CONSTRAINT '

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/tests/public/test_deferred_loading.py

@@ -9,20 +9,6 @@ from __future__ import annotations
 
 from app.examples.models.relationships import Tag, Widget, WidgetTag
 
-from plain.postgres.db import get_connection
-
-
-def _count_queries(fn):
-    conn = get_connection()
-    previous = conn.force_debug_cursor
-    conn.force_debug_cursor = True
-    conn.queries_log.clear()
-    try:
-        result = fn()
-        return result, len(conn.queries_log)
-    finally:
-        conn.force_debug_cursor = previous
-
 
 def test_only_defers_unlisted_fields(db):
     Widget.query.create(name="W", size="L")
@@ -43,11 +29,12 @@ def test_deferred_field_loads_correct_value(db):
     assert widget.size == "L"
 
 
-def test_listed_field_is_available_without_a_query(db):
+def test_listed_field_is_available_without_a_query(db, capture_queries):
     Widget.query.create(name="W", size="L")
     widget = Widget.query.only("id", "name").get()
-    _, queries = _count_queries(lambda: widget.name)
-    assert queries == 0
+    with capture_queries() as queries:
+        _ = widget.name
+    assert len(queries) == 0
 
 
 def test_refresh_from_db_reloads_values(db):
@@ -57,20 +44,22 @@ def test_refresh_from_db_reloads_values(db):
     assert widget.name == "changed"
 
 
-def test_deferred_field_access_query_count(db):
+def test_deferred_field_access_query_count(db, capture_queries):
     # WAS: each deferred field loaded in its own query (two fields = two
     # queries). NOW: the first deferred access hydrates every still-missing
     # field, so the second field needs no further query.
     Widget.query.create(name="W", size="L")
     widget = Widget.query.only("id").get()
 
-    _, first = _count_queries(lambda: widget.name)
-    assert first == 1
-    _, second = _count_queries(lambda: widget.size)
-    assert second == 0
+    with capture_queries() as first:
+        _ = widget.name
+    assert len(first) == 1
+    with capture_queries() as second:
+        _ = widget.size
+    assert len(second) == 0
 
 
-def test_deferred_fk_column_loads_only_the_fk(db):
+def test_deferred_fk_column_loads_only_the_fk(db, capture_queries):
     # The foreign key descriptor is the partial-related-instance fast path:
     # hydrating other deferred columns just to materialize a related-object
     # handle would defeat the optimization. So accessing a deferred FK loads
@@ -84,8 +73,9 @@ def test_deferred_fk_column_loads_only_the_fk(db):
     assert widget_tag.get_deferred_fields() == {"widget", "tag"}
 
     # Accessing the deferred FK loads exactly one column (the FK column).
-    _, queries = _count_queries(lambda: widget_tag.widget)
-    assert queries == 1
+    with capture_queries() as queries:
+        _ = widget_tag.widget
+    assert len(queries) == 1
     # The other deferred FK column is still deferred -- not hydrated as a
     # side effect of the first FK access.
     assert "tag" in widget_tag.get_deferred_fields()

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/tests/public/test_delete_behaviors.py

@@ -376,7 +376,7 @@ def test_delete_rejects_sliced_queryset(db):
     _create_parents()
     qs = DeleteParent.query.all()[:1]
     with pytest.raises(TypeError):
-        qs.delete()  # ty: ignore[unresolved-attribute]
+        qs.delete()
 
 
 def test_delete_rejects_distinct_queryset(db):
@@ -485,25 +485,17 @@ def test_delete_already_deleted_instance_raises(db):
 # ===========================================================================
 
 
-def test_cascade_delete_issues_one_query(db):
+def test_cascade_delete_issues_one_query(db, capture_queries):
     """Single-level CASCADE fires exactly one DELETE — Postgres handles the
     cascade internally. This is the headline win of the DB-level rewrite."""
-    from plain.postgres.db import get_connection
-
     _create_parents()
     parent = DeleteParent.query.get(name="parent")
     for _ in range(5):
         ChildCascade.query.create(parent=parent)
 
-    conn = get_connection()
-    prev_force = conn.force_debug_cursor
-    conn.force_debug_cursor = True
-    conn.queries_log.clear()
-    try:
+    with capture_queries() as queries:
         parent.delete()
-        query_count = len(conn.queries_log)
-    finally:
-        conn.force_debug_cursor = prev_force
+    query_count = len(queries)
 
     assert query_count == 1, (
         f"Expected one DELETE; got {query_count} queries — Collector may have "

{plain_postgres-0.110.2 → plain_postgres-0.111.0}/tests/public/test_queryset_repr.py

@@ -2,22 +2,8 @@ from __future__ import annotations
 
 from app.examples.models.iteration import IterationExample
 
-from plain.postgres.db import get_connection
 
-
-def _capture_queries(callable_):
-    conn = get_connection()
-    prev_force = conn.force_debug_cursor
-    conn.force_debug_cursor = True
-    conn.queries_log.clear()
-    try:
-        callable_()
-        return list(conn.queries_log)
-    finally:
-        conn.force_debug_cursor = prev_force
-
-
-def test_repr_does_not_execute_sql_when_unevaluated(db):
+def test_repr_does_not_execute_sql_when_unevaluated(db, capture_queries):
     """repr() of an unevaluated queryset must not issue a SQL query.
 
     Error reporters (Sentry, pdb, exception templates) call repr() on
@@ -26,13 +12,14 @@ def test_repr_does_not_execute_sql_when_unevaluated(db):
     """
     qs = IterationExample.query.all()
 
-    queries = _capture_queries(lambda: repr(qs))
+    with capture_queries() as queries:
+        repr(qs)
 
     assert queries == []
     assert repr(qs) == "<QuerySet [unevaluated]>"
 
 
-def test_repr_uses_cache_when_evaluated(db):
+def test_repr_uses_cache_when_evaluated(db, capture_queries):
     """Once a queryset is evaluated, repr() reflects its rows without re-querying."""
     IterationExample.query.create(name="alpha", tag="a")
     IterationExample.query.create(name="beta", tag="b")
@@ -40,7 +27,8 @@ def test_repr_uses_cache_when_evaluated(db):
     qs = IterationExample.query.all()
     list(qs)  # force evaluation, populates _result_cache
 
-    queries = _capture_queries(lambda: repr(qs))
+    with capture_queries() as queries:
+        repr(qs)
 
     assert queries == []
     rendered = repr(qs)

plain_postgres-0.111.0/tests/public/test_queryset_slicing.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import pytest
+from app.examples.models.iteration import IterationExample
+
+from plain.postgres import F, QuerySet
+
+
+@pytest.fixture
+def rows(db):
+    for i in range(25):
+        IterationExample.query.create(name=f"name{i:02d}", tag="t")
+
+
+def test_slice_of_unevaluated_queryset_returns_queryset(rows):
+    sliced = IterationExample.query.order_by("name")[:5]
+
+    assert isinstance(sliced, QuerySet)
+    assert [r.name for r in sliced] == [f"name{i:02d}" for i in range(5)]
+
+
+def test_slice_of_evaluated_queryset_returns_queryset(rows):
+    """Slicing a cached queryset returns a QuerySet, not a list.
+
+    Previously an evaluated queryset sliced to a plain list, so the return
+    type depended on whether the queryset had been iterated first.
+    """
+    qs = IterationExample.query.order_by("name")
+    list(qs)  # evaluate -> populates _result_cache
+
+    sliced = qs[:5]
+
+    assert isinstance(sliced, QuerySet)
+    assert [r.name for r in sliced] == [f"name{i:02d}" for i in range(5)]
+
+
+def test_slice_of_evaluated_queryset_does_not_requery(rows, capture_queries):
+    """Iterating a cached slice reuses the cache instead of hitting the DB."""
+    qs = IterationExample.query.order_by("name")
+    list(qs)  # evaluate
+
+    with capture_queries() as queries:
+        list(qs[:5])
+
+    assert queries == []
+
+
+def test_cached_slice_matches_sql_slice(rows):
+    """A cached slice yields the same rows as slicing via SQL limits."""
+    sql_slice = [r.name for r in IterationExample.query.order_by("name")[3:9]]
+
+    evaluated = IterationExample.query.order_by("name")
+    list(evaluated)  # evaluate
+    cache_slice = [r.name for r in evaluated[3:9]]
+
+    assert cache_slice == sql_slice == [f"name{i:02d}" for i in range(3, 9)]
+
+
+def test_reslicing_cached_slice_composes(rows):
+    """Re-slicing a cached slice composes offsets correctly."""
+    qs = IterationExample.query.order_by("name")
+    list(qs)
+
+    inner = qs[5:15][2:4]
+
+    assert isinstance(inner, QuerySet)
+    assert [r.name for r in inner] == [f"name{i:02d}" for i in range(7, 9)]
+
+
+def test_filtering_a_cached_slice_raises_like_any_slice(rows):
+    """A cached slice obeys the same "no filtering after slicing" rule."""
+    qs = IterationExample.query.order_by("name")
+    list(qs)
+    sliced = qs[:5]
+
+    with pytest.raises(TypeError, match="once a slice has been taken"):
+        sliced.filter(tag="t")
+
+
+def test_step_slicing_raises_when_unevaluated(rows):
+    with pytest.raises(ValueError, match="Step slicing is not supported"):
+        IterationExample.query.all()[::2]
+
+
+def test_step_slicing_raises_when_evaluated(rows):
+    qs = IterationExample.query.all()
+    list(qs)
+
+    with pytest.raises(ValueError, match="Step slicing is not supported"):
+        qs[::2]
+
+
+def test_negative_slicing_raises(rows):
+    with pytest.raises(ValueError, match="Negative indexing is not supported"):
+        IterationExample.query.all()[-1:]
+
+
+def test_slice_then_annotate_works_regardless_of_evaluation(rows):
+    """A function slicing then annotating behaves the same either way.
+
+    This is the motivating case: previously, passing an already-evaluated
+    queryset made `qs[:n]` a list and the `.annotate()` raised
+    AttributeError. Now it works whether or not the caller evaluated first.
+    """
+
+    def slice_then_annotate(qs):
+        return qs[:5].annotate(name2=F("name"))
+
+    unevaluated = IterationExample.query.order_by("name")
+    from_unevaluated = [r.name2 for r in slice_then_annotate(unevaluated)]
+
+    evaluated = IterationExample.query.order_by("name")
+    list(evaluated)  # evaluate first
+    from_evaluated = [r.name2 for r in slice_then_annotate(evaluated)]
+
+    assert from_unevaluated == from_evaluated == [f"name{i:02d}" for i in range(5)]
+
+
+def test_values_list_cached_slice_reuses_cache(rows, capture_queries):
+    """A cached values_list() slice stays a QuerySet and reuses the cache.
+
+    values()/values_list() use a different iterable class than the default
+    model iterable, so exercise that the cache-carry path works for it too.
+    """
+    qs = IterationExample.query.order_by("name").values_list("name", flat=True)
+    list(qs)  # evaluate -> cache holds the values
+
+    sliced = qs[:3]
+    with capture_queries() as queries:
+        list(sliced)
+
+    assert isinstance(sliced, QuerySet)
+    assert queries == []
+    assert list(sliced) == [f"name{i:02d}" for i in range(3)]
+
+
+def test_integer_index_on_cached_queryset_returns_item(rows):
+    qs = IterationExample.query.order_by("name")
+    list(qs)
+
+    item = qs[0]
+
+    assert isinstance(item, IterationExample)
+    assert item.name == "name00"