flpit 0.1.6__tar.gz → 0.2.0.dev2__tar.gz

{flpit-0.1.6 → flpit-0.2.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.1.6
+Version: 0.2.0.dev2
 Summary: Fluent LINQ for Python — flip your iterables
 License: MIT
 License-File: LICENSE
@@ -28,11 +28,23 @@ 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.
+
 ## ⚡ 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.
+* **⚡ Lazy Evaluation (`FlpIt`):** Deferred, streaming execution wrapping any standard Python `Iterable[T]`.
+* **📦 Materialized Container (`FlpList`):** Eager collection implementing Python's `Collection` protocol (with indexing and slicing), retaining familiar collection access while providing .NET `List<T>`-style semantics and fluent LINQ query operations.
+* **🎯 LINQ Semantics:** Familiar operators like `.any()`, `.first()`, `.single()`, `.order_by()`, and `.then_by()` with predictable, composable behavior.
 * **🔀 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.
@@ -186,26 +198,31 @@ list(query)  # [0, 1, 2]
 list(query)  # []
 ```
 
-## Intentional Deviation from Python List Contracts (`.count()`)
+## Intentional Semantic Deviation: `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)`.
+`FlpList` is a LINQ-oriented collection. Its query methods follow LINQ semantics even when those semantics differ from Python's built-in collection methods.
 
-* **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.
+In Python, `list.count(value)` counts occurrences of a specific value:
 
-```python
-# Pure LINQ semantics instead of standard list behavior
-total_evens = eager_list.count(lambda x: x % 2 == 0)
+```
+[1, 2, 2, 3].count(2)  # 2
 ```
 
-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:
+In LINQ, `Count()` returns the total number of elements, or elements matching a predicate:
 
-```python
-# Use the fallback for traditional Python value-counting
-occurrences = eager_list.count_item(4)
+```
+FlpList([1, 2, 2, 3]).count()                 # 4
+FlpList([1, 2, 2, 3]).count(lambda x: x > 1)  # 3
+```
+
+`FlpList.count()` deliberately follows the LINQ meaning. Python-style value counting remains available through normal Python operations when needed:
+
+```
+list(FlpList([1, 2, 2, 3])).count(2)  # 2
 ```
 
+This behavior is a core part of `FlpList`'s LINQ-oriented contract, not an incomplete `list` implementation.
+
 ## 🔗 Independent Query Pipelines
 
 Query pipelines can be composed independently without mutating the queries they were derived from:
@@ -260,14 +277,22 @@ Lazy execution does not mean that every operator is streaming. Some operators mu
 `group_by()` produces a query of groupings rather than terminating the pipeline:
 
 ```python
-groups = query.group_by(lambda x: x % 3)
+from typing import NamedTuple
+
+class GroupResult(NamedTuple):
+    remainder: int
+    values: list[int]
 
 result = (
-    groups
-    .where(...)
-    .select(...)
+    flp.it(range(1, 11))
+    .group_by(lambda x: x % 2)
+    .select(lambda group: GroupResult(
+        remainder=group.key,
+        values=list(group),
+    ))
     .to_list()
 )
+
 ```
 
 Terminal operators instead evaluate the query and return a result rather than another query:
@@ -328,4 +353,32 @@ uv add flpit
 
 ## 📜 License
 
-Distributed under the MIT License. See `LICENSE` for more information.
+Distributed under the MIT License. See `LICENSE` for more information.
+
+
+### Migrated .NET Unit Tests
+
+> Migrated from the official .NET Runtime LINQ Tests.
+> 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_count.py                              |          37 |
+| ├── test_generic_list.py                       |          95 |
+| ├── test_last.py                               |          29 |
+| ├── test_order_by.py                           |         100 |
+| ├── test_order_descending_by.py                |          45 |
+| ├── test_sum.py                                |         134 |
+| ├── test_take.py                               |          39 |
+| ├── test_then_by.py                            |          40 |
+| └── test_then_descending_by.py                 |          34 |
+----------------------------------------------------------------
+| GRAND TOTALS                                   |        1295 |
+================================================================
+```

{flpit-0.1.6 → flpit-0.2.0.dev2}/README.md

@@ -8,11 +8,23 @@
 > 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.
+
 ## ⚡ 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.
