flpit 0.2.1.dev7__tar.gz → 0.2.2__tar.gz

{flpit-0.2.1.dev7 → flpit-0.2.2}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.1.dev7
+Version: 0.2.2
 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.dev7 → flpit-0.2.2}/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.dev7 → flpit-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.2.1.dev7"
+version = "0.2.2"
 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 = [

{flpit-0.2.1.dev7 → flpit-0.2.2}/src/flpit/core/linq.py

@@ -30,6 +30,7 @@ from typing import (
     cast as typing_cast, BinaryIO,
 )
 
+import flpit.json
 from flpit.json import JsonConvert, JsonSerializerOptions
 
 TItem = TypeVar("TItem")
@@ -1235,4 +1236,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.2/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.dev7 → flpit-0.2.2}/src/flpit/json.py

@@ -11,12 +11,13 @@ from dataclasses import MISSING, dataclass
 from enum import StrEnum
 from functools import lru_cache
 from hashlib import blake2s
-from typing import Annotated, Any, ForwardRef, get_args, get_origin, get_type_hints, Callable
+from typing import Annotated, TYPE_CHECKING, Any, ForwardRef, get_args, get_origin, get_type_hints, Callable
 
 import msgspec
 
 
 class JsonNamingPolicy(StrEnum):
+    none = "None"
     lower = "lower" # pyrefly: ignore [bad-override-mutable-attribute]
     upper = "upper" # pyrefly: ignore [bad-override-mutable-attribute]
     camel = "camel"
@@ -65,25 +66,52 @@ class JsonSerializerOptions:
 # Metadata Annotation Markers
 # ---------------------------------------------------------------------------
 
-class JsonIgnore:
-    def __class_getitem__[T](cls, item: type[T]) -> Any:
-        return Annotated[item, cls]
+class JIgnore:
+    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]) -> Annotated[type[T], JInclude]:
+        return typing.cast(Annotated[type[T], JInclude], Annotated[item, cls])
 
-class JsonInclude:
-    def __class_getitem__[T](cls, item: type[T]) -> Any:
-        return Annotated[item, cls]
 
-class JsonProperty:
-    def __class_getitem__[T](cls, item: tuple[type[T], str]) -> Any:
-        target_type, json_name = item
-        return Annotated[target_type, cls(json_name)]
+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
 
-    def __init__(self, name: str):
-        self.name = name
+class JProp:
+    __slots__ = ("json_name",)
+    json_name: str
 
-JIgnore = JsonIgnore
-JInclude = JsonInclude
-JProp = JsonProperty
+    def __init__(self, json_name: str):
+        self.json_name = json_name
+
+    # 1. This handles the standard initialization/metadata if needed
+    def __repr__(self):
+        return f"JProp(json_name={self.json_name!r})"
+
+    # 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)]
+                )
+
+        return JPropTypeProxy()
+
+@dataclass
+class AnnotationModel:
+    other_name: Annotated[str, JProp("WorksToo")]
+    display_name: JProp[str].meta
+    secret: JIgnore[str] = ""
+    always_emit: JInclude[int] = 0
 
 # ---------------------------------------------------------------------
 # Generated type metadata
@@ -120,36 +148,44 @@ class _WireType:
 
 def _apply_naming_policy(name: str, policy: JsonNamingPolicy) -> str:
     """
-    Splits any attribute name (snake_case, PascalCase, UPPER_CASE)
-    into individual tokens and formats them according to the target policy.
+    Tokenizes snake_case, camelCase, PascalCase, UPPER_CASE, and kebab-case
+    identifiers, then formats the tokens according to the target policy.
+    Preserves leading underscores.
     """
-    # 1. Check if there is a leading underscore and save it
-    prefix = "_" if name.startswith("_") else ""
-    clean_name = name.lstrip("_")
-
-    # 2. Tokenize only the clean part of the string
-    tokens = [t for t in re.split(r'_(?=[a-zA-Z])|(?<=[a-z])(?=[A-Z])', clean_name) if t]
-    if not tokens:
+    if policy == JsonNamingPolicy.none:
         return name
 
-    if policy == JsonNamingPolicy.lower:
-        result = "".join(t.lower() for t in tokens)
+    # Preserve all leading underscores.
+    prefix = name[: len(name) - len(name.lstrip("_"))]
+    clean_name = name[len(prefix):]
 
