flpit 0.1.4.dev7__tar.gz → 0.1.6__tar.gz

flpit-0.1.6/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.5
+Name: flpit
+Version: 0.1.6
+Summary: Fluent LINQ for Python — flip your iterables
+License: MIT
+License-File: LICENSE
+Keywords: fluent,generators,iterable,lazy-evaluation,linq,pipeline,pyrefly,type-safe
+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 and grouping, require internal materialization during deferred execution, while the query itself remains lazy.
+* **🔄 Source Enumeration Semantics** — FlpIt preserves the enumeration characteristics of its source. A query over a re-enumerable source can be enumerated repeatedly; a one-shot source such as a Python generator remains one-shot. FlpIt does not clone or rewind arbitrary Python iterators.
+* **🔹 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.
+
+## Scope & Intent
+
+FlpIt focuses exclusively on replicating the **`IEnumerable` (`System.Linq.Enumerable`)** model.
+
+* **Direct Execution:** It operates directly on standard Python callables (lambdas and functions) over Python iterables.
+* **No Provider Abstraction:** It does not model or emit Expression Trees (`IQueryable`) for translation by external providers. There is no query-provider layer that rewrites FlpIt operations into database queries or other backend-specific operations.
+
+FlpIt therefore follows the execution model of in-memory LINQ: query operators build a pipeline, execution is deferred where the operator permits it, and each operator's actual enumeration and buffering behavior is part of the query 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])
+```
+
+## Typed Domain Objects
+
+```python
+from dataclasses import dataclass
+from flpit import flp
+
+
+@dataclass
+class Employee:
+    name: str
+    role: str
+    salary: int
+
+
+@dataclass
+class Department:
+    name: str
+    employees: list[Employee]
+
+
+company = [
+    Department(
+        "Engineering",
+        [
+            Employee("Alice", "Backend Engineer", 95_000),
+            Employee("Bob", "Frontend Engineer", 90_000),
+        ],
+    ),
+    Department(
+        "Design",
+        [
+            Employee("Charlie", "UI Designer", 82_000),
+        ],
+    ),
+]
+
+# Extract the names of backend engineers earning at least 90,000.
+backend_engineers = (
+    flp.it(company)
+    .select_many(lambda dept: dept.employees)
+    .where(lambda emp: emp.role == "Backend Engineer")
+    .where(lambda emp: emp.salary >= 90_000)
+    .select(lambda emp: emp.name)
+)
+
+# The query is evaluated when it is enumerated.
+print(list(backend_engineers))
+# ['Alice']
+```
+
+## 🔬 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 = flp.range(1, 11).where(lambda x: x % 2 == 0)
+
+query.any()       # LINQ-style terminal operation
+query.first()     # LINQ-style terminal operation
+query.single()    # LINQ-style terminal operation
+```
+
+The query can also be consumed through normal Python built-ins:
+
+```python
+any(query)
+list(query)
+```
+
+The two forms serve different purposes: LINQ-style operators provide the query API and its associated semantics, while Python built-ins continue to operate through the normal iterable protocol.
+
+## Source Repeatability
+
+FlpIt does not imply that every source is repeatable. Re-enumeration depends on the underlying source:
+
+```python
+source = [1, 2, 3]
+query = flp.it(source)
+
+list(query)  # [1, 2, 3]
+list(query)  # [1, 2, 3]
+```
+
+A one-shot iterator remains one-shot:
+
+```python
+source = (x for x in range(3))
+query = flp.it(source)
+
+list(query)  # [0, 1, 2]
+list(query)  # []
+```
+
+## Intentional Deviation from Python List Contracts (`.count()`)
+
+To faithfully provide standard .NET LINQ semantics, `FlpList` deliberately uses LINQ-style count() semantics instead of Python list.count(value) semantics of Python's standard `list.count(value)`.
+
+* **Vanilla Python `list.count(value)`** counts occurrences of a specific *value*.
+* **FlpIt `FlpList.count()`** counts all elements.
+* **FlpIt `FlpList.count(predicate)`** counts elements matching the predicate.
+
+```python
+# Pure LINQ semantics instead of standard list behavior
+total_evens = eager_list.count(lambda x: x % 2 == 0)
+```
+
+Because `FlpList` is an explicit, fluent wrapper designed to enforce LINQ behavior, this signature change is a deliberate design choice. If you need the native Python behavior to count occurrences of a specific item value, use the explicitly provided fallback method:
+
+```python
+# Use the fallback for traditional Python value-counting
+occurrences = eager_list.count_item(4)
+```
+
+## 🔗 Independent Query Pipelines
+
+Query pipelines can be composed independently without mutating the queries 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.
+
+## Execution Characteristics
+
+Lazy execution does not mean that every operator is streaming. Some operators must consume and buffer their input before they can produce their result.
+**Sorting requires buffering:** Any exact sort of an arbitrary input must inspect its elements before it can produce the ordered result. This is not specific to FlpIt; it is an inherent characteristic of sorting and applies equally to native Python sorting and .NET LINQ `OrderBy()`.
+
+| Operator               | Execution deferred | Processes incrementally | Buffers input |
+| ---------------------- | ------------------ | ----------------------- | ------------- |
+| `where()` / `select()` | Yes                | Yes                     | No            |
+| `order_by()`           | Yes                | No                      | Yes           |
+| `group_by()`           | Yes                | No                      | Yes           |
+
+`order_by()` and `group_by()` therefore remain deferred at query construction time, but enumeration of either operator requires buffering its upstream input.
+
+`group_by()` produces a query of groupings rather than terminating the pipeline:
+
+```python
+groups = query.group_by(lambda x: x % 3)
+
+result = (
+    groups
+    .where(...)
+    .select(...)
+    .to_list()
+)
+```
+
+Terminal operators instead evaluate the query and return a result rather than another query:
+
+```python
+query.any()
+query.first()
+query.single()
+query.count()
+query.aggregate(...)
+query.to_list()
+```
+
+For example, `aggregate()` processes its source incrementally but must consume the source completely to produce its final accumulated value.
+
+## 🧠 Lazy Pipelines
+
+Streaming operators do not materialize their upstream input:
+
+```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     ← terminal 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.6/README.md

@@ -0,0 +1,311 @@
+# 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 and grouping, require internal materialization during deferred execution, while the query itself remains lazy.
+* **🔄 Source Enumeration Semantics** — FlpIt preserves the enumeration characteristics of its source. A query over a re-enumerable source can be enumerated repeatedly; a one-shot source such as a Python generator remains one-shot. FlpIt does not clone or rewind arbitrary Python iterators.
+* **🔹 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.
+
+## Scope & Intent
+
+FlpIt focuses exclusively on replicating the **`IEnumerable` (`System.Linq.Enumerable`)** model.
+
+* **Direct Execution:** It operates directly on standard Python callables (lambdas and functions) over Python iterables.
+* **No Provider Abstraction:** It does not model or emit Expression Trees (`IQueryable`) for translation by external providers. There is no query-provider layer that rewrites FlpIt operations into database queries or other backend-specific operations.
+
+FlpIt therefore follows the execution model of in-memory LINQ: query operators build a pipeline, execution is deferred where the operator permits it, and each operator's actual enumeration and buffering behavior is part of the query 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])
+```
+
+## Typed Domain Objects
+
+```python
+from dataclasses import dataclass
+from flpit import flp
+
+
+@dataclass
+class Employee:
+    name: str
+    role: str
+    salary: int
+
+
+@dataclass
+class Department:
+    name: str
+    employees: list[Employee]
+
+
+company = [
+    Department(
+        "Engineering",
+        [
+            Employee("Alice", "Backend Engineer", 95_000),
+            Employee("Bob", "Frontend Engineer", 90_000),
+        ],
+    ),
+    Department(
+        "Design",
+        [
+            Employee("Charlie", "UI Designer", 82_000),
+        ],
+    ),
+]
+
+# Extract the names of backend engineers earning at least 90,000.
+backend_engineers = (
+    flp.it(company)
+    .select_many(lambda dept: dept.employees)
+    .where(lambda emp: emp.role == "Backend Engineer")
+    .where(lambda emp: emp.salary >= 90_000)
+    .select(lambda emp: emp.name)
+)
+
+# The query is evaluated when it is enumerated.
+print(list(backend_engineers))
+# ['Alice']
+```
+
+## 🔬 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 = flp.range(1, 11).where(lambda x: x % 2 == 0)
+
+query.any()       # LINQ-style terminal operation
+query.first()     # LINQ-style terminal operation
+query.single()    # LINQ-style terminal operation
+```
+
+The query can also be consumed through normal Python built-ins:
+
+```python
+any(query)
+list(query)
+```
+
+The two forms serve different purposes: LINQ-style operators provide the query API and its associated semantics, while Python built-ins continue to operate through the normal iterable protocol.
+
+## Source Repeatability
+
+FlpIt does not imply that every source is repeatable. Re-enumeration depends on the underlying source:
+
+```python
+source = [1, 2, 3]
+query = flp.it(source)
+
+list(query)  # [1, 2, 3]
+list(query)  # [1, 2, 3]
+```
+
+A one-shot iterator remains one-shot:
+
+```python
+source = (x for x in range(3))
+query = flp.it(source)
+
+list(query)  # [0, 1, 2]
+list(query)  # []
+```
+
+## Intentional Deviation from Python List Contracts (`.count()`)
+
+To faithfully provide standard .NET LINQ semantics, `FlpList` deliberately uses LINQ-style count() semantics instead of Python list.count(value) semantics of Python's standard `list.count(value)`.
+
+* **Vanilla Python `list.count(value)`** counts occurrences of a specific *value*.
+* **FlpIt `FlpList.count()`** counts all elements.
+* **FlpIt `FlpList.count(predicate)`** counts elements matching the predicate.
+
+```python
+# Pure LINQ semantics instead of standard list behavior
+total_evens = eager_list.count(lambda x: x % 2 == 0)
+```
+
+Because `FlpList` is an explicit, fluent wrapper designed to enforce LINQ behavior, this signature change is a deliberate design choice. If you need the native Python behavior to count occurrences of a specific item value, use the explicitly provided fallback method:
+
+```python
+# Use the fallback for traditional Python value-counting
+occurrences = eager_list.count_item(4)
+```
+
+## 🔗 Independent Query Pipelines
+
+Query pipelines can be composed independently without mutating the queries 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.
+
+## Execution Characteristics
+
+Lazy execution does not mean that every operator is streaming. Some operators must consume and buffer their input before they can produce their result.
+**Sorting requires buffering:** Any exact sort of an arbitrary input must inspect its elements before it can produce the ordered result. This is not specific to FlpIt; it is an inherent characteristic of sorting and applies equally to native Python sorting and .NET LINQ `OrderBy()`.
+
+| Operator               | Execution deferred | Processes incrementally | Buffers input |
+| ---------------------- | ------------------ | ----------------------- | ------------- |
+| `where()` / `select()` | Yes                | Yes                     | No            |
+| `order_by()`           | Yes                | No                      | Yes           |
+| `group_by()`           | Yes                | No                      | Yes           |
+
+`order_by()` and `group_by()` therefore remain deferred at query construction time, but enumeration of either operator requires buffering its upstream input.
+
+`group_by()` produces a query of groupings rather than terminating the pipeline:
+
+```python
+groups = query.group_by(lambda x: x % 3)
+
+result = (
+    groups
+    .where(...)
+    .select(...)
+    .to_list()
+)
+```
+
+Terminal operators instead evaluate the query and return a result rather than another query:
+
+```python
+query.any()
+query.first()
+query.single()
+query.count()
+query.aggregate(...)
+query.to_list()
+```
+
+For example, `aggregate()` processes its source incrementally but must consume the source completely to produce its final accumulated value.
+
+## 🧠 Lazy Pipelines
+
+Streaming operators do not materialize their upstream input:
+
+```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     ← terminal 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.dev7 → flpit-0.1.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.1.4.dev7"
+version = "0.1.6"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"

