flpit 0.2.4__tar.gz → 0.3.1__tar.gz

{flpit-0.2.4 → flpit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.4
+Version: 0.3.1
 Summary: Fluent LINQ for Python — flip your iterables
 Project-URL: Homepage, https://github.com/riemar/flpit
 Project-URL: Repository, https://github.com/riemar/flpit
@@ -24,6 +24,9 @@ Description-Content-Type: text/markdown
 
 # FlpIt
 
+**[🌐 View on GitHub](https://github.com/riemar/flpit)** | [📦 View on PyPI](https://pypi.org/project/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.
@@ -32,17 +35,14 @@ Description-Content-Type: text/markdown
 > 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.
 
-> **⚠️ Breaking Change — `FlpList` — v0.2.0**
->
-> `FlpList` no longer derives from `collections.UserList`.
->
-> **Retained:** Python collection behavior such as iteration, `len()`, `in`, indexing, and slicing.
->
-> **LINQ:** `append()`, `concat()`, and other LINQ operations remain available with lazy semantics.
->
-> **`List<T>` semantics:** `add()`, `add_range()`, and other mutating operations follow the `List<T>` API where applicable.
->
-> **Removed:** `copy()`, `+`, `*`, and other `UserList`-specific operations that are not part of the `FlpList` API.
+## Familiar LINQ, Now in Python
+
+FlpIt is a Python implementation of the popular .NET Language Integrated Query (LINQ), adapted to Python.
+
+If you know C# LINQ, you already know most of FlpIt. Existing LINQ examples, query patterns, and documentation can generally be translated directly.
+FlpIt aims to make its implemented LINQ operators behave like their corresponding .NET `System.Linq.Enumerable` counterparts.
+
+This makes the extensive .NET LINQ ecosystem a valuable reference for developers and AI coding assistants alike.
 
 ## ⚡ Key Features
 
@@ -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
@@ -405,8 +434,13 @@ Key features:
 - **Task coordination:** `Task.when_all()` waits for all tasks while preserving input order; `Task.when_any()` returns the first completed task; `Task.collect()` yields tasks as they complete.
 - **Cancellation:** `CancellationToken` and `CancellationTokenSource` support cooperative cancellation, cancellation callbacks, timeouts, and linked cancellation tokens.
 - **Resource management:** Configure worker capacity and pending background-work limits, handle queue saturation explicitly, and shut down the process-wide runtime with an observable shutdown report.
+- **Asyncio interoperability:** FlpIt Tasks can be awaited directly inside asyncio coroutines when Task.asyncio_interop is enabled. 
+  - This is disabled by default. 
+  - Enabling it adds runtime-detection overhead to every pending await.
+    - await in flpit runtime: 200ish nano sec (just loop detection)
+    - await in asyncio loop: 
 
-The runtime starts lazily and manages its own lifecycle. It is deliberately not an `asyncio` compatibility layer; cancellation of running synchronous functions is cooperative.
+The runtime starts lazily and manages its own lifecycle. Cancellation of running synchronous functions is cooperative.
 
 See the [Task Runtime examples](https://github.com/riemar/flpit/tree/main/examples/task) for usage examples.
 
@@ -427,25 +461,53 @@ Distributed under the MIT License. See `LICENSE` for more information.
 > Note: The test cases exercise both core types, `FlpIt` and `FlpList`, with transitions between lazy and eager execution occurring as part of the individual test cases.
 
 ```
-================================================================
-| Test Module File                               |  Test Cases |
-----------------------------------------------------------------
-| tests/nettests/                                |             |
-| ├── test_all.py                                |          80 |
-| ├── test_any.py                                |          90 |
-| ├── test_average.py                            |         572 |
-| ├── test_concat.py                             |          64 |
-| ├── test_count.py                              |          37 |
-| ├── test_generic_list.py                       |          95 |
-| ├── test_last.py                               |          29 |
-| ├── test_order_by.py                           |         100 |
-| ├── test_order_descending_by.py                |          45 |
-| ├── test_skip.py                               |          75 |
-| ├── test_sum.py                                |         134 |
-| ├── test_take.py                               |          39 |
-| ├── test_then_by.py                            |          40 |
-| └── test_then_descending_by.py                 |          34 |
-----------------------------------------------------------------
-| GRAND TOTALS                                   |        1434 |
-================================================================
+================================================================================
+| Test Module File                                               |  Test Cases |
+--------------------------------------------------------------------------------
+| tests/nettests/                                                |             |
+| ├── linq/                                                      |             |
+| │   ├── test_aggregate.py                                      |          42 |
+| │   ├── 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_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 |
+| │   ├── test_single_or_default.py                              |          48 |
+| │   ├── test_skip.py                                           |          75 |
+| │   ├── test_sum.py                                            |         134 |
+| │   ├── test_take.py                                           |          39 |
+| │   ├── test_then_by.py                                        |          40 |
+| │   ├── test_then_descending_by.py                             |          34 |
+| │   ├── test_where.py                                          |          76 |
+| │   └── test_zip.py                                            |         101 |
+| └── task/                                                      |             |
+|     ├── test_cancellation.py                                   |          69 |
+|     ├── test_task_completion_source.py                         |          26 |
+|     ├── test_task_factory.py                                   |           3 |
+|     ├── test_task_rt.py                                        |          12 |
+|     └── test_task_rt_core.py                                   |          22 |
+--------------------------------------------------------------------------------
+| GRAND TOTALS                                                   |        4733 |
+================================================================================
 ```

{flpit-0.2.4 → flpit-0.3.1}/README.md

@@ -1,5 +1,8 @@
 # FlpIt
 
+**[🌐 View on GitHub](https://github.com/riemar/flpit)** | [📦 View on PyPI](https://pypi.org/project/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.
@@ -8,17 +11,14 @@
 > 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.
 
-> **⚠️ Breaking Change — `FlpList` — v0.2.0**
->
-> `FlpList` no longer derives from `collections.UserList`.
->
-> **Retained:** Python collection behavior such as iteration, `len()`, `in`, indexing, and slicing.
->
-> **LINQ:** `append()`, `concat()`, and other LINQ operations remain available with lazy semantics.
->
-> **`List<T>` semantics:** `add()`, `add_range()`, and other mutating operations follow the `List<T>` API where applicable.
->
-> **Removed:** `copy()`, `+`, `*`, and other `UserList`-specific operations that are not part of the `FlpList` API.
+## Familiar LINQ, Now in Python
+
+FlpIt is a Python implementation of the popular .NET Language Integrated Query (LINQ), adapted to Python.
+
+If you know C# LINQ, you already know most of FlpIt. Existing LINQ examples, query patterns, and documentation can generally be translated directly.
+FlpIt aims to make its implemented LINQ operators behave like their corresponding .NET `System.Linq.Enumerable` counterparts.
+
+This makes the extensive .NET LINQ ecosystem a valuable reference for developers and AI coding assistants alike.
 
 ## ⚡ Key Features
 
@@ -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
@@ -381,8 +410,13 @@ Key features:
 - **Task coordination:** `Task.when_all()` waits for all tasks while preserving input order; `Task.when_any()` returns the first completed task; `Task.collect()` yields tasks as they complete.
 - **Cancellation:** `CancellationToken` and `CancellationTokenSource` support cooperative cancellation, cancellation callbacks, timeouts, and linked cancellation tokens.
 - **Resource management:** Configure worker capacity and pending background-work limits, handle queue saturation explicitly, and shut down the process-wide runtime with an observable shutdown report.
+- **Asyncio interoperability:** FlpIt Tasks can be awaited directly inside asyncio coroutines when Task.asyncio_interop is enabled. 
+  - This is disabled by default. 
+  - Enabling it adds runtime-detection overhead to every pending await.
+    - await in flpit runtime: 200ish nano sec (just loop detection)
+    - await in asyncio loop: 
 
-The runtime starts lazily and manages its own lifecycle. It is deliberately not an `asyncio` compatibility layer; cancellation of running synchronous functions is cooperative.
+The runtime starts lazily and manages its own lifecycle. Cancellation of running synchronous functions is cooperative.
 
 See the [Task Runtime examples](https://github.com/riemar/flpit/tree/main/examples/task) for usage examples.
 
@@ -403,25 +437,53 @@ Distributed under the MIT License. See `LICENSE` for more information.
 > Note: The test cases exercise both core types, `FlpIt` and `FlpList`, with transitions between lazy and eager execution occurring as part of the individual test cases.
 
 ```
-================================================================
-| Test Module File                               |  Test Cases |
-----------------------------------------------------------------
-| tests/nettests/                                |             |
-| ├── test_all.py                                |          80 |
-| ├── test_any.py                                |          90 |
-| ├── test_average.py                            |         572 |
-| ├── test_concat.py                             |          64 |
-| ├── test_count.py                              |          37 |
-| ├── test_generic_list.py                       |          95 |
-| ├── test_last.py                               |          29 |
-| ├── test_order_by.py                           |         100 |
-| ├── test_order_descending_by.py                |          45 |
-| ├── test_skip.py                               |          75 |
-| ├── test_sum.py                                |         134 |
-| ├── test_take.py                               |          39 |
-| ├── test_then_by.py                            |          40 |
-| └── test_then_descending_by.py                 |          34 |
-----------------------------------------------------------------
-| GRAND TOTALS                                   |        1434 |
-================================================================
+================================================================================
+| Test Module File                                               |  Test Cases |
+--------------------------------------------------------------------------------
+| tests/nettests/                                                |             |
+| ├── linq/                                                      |             |
+| │   ├── test_aggregate.py                                      |          42 |
+| │   ├── 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_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 |
+| │   ├── test_single_or_default.py                              |          48 |
+| │   ├── test_skip.py                                           |          75 |
+| │   ├── test_sum.py                                            |         134 |
+| │   ├── test_take.py                                           |          39 |
+| │   ├── test_then_by.py                                        |          40 |
+| │   ├── test_then_descending_by.py                             |          34 |
+| │   ├── test_where.py                                          |          76 |
+| │   └── test_zip.py                                            |         101 |
+| └── task/                                                      |             |
+|     ├── test_cancellation.py                                   |          69 |
+|     ├── test_task_completion_source.py                         |          26 |
+|     ├── test_task_factory.py                                   |           3 |
+|     ├── test_task_rt.py                                        |          12 |
+|     └── test_task_rt_core.py                                   |          22 |
+--------------------------------------------------------------------------------
+| GRAND TOTALS                                                   |        4733 |
+================================================================================
 ```

{flpit-0.2.4 → flpit-0.3.1}/pyproject.toml

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

{flpit-0.2.4 → flpit-0.3.1}/src/flpit/__init__.py

@@ -1,15 +1,18 @@
 """
 Fluent LINQ for Python — flip your iterables.
 """
-from __future__ import annotations
 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,
     FlpList,
-    Grouping,
+    # Grouping,
     OrderedIt,
 
     #====================
@@ -31,11 +34,18 @@ from flpit.core.linq import (
     CollectionNoneError,
     SelectorNoneError,
     SecondNoneError,
+    FuncNoneError,
+    ResultSelectorNoneError,
+    InnerNoneError,
+    OuterKeySelectorNoneError,
+    InnerKeySelectorNoneError,
     ArgumentOutOfRangeError,
     ArgumentNonNegError,
-    ArgumentOutOfBoundsError
+    ArgumentOutOfBoundsError,
 )
 
+from flpit.core._grouping import Grouping
+
 __all__ = [
     "flp",
     "FlpIt",
@@ -56,8 +66,16 @@ __all__ = [
     "CollectionNoneError",
     "SelectorNoneError",
     "SecondNoneError",
+    "FuncNoneError",
+    "ResultSelectorNoneError",
+    "InnerNoneError",
+    "OuterKeySelectorNoneError",
+    "InnerKeySelectorNoneError",
     "ArgumentOutOfRangeError",
     "ArgumentNonNegError",
     "ArgumentOutOfBoundsError",
+
+    "ZipTuple",
+    "JoinTuple",
 ]
 

flpit-0.3.1/src/flpit/core/_grouping.py

@@ -0,0 +1,29 @@
+from typing import Any
+from flpit.core.linq import FlpList
+from typing import override
+from collections.abc import Iterable
+
+class Grouping[TKey, TItem](FlpList[TItem]):
+    """Represents a collection of elements sharing a common key (.NET IGrouping<TKey, TElement>)."""
+    __slots__ = ("_key", )
+
+    def __init__(self, key: TKey, elements: Iterable[TItem]) -> None:
+        self._key: TKey = key
+        super().__init__(elements)
+
+    @property
+    def key(self) -> TKey:
+        return self._key
+
+    @override
+    def __repr__(self) -> str:
+        return f"Grouping(key={self.key!r}, elements={self.to_list()!r})"
+
+    @override
+    def __eq__(self, other: Any) -> bool:
+        # Check if the other object is a Grouping (or subclass)
+        if not isinstance(other, Grouping):
+            return False
+
+        # Compare the keys, then compare the elements inside FlpIt
+        return self.key == other.key and self.to_list() == other.to_list()

flpit-0.3.1/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/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