-    if policy == JsonNamingPolicy.upper:
-        result = "".join(t.upper() for t in tokens)
+    # Split on existing separators first, then tokenize each segment.
+    # This also correctly handles acronyms such as XMLParser and UPPER_CASE.
+    token_pattern = r"[A-Z]+(?=[A-Z][a-z]|\d|$)|[A-Z]?[a-z]+|\d+"
 
-    if policy == JsonNamingPolicy.pascal:
-        result = "".join(t.capitalize() for t in tokens)
+    tokens = [
+        token
+        for part in re.split(r"[_-]+", clean_name)
+        for token in re.findall(token_pattern, part)
+    ]
 
-    if policy == JsonNamingPolicy.kebap:
-        result = "-".join(t.lower() for t in tokens)
-
-    if policy == JsonNamingPolicy.camel:
-        # Lowercase the first token completely, capitalize all subsequent tokens
-        result = tokens[0].lower() + "".join(t.capitalize() for t in tokens[1:])
+    if not tokens:
+        return name
 
+    if policy == JsonNamingPolicy.lower:
+        result = "".join(token.lower() for token in tokens)
+    elif policy == JsonNamingPolicy.upper:
+        result = "".join(token.upper() for token in tokens)
+    elif policy == JsonNamingPolicy.pascal:
+        result = "".join(token.capitalize() for token in tokens)
+    elif policy == JsonNamingPolicy.camel:
+        result = tokens[0].lower() + "".join(
+            token.capitalize() for token in tokens[1:]
+        )
+    elif policy == JsonNamingPolicy.kebap:
+        result = "-".join(token.lower() for token in tokens)
     else:
-        result = clean_name
+        raise ValueError(f"Unsupported naming policy: {policy!r}")
 
     return prefix + result
 
@@ -182,18 +218,18 @@ def _field_directives(
     args = get_args(annotation)
     base_type = args[0]
     metadata = args[1:]
-    ignored = any(item is JsonIgnore for item in metadata)
-    included = any(item is JsonInclude for item in metadata)
+    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, JsonProperty)),
+        (item.json_name for item in metadata if isinstance(item, JProp)),
         None,
     )
     remaining = tuple(
         item
         for item in metadata
-        if item is not JsonIgnore
-        and item is not JsonInclude
-        and not isinstance(item, JsonProperty)
+        if item is not JIgnore
+        and item is not JInclude
+        and not isinstance(item, JProp)
     )
 
     if remaining:
@@ -550,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
@@ -558,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](
@@ -581,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
@@ -593,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.dev7 → flpit-0.2.2}/src/flpit/task.py

@@ -1,4 +1,4 @@
-"""Task: a small asyncio-free Task/awaitable runtime.
+"""Task: a small asyncio-free task/awaitable runtime.
 
 This is a deliberately small runtime, not an asyncio compatibility layer.
 
@@ -36,11 +36,17 @@ 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
+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
 
 T = TypeVar("T")
 _LOG = logging.getLogger("tinytask")
@@ -48,8 +54,25 @@ _MISSING = object()
 _WAKE = object()
 
 
-class OperationCanceledError(BaseException):
-    """Raised when cancellation is delivered to an operation or coroutine."""
+class OperationCanceledError(Exception):
+    """Raised when an operation is canceled.
+
+    ``token`` records the token associated with cancellation when one exists.
+    The exception intentionally derives from ``Exception`` so normal exception
+    handling can catch cancellation explicitly or through a broad handler.
+    """
+
+    def __init__(
+            self,
+            message: str = "The operation was canceled.",
+            token: CancellationToken | None = None,
+    ) -> None:
+        self.token = token
+        super().__init__(message)
+
+
+# Backwards-compatible spelling used by the first TinyTask prototype.
+CancelledError = OperationCanceledError
 
 
 class InvalidStateError(RuntimeError):
@@ -65,10 +88,10 @@ class RuntimeShutdownError(RuntimeError):
 
 
 class AggregateError(Exception):
-    """Raised by Task.when_all() when multiple child tasks fail.
+    """Represents multiple errors, preserving the original exceptions.
 