{flpit-0.1.4.dev7 → flpit-0.1.6}/src/flpit/core/linq.py

@@ -29,7 +29,13 @@ TKey = TypeVar("TKey")
 TOther = TypeVar("TOther")
 TAccumulate = TypeVar("TAccumulate")
 
-_SENTINEL = object()
+class _Sentinel:
+    __slots__ = ()
+
+    def __call__(self, *args: object, **kwargs: object) -> Any:
+        raise TypeError("_SENTINEL cannot be called")
+
+_SENTINEL = _Sentinel()
 _MISSING = object()
 
 
@@ -129,7 +135,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def any(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = None,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> bool:
         """
         Determines whether the sequence contains any elements,
@@ -141,7 +147,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         Evaluation stops as soon as the result is known.
         """
-        if predicate is not None:
+        if predicate is not _SENTINEL:
             return builtins.any(map(predicate, self))
 
         iterator = iter(self)
@@ -288,12 +294,12 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
     def zip(
             self,
             second: Iterable[TOther],
-            result_selector: Optional[Callable[[TItem, TOther], Any]] = None,
+            result_selector: Callable[[TItem, TOther], Any] | _Sentinel = _SENTINEL,
     ) -> FlpIt[Any]:
         """Applies a specified function to corresponding elements of two sequences."""
         def _generator() -> Iterator[Any]:
             for first_item, second_item in zip(self, second):
-                if result_selector is not None:
+                if result_selector is not _SENTINEL:
                     yield result_selector(first_item, second_item)
                 else:
                     yield first_item, second_item
@@ -343,7 +349,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
-     # --- Immediate Execution (Materialization & Aggregation) ---
+    # --- Immediate Execution (Materialization & Aggregation) ---
 
     @overload
     def aggregate(self, func: Callable[[TItem, TItem], TItem]) -> TItem: ...
@@ -355,9 +361,9 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def aggregate(
             self,
-            func: Callable[[Any, TItem], Any],
+            func: Callable[[Any, Any], Any],
             seed: Any = _SENTINEL,
-    ) -> Any:
+    ) -> TItem | TAccumulate:
         """Applies an accumulator function over a sequence."""
         it = iter(self)
         if seed is _SENTINEL:
