flpit 0.2.1.dev8__tar.gz → 0.2.3__tar.gz

{flpit-0.2.1.dev8 → flpit-0.2.3}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.1.dev8
+Version: 0.2.3
 Summary: Fluent LINQ for Python — flip your iterables
 Project-URL: Homepage, https://github.com/riemar/flpit
 Project-URL: Repository, https://github.com/riemar/flpit
+Project-URL: Issues, https://github.com/riemar/flpit/issues
 License: MIT
 License-File: LICENSE
 Keywords: fluent,generators,iterable,lazy-evaluation,linq,pipeline,pyrefly,type-safe
@@ -153,6 +154,52 @@ print(list(backend_engineers))
 # ['Alice']
 ```
 
+## JSON Serialization
+
+FlpIt provides typed JSON serialization and deserialization through `flpit.json.JsonConvert`, 
+backed by [`msgspec`](https://github.com/jcrist/msgspec). 
+
+It supports dataclasses, nested models, generic containers, configurable property naming, and explicit field metadata.
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+from flpit import FlpList
+from flpit.json import JProp, JIgnore, JsonConvert
+
+@dataclass
+class Person:
+    first_name: str
+    internal_id: Annotated[str, JProp("id")]
+    password: Annotated[str, JIgnore] = ""
+
+
+person = Person("Ada", "usr-42", "secret")
+raw = JsonConvert.serialize(person, Person)
+# {"firstName":"Ada","id":"usr-42"}
+
+people_json = """
+[
+    {"firstName": "Ada", "id": "usr-42"},
+    {"firstName": "Grace", "id": "usr-43"}
+]
+"""
+
+people: FlpList[Person] = FlpList.from_json(people_json, Person)
+```
+
+### Mapping and conversion
+
+- **Naming policies:** Configure automatic property naming with `JsonSerializerOptions`. The default is camel case.
+- **Explicit metadata:** `JProp` assigns a specific JSON property name, `JIgnore` excludes a field, and `JInclude` explicitly includes otherwise excluded underscore-prefixed fields.
+- **Serialization options:** Control default-value omission and whether unknown JSON fields are accepted or rejected.
+- **Typed collections:** Pass the complete target type, such as `list[Person]`, so nested and generic values can be decoded against the intended schema.
+
+For large outputs, `JsonConvert.serialize_to()` writes a JSON array to a file-like stream without first materializing the entire serialized document.
+
+By default, deserialization returns instances of the requested model type. Setting `native=True` opts into the generated `msgspec.Struct` representation instead, trading the original model type for the native representation and its performance characteristics.
+
 ## 🔬 LINQ Semantics, Python Runtime
 
 `flpit` deliberately separates the two:
@@ -348,6 +395,21 @@ to_list     ← terminal materialization
 
 Operations such as `order_by()` necessarily materialize their input internally to establish ordering.
 
