flpit 0.1.2__tar.gz → 0.1.4.dev5__tar.gz

flpit-0.1.4.dev5/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.3
+Name: flpit
+Version: 0.1.4.dev5
+Summary: Fluent LINQ for Python — flip your iterables
+Keywords: linq,fluent,iterable,pipeline,lazy-evaluation,pyrefly,type-safe,generators
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# FlpIt
+
+> **Fluent LINQ for Python — LINQ semantics, Python-native execution**
+
+`FlpIt` brings a strongly typed, LINQ-style API to standard Python iterables. It combines the fluent query model and semantics of .NET LINQ with Python's native iterable and generator model.
+
+> **Semantic goal:** `flp` strives to faithfully reproduce .NET LINQ semantics.  
+> Where Python's language or type system requires a different API contract, the contract is adapted accordingly. 
+> The implementation is actively developed, and semantic deviations may still exist.
+
+## ⚡ Key Features
+
+* **⚡ Lazy Evaluation (`FlpIt`):** Deferred, streaming execution where the underlying operation permits it. `FlpIt` wraps a standard Python `Iterable[T]`.
+* **📦 Materialized Container (`FlpList`):** Eager, mutable container backed by `collections.UserList`.
+* **🎯 LINQ Semantics:** Operators such as `.any()`, `.first()`, `.single()`, `.order_by()`, and `.then_by()` follow .NET LINQ semantics.
+* **🔀 Independent Query Pipelines:** Derived queries are independent and never mutate or retroactively affect separately created queries.
+* **🧠 Lazy Internal Materialization:** Some operators, such as ordering, require internal materialization during deferred execution, while the query itself remains lazy.
+* **🔹 Static-First Typing:** Designed for precise `pyrefly` inference without plugins (mypy and pyright might give varying results).
+* **🐍 Python-Native:** Built on standard Python iterables, iterators, generators, and callable semantics.
+
+## 🤸 Flipping the Pipeline
+
+Native Python functional operations tend to produce an inside-out, right-to-left reading pattern...
+
+```python
+# 🔁 Native Built-ins
+result = list(map(lambda x: x * 10, filter(lambda x: x % 2 == 0, range(1, 11))))
+
+# 🤸 FlpIt Pipeline
+result = (
+    flp.it(range(1, 11))
+    .where(lambda x: x % 2 == 0)
+    .select(lambda x: x * 10)
+    .to_list()
+)
+```
+
+## 💡 Quick Start
+
+```python
+
+from flpit import flp, FlpIt, FlpList
+
+# Deferred iterable via shorthand
+data: FlpIt[int] = flp.it(range(1, 11))
+
+# Lazy, streaming pipeline
+query: FlpIt[int] = (
+    data
+    .where(lambda x: x % 2 == 0)
+    .select(lambda x: x * 10)
+)
+
+# Explicit materialization
+result: FlpList[int] = query.to_list()
+# [20, 40, 60, 80, 100]
+
+# Or start directly with an eager container
+eager_list: FlpList[int] = flp.lst([1, 2, 3, 4])
+```
+
+## 🔬 LINQ Semantics, Python Runtime
+
+`flpit` deliberately separates the two:
+
+- **LINQ defines the query semantics.**
+- **Python provides the underlying iterable and execution model.**
+
+For example:
+
+```python
+query.any()
+query.first()
+query.single()
+```
+
+use LINQ semantics, while native Python operations remain Pythonic:
+
+```python
+any(query)
+list(query)
+```
+
+This provides a predictable LINQ vocabulary without attempting to replace Python's native iteration model.
+
+## 🔗 Independent Queries
+
+LINQ queries are composable without mutating the query they were derived from.
+
+For example:
+
+```python
+@dataclass
+class Item: group: str; value: int
+
+original = flp.it([Item("A", 2), Item("B", 1)])
+
+ordered = original.order_by(lambda x: x.group)
+
+extended = original.concat([Item("A", 1), Item("B", 2)])
+
+ordered_by_group_and_value = ordered.then_by(lambda x: x.value)
+```
+
+The resulting query graph is:
+
+```text
+original
+   │
+   ├── order_by ──→ ordered
+   │                  │
+   │                  └── then_by ──→ ordered_by_group_and_value
+   │
+   └── concat ─────→ extended
+```
+
+`ordered_by_group_and_value` is derived from `ordered`.  
+It does not modify `original`, and it is not affected by the separately created `extended` query.
+
+This matches the independent-query behavior of .NET LINQ.
+
+## 🧠 Lazy Pipelines
+
+Streaming operations do not materialize intermediate results:
+
+```python
+query = (
+    flp.it(source)
+    .where(predicate)
+    .select(selector)
+    .order_by(key_selector)
+    .take(100)
+)
+```
+
+Conceptually:
+
+```text
+source
+  │
+  ▼
+where       ← streaming
+  │
+  ▼
+select      ← streaming
+  │
+  ▼
+order_by    ← lazy, internally buffers when enumerated
+  │
+  ▼
+take        ← streaming
+  │
+  ▼
+to_list     ← consumer-facing materialization
+```
+
+Operations such as `order_by()` necessarily materialize their input internally to establish ordering.
+
+## ⚙️ Installation
+
+```bash
+uv add flpit
+```
+
+## 📜 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