+* **⚡ Lazy Evaluation (`FlpIt`):** Deferred, streaming execution wrapping any standard Python `Iterable[T]`.
+* **📦 Materialized Container (`FlpList`):** Eager collection implementing Python's `Collection` protocol (with indexing and slicing), retaining familiar collection access while providing .NET `List<T>`-style semantics and fluent LINQ query operations.
+* **🎯 LINQ Semantics:** Familiar operators like `.any()`, `.first()`, `.single()`, `.order_by()`, and `.then_by()` with predictable, composable behavior.
 * **🔀 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.
@@ -166,26 +178,31 @@ list(query)  # [0, 1, 2]
 list(query)  # []
 ```
 
-## Intentional Deviation from Python List Contracts (`.count()`)
+## Intentional Semantic Deviation: `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)`.
+`FlpList` is a LINQ-oriented collection. Its query methods follow LINQ semantics even when those semantics differ from Python's built-in collection methods.
 
-* **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.
+In Python, `list.count(value)` counts occurrences of a specific value:
 
-```python
-# Pure LINQ semantics instead of standard list behavior
-total_evens = eager_list.count(lambda x: x % 2 == 0)
+```
+[1, 2, 2, 3].count(2)  # 2
 ```
 
-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:
+In LINQ, `Count()` returns the total number of elements, or elements matching a predicate:
 
-```python
-# Use the fallback for traditional Python value-counting
-occurrences = eager_list.count_item(4)
+```
+FlpList([1, 2, 2, 3]).count()                 # 4
+FlpList([1, 2, 2, 3]).count(lambda x: x > 1)  # 3
+```
+
+`FlpList.count()` deliberately follows the LINQ meaning. Python-style value counting remains available through normal Python operations when needed:
+
+```
+list(FlpList([1, 2, 2, 3])).count(2)  # 2
 ```
 
+This behavior is a core part of `FlpList`'s LINQ-oriented contract, not an incomplete `list` implementation.
+
 ## 🔗 Independent Query Pipelines
 
 Query pipelines can be composed independently without mutating the queries they were derived from:
@@ -240,14 +257,22 @@ Lazy execution does not mean that every operator is streaming. Some operators mu
 `group_by()` produces a query of groupings rather than terminating the pipeline:
 
 ```python
-groups = query.group_by(lambda x: x % 3)
+from typing import NamedTuple
+
+class GroupResult(NamedTuple):
+    remainder: int
+    values: list[int]
 
 result = (
-    groups
-    .where(...)
-    .select(...)
+    flp.it(range(1, 11))
+    .group_by(lambda x: x % 2)
+    .select(lambda group: GroupResult(
+        remainder=group.key,
+        values=list(group),
+    ))
     .to_list()
 )
+
 ```
 
 Terminal operators instead evaluate the query and return a result rather than another query:
@@ -308,4 +333,32 @@ uv add flpit
 
 ## 📜 License
 
-Distributed under the MIT License. See `LICENSE` for more information.
+Distributed under the MIT License. See `LICENSE` for more information.
+
+
+### Migrated .NET Unit Tests
+
+> Migrated from the official .NET Runtime LINQ Tests.
+> 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_count.py                              |          37 |
+| ├── test_generic_list.py                       |          95 |
+| ├── test_last.py                               |          29 |
+| ├── test_order_by.py                           |         100 |
+| ├── test_order_descending_by.py                |          45 |
+| ├── test_sum.py                                |         134 |
+| ├── test_take.py                               |          39 |
+| ├── test_then_by.py                            |          40 |
+| └── test_then_descending_by.py                 |          34 |
+----------------------------------------------------------------
+| GRAND TOTALS                                   |        1295 |
+================================================================
+```

