flpit 0.1.1.dev3__tar.gz → 0.1.3__tar.gz

{flpit-0.1.1.dev3 → flpit-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flpit
-Version: 0.1.1.dev3
+Version: 0.1.3
 Summary: Fluent LINQ for Python — flip your iterables
 License: MIT
 Classifier: Development Status :: 3 - Alpha

{flpit-0.1.1.dev3 → flpit-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.1.1.dev3"
+version = "0.1.3"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,6 +25,7 @@ dev = [
     "hypothesis>=6.168.0",
     "pyrefly>=1.3.1",
     "pyright>=1.1.414",
+    "pytest-benchmark>=5.3.0",
 ]
 
 [build-system]
@@ -42,3 +43,7 @@ exclude = [
     "tests",
 ]
 typeCheckingMode = "basic"
+
+[tool.pytest.ini_options]
+addopts = "-m 'not benchmark'"
+markers = ["benchmark: performance benchmarks"]

{flpit-0.1.1.dev3 → flpit-0.1.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.1.1.dev3"
+version = "0.1.3"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,6 +23,7 @@ dev = [
     "hypothesis>=6.168.0",
     "pyrefly>=1.3.1",
     "pyright>=1.1.414",
+    "pytest-benchmark>=5.3.0",
 ]
 
 [build-system]
@@ -37,3 +38,12 @@ module-root = "src"
 include = ["src"]
 exclude = ["**/__pycache__", "tests"]
 typeCheckingMode = "basic"
+
+[tool.pytest.ini_options]
+addopts = "-m 'not benchmark'"
+markers = [
+    "benchmark: performance benchmarks",
+]
+#[tool.pyrefly]
+#extra-paths = ["src", "tests"]
+#python-interpreter-path = ".venv/bin/python" # or .venv/Scripts/python.exe on Windows

{flpit-0.1.1.dev3 → flpit-0.1.3}/src/flp/core/linq.py

@@ -1,4 +1,7 @@
 from __future__ import annotations
+from threading import Lock
+
+from typing import cast
 
 import builtins
 from collections import UserList
@@ -28,12 +31,25 @@ TOther = TypeVar("TOther")
 TAccumulate = TypeVar("TAccumulate")
 
 _SENTINEL = object()
+_MISSING = object()
 
 
 class EmptySequenceError(ValueError):
     def __init__(self, message="Sequence contains no elements"):
         super().__init__(message)
 
+class NoMatchError(ValueError):
+    def __init__(self, message="Sequence contains no matching elements"):
+        super().__init__(message)
+
+class MultipleMatchesError(ValueError):
+    def __init__(self, message="Sequence contains more than one matching element"):
+        super().__init__(message)
+
+class MultipleElementsError(ValueError):
+    def __init__(self, message="Sequence contains more than one element"):
+        super().__init__(message)
+
 
 def _guard_empty(func: Callable[..., Any]) -> Callable[..., Any]:
     """Catches Python's native empty-sequence ValueError and re-raises LINQ-compliant error."""
@@ -96,6 +112,49 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
+    @overload
+    def any(self) -> bool: ...
+
+    @overload
+    def any(self, predicate: Callable[[TItem], bool]) -> bool: ...
+
+    def any(
+            self,
+            predicate: Optional[Callable[[TItem], bool]] = None,
+    ) -> bool:
+        """
+        Determines whether the sequence contains any elements,
+        or whether any element satisfies the predicate.
+
+        Mirrors Enumerable.Any:
+            Any()
+            Any(predicate)
+
+        Evaluation stops as soon as the result is known.
+        """
+        if predicate is not None:
+            return builtins.any(map(predicate, self))
+
+        iterator = iter(self)
+        try:
+            next(iterator)
+        except StopIteration:
+            return False
+
+        return True
+
+
+    def all(self, predicate: Callable[[TItem], bool]) -> bool:
+        """
+        Determines whether all elements satisfy the predicate.
+
+        Mirrors Enumerable.All.
+
+        Returns True for an empty sequence.
+        Evaluation stops at the first element that fails the predicate.
+        """
+        return builtins.all(map(predicate, self))
+
     def concat(self, second: Iterable[TItem]) -> "FlpIt[TItem]":
         def _generator() -> Iterator[TItem]:
             yield from self
@@ -305,33 +364,61 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
                 accumulator = func(accumulator, item)
         return accumulator
 
+    @overload
+    def last(self) -> TItem: ...
+
+    @overload
+    def last(self, predicate: Callable[[TItem], bool]) -> TItem: ...
+
+    def last(
+            self,
+            predicate: Optional[Callable[[TItem], bool]] = None,
+    ) -> TItem:
+        """
+        Returns the last element of the sequence, or the last element
+        satisfying the predicate.
+
+        Mirrors Enumerable.Last:
+            Last()
+            Last(predicate)
+
+        Raises EmptySequenceError if the sequence is empty or if no
+        element satisfies the predicate.
+        """
+        last_item: TItem | object = _SENTINEL
+
+        for item in self:
+            if predicate is None or predicate(item):
+                last_item = item
+
+        if last_item is _SENTINEL:
+            raise EmptySequenceError() if predicate is None else NoMatchError()
+
+        return cast(TItem, last_item)
+
+    def _extreme(self, func, **kwargs) -> TItem:
+        result = func(self, default=_MISSING, **kwargs)
+
+        if result is _MISSING:
+            raise EmptySequenceError()
+
+        return cast(TItem, result)
+
     def min(self) -> TItem:
         """Returns the minimum value in a sequence."""
-        try:
-            return builtins.min(self)  # type: ignore[type-var]
-        except ValueError:
-            raise EmptySequenceError()
+        return self._extreme(builtins.min)
 
     def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
         """Returns the value in a sequence that has the minimum key value."""
-        try:
-            return builtins.min(self, key=key_selector)
-        except ValueError:
-            raise EmptySequenceError()
+        return self._extreme(builtins.min, key=key_selector)
 
     def max(self) -> TItem:
         """Returns the maximum value in a sequence."""
-        try:
-            return builtins.max(self)  # type: ignore[type-var]
-        except ValueError:
-            raise EmptySequenceError()
+        return self._extreme(builtins.max)
 
     def max_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
         """Returns the value in a sequence that has the maximum key value."""
-        try:
-            return builtins.max(self, key=key_selector)
-        except ValueError:
-            raise EmptySequenceError()
+        return self._extreme(builtins.max, key=key_selector)
 
     def average(
             self, selector: Optional[Callable[[TItem], Union[int, float]]] = None
@@ -372,7 +459,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def count(self, predicate: Optional[Callable[[TItem], bool]] = None) -> int:
         """Counts elements in the sequence matching an optional predicate."""
-        query = self.where(predicate) if predicate else self
+        query = self.where(predicate) if predicate is not None else self
         return builtins.sum(1 for _ in query)
 
     def element_at(self, index: int) -> TItem:
@@ -386,10 +473,10 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def first(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
         """Returns the first element matching a predicate, or raises ValueError."""
-        query = self.where(predicate) if predicate else self
+        query = self.where(predicate) if predicate is not None else self
         for item in query:
             return item
-        raise ValueError("Sequence contains no matching elements")
+        raise EmptySequenceError() if predicate is None else NoMatchError()
 
     def first_or_default(
             self, default: TResult, predicate: Optional[Callable[[TItem], bool]] = None
@@ -397,48 +484,91 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         """Returns the first element matching a predicate, or a default value."""
         try:
             return self.first(predicate)
-        except ValueError:
+        except (EmptySequenceError, NoMatchError):
             return default
 
-    def single(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
+    def single(self, predicate: Optional[Callable[[TItem], bool]] = _SENTINEL) -> TItem:
         """Returns the single, unique element matching a predicate."""
-        query = self.where(predicate) if predicate else self
+        if predicate is None:
+            raise TypeError("Predicate cannot be None")
+
+        has_predicate = predicate is not _SENTINEL
+        query = self.where(predicate) if has_predicate else self
         it = iter(query)
+
         try:
             first_val = next(it)
         except StopIteration:
-            raise ValueError("Sequence contains no matching elements")
+            raise NoMatchError() if has_predicate else EmptySequenceError()
 
         try:
             next(it)
         except StopIteration:
             return first_val
 
-        raise ValueError("Sequence contains more than one matching element")
+        raise MultipleMatchesError() if has_predicate else MultipleElementsError()
+
 
     def to_list(self) -> FlpList[TItem]:
         """Explicitly materializes the query into a FlpList."""
         return FlpList(self)
 
 
-from threading import Lock
+_OrderCriterion = tuple[Callable[[TItem], Any], bool]
+
+
+class _OrderState(Generic[TItem]):
+    """
+    Shared lazy snapshot for an OrderBy/ThenBy chain.
+
+    The upstream source is consumed at most once. After materialization,
+    the original source reference is released.
+    """
+
+    __slots__ = ("_source", "_items", "_lock")
+
+    def __init__(self, source: Iterable[TItem]) -> None:
+        self._source: Optional[Iterable[TItem]] = source
+        self._items: Optional[list[TItem]] = None
+        self._lock = Lock()
+
+    def materialize(self) -> list[TItem]:
+        items = self._items
+
+        if items is not None:
+            return items
+
+        with self._lock:
+            items = self._items
+
+            if items is None:
+                source = self._source
+
+                if source is None:
+                    raise RuntimeError("OrderState source is unavailable")
+
+                items = list(source)
+
+                self._source = None
+                self._items = items
+
+        return items
+
 
 class OrderedIt(FlpIt[TItem]):
     """
-    Ordered Iterable.
+    Lazy, memoized ordered iterable.
 
-    Sorts the source lazily on first iteration and caches the resulting order.
-    The source is consumed at most once; subsequent iterations reuse the cached
-    result.
+    The source is materialized once per OrderBy chain.
+    ThenBy nodes share that source snapshot but maintain independent
+    ordered-result caches.
     """
 
     __slots__ = (
-        "_source",
-        "_key_selector",
-        "_descending",
-        "_parent",
+        "_state",
+        "_criteria",
         "_cached_result",
-        "_lock",
+        "_result_lock",
     )
 
     def __init__(
@@ -446,116 +576,94 @@ class OrderedIt(FlpIt[TItem]):
             source: Iterable[TItem],
             key_selector: Callable[[TItem], Any],
             descending: bool = False,
-            parent: Optional["OrderedIt[TItem]"] = None,
     ) -> None:
-        super().__init__(source)
+        # Pass () to FlpIt to prevent storing a permanent reference to the raw source
+        super().__init__(())
 
-        self._source = source
-        self._key_selector = key_selector
-        self._descending = descending
-        self._parent = parent
+        self._state = _OrderState(source)
+        self._criteria: tuple[_OrderCriterion, ...] = (
+            (key_selector, descending),
+        )
 
         self._cached_result: Optional[list[TItem]] = None
-        self._lock = Lock()
+        self._result_lock = Lock()
+
+    @classmethod
+    def _from_parent(
+            cls,
+            parent: OrderedIt[TItem],
+            key_selector: Callable[[TItem], Any],
+            descending: bool,
+    ) -> OrderedIt[TItem]:
+        """
+        Create a child ordering node sharing the parent's source state.
+
+        The FlpIt source is intentionally empty because OrderedIt overrides
+        __iter__ and uses _OrderState as its real source.
+        """
+        child = cls.__new__(cls)
+
+        # Do not retain the parent OrderedIt through FlpIt's _iterable.
+        FlpIt.__init__(child, ())
+
+        child._state = parent._state
+        child._criteria = (
+            *parent._criteria,
+            (key_selector, descending),
+        )
+        child._cached_result = None
+        child._result_lock = Lock()
+
+        return child
 
     def then_by(
             self,
             key_selector: Callable[[TItem], Any],
-    ) -> "OrderedIt[TItem]":
-        return OrderedIt(
-            self._source,
+    ) -> OrderedIt[TItem]:
+        return self._from_parent(
+            self,
             key_selector,
             descending=False,
-            parent=self,
         )
 
     def then_by_descending(
             self,
             key_selector: Callable[[TItem], Any],
-    ) -> "OrderedIt[TItem]":
-        return OrderedIt(
-            self._source,
+    ) -> OrderedIt[TItem]:
+        return self._from_parent(
+            self,
             key_selector,
             descending=True,
-            parent=self,
         )
 
     def __iter__(self) -> Iterator[TItem]:
         cached = self._cached_result
 
         if cached is None:
-            with self._lock:
+            with self._result_lock:
                 cached = self._cached_result
 
                 if cached is None:
-                    # Collect the complete ordering chain.
-                    comparers: list[
-                        tuple[Callable[[TItem], Any], bool]
-                    ] = []
-
-                    node: Optional["OrderedIt[TItem]"] = self
-
-                    while node is not None:
-                        comparers.append(
-                            (node._key_selector, node._descending)
+                    # Never mutate the shared source snapshot.
+                    result = list(self._state.materialize())
+
+                    # Python sort is stable, so apply the least-significant
+                    # criterion first.
+                    for selector, descending in reversed(self._criteria):
+                        result.sort(
+                            key=selector,
+                            reverse=descending,
                         )
-                        node = node._parent
-
-                    comparers.reverse()
-
-                    # Consume the source exactly once.
-                    items = list(self._source)
-
-                    class SortWrapper:
-                        __slots__ = ("obj", "keys")
-
-                        def __init__(self, obj: Any) -> None:
-                            self.obj = obj
-                            self.keys = [
-                                selector(obj)
-                                for selector, _ in comparers
-                            ]
-
-                        def __lt__(self, other: "SortWrapper") -> bool:
-                            for index, (_, descending) in enumerate(comparers):
-                                left = self.keys[index]
-                                right = other.keys[index]
-
-                                if left == right:
-                                    continue
-
-                                return right < left if descending else left < right
-
-                            return False
-
-                    wrapped_items = [
-                        SortWrapper(item)
-                        for item in items
-                    ]
-
-                    wrapped_items.sort()
-
-                    # Store ONLY the actual result objects.
-                    cached = [
-                        wrapper.obj
-                        for wrapper in wrapped_items
-                    ]
 
+                    cached = result
                     self._cached_result = cached
 
-                    # Important: __iter__ is a generator function.
-                    # Release potentially large temporary structures
-                    # before yielding anything.
-                    del wrapped_items
-                    del items
-                    del comparers
-
         yield from cached
 
 
 class Grouping(FlpIt[TItem], Generic[TKey, TItem]):
     """Represents a collection of elements sharing a common key (.NET IGrouping<TKey, TElement>)."""
-    __slots__ = ("_key")
+    __slots__ = ("_key", )
 
     def __init__(self, key: TKey, elements: Iterable[TItem]) -> None:
         self._key: TKey = key
@@ -618,9 +726,26 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         self.data.append(first_item)
         self.data.extend(it)
 
-    def to_list(self) -> "FlpList[TItem]":
-        """Explicitly returns a new shallow copy instance to isolate mutations matching .NET."""
-        return FlpList(self.data.copy())
+    @overload
+    def any(self) -> bool: ...
+
+    @overload
+    def any(self, predicate: Callable[[TItem], bool]) -> bool: ...
+
+    def any(
+            self,
+            predicate: Optional[Callable[[TItem], bool]] = None,
+    ) -> bool:
+        if predicate is None:
+            return len(self.data) > 0
+
+        return any(predicate(item) for item in self.data)
+
+    def all(
+            self,
+            predicate: Callable[[TItem], bool],
+    ) -> bool:
+        return all(predicate(item) for item in self.data)
 
     def append_linq(self, element: TItem) -> FlpIt[TItem]:
         """Appends an element to the sequence lazily, returning a FlpIt without mutating this list."""
@@ -777,14 +902,46 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
     def first(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
         return FlpIt(self.data).first(predicate)
 
+    @overload
+    def last(self) -> TItem: ...
+
+    @overload
+    def last(self, predicate: Callable[[TItem], bool]) -> TItem: ...
+
+    def last(
+            self,
+            predicate: Optional[Callable[[TItem], bool]] = None,
+    ) -> TItem:
+        """
+        Returns the last element of the sequence, or the last element
+        satisfying the predicate.
+
+        Mirrors Enumerable.Last:
+            Last()
+            Last(predicate)
+
+        Raises EmptySequenceError if the sequence is empty or if no
+        element satisfies the predicate.
+        """
+        if predicate is None:
+            if not self.data:
+                raise EmptySequenceError()
+            return self.data[-1]
+
+        for item in reversed(self.data):
+            if predicate(item):
+                return item
+
+        raise NoMatchError()
+
     def first_or_default(
             self, default: TResult, predicate: Optional[Callable[[TItem], bool]] = None
     ) -> Union[TItem, TResult]:
         return FlpIt(self.data).first_or_default(default, predicate)
 
-    def single(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
+    def single(self, predicate: Optional[Callable[[TItem], bool]] = _SENTINEL) -> TItem:
         return FlpIt(self.data).single(predicate)
 
     def to_list(self) -> FlpList[TItem]:
         """Explicitly returns a shallow copy instance to isolate mutations."""
-        return FlpList(self.data.copy())
+        return FlpList(self.data.copy())