flpit-0.1.4.dev5/README.md

@@ -0,0 +1,167 @@
+# FlpIt
+
+> **Fluent LINQ for Python — LINQ semantics, Python-native execution**
+
+`FlpIt` brings a strongly typed, LINQ-style API to standard Python iterables. It combines the fluent query model and semantics of .NET LINQ with Python's native iterable and generator model.
+
+> **Semantic goal:** `flp` strives to faithfully reproduce .NET LINQ semantics.  
+> Where Python's language or type system requires a different API contract, the contract is adapted accordingly. 
+> The implementation is actively developed, and semantic deviations may still exist.
+
+## ⚡ Key Features
+
+* **⚡ Lazy Evaluation (`FlpIt`):** Deferred, streaming execution where the underlying operation permits it. `FlpIt` wraps a standard Python `Iterable[T]`.
+* **📦 Materialized Container (`FlpList`):** Eager, mutable container backed by `collections.UserList`.
+* **🎯 LINQ Semantics:** Operators such as `.any()`, `.first()`, `.single()`, `.order_by()`, and `.then_by()` follow .NET LINQ semantics.
+* **🔀 Independent Query Pipelines:** Derived queries are independent and never mutate or retroactively affect separately created queries.
+* **🧠 Lazy Internal Materialization:** Some operators, such as ordering, require internal materialization during deferred execution, while the query itself remains lazy.
+* **🔹 Static-First Typing:** Designed for precise `pyrefly` inference without plugins (mypy and pyright might give varying results).
+* **🐍 Python-Native:** Built on standard Python iterables, iterators, generators, and callable semantics.
+
+## 🤸 Flipping the Pipeline
+
+Native Python functional operations tend to produce an inside-out, right-to-left reading pattern...
+
+```python
+# 🔁 Native Built-ins
+result = list(map(lambda x: x * 10, filter(lambda x: x % 2 == 0, range(1, 11))))
+
+# 🤸 FlpIt Pipeline
+result = (
+    flp.it(range(1, 11))
+    .where(lambda x: x % 2 == 0)
+    .select(lambda x: x * 10)
+    .to_list()
+)
+```
+
+## 💡 Quick Start
+
+```python
+
+from flpit import flp, FlpIt, FlpList
+
+# Deferred iterable via shorthand
+data: FlpIt[int] = flp.it(range(1, 11))
+
+# Lazy, streaming pipeline
+query: FlpIt[int] = (
+    data
+    .where(lambda x: x % 2 == 0)
+    .select(lambda x: x * 10)
+)
+
+# Explicit materialization
+result: FlpList[int] = query.to_list()
+# [20, 40, 60, 80, 100]
+
+# Or start directly with an eager container
+eager_list: FlpList[int] = flp.lst([1, 2, 3, 4])
+```
+
+## 🔬 LINQ Semantics, Python Runtime
+
+`flpit` deliberately separates the two:
+
+- **LINQ defines the query semantics.**
+- **Python provides the underlying iterable and execution model.**
+
+For example:
+
+```python
+query.any()
+query.first()
+query.single()
+```
+
+use LINQ semantics, while native Python operations remain Pythonic:
+
+```python
+any(query)
+list(query)
+```
+
+This provides a predictable LINQ vocabulary without attempting to replace Python's native iteration model.
+
+## 🔗 Independent Queries
+
+LINQ queries are composable without mutating the query they were derived from.
+
+For example:
+
+```python
+@dataclass
+class Item: group: str; value: int
+
+original = flp.it([Item("A", 2), Item("B", 1)])
+
+ordered = original.order_by(lambda x: x.group)
+
+extended = original.concat([Item("A", 1), Item("B", 2)])
+
+ordered_by_group_and_value = ordered.then_by(lambda x: x.value)
+```
+
+The resulting query graph is:
+
+```text
+original
+   │
+   ├── order_by ──→ ordered
+   │                  │
+   │                  └── then_by ──→ ordered_by_group_and_value
+   │
+   └── concat ─────→ extended
+```
+
+`ordered_by_group_and_value` is derived from `ordered`.  
+It does not modify `original`, and it is not affected by the separately created `extended` query.
+
+This matches the independent-query behavior of .NET LINQ.
+
+## 🧠 Lazy Pipelines
+
+Streaming operations do not materialize intermediate results:
+
+```python
+query = (
+    flp.it(source)
+    .where(predicate)
+    .select(selector)
+    .order_by(key_selector)
+    .take(100)
+)
+```
+
+Conceptually:
+
+```text
+source
+  │
+  ▼
+where       ← streaming
+  │
+  ▼
+select      ← streaming
+  │
+  ▼
+order_by    ← lazy, internally buffers when enumerated
+  │
+  ▼
+take        ← streaming
+  │
+  ▼
+to_list     ← consumer-facing materialization
+```
+
+Operations such as `order_by()` necessarily materialize their input internally to establish ordering.
+
+## ⚙️ Installation
+
+```bash
+uv add flpit
+```
+
+## 📜 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