@@ -381,7 +387,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
     def last(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = _SENTINEL,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> TItem:
         """
         Returns the last element of the sequence, or the last element
@@ -433,12 +439,12 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         return self._extreme(builtins.max, key=key_selector)
 
     def average(
-            self, selector: Optional[Callable[[TItem], Union[int, float]]] = None
+            self, selector: Callable[[TItem], Union[int, float]] | _Sentinel = _SENTINEL
     ) -> float:
         """Computes the arithmetic mean of the sequence, optionally applying a selector."""
         total = 0.0
         count = 0
-        query = (selector(x) for x in self) if selector is not None else self
+        query = (selector(x) for x in self) if selector is not _SENTINEL else self
         for item in query:
             total += float(item)  # type: ignore[arg-type]
             count += 1
@@ -462,17 +468,22 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
     avg_by = average_by
 
     def sum(
-            self, selector: Optional[Callable[[TItem], Union[int, float]]] = None
+            self, selector: Callable[[TItem], Union[int, float]] | _Sentinel = _SENTINEL
     ) -> Union[int, float]:
         """Calculates the sum of the sequence, optionally applying a selector."""
-        if selector is not None:
+        if selector is not _SENTINEL:
             return builtins.sum(selector(x) for x in self)
         return builtins.sum(self)  # type: ignore[arg-type]
 
-    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 is not None else self
-        return builtins.sum(1 for _ in query)
+    def count(
+            self,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
+    ) -> int:
+        """Counts elements in the sequence, optionally matching a predicate."""
+        if predicate is _SENTINEL:
+            return builtins.sum(1 for _ in self)
+
+        return builtins.sum(1 for _ in self.where(predicate))
 
     def element_at(self, index: int) -> TItem:
         """Returns the element at a specified index in a sequence."""
@@ -483,15 +494,15 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
                 return item
         raise IndexError("Index out of range")
 
-    def first(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
+    def first(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         """Returns the first element matching a predicate, or raises ValueError."""
-        query = self.where(predicate) if predicate is not None else self
+        query = self.where(predicate) if predicate is not _SENTINEL else self
         for item in query:
             return item
-        raise EmptySequenceError() if predicate is None else NoMatchError()
+        raise EmptySequenceError() if predicate is _SENTINEL else NoMatchError()
 
     def first_or_default(
-            self, default: TResult, predicate: Optional[Callable[[TItem], bool]] = None
+            self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
     ) -> Union[TItem, TResult]:
         """Returns the first element matching a predicate, or a default value."""
         try:
@@ -499,12 +510,8 @@ 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:
+    def single(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         """Returns the single, unique element matching a predicate."""
-        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)
@@ -702,12 +709,16 @@ 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):
+    def __init__(self, source: Iterable[TItem] | _Sentinel=_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)
+            init_list: Iterable[TItem] = list[TItem]()  # don't depend on the base class to do the right thing
+        else:
+            init_list = typing_cast(Iterable[TItem], source)
+
+        super().__init__(init_list)
 
     def add(self, item: TItem) -> None:
         """
@@ -752,9 +763,9 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     def any(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = None,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> bool:
-        if predicate is None:
+        if predicate is _SENTINEL:
             return len(self.data) > 0
 
         return any(predicate(item) for item in self.data)
@@ -818,9 +829,8 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
     def zip(
             self,
             second: Iterable[TOther],
-            result_selector: Optional[Callable[[TItem, TOther], Any]] = None,
+            result_selector: Callable[[TItem, TOther], Any] | _Sentinel = _SENTINEL,
     ) -> 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]]:
@@ -853,7 +863,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             self,
             func: Callable[[Any, Any], Any],
             seed: Any = _SENTINEL,
-    ) -> Any:
+    ) -> TItem | TAccumulate:
         return FlpIt(self.data).aggregate(func, seed=seed)
 
     @_guard_empty
@@ -873,68 +883,44 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         return builtins.max(self.data, key=key_selector)
 
     def sum(
-            self, selector: Optional[Callable[[TItem], Union[int, float]]] = None
-    ) -> Union[int, float]:
+            self, selector: Callable[[TItem], int | float] | _Sentinel = _SENTINEL
+    ) -> int | float:
         """Calculates the sum of elements, optionally applying a selector."""
         return FlpIt(self.data).sum(selector)
 
     def average(
-            self, selector: Optional[Callable[[TItem], Union[int, float]]] = None
+            self, selector: Callable[[TItem], int | float] | _Sentinel = _SENTINEL
     ) -> float:
         """Calculates the arithmetic mean, optionally applying a selector."""
         return FlpIt(self.data).average(selector)
 
-    # --- Overloads for the Type System ---
-    # 1. Native Python UserList compatibility path (MUST be first): exact value match
-    @overload
-    def count(self, item: TItem) -> int: ...
-
-    # 2. LINQ style path: matching via predicate function
-    @overload
-    def count(self, item: Callable[[TItem], bool]) -> int: ...
-
-    # 3. LINQ style path: no arguments (counts everything)
-    @overload
-    def count(self) -> int: ...
+    def count_item(self, item: TItem) -> int:
+        return self.data.count(item) # just redirect how the count redirected before
 
