flpit 0.3.0__tar.gz → 0.3.1.dev6__tar.gz

{flpit-0.3.0 → flpit-0.3.1.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.3.0
+Version: 0.3.1.dev6
 Summary: Fluent LINQ for Python — flip your iterables
 Project-URL: Homepage, https://github.com/riemar/flpit
 Project-URL: Repository, https://github.com/riemar/flpit
@@ -311,6 +311,30 @@ It does not modify `original`, and it is not affected by the separately created
 
 This matches the independent-query behavior of .NET LINQ.
 
+### Joins
+
+```python
+customers = [("Prakash", 1), ("Tim", 2), ("Robert", 3)]
+orders    = [(10, 1), (11, 1), (12, 4)]          # (order_id, customer_id)
+
+flp.it(customers).join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c[0], o[0]))
+# [("Prakash", 10), ("Prakash", 11)]                          inner join   (.NET Join)
+
+flp.it(customers).left_join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c[0], o and o[0]))
+# [("Prakash", 10), ("Prakash", 11), ("Tim", None), ("Robert", None)]   (.NET 10 LeftJoin)
+
+flp.it(customers).full_join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c and c[0], o and o[0]))
+# [("Prakash", 10), ("Prakash", 11), ("Tim", None), ("Robert", None), (None, 12)]
+```
+
+Without a result selector all three yield `JoinTuple(outer, inner)`.
+
+* Elements whose key is `None` never match. `left_join()` / `full_join()` still emit them as unmatched.
+* An unmatched side is passed to the result selector as `None` (the Python equivalent of .NET `default`).
+* `full_join()` has no .NET LINQ equivalent. It yields the `left_join()` rows in outer order, followed by every inner element that was never matched (in inner order).
+* Argument validation is eager (`InnerNoneError`, `OuterKeySelectorNoneError`, `InnerKeySelectorNoneError`, `ResultSelectorNoneError`); everything else is deferred.
+* Custom equality comparers are not supported yet (keys are compared with `==` / `hash`, like `group_by()`).
+
 ## 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.
@@ -321,9 +345,14 @@ Lazy execution does not mean that every operator is streaming. Some operators mu
 | `where()` / `select()` | Yes                | Yes                     | No            |
 | `order_by()`           | Yes                | No                      | Yes           |
 | `group_by()`           | Yes                | No                      | Yes           |
+| `join()`               | Yes                | Yes (outer)             | Yes (inner)   |
+| `left_join()`          | Yes                | Yes (outer)             | Yes (inner)   |
+| `full_join()`          | Yes                | Yes (outer)             | Yes (inner)   |
 
 `order_by()` and `group_by()` therefore remain deferred at query construction time, but enumeration of either operator requires buffering its upstream input.
 
+`join()`, `left_join()` and `full_join()` build a hash lookup of the `inner` sequence when enumeration starts and stream the outer sequence (O(N + M)).
+
 `group_by()` produces a query of groupings rather than terminating the pipeline:
 
 ```python
@@ -441,17 +470,26 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | │   ├── test_all.py                                            |          80 |
 | │   ├── test_any.py                                            |          90 |
 | │   ├── test_average.py                                        |         572 |
+| │   ├── test_chunk.py                                          |          22 |
 | │   ├── test_concat.py                                         |          64 |
+| │   ├── test_contains.py                                       |         108 |
 | │   ├── test_count.py                                          |          37 |
 | │   ├── test_distinct.py                                       |          87 |
 | │   ├── test_element_at.py                                     |          43 |
 | │   ├── test_first.py                                          |          29 |
 | │   ├── test_first_or_default.py                               |          50 |
+| │   ├── test_full_join.py                                      |          37 |
 | │   ├── test_generic_list.py                                   |          95 |
 | │   ├── test_group_by.py                                       |          23 |
+| │   ├── test_join.py                                           |          47 |
 | │   ├── test_last.py                                           |          29 |
-| │   ├── test_order_by.py                                       |          98 |
+| │   ├── test_last_or_default.py                                |          45 |
+| │   ├── test_left_join.py                                      |          47 |
+| │   ├── test_max.py                                            |        1100 |
+| │   ├── test_min.py                                            |         968 |
+| │   ├── test_order_by.py                                       |         100 |
 | │   ├── test_order_descending_by.py                            |          45 |
+| │   ├── test_reverse.py                                        |          35 |
 | │   ├── test_select.py                                         |         140 |
 | │   ├── test_select_many.py                                    |          85 |
 | │   ├── test_single.py                                         |          34 |
@@ -461,7 +499,8 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | │   ├── test_take.py                                           |          39 |
 | │   ├── test_then_by.py                                        |          40 |
 | │   ├── test_then_descending_by.py                             |          34 |
-| │   └── test_where.py                                          |          76 |
+| │   ├── test_where.py                                          |          76 |
+| │   └── test_zip.py                                            |         101 |
 | └── task/                                                      |             |
 |     ├── test_cancellation.py                                   |          69 |
 |     ├── test_task_completion_source.py                         |          26 |
@@ -469,6 +508,6 @@ Distributed under the MIT License. See `LICENSE` for more information.
 |     ├── test_task_rt.py                                        |          12 |
 |     └── test_task_rt_core.py                                   |          22 |
 --------------------------------------------------------------------------------
-| GRAND TOTALS                                                   |        2221 |
+| GRAND TOTALS                                                   |        4733 |
 ================================================================================
 ```

{flpit-0.3.0 → flpit-0.3.1.dev6}/README.md

@@ -287,6 +287,30 @@ It does not modify `original`, and it is not affected by the separately created
 
 This matches the independent-query behavior of .NET LINQ.
 
+### Joins
+
+```python
+customers = [("Prakash", 1), ("Tim", 2), ("Robert", 3)]
+orders    = [(10, 1), (11, 1), (12, 4)]          # (order_id, customer_id)
+
+flp.it(customers).join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c[0], o[0]))
+# [("Prakash", 10), ("Prakash", 11)]                          inner join   (.NET Join)
+
+flp.it(customers).left_join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c[0], o and o[0]))
+# [("Prakash", 10), ("Prakash", 11), ("Tim", None), ("Robert", None)]   (.NET 10 LeftJoin)
+
+flp.it(customers).full_join(orders, lambda c: c[1], lambda o: o[1], lambda c, o: (c and c[0], o and o[0]))
+# [("Prakash", 10), ("Prakash", 11), ("Tim", None), ("Robert", None), (None, 12)]
+```
+
+Without a result selector all three yield `JoinTuple(outer, inner)`.
+
+* Elements whose key is `None` never match. `left_join()` / `full_join()` still emit them as unmatched.
+* An unmatched side is passed to the result selector as `None` (the Python equivalent of .NET `default`).
+* `full_join()` has no .NET LINQ equivalent. It yields the `left_join()` rows in outer order, followed by every inner element that was never matched (in inner order).
+* Argument validation is eager (`InnerNoneError`, `OuterKeySelectorNoneError`, `InnerKeySelectorNoneError`, `ResultSelectorNoneError`); everything else is deferred.
+* Custom equality comparers are not supported yet (keys are compared with `==` / `hash`, like `group_by()`).
+
 ## 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.
@@ -297,9 +321,14 @@ Lazy execution does not mean that every operator is streaming. Some operators mu
 | `where()` / `select()` | Yes                | Yes                     | No            |
 | `order_by()`           | Yes                | No                      | Yes           |
 | `group_by()`           | Yes                | No                      | Yes           |
+| `join()`               | Yes                | Yes (outer)             | Yes (inner)   |
+| `left_join()`          | Yes                | Yes (outer)             | Yes (inner)   |
+| `full_join()`          | Yes                | Yes (outer)             | Yes (inner)   |
 
 `order_by()` and `group_by()` therefore remain deferred at query construction time, but enumeration of either operator requires buffering its upstream input.
 
+`join()`, `left_join()` and `full_join()` build a hash lookup of the `inner` sequence when enumeration starts and stream the outer sequence (O(N + M)).
+
 `group_by()` produces a query of groupings rather than terminating the pipeline:
 
 ```python
@@ -417,17 +446,26 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | │   ├── test_all.py                                            |          80 |
 | │   ├── test_any.py                                            |          90 |
 | │   ├── test_average.py                                        |         572 |
+| │   ├── test_chunk.py                                          |          22 |
 | │   ├── test_concat.py                                         |          64 |
+| │   ├── test_contains.py                                       |         108 |
 | │   ├── test_count.py                                          |          37 |
 | │   ├── test_distinct.py                                       |          87 |
 | │   ├── test_element_at.py                                     |          43 |
 | │   ├── test_first.py                                          |          29 |
 | │   ├── test_first_or_default.py                               |          50 |
+| │   ├── test_full_join.py                                      |          37 |
 | │   ├── test_generic_list.py                                   |          95 |
 | │   ├── test_group_by.py                                       |          23 |
+| │   ├── test_join.py                                           |          47 |
 | │   ├── test_last.py                                           |          29 |
-| │   ├── test_order_by.py                                       |          98 |
+| │   ├── test_last_or_default.py                                |          45 |
+| │   ├── test_left_join.py                                      |          47 |
+| │   ├── test_max.py                                            |        1100 |
+| │   ├── test_min.py                                            |         968 |
+| │   ├── test_order_by.py                                       |         100 |
 | │   ├── test_order_descending_by.py                            |          45 |
+| │   ├── test_reverse.py                                        |          35 |
 | │   ├── test_select.py                                         |         140 |
 | │   ├── test_select_many.py                                    |          85 |
 | │   ├── test_single.py                                         |          34 |
@@ -437,7 +475,8 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | │   ├── test_take.py                                           |          39 |
 | │   ├── test_then_by.py                                        |          40 |
 | │   ├── test_then_descending_by.py                             |          34 |
-| │   └── test_where.py                                          |          76 |
+| │   ├── test_where.py                                          |          76 |
+| │   └── test_zip.py                                            |         101 |
 | └── task/                                                      |             |
 |     ├── test_cancellation.py                                   |          69 |
 |     ├── test_task_completion_source.py                         |          26 |
@@ -445,6 +484,6 @@ Distributed under the MIT License. See `LICENSE` for more information.
 |     ├── test_task_rt.py                                        |          12 |
 |     └── test_task_rt_core.py                                   |          22 |
 --------------------------------------------------------------------------------
-| GRAND TOTALS                                                   |        2221 |
+| GRAND TOTALS                                                   |        4733 |
 ================================================================================
 ```

{flpit-0.3.0 → flpit-0.3.1.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.3.0"
+version = "0.3.1.dev6"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.12"

{flpit-0.3.0 → flpit-0.3.1.dev6}/src/flpit/__init__.py

@@ -4,6 +4,10 @@ Fluent LINQ for Python — flip your iterables.
 from importlib.metadata import version
 __version__ = version("flpit")
 
+# noinspection protected-member
+from flpit.core._zip import ZipTuple
+from flpit.core._join import JoinTuple
+
 from flpit import flp
 from flpit.core.linq import (
     FlpIt,
@@ -32,9 +36,12 @@ from flpit.core.linq import (
     SecondNoneError,
     FuncNoneError,
     ResultSelectorNoneError,
+    InnerNoneError,
+    OuterKeySelectorNoneError,
+    InnerKeySelectorNoneError,
     ArgumentOutOfRangeError,
     ArgumentNonNegError,
-    ArgumentOutOfBoundsError
+    ArgumentOutOfBoundsError,
 )
 
 from flpit.core._grouping import Grouping
@@ -61,8 +68,14 @@ __all__ = [
     "SecondNoneError",
     "FuncNoneError",
     "ResultSelectorNoneError",
+    "InnerNoneError",
+    "OuterKeySelectorNoneError",
+    "InnerKeySelectorNoneError",
     "ArgumentOutOfRangeError",
     "ArgumentNonNegError",
     "ArgumentOutOfBoundsError",
+
+    "ZipTuple",
+    "JoinTuple",
 ]
 

flpit-0.3.1.dev6/src/flpit/core/_join.py

@@ -0,0 +1,7 @@
+from typing import NamedTuple
+
+
+class JoinTuple[TOuter, TInner](NamedTuple):
+    """Default result of join / left_join / full_join when no result selector is given."""
+    outer: TOuter
+    inner: TInner

flpit-0.3.1.dev6/src/flpit/core/_zip.py

@@ -0,0 +1,13 @@
+from typing import NamedTuple
+
+class ZipTuple[TFirst, TSecond](NamedTuple):
+    first: TFirst
+    second: TSecond
+
+    @property
+    def item1(self) -> TFirst:
+        return self.first
+
+    @property
+    def item2(self) -> TSecond:
+        return self.second

{flpit-0.3.0 → flpit-0.3.1.dev6}/src/flpit/core/linq.py

@@ -8,8 +8,10 @@ from contextlib import AbstractContextManager
 
 import builtins
 from collections import UserList
-from functools import wraps
-from itertools import islice
+from functools import wraps, partial as _partial
+from operator import is_not as _is_not, ne as _ne, eq as _eq
+from itertools import islice, chain, compress
+from numbers import Real as _Real
 
 from typing import (
     Any,
@@ -33,6 +35,8 @@ from typing import (
 )
 
 from flpit.json import JsonConvert, JsonSerializerOptions
+from flpit import ZipTuple
+from flpit.core._join import JoinTuple
 
 TKey = TypeVar("TKey")
 TOther = TypeVar("TOther")
@@ -105,9 +109,21 @@ class FuncNoneError(ArgumentNullError):
         super().__init__("func")
 
 class ResultSelectorNoneError(ArgumentNullError):
-    def __init__(self):
+    def __init__(self) -> None:
         super().__init__("resultSelector")
 
+class InnerNoneError(ArgumentNullError):
+    def __init__(self) -> None:
+        super().__init__("inner")
+
+class OuterKeySelectorNoneError(ArgumentNullError):
+    def __init__(self) -> None:
+        super().__init__("outerKeySelector")
+
+class InnerKeySelectorNoneError(ArgumentNullError):
+    def __init__(self) -> None:
+        super().__init__("innerKeySelector")
+
 class ArgumentOutOfRangeError(ArgumentError):
     def __init__(self, argument: str, pattern:str="Index was out of range. Must be non-negative and less than the size of the collection."):
         super().__init__(f"{pattern} (Parameter '{argument}')")
@@ -121,25 +137,147 @@ class ArgumentOutOfBoundsError(ArgumentError):
         super().__init__("Offset and length were out of bounds for the array or count is greater than the number of elements from index to the end of the source collection.")
 
 
-def _guard_empty[SelfT: Sized, R, **P](
-        func: Callable[Concatenate[SelfT, P], R],
-) -> Callable[Concatenate[SelfT, P], R]:
-    """Translate empty-sequence ValueError into EmptySequenceError."""
+_NOT_NONE = _partial(_is_not, None)
+_EXTREME_CHUNK = 1024
 
-    @wraps(func)
-    def wrapper(
-            self: SelfT,
-            *args: P.args,
-            **kwargs: P.kwargs,
-    ) -> R:
-        try:
-            return func(self, *args, **kwargs)
-        except ValueError as e:
-            if len(self) == 0:
-                raise EmptySequenceError() from e
-            raise
 
-    return wrapper
+def _project(items: Iterable[Any], selector: Any) -> Iterable[Any]:
+    """Applies an optional selector lazily (C-level map); None selector is an error."""
+    if selector is _SENTINEL:
+        return items
+    if selector is None:
+        raise SelectorNoneError()
+    return map(selector, items)
+
+
+def _extreme_values(items: Iterable[Any], is_min: bool) -> Any:
+    """
+    Single-pass min/max of values with .NET Enumerable.Min/Max semantics.
+
+    flpit has no runtime generics, so every sequence is "None-able":
+
+    - empty input or only None values -> None
+    - None values are skipped (nullable Min/Max)
+    - numeric NaN uses .NET's total order, where NaN is smaller than every
+      other value, including -inf:  min -> NaN if any is present,
+      max -> NaN only if every value is NaN
+      (builtins.min/max depend on where the NaN sits, since every comparison
+      with NaN is False)
+
+    Only the leading run of None values is scanned in Python; the remainder
+    is filtered at C speed. Numeric input is reduced in bounded chunks so NaN
+    can be detected at C speed (x != x is True only for NaN) in O(chunk) memory.
+    """
+    pick = builtins.min if is_min else builtins.max
+    it = iter(items)
+
+    for first in it:
+        if first is None:
+            continue
+
+        rest = filter(_NOT_NONE, it)
+
+        if not isinstance(first, (_Real, Decimal)):
+            # Non-numeric (str, tuple, date, ...): no NaN semantics apply.
+            return pick(chain((first,), rest)) # pyrefly: ignore [bad-specialization]
+
+        if is_min:
+            if first != first:
+                return first
+
+            best = first
+            while chunk := list(islice(rest, _EXTREME_CHUNK)):
+                if any(map(_ne, chunk, chunk)):
+                    return next(x for x in chunk if x != x)
+                best = pick(best, pick(chunk)) # pyrefly: ignore [bad-specialization]
+            return best
+
+        nan: Any = first if first != first else _MISSING
+        best = _MISSING if nan is not _MISSING else first
+        while chunk := list(islice(rest, _EXTREME_CHUNK)):
+            if any(map(_ne, chunk, chunk)):
+                if nan is _MISSING:
+                    nan = next(x for x in chunk if x != x)
+                chunk = list(compress(chunk, map(_eq, chunk, chunk)))
+                if not chunk:
+                    continue
+            candidate = builtins.max(chunk) # pyrefly: ignore [bad-specialization]
+            best = candidate if best is _MISSING else builtins.max(best, candidate) # pyrefly: ignore [bad-specialization]
+        return nan if best is _MISSING else best
+
+    return None
+
+
+def _extreme_by(items: Iterable[Any], key_selector: Any, is_min: bool) -> Any:
+    """
+    Single-pass MinBy/MaxBy returning the *element* with the extreme key.
+
+    Follows .NET Enumerable.MinBy/MaxBy:
+    - empty input                  -> None (no runtime generics: everything is None-able)
+    - key_selector is None         -> SelectorNoneError as soon as there is an element
+                                      to select a key for (empty input still gives None)
+    - None keys are skipped; if every key is None the first element is returned
+    - ties keep the first element
+    - NaN keys order below every other number (Comparer<double>.Default):
+      min_by returns the first NaN-keyed element, max_by ignores NaN keys
+      unless all keys are NaN.
+
+    The selector runs exactly once per element, in order. Work is done in
+    bounded chunks so None/NaN filtering and the reduction run at C speed.
+    """
+    it = iter(items)
+
+    if key_selector is None:
+        for _ in it:
+            raise SelectorNoneError()
+        return None
+
+    pick = builtins.min if is_min else builtins.max
+    first_item: Any = _MISSING
+    nan_item: Any = _MISSING
+    best_item: Any = _MISSING
+    best_key: Any = _MISSING
+
+    while chunk := list(islice(it, _EXTREME_CHUNK)):
+        if first_item is _MISSING:
+            first_item = chunk[0]
+
+        keys = list(map(key_selector, chunk))
+
+        if not all(map(_NOT_NONE, keys)):
+            mask = list(map(_NOT_NONE, keys))
+            keys = list(compress(keys, mask))
+            chunk = list(compress(chunk, mask))
+            if not keys:
+                continue
+
+        if any(map(_ne, keys, keys)):
+            nan_index = next(i for i, k in enumerate(keys) if k != k)
+            if is_min:
+                return chunk[nan_index]
+            if nan_item is _MISSING:
+                nan_item = chunk[nan_index]
+            mask = list(map(_eq, keys, keys))
+            keys = list(compress(keys, mask))
+            chunk = list(compress(chunk, mask))
+            if not keys:
+                continue
+
+        extreme = pick(keys)
+        if best_key is _MISSING or (extreme < best_key if is_min else extreme > best_key):
+            best_key = extreme
+            best_item = chunk[keys.index(extreme)]
+
+    if best_item is not _MISSING:
+        return best_item
+    if nan_item is not _MISSING:
+        return nan_item
+    if first_item is not _MISSING:
+        return first_item
+
+    # raise EmptySequenceError()
+    # no proper generic runtime type, so everything is assumed to be nullable
+    return None
 
 
 def dotnet_context() -> AbstractContextManager[decimal.Context]:
@@ -167,6 +305,73 @@ class _FactoryIterable[TItem](Iterable[TItem]):
         return self._factory()
 
 
+# Exact builtin types whose iter() has no side effects and no failure mode, so
+# calling it eagerly is indistinguishable from calling it on the first next().
+_PURE_ITER_TYPES = (list, tuple, range)
+
+
+def _is_pure(source: object) -> bool:
+    return type(source) in _PURE_ITER_TYPES or getattr(source, "_pure", False) is True
+
+
+class _WhereIterable[TItem](Iterable[TItem]):
+    """Deferred filter node with independent iteration state."""
+    __slots__ = ("_source", "_predicate", "_pure")
+
+    def __init__(self, source: Iterable[TItem], predicate: Callable[[TItem], bool]) -> None:
+        self._source = source
+        self._predicate = predicate
+        self._pure = _is_pure(source)
+
+    def __iter__(self) -> Iterator[TItem]:
+        if self._pure:  # whole chain bottoms out in a list/tuple/range: no wrapper needed
+            return filter(self._predicate, iter(self._source))  # type: ignore[arg-type]
+        # chain.from_iterable defers iter(source) to the first next(), like a generator would.
+        return filter(self._predicate, chain.from_iterable((self._source,)))  # type: ignore[arg-type]
+
+
+class _SelectIterable[TItem, TResult](Iterable[TResult]):
+    """Deferred projection node with independent iteration state."""
+    __slots__ = ("_source", "_selector", "_pure")
+
+    def __init__(self, source: Iterable[TItem], selector: Callable[[TItem], TResult]) -> None:
+        self._source = source
+        self._selector = selector
+        self._pure = _is_pure(source)
+
+    def __iter__(self) -> Iterator[TResult]:
+        if self._pure:
+            return map(self._selector, iter(self._source))  # type: ignore[arg-type]
+        return map(self._selector, chain.from_iterable((self._source,)))  # type: ignore[arg-type]
+
+
+def _validate_join_args(
+        inner: Any,
+        outer_key_selector: Any,
+        inner_key_selector: Any,
+        result_selector: Any,
+) -> None:
+    """Eager argument validation shared by join / left_join / full_join (mirrors .NET)."""
+    if inner is None:
+        raise InnerNoneError()
+    if outer_key_selector is None:
+        raise OuterKeySelectorNoneError()
+    if inner_key_selector is None:
+        raise InnerKeySelectorNoneError()
+    if result_selector is None:
+        raise ResultSelectorNoneError()
+
+
+def _build_lookup(inner: Iterable[Any], inner_key_selector: Callable[[Any], Any]) -> dict[Any, list[Any]]:
+    """Hash lookup key -> inner elements (insertion order kept). Elements with a None key are dropped."""
+    lookup: dict[Any, list[Any]] = {}
+    for inner_item in inner:
+        key = inner_key_selector(inner_item)
+        if key is not None:
+            lookup.setdefault(key, []).append(inner_item)
+    return lookup
+
+
 class FlpIt[TItem](Iterable[TItem]):
     """
     | Fluent Iterable
@@ -263,28 +468,33 @@ class FlpIt[TItem](Iterable[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
+    def contains(self, value: TItem) -> bool:
+        source = self._iterable
+
+        if isinstance(source, Collection):
+            return value in source
+
+        for item in source:
+            if item == value:
+                return True
+
+        return False
+
+    def _node_source(self) -> Iterable[TItem]:
+        """Return the upstream iterable, preserving subclasses that customize iteration."""
+        return self._iterable if type(self) is FlpIt else self
+
     def where(self, predicate: Callable[[TItem], bool]) -> FlpIt[TItem]:
-        """Filters elements based on a predicate."""
+        """Filters elements based on a predicate (deferred)."""
         if predicate is None:
             raise PredicateNoneError()
-
-        def _generator() -> Iterator[TItem]:
-            for item in self:
-                if predicate(item):
-                    yield item
-        # return typing_cast(FlpIt[TItem], FlpIt[TItem](_FactoryIterable(_generator)))
-        return FlpIt[TItem](_FactoryIterable(_generator))
+        return FlpIt[TItem](_WhereIterable(self._node_source(), predicate))
 
     def select[TResult](self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
-        """Projects each element into a new form."""
+        """Projects each element into a new form (deferred)."""
         if selector is None:
             raise SelectorNoneError()
-
-        def _generator() -> Iterator[TResult]:
-            for item in self:
-                yield selector(item)
-
-        return FlpIt(_FactoryIterable(_generator))
+        return FlpIt(_SelectIterable(self._node_source(), selector))
 
     def select_many[TResult](
             self, selector: Callable[[TItem], Iterable[TResult]]
@@ -384,7 +594,7 @@ class FlpIt[TItem](Iterable[TItem]):
         return FlpIt(_FactoryIterable(_generator))
 
     @overload
-    def zip(self, second: Iterable[TOther]) -> FlpIt[tuple[TItem, TOther]]: ...
+    def zip(self, second: Iterable[TOther]) -> FlpIt[ZipTuple[TItem, TOther]]: ...
 
     @overload
     def zip[TResult, TOther](
@@ -399,19 +609,198 @@ class FlpIt[TItem](Iterable[TItem]):
             result_selector: Callable[[TItem, TOther], Any] | _Sentinel = _SENTINEL,
     ) -> FlpIt[Any]:
         """Applies a specified function to corresponding elements of two sequences."""
+        if second is None:
+            raise SecondNoneError()
+
+        if result_selector is None:
+            raise ResultSelectorNoneError()
+
         def _generator() -> Iterator[Any]:
             for first_item, second_item in zip(self, second):
                 if result_selector is not _SENTINEL:
                     yield result_selector(first_item, second_item)
                 else:
-                    yield first_item, second_item
+                    yield ZipTuple(first_item, second_item)
+
+        return FlpIt(_FactoryIterable(_generator))
+
+    @overload
+    def join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem, TInner]]: ...
+
+    @overload
+    def join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        """
+        Inner join: correlates the elements of two sequences based on matching keys.
+
+        Yields one result per matching (outer, inner) pair, in outer order and, per outer element,
+        in inner order. Elements whose key is ``None`` never match. Arguments are validated eagerly;
+        ``inner`` is buffered into a hash lookup when enumeration starts (O(N + M)).
+        """
+        _validate_join_args(inner, outer_key_selector, inner_key_selector, result_selector)
+
+        def _generator() -> Iterator[Any]:
+            lookup = _build_lookup(inner, inner_key_selector)
+            if not lookup:  # like .NET: nothing can match, so the outer sequence is not enumerated
+                return
+            for outer_item in self:
+                key = outer_key_selector(outer_item)
+                if key is None:
+                    continue
+                matches = lookup.get(key)
+                if matches is None:
+                    continue
+                for inner_item in matches:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(outer_item, inner_item)
+                    else:
+                        yield result_selector(outer_item, inner_item)
+
+        return FlpIt(_FactoryIterable(_generator))
+
+    @overload
+    def left_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem, TInner | None]]: ...
+
+    @overload
+    def left_join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner | None], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def left_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner | None], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        """
+        Left outer join (.NET ``LeftJoin``): every outer element is produced at least once.
+
+        Outer elements without a match (including those with a ``None`` key) are paired with
+        ``None`` as the inner element, i.e. ``result_selector(outer, None)``.
+        """
+        _validate_join_args(inner, outer_key_selector, inner_key_selector, result_selector)
+
+        def _generator() -> Iterator[Any]:
+            lookup = _build_lookup(inner, inner_key_selector)
+            for outer_item in self:
+                key = outer_key_selector(outer_item)
+                matches = None if key is None else lookup.get(key)
+                if matches is None:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(outer_item, None)
+                    else:
+                        yield result_selector(outer_item, None)
+                    continue
+                for inner_item in matches:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(outer_item, inner_item)
+                    else:
+                        yield result_selector(outer_item, inner_item)
+
+        return FlpIt(_FactoryIterable(_generator))
+
+    @overload
+    def full_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem | None, TInner | None]]: ...
+
+    @overload
+    def full_join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem | None, TInner | None], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def full_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem | None, TInner | None], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        """
+        Full outer join (no .NET LINQ equivalent).
+
+        Produces everything ``left_join`` does (unmatched outer elements paired with ``None``),
+        followed by every inner element that was never matched by any outer element, paired with
+        ``None`` as the outer element (``result_selector(None, inner)``), in inner order.
+        Elements with a ``None`` key never match and therefore always appear unmatched.
+        The outer sequence is streamed; the inner sequence is buffered.
+        """
+        _validate_join_args(inner, outer_key_selector, inner_key_selector, result_selector)
+
+        def _generator() -> Iterator[Any]:
+            inner_items: list[tuple[Any, TInner]] = []
+            lookup: dict[Any, list[TInner]] = {}
+            for inner_item in inner:
+                inner_key = inner_key_selector(inner_item)
+                inner_items.append((inner_key, inner_item))
+                if inner_key is not None:
+                    lookup.setdefault(inner_key, []).append(inner_item)
+
+            matched_keys: set[Any] = set()
+            for outer_item in self:
+                key = outer_key_selector(outer_item)
+                matches = None if key is None else lookup.get(key)
+                if matches is None:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(outer_item, None)
+                    else:
+                        yield result_selector(outer_item, None)
+                    continue
+                matched_keys.add(key)
+                for inner_item in matches:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(outer_item, inner_item)
+                    else:
+                        yield result_selector(outer_item, inner_item)
+
+            for inner_key, inner_item in inner_items:
+                if inner_key is None or inner_key not in matched_keys:
+                    if result_selector is _SENTINEL:
+                        yield JoinTuple(None, inner_item)
+                    else:
+                        yield result_selector(None, inner_item)
 
         return FlpIt(_FactoryIterable(_generator))
 
     def chunk(self, size: int) -> FlpIt[FlpList[TItem]]:
         """Splits the elements of a sequence into chunks of size at most size."""
         if size <= 0:
-            raise ValueError("Chunk size must be greater than 0.")
+            raise ArgumentOutOfRangeError("Specified argument was out of the range of valid values. (Parameter 'size')")
 
         def _generator() -> Iterator[FlpList[TItem]]:
             current_chunk: List[TItem] = []
@@ -554,29 +943,44 @@ class FlpIt[TItem](Iterable[TItem]):
 
         return typing_cast(TItem, last_item)
 
-    def _extreme(self, func: Any, **kwargs: Any) -> TItem:
-        result = func(self, default=_MISSING, **kwargs)
+    @overload
+    def min(self) -> TItem: ...
 
-        if result is _MISSING:
-            raise EmptySequenceError()
+    @overload
+    def min[TResult](self, selector: Callable[[TItem], TResult]) -> TResult: ...
 
-        return typing_cast(TItem, result)
+    def min(self, selector: Callable[[TItem], Any] | _Sentinel = _SENTINEL) -> Any:
+        """
+        Returns the minimum value in a sequence, optionally projecting each
+        element through a selector first (Enumerable.Min / Min(selector)).
 
-    def min(self) -> TItem:
-        """Returns the minimum value in a sequence."""
-        return self._extreme(builtins.min)
+        With a selector the minimum *projected value* is returned, not the
+        element (use min_by for that). None values are ignored; all-None
+        returns None; empty raises EmptySequenceError; NaN wins if present.
+        """
+        return _extreme_values(_project(self, selector), True)
 
-    def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        """Returns the value in a sequence that has the minimum key value."""
-        return self._extreme(builtins.min, key=key_selector)
+    @overload
+    def max(self) -> TItem: ...
 
-    def max(self) -> TItem:
-        """Returns the maximum value in a sequence."""
-        return self._extreme(builtins.max)
+    @overload
+    def max[TResult](self, selector: Callable[[TItem], TResult]) -> TResult: ...
+
+    def max(self, selector: Callable[[TItem], Any] | _Sentinel = _SENTINEL) -> Any:
+        """
+        Returns the maximum value in a sequence, optionally projecting each
+        element through a selector first (Enumerable.Max / Max(selector)).
+        Same None / NaN / empty rules as min.
+        """
+        return _extreme_values(_project(self, selector), False)
+
+    def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
+        """Returns the element with the minimum key (Enumerable.MinBy)."""
+        return _extreme_by(self, key_selector, True)
 
     def max_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        """Returns the value in a sequence that has the maximum key value."""
-        return self._extreme(builtins.max, key=key_selector)
+        """Returns the element with the maximum key (Enumerable.MaxBy)."""
+        return _extreme_by(self, key_selector, False)
 
     def average(
             self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
@@ -672,6 +1076,23 @@ class FlpIt[TItem](Iterable[TItem]):
         except (EmptySequenceError, NoMatchError):
             return default
 
+    def last_or_default[TResult](
+            self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
+    ) -> TItem | TResult:
+        """Returns the last element matching a predicate, or a default value."""
+        try:
+            return self.last(predicate)
+        except (EmptySequenceError, NoMatchError):
+            return default
+
+    def reverse(self) -> FlpIt[TItem]:
+        """Returns the elements of the sequence in reverse order."""
+        def _generator() -> Iterator[TItem]:
+            items = list(self)
+            yield from reversed(items)
+
+        return FlpIt(_FactoryIterable(_generator))
+
     def single(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         """Returns the single, unique element matching a predicate."""
         has_predicate = predicate is not _SENTINEL
@@ -1154,7 +1575,7 @@ class FlpList[TItem](Collection[TItem]):
         return FlpIt(self.__list.data).distinct_by(key_selector)
 
     @overload
-    def zip(self, second: Iterable[TOther]) -> FlpIt[tuple[TItem, TOther]]: ...
+    def zip(self, second: Iterable[TOther]) -> FlpIt[ZipTuple[TItem, TOther]]: ...
 
     @overload
     def zip[TResult, TOther](
@@ -1170,6 +1591,84 @@ class FlpList[TItem](Collection[TItem]):
     ) -> FlpIt[Any]:
         return FlpIt(self.__list.data).zip(second, result_selector)
 
+    @overload
+    def join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem, TInner]]: ...
+
+    @overload
+    def join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        return FlpIt(self.__list.data).join(inner, outer_key_selector, inner_key_selector, result_selector)
+
+    @overload
+    def left_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem, TInner | None]]: ...
+
+    @overload
+    def left_join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner | None], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def left_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem, TInner | None], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        return FlpIt(self.__list.data).left_join(inner, outer_key_selector, inner_key_selector, result_selector)
+
+    @overload
+    def full_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+    ) -> FlpIt[JoinTuple[TItem | None, TInner | None]]: ...
+
+    @overload
+    def full_join[TResult, TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem | None, TInner | None], TResult],
+    ) -> FlpIt[TResult]: ...
+
+    def full_join[TInner](
+            self,
+            inner: Iterable[TInner],
+            outer_key_selector: Callable[[TItem], Any],
+            inner_key_selector: Callable[[TInner], Any],
+            result_selector: Callable[[TItem | None, TInner | None], Any] | _Sentinel = _SENTINEL,
+    ) -> FlpIt[Any]:
+        return FlpIt(self.__list.data).full_join(inner, outer_key_selector, inner_key_selector, result_selector)
+
     def chunk(self, size: int) -> FlpIt[FlpList[TItem]]:
         return FlpIt(self.__list.data).chunk(size)
 
@@ -1208,21 +1707,29 @@ class FlpList[TItem](Collection[TItem]):
     def aggregate(self, *args: Any) -> Any:
         return FlpIt(self.__list.data).aggregate(*args)
 
-    @_guard_empty
-    def min(self) -> TItem:
-        return builtins.min(self.__list.data) # pyrefly: ignore [bad-specialization]
+    @overload
+    def min(self) -> TItem: ...
+
+    @overload
+    def min[TResult](self, selector: Callable[[TItem], TResult]) -> TResult: ...
 
-    @_guard_empty
-    def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        return builtins.min(self.__list.data, key=key_selector)
+    def min(self, selector: Callable[[TItem], Any] | _Sentinel = _SENTINEL) -> Any:
+        return _extreme_values(_project(self.__list.data, selector), True)
+
+    @overload
+    def max(self) -> TItem: ...
 
-    @_guard_empty
-    def max(self) -> TItem:
-        return builtins.max(self.__list.data) # pyrefly: ignore [bad-specialization]
+    @overload
+    def max[TResult](self, selector: Callable[[TItem], TResult]) -> TResult: ...
+
+    def max(self, selector: Callable[[TItem], Any] | _Sentinel = _SENTINEL) -> Any:
+        return _extreme_values(_project(self.__list.data, selector), False)
+
+    def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
+        return _extreme_by(self.__list.data, key_selector, True)
 
-    @_guard_empty
     def max_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        return builtins.max(self.__list.data, key=key_selector)
+        return _extreme_by(self.__list.data, key_selector, False)
 
     def sum(
             self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
@@ -1300,6 +1807,14 @@ class FlpList[TItem](Collection[TItem]):
     ) -> TItem | TResult:
         return FlpIt(self.__list.data).first_or_default(default, predicate)
 
+    def last_or_default[TResult](
+            self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
+    ) -> TItem | TResult:
+        try:
+            return self.last(predicate)
+        except (EmptySequenceError, NoMatchError):
+            return default
+
     def single(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         return FlpIt(self.__list.data).single(predicate)
 
@@ -1360,4 +1875,4 @@ class FlpList[TItem](Collection[TItem]):
         JsonConvert.serialize_to(self, item_type, output, jso)
 
 # I hate it, but Python being Python
-from ._grouping import Grouping
+from ._grouping import Grouping

{flpit-0.3.0 → flpit-0.3.1.dev6}/src/flpit/csv.py

@@ -186,148 +186,3 @@ class CsvLoader:
                     from_attributes=True,
                     strict=False,
                 )
-
-# import csv
-# import io
-# from dataclasses import dataclass
-# from pathlib import Path
-# from typing import TextIO
-#
-# import msgspec
-#
-# from flpit.core.linq import FlpList
-# from flpit.json import (
-#     JProp,
-#     JsonNamingPolicy,
-#     JsonSerializerOptions,
-#     wire_type_for,
-# )
-#
-#
-# class CsvCol(JProp):
-#     """Explicit CSV column name using the existing property metadata."""
-#
-#
-# @dataclass(frozen=True, slots=True)
-# class CsvOptions:
-#     """CSV parsing and field-mapping options.
-#
-#     The naming policy defaults to none, so CSV headers match Python field
-#     names unless an explicit CsvCol/JProp name is supplied.
-#     """
-#
-#     delimiter: str = ","
-#     quotechar: str = '"'
-#     escapechar: str | None = None
-#     doublequote: bool = True
-#     skipinitialspace: bool = False
-#     strict: bool = False
-#     encoding: str = "utf-8-sig"
-#     naming_policy: JsonNamingPolicy = JsonNamingPolicy.none
-#
-#     def __post_init__(self) -> None:
-#         if len(self.delimiter) != 1:
-#             raise ValueError("delimiter must be exactly one character")
-#         if len(self.quotechar) != 1:
-#             raise ValueError("quotechar must be exactly one character")
-#         if self.escapechar is not None and len(self.escapechar) != 1:
-#             raise ValueError("escapechar must be exactly one character")
-#
-#     def to_json_options(self) -> JsonSerializerOptions:
-#         """Map CSV field naming to the shared wire-schema builder."""
-#         return JsonSerializerOptions(naming_policy=self.naming_policy)
-#
-#
-# class CsvLoader:
-#     @staticmethod
-#     def load[T](
-#             data: str | Path,
-#             item_type: type[T],
-#             options: CsvOptions | None = None,
-#     ) -> FlpList[T]:
-#         """Load CSV content or a CSV file into a FlpList.
-#
-#         CSV headers are matched using the configured naming policy and
-#         explicit property metadata. The naming policy is passed to the
-#         existing JSON wire-schema builder so annotation handling stays
-#         consistent with JsonConvert.
-#
-#         CSV values are converted in lax mode because CSV supplies text
-#         values, including numeric values represented as strings.
-#
-#         Args:
-#             data: CSV content as a string, or a Path to a CSV file.
-#             item_type: Model type to construct for each row.
-#             options: CSV dialect, encoding and naming options.
-#
-#         Returns:
-#             A FlpList containing instances of item_type.
-#         """
-#         csv_options = options or CsvOptions()
-#         json_options = csv_options.to_json_options()
-#         wire_type = wire_type_for(item_type, json_options)
-#
-#         if isinstance(data, Path):
-#             with data.open(
-#                     "r",
-#                     newline="",
-#                     encoding=csv_options.encoding,
-#             ) as stream:
-#                 return CsvLoader._load_stream(
-#                     stream, item_type, wire_type, csv_options
-#                 )
-#
-#         with io.StringIO(data, newline="") as stream:
-#             return CsvLoader._load_stream(
-#                 stream, item_type, wire_type, csv_options
-#             )
-#
-#     @staticmethod
-#     def _load_stream[T](
-#             stream: TextIO,
-#             item_type: type[T],
-#             wire_type: type,
-#             options: CsvOptions,
-#     ) -> FlpList[T]:
-#         reader = csv.DictReader(
-#             stream,
-#             delimiter=options.delimiter,
-#             quotechar=options.quotechar,
-#             escapechar=options.escapechar,
-#             doublequote=options.doublequote,
-#             skipinitialspace=options.skipinitialspace,
-#             strict=options.strict,
-#         )
-#
-#         if reader.fieldnames is None:
-#             raise ValueError("CSV input must contain a header row")
-#
-#         if len(reader.fieldnames) != len(set(reader.fieldnames)):
-#             raise ValueError("CSV column names must be unique")
-#
-#         def convert_rows():
-#             for row in reader:
-#                 if None in row:
-#                     raise ValueError(
-#                         f"CSV row ending at line {reader.line_num} "
-#                         "contains more values than the header"
-#                     )
-#
-#                 wire_obj = msgspec.convert(
-#                     row,
-#                     wire_type,
-#                     from_attributes=True,
-#                     strict=False,
-#                 )
-#
-#                 # Reconstruct the declared model rather than leaking the
-#                 # dynamically generated wire type to the caller.
-#                 yield msgspec.convert(
-#                     wire_obj,
-#                     item_type,
-#                     from_attributes=True,
-#                     strict=False,
-#                 )
-#
-#         return FlpList[T](convert_rows())
-#