{flpit-0.1.2 → flpit-0.1.4.dev5}/pyproject.toml

@@ -1,9 +1,19 @@
 [project]
 name = "flpit"
-version = "0.1.2"
+version = "0.1.4.dev5"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"
+keywords = [
+    "linq",
+    "fluent",
+    "iterable",
+    "pipeline",
+    "lazy-evaluation",
+    "pyrefly",
+    "type-safe",
+    "generators",
+]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -12,7 +22,9 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
 ]
 dependencies = []
 
@@ -25,6 +37,7 @@ dev = [
     "hypothesis>=6.168.0",
     "pyrefly>=1.3.1",
     "pyright>=1.1.414",
+    "pytest-benchmark>=5.3.0",
 ]
 
 [build-system]
@@ -32,13 +45,26 @@ requires = ["uv_build>=0.12.10,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
-module-name = "flp"
-module-root = "src"
+module-name = "flpit"
+namespace = true
+source-include = [
+    "src/flp/**/*",
+    "src/flpit/**/*",
+]
 
-[tool.pyright]
-include = ["src"]
-exclude = [
+[tool.pyrefly]
+project-includes = ["src"]
+project-excludes = [
     "**/__pycache__",
     "tests",
 ]
-typeCheckingMode = "basic"
+search-path = ["src"]
+preset = "strict"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+    "tests",
+]
+addopts = "-m 'not benchmark'"
+markers = ["benchmark: performance benchmarks"]

{flpit-0.1.2 → flpit-0.1.4.dev5}/pyproject.toml.orig

@@ -1,10 +1,11 @@
 [project]
 name = "flpit"
-version = "0.1.2"
+version = "0.1.4.dev5"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "MIT" }
+keywords = ["linq", "fluent", "iterable", "pipeline", "lazy-evaluation", "pyrefly", "type-safe", "generators"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
@@ -13,7 +14,9 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed"
 ]
 dependencies = []
 
@@ -23,6 +26,7 @@ dev = [
     "hypothesis>=6.168.0",
     "pyrefly>=1.3.1",
     "pyright>=1.1.414",
+    "pytest-benchmark>=5.3.0",
 ]
 
 [build-system]