-    # --- 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:
+    def count( # type: ignore  # pyrefly: ignore [bad-override-param-name]  # pyright: ignore[reportIncompatibleMethodOverride]
+            self,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
+    ) -> int:
         """
-        Counts elements using Python/UserList or .NET LINQ conventions.
+        Counts elements using LINQ semantics.
 
         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)``.
+            count()          -> total number of elements
+            count(predicate) -> number of elements satisfying the predicate
         """
-        # Scenario C: No argument passed (.count()) -> Return total length
-        if item is _SENTINEL:
+        if predicate is _SENTINEL:
             return len(self.data)
 
-        # Scenario A: A LINQ predicate function was passed
-        if callable(item):
-            return FlpIt(self.data).count(item)
-
-        # Scenario B: An exact raw value was passed (.count(4))
-        # Invokes the original parent implementation of UserList to remain 100% compliant
-        return super().count(item)
+        return FlpIt(self.data).count(predicate)
 
     def element_at(self, index: int) -> TItem:
         if index < 0 or index >= len(self.data):
             raise IndexError("Index out of range")
         return self.data[index]
 
-    def first(self, predicate: Optional[Callable[[TItem], bool]] = None) -> TItem:
+    def first(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         return FlpIt(self.data).first(predicate)
 
     @overload
@@ -945,7 +931,7 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
 
     def last(
             self,
-            predicate: Optional[Callable[[TItem], bool]] = _SENTINEL,
+            predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> TItem:
         """
         Returns the last element of the sequence, or the last element
@@ -970,15 +956,14 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             if predicate(item):
                 return item
 
-        raise EmptySequenceError() if predicate is None else NoMatchError()
+        raise EmptySequenceError() if predicate is _SENTINEL else NoMatchError()
 
     def first_or_default(
-            self, default: TResult, predicate: Optional[Callable[[TItem], bool]] = None
-    ) -> Union[TItem, TResult]:
+            self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
+    ) -> 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:
+    def single(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         return FlpIt(self.data).single(predicate)
 
     def to_list(self) -> FlpList[TItem]:

flpit-0.1.4.dev7/PKG-INFO

@@ -1,187 +0,0 @@
-Metadata-Version: 2.5
-Name: flpit
-Version: 0.1.4.dev7
-Summary: Fluent LINQ for Python — flip your iterables
-License: MIT
-License-File: LICENSE
-Keywords: fluent,generators,iterable,lazy-evaluation,linq,pipeline,pyrefly,type-safe
-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.dev7/README.md

@@ -1,167 +0,0 @@
-# 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.