+## ⚙️ Task Runtime
+
+FlpIt includes a lightweight, `asyncio`-free task runtime for scheduling and coordinating concurrent work, with synchronous callables executed through a bounded worker pool.
+
+Key features:
+
+- **Task scheduling:** `Task.run()` schedules coroutines, awaitables, and synchronous callables.
+- **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.
+
+The runtime starts lazily and manages its own lifecycle. It is deliberately not an `asyncio` compatibility layer; cancellation of running synchronous functions is cooperative.
+
+See the [Task Runtime examples](https://github.com/riemar/flpit/tree/main/examples/task) for usage examples.
+
 ## ⚙️ Installation
 
 ```bash

{flpit-0.2.1.dev8 → flpit-0.2.3}/README.md

@@ -130,6 +130,52 @@ print(list(backend_engineers))
 # ['Alice']
 ```
 
+## JSON Serialization
+
+FlpIt provides typed JSON serialization and deserialization through `flpit.json.JsonConvert`, 
+backed by [`msgspec`](https://github.com/jcrist/msgspec). 
+
+It supports dataclasses, nested models, generic containers, configurable property naming, and explicit field metadata.
+
+```python
+from dataclasses import dataclass
+from typing import Annotated
+
+from flpit import FlpList
+from flpit.json import JProp, JIgnore, JsonConvert
+
+@dataclass
+class Person:
+    first_name: str
+    internal_id: Annotated[str, JProp("id")]
+    password: Annotated[str, JIgnore] = ""
+
+
+person = Person("Ada", "usr-42", "secret")
+raw = JsonConvert.serialize(person, Person)
+# {"firstName":"Ada","id":"usr-42"}
+
+people_json = """
+[
+    {"firstName": "Ada", "id": "usr-42"},
+    {"firstName": "Grace", "id": "usr-43"}
+]
+"""
+
+people: FlpList[Person] = FlpList.from_json(people_json, Person)
+```
+
+### Mapping and conversion
+
+- **Naming policies:** Configure automatic property naming with `JsonSerializerOptions`. The default is camel case.
+- **Explicit metadata:** `JProp` assigns a specific JSON property name, `JIgnore` excludes a field, and `JInclude` explicitly includes otherwise excluded underscore-prefixed fields.
+- **Serialization options:** Control default-value omission and whether unknown JSON fields are accepted or rejected.
+- **Typed collections:** Pass the complete target type, such as `list[Person]`, so nested and generic values can be decoded against the intended schema.
+
+For large outputs, `JsonConvert.serialize_to()` writes a JSON array to a file-like stream without first materializing the entire serialized document.
+
+By default, deserialization returns instances of the requested model type. Setting `native=True` opts into the generated `msgspec.Struct` representation instead, trading the original model type for the native representation and its performance characteristics.
+
 ## 🔬 LINQ Semantics, Python Runtime
 
 `flpit` deliberately separates the two:
@@ -325,6 +371,21 @@ to_list     ← terminal materialization
 
 Operations such as `order_by()` necessarily materialize their input internally to establish ordering.
 
+## ⚙️ Task Runtime
+
+FlpIt includes a lightweight, `asyncio`-free task runtime for scheduling and coordinating concurrent work, with synchronous callables executed through a bounded worker pool.
+
+Key features:
+
+- **Task scheduling:** `Task.run()` schedules coroutines, awaitables, and synchronous callables.
+- **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.
+
+The runtime starts lazily and manages its own lifecycle. It is deliberately not an `asyncio` compatibility layer; cancellation of running synchronous functions is cooperative.
+
+See the [Task Runtime examples](https://github.com/riemar/flpit/tree/main/examples/task) for usage examples.
+
 ## ⚙️ Installation
 
 ```bash

{flpit-0.2.1.dev8 → flpit-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.2.1.dev8"
+version = "0.2.3"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,7 @@ dependencies = [
 [project.urls]
 Homepage = "https://github.com/riemar/flpit"
 Repository = "https://github.com/riemar/flpit"
+Issues = "https://github.com/riemar/flpit/issues"
 
 [dependency-groups]
 dev = [
@@ -54,7 +55,7 @@ include = ["src/flp", "src/flpit"]
 [tool.pyrefly]
 project-includes = ["src"]
 project-excludes = ["**/__pycache__", "tests"]
-search-path = ["src"]
+search-path = ["src", "typing"]
 preset = "strict"
 
 [tool.pytest.ini_options]

{flpit-0.2.1.dev8 → flpit-0.2.3}/src/flpit/core/linq.py

@@ -14,7 +14,6 @@ from itertools import islice
 from typing import (
     Any,
     Callable,
-    Generic,
     Iterable,
     Iterator,
     Collection,
@@ -27,13 +26,14 @@ from typing import (
     Union,
     override,
     overload,
-    cast as typing_cast, BinaryIO,
+    cast as typing_cast,
+    BinaryIO,
+    Concatenate,
+    Sized
 )
 
 from flpit.json import JsonConvert, JsonSerializerOptions
 
-TItem = TypeVar("TItem")
-TResult = TypeVar("TResult")
 TKey = TypeVar("TKey")
 TOther = TypeVar("TOther")
 TAccumulate = TypeVar("TAccumulate")
@@ -113,16 +113,24 @@ 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(func: Callable[..., Any]) -> Callable[..., Any]:
-    """Catches Python's native empty-sequence ValueError and re-raises LINQ-compliant error."""
+def _guard_empty[SelfT: Sized, R, **P](
+        func: Callable[Concatenate[SelfT, P], R],
+) -> Callable[Concatenate[SelfT, P], R]:
+    """Translate empty-sequence ValueError into EmptySequenceError."""
+
     @wraps(func)
-    def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+    def wrapper(
+            self: SelfT,
+            *args: P.args,
+            **kwargs: P.kwargs,
+    ) -> R:
         try:
             return func(self, *args, **kwargs)
         except ValueError as e:
-            if not self._FlpList__list.data:
+            if len(self) == 0:
                 raise EmptySequenceError() from e
             raise
+
     return wrapper
 
 
@@ -136,7 +144,7 @@ def dotnet_context() -> AbstractContextManager[decimal.Context]:
     return decimal.localcontext(ctx)
 
 
-class _FactoryIterable(Iterable[TItem], Generic[TItem]):
+class _FactoryIterable[TItem](Iterable[TItem]):
     """
     Wraps a generator factory function into a clean Iterable[T].
     Ensures __iter__ produces a brand-new iterator instance on every call
@@ -151,7 +159,7 @@ class _FactoryIterable(Iterable[TItem], Generic[TItem]):
         return self._factory()
 
 
-class FlpIt(Iterable[TItem], Generic[TItem]):
+class FlpIt[TItem](Iterable[TItem]):
     """
     | Fluent Iterable
     Lazy evaluation wrapper around an iterable, inspired by .NET LINQ's
@@ -172,7 +180,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         return iter(self._iterable)
 
     # noinspection unused-parameter
-    def as_type(self, target_type: Type[TResult]) -> FlpIt[TResult]:
+    def as_type[TResult](self, target_type: Type[TResult]) -> FlpIt[TResult]:
         """Zero-cost static type hint update returning self directly without checks or allocations."""
         return self  # type: ignore[return-value]
 
@@ -256,7 +264,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         # return typing_cast(FlpIt[TItem], FlpIt[TItem](_FactoryIterable(_generator)))
         return FlpIt[TItem](_FactoryIterable(_generator))
 
-    def select(self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
+    def select[TResult](self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
         """Projects each element into a new form."""
         def _generator() -> Iterator[TResult]:
             for item in self:
@@ -264,7 +272,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
-    def select_many(
+    def select_many[TResult](
             self, selector: Callable[[TItem], Iterable[TResult]]
     ) -> FlpIt[TResult]:
         """Flattens sequence projections."""
@@ -309,7 +317,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
-    def cast(self, target_type: Type[TResult]) -> FlpIt[TResult]:
+    def cast[TResult](self, target_type: Type[TResult]) -> FlpIt[TResult]:
         """Casts elements to a specified type or raises TypeError if cast fails."""
         def _generator() -> Iterator[TResult]:
             for item in self:
@@ -321,7 +329,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
-    def of_type(self, target_type: Type[TResult]) -> FlpIt[TResult]:
+    def of_type[TResult](self, target_type: Type[TResult]) -> FlpIt[TResult]:
         """Filters the elements of an Iterable based on a specified type."""
         def _generator() -> Iterator[TResult]:
             for item in self:
@@ -359,7 +367,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
     def zip(self, second: Iterable[TOther]) -> FlpIt[tuple[TItem, TOther]]: ...
 
     @overload
-    def zip(
+    def zip[TResult, TOther](
             self,
             second: Iterable[TOther],
             result_selector: Callable[[TItem, TOther], TResult],
@@ -597,7 +605,7 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
             return item
         raise EmptySequenceError() if predicate is _SENTINEL else NoMatchError()
 
-    def first_or_default(
+    def first_or_default[TResult](
             self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
     ) -> Union[TItem, TResult]:
         """Returns the first element matching a predicate, or a default value."""
@@ -672,14 +680,7 @@ class _NoneOrderKey:
 
 _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]):
+class OrderedIt[TItem](FlpIt[TItem]):
     __slots__ = ("_criteria",)
 
     def __init__(
@@ -700,13 +701,21 @@ class OrderedIt(FlpIt[TItem]):
         else:
             self._criteria = _criteria + ((selector, descending),)
 
+    @staticmethod
+    def __none_aware_key(
+            selector: Callable[[TItem], Any],
+            item: TItem,
+    ) -> Any:
+        key = selector(item)
+        return _NONE_ORDER_KEY if key is None else key
+
     @override
     def __iter__(self) -> Iterator[TItem]:
         items = list(self._iterable)
 
         for selector, descending in reversed(self._criteria):
             items.sort(
-                key=partial(_none_aware_key, selector),
+                key=partial(self.__none_aware_key, selector),
                 reverse=descending,
             )
 
@@ -735,7 +744,7 @@ class OrderedIt(FlpIt[TItem]):
         )
 
 
-class Grouping(FlpIt[TItem], Generic[TKey, TItem]):
+class Grouping[TKey, TItem](FlpIt[TItem]):
     """Represents a collection of elements sharing a common key (.NET IGrouping<TKey, TElement>)."""
     __slots__ = ("_key", )
 
@@ -759,7 +768,7 @@ class Grouping(FlpIt[TItem], Generic[TKey, TItem]):
         return self.key == other.key and self.to_list() == other.to_list()
 
 
-class FlpList(Collection[TItem], Generic[TItem]):
+class FlpList[TItem](Collection[TItem]):
     """
     | Fluent List
     A materialized list extending UserList that yields lazy FlpIt instances for query operations.
@@ -780,7 +789,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
     # =====================================================================
     # 1. THE ABC CONTRACT
     # =====================================================================
-    def __iter__(self) -> Iterator[Any]:
+    def __iter__(self) -> Iterator[TItem]:
         return self.__list.__iter__()
 
     def __len__(self) -> int:
@@ -1031,17 +1040,16 @@ class FlpList(Collection[TItem], Generic[TItem]):
     def concat(self, second: Iterable[TItem]) -> FlpIt[TItem]:
         return FlpIt(self.__list.data).concat(second)
 
-    # noinspection unused-parameter
-    def as_type(self, target_type: Type[TResult]) -> FlpList[TResult]:
-        return self  # type: ignore[return-value]
+    def as_type[TResult](self, target_type: Type[TResult]) -> FlpList[TResult]:
+        return typing_cast(FlpList[TResult], self)
 
     def where(self, predicate: Callable[[TItem], bool]) -> FlpIt[TItem]:
         return FlpIt[TItem](self.__list.data).where(predicate)
 
-    def select(self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
+    def select[TResult](self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).select(selector)
 
-    def select_many(
+    def select_many[TResult](
             self, selector: Callable[[TItem], Iterable[TResult]]
     ) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).select_many(selector)
@@ -1052,10 +1060,10 @@ class FlpList(Collection[TItem], Generic[TItem]):
     def take(self, count: int) -> FlpIt[TItem]:
         return FlpIt(self.__list.data).take(count)
 
-    def cast(self, target_type: Type[TResult]) -> FlpIt[TResult]:
+    def cast[TResult](self, target_type: Type[TResult]) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).cast(target_type)
 
-    def of_type(self, target_type: Type[TResult]) -> FlpIt[TResult]:
+    def of_type[TResult](self, target_type: Type[TResult]) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).of_type(target_type)
 
     def distinct(self) -> FlpIt[TItem]:
@@ -1070,7 +1078,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
     def zip(self, second: Iterable[TOther]) -> FlpIt[tuple[TItem, TOther]]: ...
 
     @overload
-    def zip(
+    def zip[TResult, TOther](
             self,
             second: Iterable[TOther],
             result_selector: Callable[[TItem, TOther], TResult],
@@ -1203,7 +1211,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
 
         raise EmptySequenceError() if predicate is _SENTINEL else NoMatchError()
 
-    def first_or_default(
+    def first_or_default[TResult](
             self, default: TResult, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL
     ) -> TItem | TResult:
         return FlpIt(self.__list.data).first_or_default(default, predicate)
@@ -1235,4 +1243,4 @@ class FlpList(Collection[TItem], Generic[TItem]):
             output: BinaryIO,
             jso: JsonSerializerOptions | None = None,
     ) -> None:
-        JsonConvert.serialize_to(self, item_type, output, jso)
+        JsonConvert.serialize_to(self, item_type, output, jso)

flpit-0.2.3/src/flpit/csv.py

@@ -0,0 +1,333 @@
+from __future__ import annotations
+
+import csv
+import io
+from csv import DictReader
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Iterator, TextIO
+
+import msgspec
+
+from flpit import FlpIt, FlpList
+from flpit.json import (
+    JProp,
+    JsonNamingPolicy,
+    JsonSerializerOptions,
+    wire_type_for,
+)
+
+
+class CsvCol(JProp):
+    """Explicit CSV column name.
+
+    Inherits JProp so the existing wire-schema machinery recognizes
+    the metadata without a separate conversion implementation.
+    """
+
+
+@dataclass(frozen=True, slots=True)
+class CsvOptions:
+    """CSV parsing and property-mapping options.
+
+    Naming defaults to none: headers match declared property names unless
+    CsvCol specifies an explicit column name.
+    """
+
+    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")
+
+
+@lru_cache(maxsize=None)
+def _json_options_for_csv(
+        naming_policy: JsonNamingPolicy,
+) -> JsonSerializerOptions:
+    """Reuse options identity because the wire-type cache keys by options ID."""
+    return JsonSerializerOptions(naming_policy=naming_policy)
+
+
+class CsvLoader:
+    """Load typed records from CSV without adding format methods to FlpList/FlpIt."""
+
+    @staticmethod
+    def load_list[T](
+            data: str | Path,
+            item_type: type[T],
+            options: CsvOptions | None = None,
+    ) -> FlpList[T]:
+        """Load CSV rows eagerly using bulk conversion.
+
+        Args:
+            data: CSV text, or a Path to a CSV file.
+            item_type: Type of each resulting model.
+            options: CSV dialect, encoding, and naming policy.
+
+        Returns:
+            An eagerly populated FlpList of item_type instances.
+        """
+        opts = options or CsvOptions()
+        jso = _json_options_for_csv(opts.naming_policy)
+        target: type[list[T]] = list[item_type]
+        wire_type = wire_type_for(target, jso)
+
+        with CsvLoader._open_text(data, opts) as stream:
+            reader: DictReader[Any] = CsvLoader._reader(stream, opts)
+            rows = CsvLoader._read_rows(reader)
+
+        output = msgspec.convert(
+            rows,
+            wire_type,
+            from_attributes=True,
+            strict=False,
+        )
+        del rows
+
+        return FlpList[T](output)
+
+    @staticmethod
+    def load_it[T](
+            data: str | Path,
+            item_type: type[T],
+            options: CsvOptions | None = None,
+    ) -> FlpIt[T]:
+        """Load CSV rows lazily, converting one row when it is consumed.
+
+        For Path input, the file is opened on iteration and closed when
+        the iterator is exhausted or closed. CSV parsing and conversion
+        errors therefore occur during iteration, not at this call.
+        """
+        opts = options or CsvOptions()
+        jso = _json_options_for_csv(opts.naming_policy)
+        wire_item_type = wire_type_for(item_type, jso)
+
+        return FlpIt[T](
+            CsvLoader._iter_items(data, item_type, wire_item_type, opts)
+        )
+
+    @staticmethod
+    def _open_text(data: str | Path, options: CsvOptions) -> TextIO:
+        if isinstance(data, Path):
+            return data.open("r", newline="", encoding=options.encoding)
+        return io.StringIO(data.removeprefix("\ufeff"), newline="")
+
+    @staticmethod
+    def _reader(stream: TextIO, options: CsvOptions) -> csv.DictReader[Any]:
+        reader = csv.DictReader(
+            stream,
+            delimiter=options.delimiter,
+            quotechar=options.quotechar,
+            escapechar=options.escapechar,
+            doublequote=options.doublequote,
+            skipinitialspace=options.skipinitialspace,
+            strict=options.strict,
+        )
+
+        headers = reader.fieldnames
+        if headers is None:
+            raise ValueError("CSV input must contain a header row")
+
+        if any(header == "" for header in headers):
+            raise ValueError("CSV column names must not be empty")
+
+        if len(headers) != len(set(headers)):
+            raise ValueError("CSV column names must be unique")
+
+        return reader
+
+    @staticmethod
+    def _read_rows(reader: csv.DictReader[Any]) -> list[dict[str, Any]]:
+        rows: list[dict[str, Any]] = []
+
+        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"
+                )
+            rows.append(row)
+
+        return rows
+
+    @staticmethod
+    def _iter_items[T](
+            data: str | Path,
+            item_type: type[T],
+            wire_item_type: Any,
+            options: CsvOptions,
+    ) -> Iterator[T]:
+        with CsvLoader._open_text(data, options) as stream:
+            reader = CsvLoader._reader(stream, options)
+
+            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"
+                    )
+
+                yield msgspec.convert(
+                    row,
+                    wire_item_type,
+                    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())
+#

{flpit-0.2.1.dev8 → flpit-0.2.3}/src/flpit/json.py

@@ -67,37 +67,49 @@ class JsonSerializerOptions:
 # ---------------------------------------------------------------------------
 
 class JIgnore:
-    def __class_getitem__[T](cls, item: type[T]) -> Any:
-        return Annotated[item, cls]
+    def __class_getitem__[T](cls, item: type[T]) -> Annotated[type[T], JIgnore]:
+        return typing.cast(Annotated[type[T], JIgnore], Annotated[item, cls])
 
 class JInclude:
-    def __class_getitem__[T](cls, item: type[T]) -> Any:
-        return Annotated[item, cls]
+    def __class_getitem__[T](cls, item: type[T]) -> Annotated[type[T], JInclude]:
+        return typing.cast(Annotated[type[T], JInclude], Annotated[item, cls])
+
+
+class JPropMeta(type):
+    def __getattr__(cls, name: str) -> Any:
+        class SpecializedJProp:
+            def __class_getitem__[T](sub_cls, item: type[T]) -> Annotated[type[T], JProp]:
+                return typing.cast(Annotated[type[T], JProp], Annotated[item, JProp(json_name=name)])
+        return SpecializedJProp
 
 class JProp:
-    def __class_getitem__[T](cls, item: tuple[type[T], str]) -> Any:
-        target_type, json_name = item
-        return Annotated[target_type, cls(json_name)]
+    __slots__ = ("json_name",)
+    json_name: str
 
-    def __init__(self, name: str):
-        self.name = name
+    def __init__(self, json_name: str):
+        self.json_name = json_name
 
-class Dummy:
-    def __getitem__[T](self, item: tuple[type[T], str]) -> Any:
-        target_type, json_name = item
-        return Annotated[target_type, self]
+    # 1. This handles the standard initialization/metadata if needed
+    def __repr__(self):
+        return f"JProp(json_name={self.json_name!r})"
 
-    def __init__(self, name: str):
-        self.name = name
+    # 2. This intercepts JProp[str] (the type subscription first)
+    def __class_getitem__[T](cls, item: type[T]) -> Any:
+        # We return a proxy class that remembers the type 'item' (e.g., str | None)
+        class JPropTypeProxy:
+            def __getattr__(self, name: str) -> Annotated[type[T], JProp]:
+                # 3. This intercepts .JsonPropNameToUse and returns the Annotated type
+                return typing.cast(
+                    Annotated[type[T], JProp],
+                    Annotated[item, JProp(json_name=name)]
+                )
 
-# just alias it
-J = Annotated
+        return JPropTypeProxy()
 
 @dataclass
 class AnnotationModel:
-    internal_id: JProp[int, "any_arbitrary_string_you_want"]
-    display_name: J[str, JProp("")]
-    display_name_2: Dummy("name")[str]
+    other_name: Annotated[str, JProp("WorksToo")]
+    display_name: JProp[str].meta
     secret: JIgnore[str] = ""
     always_emit: JInclude[int] = 0
 
@@ -209,7 +221,7 @@ def _field_directives(
     ignored = any(item is JIgnore for item in metadata)
     included = any(item is JInclude for item in metadata)
     json_name = next(
-        (item.name for item in metadata if isinstance(item, JProp)),
+        (item.json_name for item in metadata if isinstance(item, JProp)),
         None,
     )
     remaining = tuple(
@@ -574,6 +586,13 @@ def _get_decoder(wire_type: Any):
 _JSON_ENCODER = msgspec.json.Encoder()
 
 
+class JsonSerializationError(Exception):
+    pass
+
+class JsonDeserializationError(Exception):
+    pass
+
+
 class JsonConvert:
 
     @staticmethod
@@ -582,22 +601,29 @@ class JsonConvert:
             target: type[T],
             jso: JsonSerializerOptions | None = None
     ) -> T:
+        if data is None:
+            raise JsonDeserializationError("data must not be None")
+
         if jso is None:
             jso = JsonSerializerOptions()
 
         wire_type = wire_type_for(target, jso)
-        parsed = _get_decoder(wire_type).decode(data)
 
-        if jso.native:
-            return parsed
+        try:
+            parsed = _get_decoder(wire_type).decode(data)
 
-        result = msgspec.convert(
-            parsed,
-            target,
-            from_attributes=True,
-        )
+            if jso.native:
+                return parsed
 
-        return result
+            result = msgspec.convert(
+                parsed,
+                target,
+                from_attributes=True,
+            )
+
+            return result
+        except msgspec.MsgspecError as exc:
+            raise JsonDeserializationError(str(exc)) from exc
 
     @staticmethod
     def serialize[T](
@@ -605,6 +631,9 @@ class JsonConvert:
             target: type[T],
             jso: JsonSerializerOptions | None = None
     ) -> str:
+        if data is None:
+            raise JsonSerializationError("data must not be None")
+
         return JsonConvert.serialize_bytes(data, target, jso).decode("utf-8")
 
     @staticmethod
@@ -617,8 +646,11 @@ class JsonConvert:
             jso = JsonSerializerOptions()
 
         wire_type = wire_type_for(target, jso)
-        wire_obj = msgspec.convert(data, wire_type, from_attributes=True)
-        return _JSON_ENCODER.encode(wire_obj)
+        try:
+            wire_obj = msgspec.convert(data, wire_type, from_attributes=True)
+            return _JSON_ENCODER.encode(wire_obj)
+        except msgspec.MsgspecError as exc:
+            raise JsonSerializationError(str(exc)) from exc
 
     @staticmethod
     def serialize_to[T](

{flpit-0.2.1.dev8 → flpit-0.2.3}/src/flpit/task.py

@@ -36,11 +36,15 @@ import socket
 import threading
 import time
 from collections import deque
+from collections.abc import Generator
 from concurrent.futures import Future, ThreadPoolExecutor
 from dataclasses import dataclass
 from itertools import count
-from typing import Any, Callable, Coroutine, Generic, TypeVar, cast, Iterable, Final
+from typing import Any, Generic, TypeVar, cast, Iterable, Final, overload
 import functools
+from functools import wraps
+from collections.abc import Awaitable, Callable, Coroutine
+
 
 import flpit
 
@@ -409,17 +413,17 @@ class _WaitIO(_Operation):
         self.mode = mode
 
 
-class _WaitTask(_Operation):
-    def __init__(self, runtime: "_Runtime", task: "Task[Any]") -> None:
+class _WaitTask[T](_Operation):
+    def __init__(self, runtime: "_Runtime", ttw: "Task[T]") -> None:
         super().__init__(runtime)
-        self.task = task
+        self.task = ttw
 
 
-class _WaitMany(_Operation):
+class _WaitMany[T](_Operation):
     """Wait for all or any of a set of tasks to complete."""
 
     def __init__(
-            self, runtime: "_Runtime", tasks: tuple["Task[Any]", ...], mode: str
+            self, runtime: "_Runtime", tasks: tuple["Task[T]", ...], mode: str
     ) -> None:
         super().__init__(runtime)
         if mode not in ("all", "any"):
@@ -559,14 +563,14 @@ class Task(Generic[T]):
     @classmethod
     def run(
             cls,
-            work: Any,
+            work: Callable[..., T],
             /,
             *args: Any,
             name: str | None = None,
             token: CancellationToken | None = None,
             pass_token: bool = False,
             **kwargs: Any,
-    ) -> "Task[Any]":
+    ) -> "Task[T]":
         """Schedule a coroutine/awaitable or ordinary callable.
 
         Ordinary functions run in the bounded worker pool. ``token`` controls
@@ -616,6 +620,8 @@ class Task(Generic[T]):
         normalized = _normalize_tasks(tasks, allow_empty=True)
         return cast(
             "Task[list[Any]]",
+            # todo: make run type compatible via Generator[Y, S, R]
+            # pyrefly: ignore [bad-argument-type]
             cls.run(_when_all_coroutine, normalized, name=name, token=token),
         )
 
@@ -641,6 +647,8 @@ class Task(Generic[T]):
         normalized = _normalize_tasks(tasks, allow_empty=False)
         return cast(
             "Task[Task[Any]]",
+            # todo: make run type compatible via Generator[Y, S, R]
+            # pyrefly: ignore [bad-argument-type]
             cls.run(_when_any_coroutine, normalized, name=name, token=token),
         )
 
@@ -726,19 +734,17 @@ class Task(Generic[T]):
     def cancelled(self) -> bool:
         return self._completed.is_set() and self._state == self.CANCELLED
 
-    def result(self, timeout: float | None = None) -> T:
+    def result(self) -> T:
         """Block an external thread until completion and return/raise the result."""
         if not self.done() and self._runtime.is_runtime_thread():
             raise RuntimeError("Task.result() would block the runtime thread; use 'await task'")
-        if not self._completed.wait(timeout):
-            raise TimeoutError(f"{self.name} did not complete before the timeout")
+        self._completed.wait()
         return self._raise_or_return()
 
-    def exception(self, timeout: float | None = None) -> BaseException | None:
+    def exception(self) -> BaseException | None:
         if not self.done() and self._runtime.is_runtime_thread():
             raise RuntimeError("Task.exception() would block the runtime thread")
-        if not self._completed.wait(timeout):
-            raise TimeoutError(f"{self.name} did not complete before the timeout")
+        self._completed.wait()
         if self._state == self.CANCELLED:
             raise self._cancellation_exception()
         return self._exception
@@ -758,10 +764,10 @@ class Task(Generic[T]):
             return False
         return True
 
-    def __await__(self):
+    def __await__(self) -> Generator[Any, T, T]:
         if self.done():
             return self._raise_or_return()
-        result = yield _WaitTask(self._runtime, self)
+        result = yield _WaitTask[T](self._runtime, self)
         return result
 
     def _raise_or_return(self) -> T:
@@ -1088,9 +1094,10 @@ def _normalize_tasks(items: tuple[Any, ...], *, allow_empty: bool) -> tuple[Task
     return tuple(normalized)
 
 
-async def _when_all_coroutine(tasks: tuple[Task[Any], ...]) -> list[Any]:
+async def _when_all_coroutine(tasks: tuple[Task[T], ...]) -> list[T]:
     await _WaitMany(_get_runtime(), tasks, "all")
     failures = tuple(task._exception for task in tasks if task._state == Task.FAILED)
+
     if len(failures) == 1:
         assert failures[0] is not None
         raise failures[0]
@@ -1101,7 +1108,7 @@ async def _when_all_coroutine(tasks: tuple[Task[Any], ...]) -> list[Any]:
     return [task._result for task in tasks]
 
 
-async def _when_any_coroutine(tasks: tuple[Task[Any], ...]) -> Task[Any]:
+async def _when_any_coroutine(tasks: tuple[Task[T], ...]) -> Task[T]:
     winner = await _WaitMany(_get_runtime(), tasks, "any")
     return cast(Task[Any], winner)
 
@@ -1823,17 +1830,38 @@ def _shutdown_at_exit() -> None:
 
 atexit.register(_shutdown_at_exit)
 
-def task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
+
+@overload
+def task[**P, T](
+        function: Callable[P, Awaitable[T]]
+) -> Callable[P, Task[T]]: ...
+
+@overload
+def task[**P, T](
+        function: Callable[P, T]
+) -> Callable[P, Task[T]]: ...
+
+def task(function: Callable[..., Any]) -> Callable[..., Task[Any]]:
     """
     | Wraps sync functions and non-asyncio dependent coroutines to eagerly executed await-able tasks
     """
-    @functools.wraps(async_function)
+    @wraps(function)
     def wrapper(*args: Any, **kwargs: Any) -> Task[Any]:
-        return Task.run(async_function, *args, **kwargs)
+        return Task.run(function, *args, **kwargs)
 
     return wrapper
 
 
+@overload
+def asyncio_task[**P, T](
+        async_function: Callable[P, Awaitable[T]]
+) -> Callable[P, Task[T]]: ...
+
+@overload
+def asyncio_task[**P, T](
+        async_function: Callable[P, T], /
+) -> Callable[P, Task[T]]: ...
+
 def asyncio_task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
     """
     | Wraps async functions with a dependency on asyncio to be compatible with Task.run(coro)
@@ -1852,7 +1880,7 @@ def asyncio_task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]
 
 
 class _SyncBridge:
-    def __rshift__(self, ttwa: Task[T]) -> Any:
+    def __rshift__(self, ttwa: Task[T]) -> T:
         frame = inspect.currentframe()
         try:
             assert frame is not None