@@ -30,14 +34,23 @@ requires = ["uv_build>=0.12.10,<0.13.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
-module-name = "flp"
-module-root = "src"
+module-name = "flpit"
+namespace = true
+source-include = ["src/flp/**/*", "src/flpit/**/*"]
 
-[tool.pyright]
-include = ["src"]
-exclude = ["**/__pycache__", "tests"]
-typeCheckingMode = "basic"
+[tool.pyrefly]
+project-includes = ["src"]
+project-excludes = ["**/__pycache__", "tests"]
+search-path = ["src"]
+preset = "strict"
+
+[tool.pytest.ini_options]
+pythonpath = [
+    "src",
+    "tests"
+]
+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.4.dev5/src/flp/__init__.py

@@ -0,0 +1,21 @@
+import warnings
+import flpit  # The NEW location
+
+# Enforce a loud, clear deprecation alert
+warnings.warn(
+    "The top-level 'flp' namespace is deprecated and has been moved to 'flpit'. "
+    "Please update your imports to 'from flpit import flp, FlpIt, FlpList'"
+    "This legacy entry point will throw a hard ImportError in a future version.",
+    DeprecationWarning,
+    stacklevel=2
+)
+
+__all__ = getattr(flpit.flp, "__all__", []) + getattr(flpit, "__all__", [])
+mods = [flpit, flpit.flp]
+
+def __getattr__(name: str):
+    for mod in mods:
+        if hasattr(mod, name):
+            return getattr(mod, name)
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

flpit-0.1.4.dev5/src/flpit/__init__.py

@@ -0,0 +1,37 @@
+"""
+Fluent LINQ for Python — flip your iterables.
+"""
+from __future__ import annotations
+from importlib.metadata import version
+__version__ = version("flpit")
+
+import builtins
+from typing import Iterable as _Iterable, TypeVar
+
+from flpit import flp
+from flpit.core.linq import (
+    FlpIt,
+    FlpList,
+    Grouping,
+    OrderedIt,
+    EmptySequenceError,
+    NoMatchError,
+    MultipleElementsError,
+    MultipleMatchesError,
+    SourceNoneError,
+    PredicateNoneError,
+)
+
+__all__ = [
+    "FlpIt",
+    "FlpList",
+    "Grouping",
+    "OrderedIt",
+    "EmptySequenceError",
+    "NoMatchError",
+    "MultipleElementsError",
+    "MultipleMatchesError",
+    "SourceNoneError",
+    "PredicateNoneError",
+]
+

{flpit-0.1.2/src/flp → flpit-0.1.4.dev5/src/flpit}/core/linq.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
-
-from typing import cast
+from threading import Lock
 
 import builtins
 from collections import UserList
@@ -19,6 +18,7 @@ from typing import (
     Type,
     TypeVar,
     Union,
+    override,
     overload,
     cast as typing_cast,
 )
@@ -34,26 +34,34 @@ _MISSING = object()
 
 
 class EmptySequenceError(ValueError):
-    def __init__(self, message="Sequence contains no elements"):
-        super().__init__(message)
+    def __init__(self):
+        super().__init__("Sequence contains no elements")
 
 class NoMatchError(ValueError):
-    def __init__(self, message="Sequence contains no matching elements"):
-        super().__init__(message)
+    def __init__(self):
+        super().__init__("Sequence contains no matching elements")
 
 class MultipleMatchesError(ValueError):
-    def __init__(self, message="Sequence contains more than one matching element"):
-        super().__init__(message)
+    def __init__(self):
+        super().__init__("Sequence contains more than one matching element")
 
 class MultipleElementsError(ValueError):
-    def __init__(self, message="Sequence contains more than one element"):
-        super().__init__(message)
+    def __init__(self):
+        super().__init__("Sequence contains more than one element")
+
+class SourceNoneError(TypeError):
+    def __init__(self):
+        super().__init__("Value cannot be None. (Argument 'source')")
+
+class PredicateNoneError(TypeError):
+    def __init__(self):
+        super().__init__("Value cannot be None. (Argument 'predicate')")
 
 
 def _guard_empty(func: Callable[..., Any]) -> Callable[..., Any]:
     """Catches Python's native empty-sequence ValueError and re-raises LINQ-compliant error."""
     @wraps(func)
-    def wrapper(self, *args: Any, **kwargs: Any) -> Any:
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
         try:
             return func(self, *args, **kwargs)
         except ValueError as e:
@@ -90,8 +98,10 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
     """
     __slots__ = ("_iterable",)
 
-    def __init__(self, iterable: Iterable[TItem]) -> None:
-        self._iterable: Iterable[TItem] = iterable
+    def __init__(self, source: Iterable[TItem]) -> None:
+        if source is None:
+            raise SourceNoneError()
+        self._iterable: Iterable[TItem] = source
 
     def __iter__(self) -> Iterator[TItem]:
         return iter(self._iterable)
@@ -371,7 +381,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def last(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = None,
+            predicate: Optional[Callable[[TItem], bool]] = _SENTINEL,
     ) -> TItem:
         """
         Returns the last element of the sequence, or the last element
@@ -384,24 +394,27 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         Raises EmptySequenceError if the sequence is empty or if no
         element satisfies the predicate.
         """
-        last_item: TItem | object = _SENTINEL
+        if predicate is None:
+            raise PredicateNoneError()
+
+        last_item: TItem | object = _MISSING
 
         for item in self:
-            if predicate is None or predicate(item):
+            if predicate is _SENTINEL or predicate(item):
                 last_item = item
 
-        if last_item is _SENTINEL:
-            raise EmptySequenceError() if predicate is None else NoMatchError()
+        if last_item is _MISSING:
+            raise EmptySequenceError() if predicate is _SENTINEL else NoMatchError()
 
-        return cast(TItem, last_item)
+        return typing_cast(TItem, last_item)
 
-    def _extreme(self, func, **kwargs) -> TItem:
+    def _extreme(self, func: Any, **kwargs: Any) -> TItem:
         result = func(self, default=_MISSING, **kwargs)
 
         if result is _MISSING:
             raise EmptySequenceError()
 
-        return cast(TItem, result)
+        return typing_cast(TItem, result)
 
     def min(self) -> TItem:
         """Returns the minimum value in a sequence."""
@@ -486,6 +499,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         except (EmptySequenceError, NoMatchError):
             return default
 
+    # pyrefly: ignore [bad-function-definition]
     def single(self, predicate: Optional[Callable[[TItem], bool]] = _SENTINEL) -> TItem:
         """Returns the single, unique element matching a predicate."""
         if predicate is None:
@@ -513,24 +527,58 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         return FlpList(self)
 
 
-from threading import Lock
+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__(
@@ -538,116 +586,96 @@ 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[tuple[Callable[[TItem], Any], bool], ...] = (
+            (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,
         )
 
+    @override
     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
@@ -674,6 +702,12 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
     | Fluent List
     A materialized list extending UserList that yields lazy FlpIt instances for query operations.
     """
+    def __init__(self, source: TItem=_SENTINEL):
+        if source is None:
+            raise SourceNoneError()
+        if source is _SENTINEL:
+            source = [] # don't depend on the base class to do the right thing
+        super().__init__(source)
 
     def add(self, item: TItem) -> None:
         """
@@ -786,6 +820,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             second: Iterable[TOther],
             result_selector: Optional[Callable[[TItem, TOther], Any]] = None,
     ) -> FlpIt[Any]:
+        # pyrefly: ignore [bad-argument-type] # yeah well if overloads are just pretend
         return FlpIt(self.data).zip(second, result_selector)
 
     def chunk(self, size: int) -> FlpIt[FlpList[TItem]]:
@@ -823,7 +858,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     @_guard_empty
     def min(self) -> TItem:
-        return builtins.min(self.data)
+        return builtins.min(self.data) # pyrefly: ignore [bad-specialization]
 
     @_guard_empty
     def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
@@ -831,7 +866,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     @_guard_empty
     def max(self) -> TItem:
-        return builtins.max(self.data)
+        return builtins.max(self.data) # pyrefly: ignore [bad-specialization]
 
     @_guard_empty
     def max_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
@@ -850,7 +885,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         return FlpIt(self.data).average(selector)
 
     # --- Overloads for the Type System ---
-    # 1. Native compatibility path (MUST be first): exact value match
+    # 1. Native Python UserList compatibility path (MUST be first): exact value match
     @overload
     def count(self, item: TItem) -> int: ...
 
@@ -864,8 +899,24 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     # --- The Clean Implementation ---
     # We name the parameter 'item' to perfectly match UserList, but default it to None
+    @override
     def count(self, item: Any = _SENTINEL) -> int:
-        """Counts elements in the list matching an optional predicate or exact value."""
+        """
+        Counts elements using Python/UserList or .NET LINQ conventions.
+
+        Supported forms:
+
+            count()          -> count all elements                  (.NET LINQ)
+            count(predicate) -> count elements matching predicate   (.NET LINQ)
+            count(value)     -> count occurrences of an exact value (Python)
+
+        Note:
+            Because Python callables are also valid list values, ``count(value)``
+            is inherently ambiguous when ``value`` is callable. A callable
+            argument is interpreted as a LINQ predicate, so counting occurrences
+            of a callable object via the native ``UserList.count(value)`` behavior
+            is not distinguishable from ``count(predicate)``.
+        """
         # Scenario C: No argument passed (.count()) -> Return total length
         if item is _SENTINEL:
             return len(self.data)
@@ -894,7 +945,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     def last(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = None,
+            predicate: Optional[Callable[[TItem], bool]] = _SENTINEL,
     ) -> TItem:
         """
         Returns the last element of the sequence, or the last element
@@ -908,6 +959,9 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         element satisfies the predicate.
         """
         if predicate is None:
+            raise PredicateNoneError()
+
+        if predicate is _SENTINEL:
             if not self.data:
                 raise EmptySequenceError()
             return self.data[-1]
@@ -916,13 +970,14 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             if predicate(item):
                 return item
 
-        raise NoMatchError()
+        raise EmptySequenceError() if predicate is None else 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)
 
+    # pyrefly: ignore [bad-function-definition]
     def single(self, predicate: Optional[Callable[[TItem], bool]] = _SENTINEL) -> TItem:
         return FlpIt(self.data).single(predicate)
 

flpit-0.1.2/src/flp/__init__.py → flpit-0.1.4.dev5/src/flpit/flp.py

@@ -3,12 +3,11 @@ Fluent LINQ for Python — flip your iterables.
 """
 from __future__ import annotations
 from importlib.metadata import version
-__version__ = version("flpit")
 
 import builtins
 from typing import Iterable as _Iterable, TypeVar
 
-from flp.core.linq import Grouping, FlpList, FlpIt, OrderedIt
+from flpit.core.linq import FlpList, FlpIt
 
 TItem = TypeVar("TItem")
 
@@ -30,10 +29,6 @@ def repeat(element: TItem, count: int) -> FlpIt[TItem]:
     return FlpIt(element for _ in builtins.range(count))
 
 __all__ = [
-    "FlpIt",
-    "OrderedIt",
-    "Grouping",
-    "FlpList",
     "it",
     "lst",
     "range",

flpit-0.1.2/PKG-INFO

@@ -1,61 +0,0 @@
-Metadata-Version: 2.3
-Name: flpit
-Version: 0.1.2
-Summary: Fluent LINQ for Python — flip your iterables
-License: MIT
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
-# flp
-
-> **Fluent LINQ for Python – flip your iterables**
-
-`flp` brings a LINQ-inspired fluent API to standard Python iterables with full static typing.
-
-## ⚡ Key Features
-
-* **⚡ Lazy Evaluation (`FlpIt`):** Deferred execution using Python iterators and generators.
-* **📦 Materialized Container (`FlpList`):** Eager, mutable container backed by `collections.UserList`.
-* **🔹 Static-First Typing:** Built for full `mypy` and `pyright` inference without plugins.
-* **🔄 No Implicit Caching:** Query results are not cached unless explicitly documented, such as `order_by`.
-
-## ⚙️ Installation
-
-```bash
-uv add flpit
-```
-
-## 💡 Quick Start
-
-```python
-import flp
-from flp import FlpIt, FlpList
-
-# Deferred iterable via shorthand
-data: FlpIt[int] = flp.it([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-
-# Deferred / lazy pipeline
-query: FlpIt[int] = (
-    data
-    .where(lambda x: x % 2 == 0)
-    .select(lambda x: x * 10)
-)
-
-# Materialize query results explicitly
-result: FlpList[int] = query.to_list()  # [20, 40, 60, 80, 100]
-
-# Or start directly with an eager container
-eager_list: FlpList[int] = flp.lst([1, 2, 3, 4])
-```
-
-## 📜 License
-
-Distributed under the MIT License. See `LICENSE` for more information.

flpit-0.1.2/README.md

@@ -1,45 +0,0 @@
-# flp
-
-> **Fluent LINQ for Python – flip your iterables**
-
-`flp` brings a LINQ-inspired fluent API to standard Python iterables with full static typing.
-
-## ⚡ Key Features
-
-* **⚡ Lazy Evaluation (`FlpIt`):** Deferred execution using Python iterators and generators.
-* **📦 Materialized Container (`FlpList`):** Eager, mutable container backed by `collections.UserList`.
-* **🔹 Static-First Typing:** Built for full `mypy` and `pyright` inference without plugins.
-* **🔄 No Implicit Caching:** Query results are not cached unless explicitly documented, such as `order_by`.
-
-## ⚙️ Installation
-
-```bash
-uv add flpit
-```
-
-## 💡 Quick Start
-
-```python
-import flp
-from flp import FlpIt, FlpList
-
-# Deferred iterable via shorthand
-data: FlpIt[int] = flp.it([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
-
-# Deferred / lazy pipeline
-query: FlpIt[int] = (
-    data
-    .where(lambda x: x % 2 == 0)
-    .select(lambda x: x * 10)
-)
-
-# Materialize query results explicitly
-result: FlpList[int] = query.to_list()  # [20, 40, 60, 80, 100]
-
-# Or start directly with an eager container
-eager_list: FlpList[int] = flp.lst([1, 2, 3, 4])
-```
-
-## 📜 License
-
-Distributed under the MIT License. See `LICENSE` for more information.