-    The original exceptions are available in the ``exceptions`` tuple. A single
-    child failure is re-raised directly to keep the common case ergonomic.
+    The default message follows the .NET ``AggregateException`` convention.
+    ``exceptions`` is stored as an immutable snapshot.
     """
 
     def __init__(
@@ -77,6 +100,10 @@ class AggregateError(Exception):
             message: str = "One or more errors occurred.",
     ) -> None:
         self.exceptions = tuple(exceptions)
+        if not self.exceptions:
+            raise ValueError("exceptions must contain at least one exception")
+        if not all(isinstance(error, Exception) for error in self.exceptions):
+            raise TypeError("exceptions must contain Exception instances")
         super().__init__(message)
 
 
@@ -258,11 +285,13 @@ class CancellationTokenSource:
             self._linked_registrations.clear()
         if timer is not None:
             timer.cancel()
-        cancelled = self._state.cancel()
-        # A linked source no longer needs to hold registrations after its own
-        # cancellation has fired. This is safe even when called from a link callback.
-        for registration in links:
-            registration.dispose()
+        try:
+            cancelled = self._state.cancel()
+        finally:
+            # A linked source no longer needs to hold registrations after its own
+            # cancellation has fired. Also clean these up if a callback failed.
+            for registration in links:
+                registration.dispose()
         return cancelled
 
     def cancel_after(self, seconds: float | None) -> None:
@@ -384,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"):
@@ -447,7 +476,7 @@ async def _delay_coroutine(runtime: "_Runtime", delay: float) -> None:
 
 
 class Task(Generic[T]):
-    """Result-bearing task managed by TinyTask's process-wide scheduler."""
+    """Result-bearing task managed by FlpIt's process-wide scheduler."""
 
     PENDING = "pending"
     SUCCEEDED = "succeeded"
@@ -478,6 +507,13 @@ class Task(Generic[T]):
         self._token = token or CancellationToken.none()
         self._token_registration: CancellationTokenRegistration | None = None
         self._pass_token = False
+        self._is_promise_task = False
+        self.async_state: Any = None
+
+    @property
+    def status(self) -> str:
+        """Current task state: pending, succeeded, failed, or cancelled."""
+        return self._state
 
     @classmethod
     def configure(
@@ -527,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
@@ -584,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),
         )
 
@@ -609,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),
         )
 
@@ -694,23 +734,26 @@ 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 OperationCanceledError(f"{self.name} was cancelled")
+            raise self._cancellation_exception()
         return self._exception
 
+    def _cancellation_exception(self) -> OperationCanceledError:
+        if isinstance(self._exception, OperationCanceledError):
+            return self._exception
+        return OperationCanceledError(f"{self.name} was cancelled")
+
     def cancel(self) -> bool:
         """Request cancellation of this Task, independently of other token users."""
         if self.done():
@@ -721,15 +764,15 @@ 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:
         if self._state == self.CANCELLED:
-            raise OperationCanceledError(f"{self.name} was cancelled")
+            raise self._cancellation_exception()
         if self._state == self.FAILED:
             assert self._exception is not None
             raise self._exception
@@ -747,7 +790,12 @@ class Task(Generic[T]):
             return
         self._cancel_requested = True
         self._runtime._detach_wait(self)
