fpstreams 2.2.0__tar.gz → 2.2.1__tar.gz

{fpstreams-2.2.0 → fpstreams-2.2.1}/CHANGELOG.md

@@ -5,6 +5,22 @@ including changed defaults.
 
 ## Unreleased
 
+## 2.2.1 - 2026-10-07
+
+### Fixed
+
+- Editors resolve the public `rows` factory directly, preserving method completion,
+  parameter hints, and docstrings instead of treating it as the record module.
+- Core `flow()` and `rows()` factories retain iterable element types without optional
+  data adapters installed. A shared series protocol preserves one-dimensional series
+  typing without importing Polars into the core type declarations.
+
+### Changed
+
+- Automatic planning skips NumPy buffer probes for exact list, tuple, and range
+  sources. Python identity terminal plans on exact containers also avoid a temporary
+  decision object, reducing the fixed cost of small workloads.
+
 ## 2.2.0 - 2026-10-06
 
 ### Added

{fpstreams-2.2.0 → fpstreams-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fpstreams
-Version: 2.2.0
+Version: 2.2.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -87,6 +87,16 @@ python -m pip install "fpstreams[data]"    # NumPy, pandas, and PyArrow
 python -m pip install "fpstreams[polars]"  # Polars and PyArrow
 ~~~
 
+## Editor support
+
+fpstreams includes inline type annotations, docstrings, and the `py.typed` marker.
+Select the Python interpreter where fpstreams is installed in your editor to get
+method completions, parameter hints, and hover documentation.
+
+Version 2.2.1 fixes `rows` factory completion and keeps core
+iterable element types when optional data adapters are absent. For example,
+`flow([1, 2, 3])` is inferred as `Flow[int]`.
+
 ## Quick start
 
 This example filters paid orders, groups them by region, and reports both the

{fpstreams-2.2.0 → fpstreams-2.2.1}/README.md

@@ -32,6 +32,16 @@ python -m pip install "fpstreams[data]"    # NumPy, pandas, and PyArrow
 python -m pip install "fpstreams[polars]"  # Polars and PyArrow
 ~~~
 
+## Editor support
+
+fpstreams includes inline type annotations, docstrings, and the `py.typed` marker.
+Select the Python interpreter where fpstreams is installed in your editor to get
+method completions, parameter hints, and hover documentation.
+
+Version 2.2.1 fixes `rows` factory completion and keeps core
+iterable element types when optional data adapters are absent. For example,
+`flow([1, 2, 3])` is inferred as `Flow[int]`.
+
 ## Quick start
 
 This example filters paid orders, groups them by region, and reports both the

{fpstreams-2.2.0 → fpstreams-2.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "fpstreams"
-version = "2.2.0"
+version = "2.2.1"
 description = "Lazy Python pipelines for iterables and records, with bounded async concurrency."
 readme = "README.md"
 authors = [

{fpstreams-2.2.0 → fpstreams-2.2.1}/rust/Cargo.lock

@@ -4,7 +4,7 @@ version = 4
 
 [[package]]
 name = "fpstreams-native"
-version = "2.2.0"
+version = "2.2.1"
 dependencies = [
  "pyo3",
  "pyo3-build-config",

{fpstreams-2.2.0 → fpstreams-2.2.1}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fpstreams-native"
-version = "2.2.0"
+version = "2.2.1"
 edition = "2024"
 rust-version = "1.85"
 description = "Native fused execution kernels for fpstreams."

{fpstreams-2.2.0 → fpstreams-2.2.1}/src/fpstreams/__init__.py

@@ -39,9 +39,10 @@ from .streams import (
     flow,
     pairs,
 )
-from .tabular import Rows, SpillLimits, rows
+from .tabular import Rows, SpillLimits
+from .tabular.factory import rows as rows
 
-__version__ = "2.2.0"
+__version__ = "2.2.1"
 Stream = Flow
 ParallelStream = Flow
 

{fpstreams-2.2.0 → fpstreams-2.2.1}/src/fpstreams/planning/native.py

@@ -44,6 +44,9 @@ _I64_MIN = -(2**63)
 _I64_MAX = 2**63 - 1
 _AUTO_THRESHOLD = 8
 _AUTO_IDENTITY_I64_SUM_THRESHOLD = 65_536
+_AUTO_IDENTITY_CONTAINER_REASON = (
+    "identity list/tuple stays in Python below its direct native crossover"
+)
 _COPY_SHORT_CIRCUIT_LIMIT = 1_024
 _COPY_SHORT_CIRCUIT_RATIO = 64
 _ALLOCATING_I64_MAP_ROOTS = frozenset({"add", "sub", "mul", "floordiv", "neg"})
@@ -108,61 +111,65 @@ def validate_terminal(terminal: str) -> TerminalName:
 
 
 def _terminal_metadata(
-    decision: EngineDecision,
+    decision: EngineDecision | None,
     plan: Pipeline,
     terminal: TerminalName,
     *,
     source_is_container: bool | None = None,
+    python_reason: str = "",
 ) -> EngineDecision:
-    """Attach worst-case data movement and complexity metadata to a terminal decision."""
+    """Attach terminal metadata, constructing a Python-only decision in one allocation."""
     source = plan.source.native_data
-    crosses_native_boundary = decision.engine in {"native", "hybrid"}
+    engine = "python" if decision is None else decision.engine
+    program = None if decision is None else decision.program
+    crosses_native_boundary = engine in {"native", "hybrid"}
     if source_is_container is None:
         source_is_container = (
             isinstance(source, (list, tuple)) or _numpy_buffer_kind(source) is not None
         )
     metadata_count = terminal == "count" and exact_count(plan) is not None
     direct_i64_container_sum = (
-        decision.engine == "native"
-        and decision.program is not None
-        and decision.program.kind == "i64"
-        and not decision.program.stages
+        engine == "native"
+        and program is not None
+        and program.kind == "i64"
+        and not program.stages
         and type(source) in (list, tuple)
         and terminal == "sum"
     )
     direct_exact_container_mean = (
-        decision.engine == "native"
-        and decision.program is not None
-        and not decision.program.stages
+        engine == "native"
+        and program is not None
+        and not program.stages
         and type(source) in (list, tuple)
         and terminal == "mean"
         and _exact_number_mean_available()
     )
     range_metadata = (
-        decision.engine == "native"
+        engine == "native"
         and type(source) is range
         and not plan.operations
         and terminal in {"sum", "min", "max", "last"}
     )
     probe_path = (
-        decision.engine == "native"
-        and decision.program is not None
+        engine == "native"
+        and program is not None
         and type(source) in (list, tuple)
         and terminal in {"first", "any", "all"}
-        and _container_probe_available(decision.program.kind)
+        and _container_probe_available(program.kind)
     )
+    decision_reason = python_reason if decision is None else decision.reason
     reason = (
-        f"{decision.reason}; bounded probe; only undecided fallback bulk-copies"
+        f"{decision_reason}; bounded probe; only undecided fallback bulk-copies"
         if probe_path
-        else f"{decision.reason}; retained range terminal uses constant-time metadata"
+        else f"{decision_reason}; retained range terminal uses constant-time metadata"
         if range_metadata
-        else decision.reason
+        else decision_reason
     )
     return EngineDecision(
-        decision.engine,
+        engine,
         reason,
-        decision.program,
-        decision.native_operation_count,
+        program,
+        0 if decision is None else decision.native_operation_count,
         # An undecided bounded probe restarts the legacy bulk adapter, and numeric
         # buffer kernels may snapshot exporters before detached computation.
         scans_source=crosses_native_boundary and source_is_container and not metadata_count,
@@ -173,7 +180,7 @@ def _terminal_metadata(
             and not direct_i64_container_sum
             and not direct_exact_container_mean
         ),
-        materializes=terminal == "list" or decision.engine == "hybrid",
+        materializes=terminal == "list" or engine == "hybrid",
         complexity=(
             "O(1)"
             if metadata_count or range_metadata
@@ -234,6 +241,9 @@ def _numpy_f64_buffer(source: object) -> Any | None:
 
 def _numpy_buffer_kind(source: object) -> NativeKind | None:
     """Return the exact native representation exposed by an explicit NumPy column."""
+    source_type = type(source)
+    if source_type is list or source_type is tuple or source_type is range:
+        return None
     if _numpy_i64_buffer(source) is not None:
         return "i64"
     if _numpy_f64_buffer(source) is not None:
@@ -783,6 +793,45 @@ def _buffer_short_circuit_decision(
     return None
 
 
+def _identity_source_terminal_context(
+    plan: Pipeline,
+    terminal: TerminalName,
+    source: object,
+) -> tuple[EngineDecision | None, NativeKind | None, bool]:
+    """Choose exact-container routes before considering numeric buffer metadata."""
+    source_type = type(source)
+    if (
+        plan.engine == "auto"
+        and (source_type is list or source_type is tuple)
+        and terminal not in {"mean", "statistics"}
+        and not _auto_direct_i64_sum_candidate(source, terminal)
+    ):
+        return (
+            _terminal_metadata(
+                None,
+                plan,
+                terminal,
+                source_is_container=True,
+                python_reason=_AUTO_IDENTITY_CONTAINER_REASON,
+            ),
+            None,
+            True,
+        )
+    buffer_kind = _numpy_buffer_kind(source)
+    source_is_container = isinstance(source, (list, tuple)) or buffer_kind is not None
+    return (
+        _forced_native_exact_count_decision(
+            plan,
+            terminal,
+            source,
+            buffer_kind,
+            source_is_container=source_is_container,
+        ),
+        buffer_kind,
+        source_is_container,
+    )
+
+
 def _select_operation_terminal_engine(
     plan: Pipeline,
     terminal: TerminalName,
@@ -850,17 +899,11 @@ def select_terminal_engine(plan: Pipeline, terminal: TerminalName) -> EngineDeci
     source = plan.source.native_data
     if retained_one_shot := _retained_one_shot_decision(plan):
         return _terminal_metadata(retained_one_shot, plan, terminal)
-    buffer_kind = _numpy_buffer_kind(source)
-    source_is_container = isinstance(source, (list, tuple)) or buffer_kind is not None
-    metadata_count = _forced_native_exact_count_decision(
-        plan,
-        terminal,
-        source,
-        buffer_kind,
-        source_is_container=source_is_container,
+    source_decision, buffer_kind, source_is_container = _identity_source_terminal_context(
+        plan, terminal, source
     )
-    if metadata_count is not None:
-        return metadata_count
+    if source_decision is not None:
+        return source_decision
     if buffered := _buffer_short_circuit_decision(plan, terminal, buffer_kind):
         return _terminal_metadata(
             buffered,
@@ -875,10 +918,7 @@ def select_terminal_engine(plan: Pipeline, terminal: TerminalName) -> EngineDeci
         and not _auto_direct_i64_sum_candidate(source, terminal)
     ):
         return _terminal_metadata(
-            EngineDecision(
-                "python",
-                "identity list/tuple stays in Python below its direct native crossover",
-            ),
+            EngineDecision("python", _AUTO_IDENTITY_CONTAINER_REASON),
             plan,
             terminal,
             source_is_container=source_is_container,

{fpstreams-2.2.0 → fpstreams-2.2.1}/src/fpstreams/streams/flow.py

@@ -10,7 +10,6 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from importlib import import_module
 from typing import (
-    TYPE_CHECKING,
     Any,
     Generic,
     Literal,
@@ -22,9 +21,6 @@ from typing import (
 
 import fpstreams
 
-if TYPE_CHECKING:
-    import polars as pl
-
 from ..expressions.selectors import Selector, compile_selector
 from ..planning.explain import PlanExplanation, explain_query
 from ..planning.gather import Gatherer
@@ -95,6 +91,17 @@ _MISSING = object()
 _TABULAR_MODULE_ROOTS = frozenset(("pandas", "polars", "pyarrow"))
 
 
+class _SeriesSource(Protocol[T]):
+    """Describe a one-dimensional series without importing an optional adapter."""
+
+    @property
+    def shape(self) -> tuple[int]: ...
+
+    def __iter__(self) -> Iterator[T]: ...
+
+    def to_list(self) -> list[T]: ...
+
+
 class _ArrowCStreamProvider(Protocol):
     """Static shape of the Arrow PyCapsule stream protocol."""
 
@@ -1365,14 +1372,6 @@ class _FlowFactory:
                 return self.from_dataframe(source)
         return None
 
-    if TYPE_CHECKING:
-
-        @overload
-        def __call__(
-            self,
-            source: pl.Series,
-        ) -> Flow[Any]: ...
-
     @overload
     def __call__(self, source: Flow[T]) -> Flow[T]: ...
 
@@ -1381,6 +1380,9 @@ class _FlowFactory:
     # before considering structural tabular protocols.
     def __call__(self, source: fpstreams.Rows[T]) -> Flow[T]: ...  # type: ignore[overload-overlap]
 
+    @overload
+    def __call__(self, source: _SeriesSource[T]) -> Flow[T]: ...
+
     @overload
     def __call__(
         self,

{fpstreams-2.2.0 → fpstreams-2.2.1}/src/fpstreams/tabular/__init__.py

@@ -1,8 +1,10 @@
 """Record-oriented pipelines and tabular interoperability."""
 
-from .factory import rows
+from .factory import rows as _rows_factory
 from .grouped import GroupedRows
 from .rows import Rows
 from .spill_limits import SpillLimits
 
+rows = _rows_factory
+
 __all__ = ["GroupedRows", "Rows", "SpillLimits", "rows"]

{fpstreams-2.2.0 → fpstreams-2.2.1}/src/fpstreams/tabular/factory.py

@@ -4,13 +4,10 @@ from __future__ import annotations
 
 import os
 from collections.abc import Callable, Iterable, Mapping
-from typing import TYPE_CHECKING, Any, BinaryIO, TextIO, TypeAlias, TypeVar, overload
-
-if TYPE_CHECKING:
-    import polars as pl
+from typing import Any, BinaryIO, TextIO, TypeAlias, TypeVar, overload
 
 from ..expressions.selectors import Selector
-from ..streams.flow import Flow, _ArrowCStreamProvider, _DataFrameProvider
+from ..streams.flow import Flow, _ArrowCStreamProvider, _DataFrameProvider, _SeriesSource
 from .rows import Rows
 from .sql import (
     ConnectionFactory,
@@ -26,14 +23,6 @@ class _RowsFactory:
 
     __slots__ = ()
 
-    if TYPE_CHECKING:
-
-        @overload
-        def __call__(
-            self,
-            source: pl.Series,
-        ) -> Rows[Any]: ...
-
     @overload
     def __call__(self, source: Flow[T]) -> Rows[T]: ...
 
@@ -41,6 +30,9 @@ class _RowsFactory:
     # Rows also exports Arrow, but the compatibility factory must preserve its record type.
     def __call__(self, source: Rows[T]) -> Rows[T]: ...  # type: ignore[overload-overlap]
 
+    @overload
+    def __call__(self, source: _SeriesSource[T]) -> Rows[T]: ...
+
     @overload
     def __call__(
         self,