{flpit-0.1.6 → flpit-0.2.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.1.6"
+version = "0.2.0.dev2"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -27,6 +27,7 @@ dev = [
     "pyrefly>=1.3.1",
     "pyright>=1.1.414",
     "pytest-benchmark>=5.3.0",
+    "mypy>=2.4.0",
 ]
 
 

{flpit-0.1.6 → flpit-0.2.0.dev2}/src/flpit/core/linq.py

@@ -1,19 +1,21 @@
 from __future__ import annotations
-from threading import Lock
+from typing import SupportsIndex
+import decimal
+from decimal import Decimal, Overflow, Inexact
 
 import builtins
 from collections import UserList
 from functools import wraps
 from itertools import islice
+
 from typing import (
     Any,
     Callable,
     Generic,
     Iterable,
     Iterator,
+    Collection,
     List,
-    Optional,
-    Sequence,
     Set,
     Type,
     TypeVar,
@@ -22,7 +24,6 @@ from typing import (
     overload,
     cast as typing_cast,
 )
-
 TItem = TypeVar("TItem")
 TResult = TypeVar("TResult")
 TKey = TypeVar("TKey")
@@ -63,6 +64,14 @@ class PredicateNoneError(TypeError):
     def __init__(self):
         super().__init__("Value cannot be None. (Argument 'predicate')")
 
+class CollectionNoneError(TypeError):
+    def __init__(self):
+        super().__init__("Value cannot be None. (Argument 'collection')")
+
+class SelectorNoneError(TypeError):
+    def __init__(self):
+        super().__init__("Value cannot be None. (Parameter 'keySelector')")
+
 
 def _guard_empty(func: Callable[..., Any]) -> Callable[..., Any]:
     """Catches Python's native empty-sequence ValueError and re-raises LINQ-compliant error."""
@@ -71,12 +80,23 @@ def _guard_empty(func: Callable[..., Any]) -> Callable[..., Any]:
         try:
             return func(self, *args, **kwargs)
         except ValueError as e:
-            if not self.data:
+            if not self._FlpList__list.data:
                 raise EmptySequenceError() from e
             raise
     return wrapper
 
 
+# noinspection unresolved-references,protected-member
+def dotnet_context() -> decimal._ContextManager: # awesome that type was not intended
+    # 1. Create and configure pure Context object
+    ctx = decimal.getcontext().copy()
+    ctx.prec = max(ctx.prec, 29)
+    ctx.traps[Overflow] = True
+    ctx.traps[Inexact] = True
+
+    return decimal.localcontext(ctx)
+
+
 class _FactoryIterable(Iterable[TItem], Generic[TItem]):
     """
     Wraps a generator factory function into a clean Iterable[T].
@@ -439,41 +459,61 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         return self._extreme(builtins.max, key=key_selector)
 
     def average(
-            self, selector: Callable[[TItem], Union[int, float]] | _Sentinel = _SENTINEL
-    ) -> float:
+            self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
+    ) -> float | int | Decimal | None:
         """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 _SENTINEL else self
-        for item in query:
-            total += float(item)  # type: ignore[arg-type]
-            count += 1
-        if count == 0:
-            raise EmptySequenceError()
-        return total / count
+        with dotnet_context():
+            total, count = self.__sum_and_count(selector)
 
-    avg = average
+            if total is None:
+                return None
 
-    def average_by(self, key_selector: Callable[[TItem], Union[int, float]]) -> float:
-        """Computes the average of a sequence of numeric values projected by a key selector."""
-        total = 0.0
-        count = 0
-        for item in self:
-            total += float(key_selector(item))
-            count += 1
-        if count == 0:
-            raise EmptySequenceError()
-        return total / count
+            if isinstance(total, Decimal):
+                return total / Decimal(count)
 
-    avg_by = average_by
+            assert total is not None
+            assert isinstance(total, Decimal) or isinstance(total, int) or isinstance(total, float)
+            return total / count
+
+    avg = average
 
     def sum(
-            self, selector: Callable[[TItem], Union[int, float]] | _Sentinel = _SENTINEL
-    ) -> Union[int, float]:
+            self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
+    ) -> Union[int, float, Decimal]:
         """Calculates the sum of the sequence, optionally applying a selector."""
-        if selector is not _SENTINEL:
-            return builtins.sum(selector(x) for x in self)
-        return builtins.sum(self)  # type: ignore[arg-type]
+        with dotnet_context():
+            total, count = self.__sum_and_count(selector)
+
+            if count == 0:
+                return 0
+
+            assert total is not None
+            assert isinstance(total, Decimal) or isinstance(total, int) or isinstance(total, float)
+            return total
+
+    def __sum_and_count(self, selector: Callable[[TItem], int | float | Decimal]) -> tuple[Decimal | float | int | TItem | None, int]:
+        if selector is None:
+            raise SelectorNoneError()
+
+        total = None
+        count: int = 0
+        query = (selector(x) for x in self) if selector is not _SENTINEL else self
+
+        for item in query:
+            if item is not None:
+                if total is None:
+                    total = item
+                else:
+                    try:
+                        total += item
+                    except (Overflow, Inexact):
+                        raise OverflowError(
+                            "System.OverflowException: Value was either too large or too small for a Decimal."
+                        )
+                count += 1
+
+        return total, count
+
 
     def count(
             self,
@@ -533,152 +573,85 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         """Explicitly materializes the query into a FlpList."""
         return FlpList(self)
 
+from functools import partial
 
-class _OrderState(Generic[TItem]):
-    """
-    Shared lazy snapshot for an OrderBy/ThenBy chain.
-
-    The upstream source is consumed at most once. After materialization,
-    the original source reference is released.
-    """
-
-    __slots__ = ("_source", "_items", "_lock")
-
-    def __init__(self, source: Iterable[TItem]) -> None:
-        self._source: Optional[Iterable[TItem]] = source
-        self._items: Optional[list[TItem]] = None
-        self._lock = Lock()
-
-    def materialize(self) -> list[TItem]:
-        items = self._items
-
-        if items is not None:
-            return items
-
-        with self._lock:
-            items = self._items
+class _NoneOrderKey:
+    __slots__ = ()
 
-            if items is None:
-                source = self._source
+    def __lt__(self, other: object) -> bool:
+        return other is not self
 
-                if source is None:
-                    raise RuntimeError("OrderState source is unavailable")
+    def __gt__(self, other: object) -> bool:
+        return False
 
-                items = list(source)
+    def __eq__(self, other: object) -> bool:
+        return other is self
 
-                self._source = None
-                self._items = items
 
-        return items
+_NONE_ORDER_KEY = _NoneOrderKey()
 
+def _none_aware_key(
+        selector: Callable[[TItem], Any],
+        item: TItem,
+) -> Any:
+    key = selector(item)
+    return _NONE_ORDER_KEY if key is None else key
 
 class OrderedIt(FlpIt[TItem]):
-    """
-    Lazy, memoized ordered iterable.
-
-    The source is materialized once per OrderBy chain.
-    ThenBy nodes share that source snapshot but maintain independent
-    ordered-result caches.
-    """
-
-    __slots__ = (
-        "_state",
-        "_criteria",
-        "_cached_result",
-        "_result_lock",
-    )
+    __slots__ = ("_criteria",)
 
     def __init__(
             self,
             source: Iterable[TItem],
-            key_selector: Callable[[TItem], Any],
+            selector: Callable[[TItem], Any],
             descending: bool = False,
-    ) -> None:
-        # Pass () to FlpIt to prevent storing a permanent reference to the raw source
-        super().__init__(())
-
-
-        self._state = _OrderState(source)
-        self._criteria: tuple[tuple[Callable[[TItem], Any], bool], ...] = (
-            (key_selector, descending),
-        )
+            *,
+            _criteria: tuple[tuple[Callable[[TItem], Any], bool], ...] | None = None,
+    ):
+        if selector is None:
+            raise SelectorNoneError()
 
-        self._cached_result: Optional[list[TItem]] = None
-        self._result_lock = Lock()
+        super().__init__(source)
 
-    @classmethod
-    def _from_parent(
-            cls,
-            parent: OrderedIt[TItem],
-            key_selector: Callable[[TItem], Any],
-            descending: bool,
-    ) -> OrderedIt[TItem]:
-        """
-        Create a child ordering node sharing the parent's source state.
-
-        The FlpIt source is intentionally empty because OrderedIt overrides
-        __iter__ and uses _OrderState as its real source.
-        """
-        child = cls.__new__(cls)
+        if _criteria is None:
+            self._criteria = ((selector, descending),)
+        else:
+            self._criteria = _criteria + ((selector, descending),)
 
-        # Do not retain the parent OrderedIt through FlpIt's _iterable.
-        FlpIt.__init__(child, ())
+    @override
+    def __iter__(self) -> Iterator[TItem]:
+        items = list(self._iterable)
 
-        child._state = parent._state
-        child._criteria = (
-            *parent._criteria,
-            (key_selector, descending),
-        )
-        child._cached_result = None
-        child._result_lock = Lock()
+        for selector, descending in reversed(self._criteria):
+            items.sort(
+                key=partial(_none_aware_key, selector),
+                reverse=descending,
+            )
 
-        return child
+        yield from items
 
     def then_by(
             self,
             key_selector: Callable[[TItem], Any],
-    ) -> OrderedIt[TItem]:
-        return self._from_parent(
-            self,
+    ) -> "OrderedIt[TItem]":
+        return OrderedIt(
+            self._iterable,
             key_selector,
-            descending=False,
+            False,
+            _criteria=self._criteria,
         )
 
     def then_by_descending(
             self,
             key_selector: Callable[[TItem], Any],
-    ) -> OrderedIt[TItem]:
-        return self._from_parent(
-            self,
+    ) -> "OrderedIt[TItem]":
+        return OrderedIt(
+            self._iterable,
             key_selector,
-            descending=True,
+            True,
+            _criteria=self._criteria,
         )
 
-    @override
-    def __iter__(self) -> Iterator[TItem]:
-        cached = self._cached_result
-
-        if cached is None:
-            with self._result_lock:
-                cached = self._cached_result
-
-                if cached is None:
-                    # Never mutate the shared source snapshot.
-                    result = list(self._state.materialize())
-
-                    # Python sort is stable, so apply the least-significant
-                    # criterion first.
-                    for selector, descending in reversed(self._criteria):
-                        result.sort(
-                            key=selector,
-                            reverse=descending,
-                        )
-
-                    cached = result
-                    self._cached_result = cached
-
-        yield from cached
-
 
 class Grouping(FlpIt[TItem], Generic[TKey, TItem]):
     """Represents a collection of elements sharing a common key (.NET IGrouping<TKey, TElement>)."""
@@ -704,7 +677,7 @@ class Grouping(FlpIt[TItem], Generic[TKey, TItem]):
         return self.key == other.key and self.to_list() == other.to_list()
 
 
-class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
+class FlpList(Collection[TItem], Generic[TItem]):
     """
     | Fluent List
     A materialized list extending UserList that yields lazy FlpIt instances for query operations.
@@ -718,7 +691,88 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         else:
             init_list = typing_cast(Iterable[TItem], source)
 
-        super().__init__(init_list)
+        self.__list: UserList[TItem] = UserList[TItem](init_list)
+
+    # =====================================================================
+    # 1. THE ABC CONTRACT
+    # =====================================================================
+    def __iter__(self) -> Iterator[Any]:
+        return self.__list.__iter__()
+
+    def __len__(self) -> int:
+        """Evaluates the stream to get total count."""
+        return self.__list.__len__()
+
+    def __contains__(self, item: TItem) -> bool:
+        return self.__list.__contains__(item)
+
+    # =====================================================================
+    # 2. Keep some of the Python UserList like behavior
+    # =====================================================================
+
+    def __repr__(self):
+        return self.__list.__repr__()
+
+    def __str__(self) -> str:
+        return self.__list.__str__()
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, FlpList):
+            return self.__list.__eq__(other.__list)
+        return self.__list.__eq__(other)
+
+    def __lt__(self, other: Any) -> bool:
+        target = other.__list if isinstance(other, FlpList) else other
+        return self.__list.__lt__(target)
+
+    def __le__(self, other: Any) -> bool:
+        target = other.__list if isinstance(other, FlpList) else other
+        return self.__list.__le__(target)
+
+    def __gt__(self, other: Any) -> bool:
+        target = other.__list if isinstance(other, FlpList) else other
+        return self.__list.__gt__(target)
+
+    def __ge__(self, other: Any) -> bool:
+        target = other.__list if isinstance(other, FlpList) else other
+        return self.__list.__ge__(target)
+
+
+    @overload
+    def __getitem__(self, index: SupportsIndex) -> TItem: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> FlpList[TItem]: ...
+
+    def __getitem__(self, index: SupportsIndex | slice):
+        if isinstance(index, slice):
+            return self.__class__(self.__list[index])
+        else:
+            return self.__list[index]
+
+    @overload
+    def __setitem__(self, index: SupportsIndex, value: TItem) -> None: ...
+
+    @overload
+    def __setitem__(self, index: slice, value: Iterable[TItem]) -> None: ...
+
+    def __setitem__(
+            self,
+            index: SupportsIndex | slice,
+            value: TItem | Iterable[TItem],
+    ) -> None:
+        if isinstance(index, slice):
+            if not isinstance(value, Iterable):
+                raise TypeError("slice assignment requires an iterable value")
+            self.__list.data[index] = value
+        else:
+            if isinstance(value, Iterable):
+                raise TypeError("item assignment requires a non-iterable value")
+            self.__list.data[index] = value
+
+    # =====================================================================
+    # 3. Put .NET List<T> mechanics on top
+    # =====================================================================
 
     def add(self, item: TItem) -> None:
         """
@@ -728,9 +782,9 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         - type checks
         - manual of_type(...) filter if you don't trust your checks
         """
-        self.data.append(item)
+        self.__list.data.append(item)
 
-    def add_range(self, items: Iterable[TItem]) -> None:
+    def add_range(self, collection: Iterable[TItem]) -> None:
         """
         | Adds an Iterable sequence or stream.
         Optimizes paths based on input type without destroying volatile generators.
@@ -739,21 +793,131 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         - type checks
         - manual of_type(...) filter if you don't trust your checks
         """
-        # 1. Optimized Path: Fast memory extensions for pre-materialized sequences
-        if isinstance(items, (Sequence, list, tuple, UserList)):
-            self.data.extend(items)
-            return
+        if collection is None:
+            raise CollectionNoneError()
+
+        if isinstance(collection, UserList):
+            self.__list.data.extend(collection.data)
+        elif isinstance(collection, FlpList):
+            self.__list.data.extend(collection.__list.data)
+        else:
+            self.__list.data.extend(collection)
+
+    def clear(self) -> None:
+        self.__list.data.clear()
+
+    def contains(self, item: TItem) -> bool:
+        return item in self.__list.data
+
+    def exists(self, predicate: Callable[[TItem], bool]) -> bool:
+        return any(predicate(item) for item in self.__list.data)
+
+    def find(self, predicate: Callable[[TItem], bool]) -> TItem | None:
+        if predicate is None:
+            raise PredicateNoneError()
+
+        for item in self.__list.data:
+            if predicate(item):
+                return item
+
+        return None
+
+    def find_all(self, predicate: Callable[[TItem], bool]) -> FlpList[TItem]:
+        if predicate is None:
+            raise PredicateNoneError()
+
+        return FlpList(item for item in self.__list.data if predicate(item))
 
-        # 2. Stream Path: Volatile one-shot generator handling
-        it = iter(items)
+    def insert(self, index: int, item: TItem) -> None:
+        if index < 0 or index > len(self.__list.data):
+            raise IndexError(f"Index {index} is out of range.")
+
+        self.__list.data.insert(index, item)
+
+    def insert_range(self, index: int, collection: Iterable[TItem]) -> None:
+        if collection is None:
+            raise CollectionNoneError()
+
+        if index < 0 or index > len(self.__list.data):
+            raise IndexError(f"Index {index} is out of range.")
+
+        self.__list.data[index:index] = list(collection)
+
+    def remove(self, item: TItem) -> bool:
         try:
-            first_item = next(it)
-        except StopIteration:
+            self.__list.data.remove(item)
+            return True
+        except ValueError:
+            return False
+
+    def remove_all(self, predicate: Callable[[TItem], bool]) -> int:
+        if predicate is None:
+            raise PredicateNoneError()
+
+        original_length = len(self.__list.data)
+
+        self.__list.data[:] = [
+            item
+            for item in self.__list.data
+            if not predicate(item)
+        ]
+
+        return original_length - len(self.__list.data)
+
+    def remove_at(self, index: int) -> None:
+        if index < 0 or index > len(self.__list.data):
+            raise IndexError(f"Index {index} is out of range.")
+
+        del self.__list.data[index]
+
+    def remove_range(self, index: int, count: int) -> None:
+        size = len(self.__list.data)
+
+        if index < 0 or index > size:
+            raise IndexError("index")
+
+        if count < 0:
+            raise IndexError("count")
+
+        if count > size - index:
+            raise IndexError("The range is invalid.")
+
+        del self.__list.data[index : index + count]
+
+    @overload
+    def reverse(self) -> None: ...
+
+    @overload
+    def reverse(self, index: int, count: int) -> None: ...
+
+    def reverse(self, index: int = 0, count: int | None = None) -> None:
+        if count is None:
+            self.__list.data.reverse()
             return
 
-        # Append the tracked peek-element and stream the remainder safely
-        self.data.append(first_item)
-        self.data.extend(it)
+        size = len(self.__list.data)
+
+        # Apply your List<T>-compatible argument validation here.
+        if index < 0 or index > size:
+            raise IndexError("Non-negative number required.")
+
+        if count < 0:
+            raise IndexError("Non-negative number required.")
+
+        if index + count > size:
+            raise IndexError(
+                "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."
+            )
+
+        self.__list.data[index:index + count] = reversed(
+            self.__list.data[index:index + count]
+        )
+
+    # =====================================================================
+    # 4. IEnumerable add-ons
+    # =====================================================================
 
     @overload
     def any(self) -> bool: ...
@@ -766,55 +930,55 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> bool:
         if predicate is _SENTINEL:
-            return len(self.data) > 0
+            return len(self.__list.data) > 0
 
-        return any(predicate(item) for item in self.data)
+        return any(predicate(item) for item in self.__list.data)
 
     def all(
             self,
             predicate: Callable[[TItem], bool],
     ) -> bool:
-        return all(predicate(item) for item in self.data)
+        return all(predicate(item) for item in self.__list.data)
 
-    def append_linq(self, element: TItem) -> FlpIt[TItem]:
+    def append(self, element: TItem) -> FlpIt[TItem]:
         """Appends an element to the sequence lazily, returning a FlpIt without mutating this list."""
-        return FlpIt(self.data).append(element)
+        return FlpIt(self.__list.data).append(element)
 
     def prepend(self, element: TItem) -> FlpIt[TItem]:
         """Prepends an element to the sequence lazily, returning a FlpIt without mutating this list."""
-        return FlpIt(self.data).prepend(element)
+        return FlpIt(self.__list.data).prepend(element)
 
     # noinspection unused-parameter
     def as_type(self, target_type: Type[TResult]) -> FlpList[TResult]:
         return self  # type: ignore[return-value]
 
     def where(self, predicate: Callable[[TItem], bool]) -> FlpIt[TItem]:
-        return FlpIt(self.data).where(predicate)
+        return FlpIt(self.__list.data).where(predicate)
 
     def select(self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
-        return FlpIt(self.data).select(selector)
+        return FlpIt(self.__list.data).select(selector)
 
     def select_many(
             self, selector: Callable[[TItem], Iterable[TResult]]
     ) -> FlpIt[TResult]:
-        return FlpIt(self.data).select_many(selector)
+        return FlpIt(self.__list.data).select_many(selector)
 
     def take(self, count: int) -> FlpIt[TItem]:
-        return FlpIt(self.data).take(count)
+        return FlpIt(self.__list.data).take(count)
 
     def cast(self, target_type: Type[TResult]) -> FlpIt[TResult]:
-        return FlpIt(self.data).cast(target_type)
+        return FlpIt(self.__list.data).cast(target_type)
 
     def of_type(self, target_type: Type[TResult]) -> FlpIt[TResult]:
-        return FlpIt(self.data).of_type(target_type)
+        return FlpIt(self.__list.data).of_type(target_type)
 
     def distinct(self) -> FlpIt[TItem]:
-        return FlpIt(self.data).distinct()
+        return FlpIt(self.__list.data).distinct()
 
     def distinct_by(
             self, key_selector: Callable[[TItem], TKey]
     ) -> FlpIt[TItem]:
-        return FlpIt(self.data).distinct_by(key_selector)
+        return FlpIt(self.__list.data).distinct_by(key_selector)
 
     @overload
     def zip(self, second: Iterable[TOther]) -> FlpIt[tuple[TItem, TOther]]: ...
@@ -831,25 +995,25 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             second: Iterable[TOther],
             result_selector: Callable[[TItem, TOther], Any] | _Sentinel = _SENTINEL,
     ) -> FlpIt[Any]:
-        return FlpIt(self.data).zip(second, result_selector)
+        return FlpIt(self.__list.data).zip(second, result_selector)
 
     def chunk(self, size: int) -> FlpIt[FlpList[TItem]]:
-        return FlpIt(self.data).chunk(size)
+        return FlpIt(self.__list.data).chunk(size)
 
     def order_by(
             self, key_selector: Callable[[TItem], Any]
     ) -> OrderedIt[TItem]:
-        return FlpIt(self.data).order_by(key_selector)
+        return FlpIt(self.__list.data).order_by(key_selector)
 
     def order_by_descending(
             self, key_selector: Callable[[TItem], Any]
     ) -> OrderedIt[TItem]:
-        return FlpIt(self.data).order_by_descending(key_selector)
+        return FlpIt(self.__list.data).order_by_descending(key_selector)
 
     def group_by(
             self, key_selector: Callable[[TItem], TKey]
     ) -> FlpIt[Grouping[TKey, TItem]]:
-        return FlpIt(self.data).group_by(key_selector)
+        return FlpIt(self.__list.data).group_by(key_selector)
 
     @overload
     def aggregate(self, func: Callable[[TItem, TItem], TItem]) -> TItem: ...
@@ -864,41 +1028,37 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             func: Callable[[Any, Any], Any],
             seed: Any = _SENTINEL,
     ) -> TItem | TAccumulate:
-        return FlpIt(self.data).aggregate(func, seed=seed)
+        return FlpIt(self.__list.data).aggregate(func, seed=seed)
 
     @_guard_empty
     def min(self) -> TItem:
-        return builtins.min(self.data) # pyrefly: ignore [bad-specialization]
+        return builtins.min(self.__list.data) # pyrefly: ignore [bad-specialization]
 
     @_guard_empty
     def min_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        return builtins.min(self.data, key=key_selector)
+        return builtins.min(self.__list.data, key=key_selector)
 
     @_guard_empty
     def max(self) -> TItem:
-        return builtins.max(self.data) # pyrefly: ignore [bad-specialization]
+        return builtins.max(self.__list.data) # pyrefly: ignore [bad-specialization]
 
     @_guard_empty
     def max_by(self, key_selector: Callable[[TItem], Any]) -> TItem:
-        return builtins.max(self.data, key=key_selector)
+        return builtins.max(self.__list.data, key=key_selector)
 
     def sum(
-            self, selector: Callable[[TItem], int | float] | _Sentinel = _SENTINEL
-    ) -> int | float:
+            self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
+    ) -> int | float | Decimal:
         """Calculates the sum of elements, optionally applying a selector."""
-        return FlpIt(self.data).sum(selector)
+        return FlpIt(self.__list.data).sum(selector)
 
     def average(
-            self, selector: Callable[[TItem], int | float] | _Sentinel = _SENTINEL
-    ) -> float:
+            self, selector: Callable[[TItem], int | float | Decimal] | _Sentinel = _SENTINEL
+    ) -> float | int | Decimal | None:
         """Calculates the arithmetic mean, optionally applying a selector."""
-        return FlpIt(self.data).average(selector)
+        return FlpIt(self.__list.data).average(selector)
 
-    def count_item(self, item: TItem) -> int:
-        return self.data.count(item) # just redirect how the count redirected before
-
-    @override
-    def count( # type: ignore  # pyrefly: ignore [bad-override-param-name]  # pyright: ignore[reportIncompatibleMethodOverride]
+    def count(
             self,
             predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL,
     ) -> int:
@@ -906,22 +1066,21 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
         Counts elements using LINQ semantics.
 
         Supported forms:
-
-            count()          -> total number of elements
-            count(predicate) -> number of elements satisfying the predicate
+            - count()          -> total number of elements
+            - count(predicate) -> number of elements satisfying the predicate
         """
         if predicate is _SENTINEL:
-            return len(self.data)
+            return len(self.__list.data)
 
-        return FlpIt(self.data).count(predicate)
+        return FlpIt(self.__list.data).count(predicate)
 
     def element_at(self, index: int) -> TItem:
-        if index < 0 or index >= len(self.data):
+        if index < 0 or index >= len(self.__list.data):
             raise IndexError("Index out of range")
-        return self.data[index]
+        return self.__list.data[index]
 
     def first(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
-        return FlpIt(self.data).first(predicate)
+        return FlpIt(self.__list.data).first(predicate)
 
     @overload
     def last(self) -> TItem: ...
@@ -948,11 +1107,11 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
             raise PredicateNoneError()
 
         if predicate is _SENTINEL:
-            if not self.data:
+            if not self.__list.data:
                 raise EmptySequenceError()
-            return self.data[-1]
+            return self.__list.data[-1]
 
-        for item in reversed(self.data):
+        for item in reversed(self.__list.data):
             if predicate(item):
                 return item
 
@@ -961,11 +1120,11 @@ class FlpList(UserList[TItem], Sequence[TItem], Generic[TItem]):
     def first_or_default(
             self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
     ) -> TItem | TResult:
-        return FlpIt(self.data).first_or_default(default, predicate)
+        return FlpIt(self.__list.data).first_or_default(default, predicate)
 
     def single(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
-        return FlpIt(self.data).single(predicate)
+        return FlpIt(self.__list.data).single(predicate)
 
     def to_list(self) -> FlpList[TItem]:
         """Explicitly returns a shallow copy instance to isolate mutations."""
-        return FlpList(self.data.copy())
+        return FlpList(self.__list.data.copy())