-        if not self._running:
+        if self._is_promise_task:
+            self._finish(
+                self.CANCELLED,
+                exception=OperationCanceledError(f"{self.name} cancelled"),
+            )
+        elif not self._running:
             self._runtime._schedule(self, exc=OperationCanceledError(f"{self.name} cancelled"))
 
     def _finish(
@@ -815,6 +863,165 @@ class Task(Generic[T]):
         return f"<{self.name} state={self._state}>"
 
 
+class TaskCompletionSource(Generic[T]):
+    """Externally controlled producer for a stable, awaitable ``Task[T]``.
+
+    The source can complete its task with a result, exception, cancellation, or
+    the terminal outcome of an already-completed task. Completion methods are
+    safe to call from arbitrary threads. Exactly one terminal transition wins.
+
+    ``state`` is carried by the task as ``task.async_state`` for diagnostics and
+    callback-to-task adapters. ``set_result()`` without a value is allowed for
+    the non-generic-style use case and completes with ``None``.
+    """
+
+    def __init__(self, state: Any = None) -> None:
+        runtime = _get_runtime()
+        self._runtime = runtime
+        self._task: Task[T] = Task(runtime)
+        self._task._is_promise_task = True
+        self._task.async_state = state
+        # Promise tasks are tracked so runtime shutdown can cancel unresolved
+        # externally-completed tasks and wake any awaiters.
+        runtime._call_sync(lambda: runtime._tasks.add(self._task), internal=False)
+
+    @property
+    def task(self) -> Task[T]:
+        """The stable task controlled by this source."""
+        return self._task
+
+    @property
+    def Task(self) -> Task[T]:  # .NET-spelling alias for source-porting convenience
+        return self._task
+
+    def set_result(self, result: T = cast(T, _MISSING)) -> None:
+        if result is _MISSING:
+            result = cast(T, None)
+        if not self.try_set_result(result):
+            raise InvalidStateError("TaskCompletionSource task has already completed")
+
+    def try_set_result(self, result: T = cast(T, _MISSING)) -> bool:
+        if result is _MISSING:
+            result = cast(T, None)
+        return self._try_complete(Task.SUCCEEDED, result=result)
+
+    @staticmethod
+    def _normalize_exceptions(
+            error: Exception | Iterable[Exception],
+    ) -> tuple[Exception, ...] | Exception:
+        if isinstance(error, Exception):
+            return error
+        if error is None:
+            raise TypeError("exception must not be None")
+        if isinstance(error, (str, bytes, bytearray)):
+            raise TypeError("exception must be an Exception or iterable of Exceptions")
+        try:
+            exceptions = tuple(error)
+        except TypeError as exc:
+            raise TypeError("exception must be an Exception or iterable of Exceptions") from exc
+        if not exceptions:
+            raise ValueError("exception iterable must not be empty")
+        if not all(isinstance(item, Exception) for item in exceptions):
+            raise TypeError("exception iterable must contain only Exception instances")
+        return exceptions
+
+    def set_exception(self, error: Exception | Iterable[Exception]) -> None:
+        normalized = self._normalize_exceptions(error)
+        exception = (
+            normalized
+            if isinstance(normalized, Exception)
+            else AggregateError(normalized)
+        )
+        if not self._try_complete(Task.FAILED, exception=exception):
+            raise InvalidStateError("TaskCompletionSource task has already completed")
+
+    def try_set_exception(self, error: Exception | Iterable[Exception]) -> bool:
+        normalized = self._normalize_exceptions(error)
+        exception = (
+            normalized
+            if isinstance(normalized, Exception)
+            else AggregateError(normalized)
+        )
+        return self._try_complete(Task.FAILED, exception=exception)
+
+    def set_canceled(self, token: CancellationToken | None = None) -> None:
+        self._validate_token(token)
+        cancellation = OperationCanceledError(
+            "The task was canceled.", token=token
+        )
+        if not self._try_complete(Task.CANCELLED, exception=cancellation):
+            raise InvalidStateError("TaskCompletionSource task has already completed")
+
+    def try_set_canceled(self, token: CancellationToken | None = None) -> bool:
+        self._validate_token(token)
+        cancellation = OperationCanceledError(
+            "The task was canceled.", token=token
+        )
+        return self._try_complete(Task.CANCELLED, exception=cancellation)
+
+    @staticmethod
+    def _validate_token(token: CancellationToken | None) -> None:
+        if token is not None and not isinstance(token, CancellationToken):
+            raise TypeError("token must be a CancellationToken or None")
+
+    def set_from_task(self, completed_task: flpit.task.Task[Any]) -> None:
+        self._validate_completed_task(completed_task)
+        if not self._try_copy_task(completed_task):
+            raise InvalidStateError("TaskCompletionSource task has already completed")
+
+    def try_set_from_task(self, completed_task: flpit.task.Task[Any]) -> bool:
+        self._validate_completed_task(completed_task)
+        return self._try_copy_task(completed_task)
+
+    def _validate_completed_task(self, source: "flpit.task.Task[Any] | None") -> None:
+        if source is None:
+            raise TypeError("completed_task must not be None")
+        if not isinstance(source, Task):
+            raise TypeError("completed_task must be a Task instance")
+        if not source.done():
+            raise ValueError("completed_task must already be completed")
+
+    def _try_copy_task(self, source: "flpit.task.Task[Any]") -> bool:
+        if source._state == Task.SUCCEEDED:
+            return self._try_complete(Task.SUCCEEDED, result=source._result)
+        if source._state == Task.FAILED:
+            assert source._exception is not None
+            return self._try_complete(Task.FAILED, exception=source._exception)
+        if source._state == Task.CANCELLED:
+            return self._try_complete(
+                Task.CANCELLED,
+                exception=source._cancellation_exception(),
+            )
+        # A terminal state not recognized here would indicate a runtime invariant
+        # violation rather than a normal rejected completion.
+        raise InvalidStateError(f"Cannot copy task in state {source._state!r}")
+
+    def _try_complete(
+            self,
+            state: str,
+            *,
+            result: Any = None,
+            exception: Exception | BaseException | None = None,
+    ) -> bool:
+        if self._task.done():
+            return False
+
+        def complete_on_runtime() -> bool:
+            if self._task.done():
+                return False
+            self._task._finish(state, result=result, exception=exception)
+            return True
+
+        try:
+            return bool(self._runtime._call_sync(complete_on_runtime, internal=True))
+        except RuntimeShutdownError:
+            # Shutdown may have won the race and completed this promise task as
+            # cancelled. In that case TrySet* follows the standard lost-race path.
+            if self._task.done():
+                return False
+            raise
+
+
 def _normalize_tasks(items: tuple[Any, ...], *, allow_empty: bool) -> tuple[Task[Any], ...]:
     """Normalize task-combinator inputs, scheduling raw awaitables as Tasks.
 
@@ -887,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]
@@ -900,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)
 
@@ -995,6 +1203,39 @@ class _Runtime:
         message = str(context.get("message", "Unexpected TinyTask runtime error"))
         _LOG.error("%s", message, exc_info=(type(error), error, error.__traceback__))
 
+    def _call_sync(self, callback: Callable[[], T], *, internal: bool = False) -> T:
+        """Run a small state mutation on the scheduler thread and return its value.
+
+        External completion APIs use this so callbacks/awaiters are manipulated
+        only by the scheduler thread while callers retain synchronous Set/TrySet
+        semantics. The operation fails rather than hanging if the runtime stops.
+        """
+        self._ensure_started()
+        if self.is_runtime_thread():
+            return callback()
+
+        completed = threading.Event()
+        outcome: dict[str, Any] = {}
+
+        def invoke() -> None:
+            try:
+                outcome["value"] = callback()
+            except BaseException as error:
+                outcome["error"] = error
+            finally:
+                completed.set()
+
+        self._post(invoke, internal=internal)
+        while not completed.wait(0.05):
+            thread = self._thread
+            if thread is None or not thread.is_alive():
+                raise RuntimeShutdownError(
+                    "TinyTask runtime stopped before the scheduled operation ran"
+                )
+        if "error" in outcome:
+            raise outcome["error"]
+        return cast(T, outcome.get("value"))
+
     def _post(self, callback: Callable[[], None], *, internal: bool = False) -> None:
         self._ensure_started()
         execute_inline = False
@@ -1412,12 +1653,16 @@ class _Runtime:
             self._schedule(task)
 
     def _next_timeout(self) -> float | None:
+        max_selector_wait = 24 * 60 * 60  # 24 hours, in seconds
+
         while self._timers:
             deadline, _, task, operation = self._timers[0]
             if task.done() or task._waiting_on is not operation:
                 heapq.heappop(self._timers)
             else:
-                return max(0.0, deadline - time.monotonic())
+                remaining = max(0.0, deadline - time.monotonic())
+                return min(remaining, max_selector_wait)
+
         return None
 
     def _begin_shutdown(self) -> None:
@@ -1585,17 +1830,41 @@ def _shutdown_at_exit() -> None:
 
 atexit.register(_shutdown_at_exit)
 
-def task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
-    @functools.wraps(async_function)
+
+@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
+    """
+    @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
 
 
-def coro_task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
+@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 an async coroutine function to be compatible with Task.run(coro)
+    | Wraps async functions with a dependency on asyncio to be compatible with Task.run(coro)
 
     Use with caution as this transfers execution control to an isolated asyncio loop runner.
     """
@@ -1608,3 +1877,25 @@ def coro_task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
             return runner.run(coro)
 
     return task(wrapper)
+
+
+class _SyncBridge:
+    def __rshift__(self, ttwa: Task[T]) -> T:
+        frame = inspect.currentframe()
+        try:
+            assert frame is not None
+            caller: Any = frame.f_back
+            if caller and caller.f_code.co_flags & inspect.CO_COROUTINE:
+                raise RuntimeError("twait >> cannot be used inside async def")
+
+            return ttwa.result()
+        finally:
+            del frame
+
+
+twait: Final = _SyncBridge()
+"""
+| If you seriously want to await in a sync context make it nice
+
+twait >> Task.delay()
+"""