flpit 0.2.0__tar.gz → 0.2.1__tar.gz

flpit-0.2.0/README.md → flpit-0.2.1/PKG-INFO

@@ -1,3 +1,27 @@
+Metadata-Version: 2.5
+Name: flpit
+Version: 0.2.1
+Summary: Fluent LINQ for Python — flip your iterables
+Project-URL: Homepage, https://github.com/riemar/flpit
+Project-URL: Repository, https://github.com/riemar/flpit
+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
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: msgspec>=0.22.0
+Description-Content-Type: text/markdown
+
 # FlpIt
 
 > **Fluent LINQ for Python — LINQ semantics, Python-native execution**
@@ -130,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:
@@ -325,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.0/PKG-INFO → flpit-0.2.1/README.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.5
-Name: flpit
-Version: 0.2.0
-Summary: Fluent LINQ for Python — flip your iterables
-Project-URL: Homepage, https://github.com/riemar/flpit
-License: MIT
-License-File: LICENSE
-Keywords: fluent,generators,iterable,lazy-evaluation,linq,pipeline,pyrefly,type-safe
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-
 # FlpIt
 
 > **Fluent LINQ for Python — LINQ semantics, Python-native execution**
@@ -151,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:
@@ -346,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.0 → flpit-0.2.1}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "flpit"
-version = "0.2.0"
+version = "0.2.1"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 license = { text = "MIT" }
 keywords = ["linq", "fluent", "iterable", "pipeline", "lazy-evaluation", "pyrefly", "type-safe", "generators"]
 classifiers = [
@@ -11,17 +11,21 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed"
 ]
-dependencies = []
+dependencies = [
+    "msgspec>=0.22.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/riemar/flpit"
+Repository = "https://github.com/riemar/flpit"
+Issues = "https://github.com/riemar/flpit/issues"
 
 [dependency-groups]
 dev = [
@@ -31,6 +35,7 @@ dev = [
     "pyright>=1.1.414",
     "pytest-benchmark>=5.3.0",
     "mypy>=2.4.0",
+    "httpx>=0.28.1",
 ]
 
 

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

@@ -1,7 +1,10 @@
 from __future__ import annotations
-from typing import SupportsIndex
+
+from io import BytesIO, StringIO
+
 import decimal
 from decimal import Decimal, Overflow, Inexact
+from contextlib import AbstractContextManager
 
 import builtins
 from collections import UserList
@@ -15,15 +18,21 @@ from typing import (
     Iterable,
     Iterator,
     Collection,
+    SupportsIndex,
     List,
     Set,
     Type,
     TypeVar,
+    ClassVar,
     Union,
     override,
     overload,
-    cast as typing_cast,
+    cast as typing_cast, BinaryIO,
 )
+
+import flpit.json
+from flpit.json import JsonConvert, JsonSerializerOptions
+
 TItem = TypeVar("TItem")
 TResult = TypeVar("TResult")
 TKey = TypeVar("TKey")
@@ -118,8 +127,7 @@ def _guard_empty(func: Callable[..., Any]) -> Callable[..., Any]:
     return wrapper
 
 
-# noinspection unresolved-references,protected-member
-def dotnet_context() -> decimal._ContextManager: # awesome that type was not intended
+def dotnet_context() -> AbstractContextManager[decimal.Context]:
     # 1. Create and configure pure Context object
     ctx = decimal.getcontext().copy()
     ctx.prec = max(ctx.prec, 29)
@@ -246,8 +254,8 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
             for item in self:
                 if predicate(item):
                     yield item
-
-        return typing_cast(FlpIt[TItem], FlpIt(_FactoryIterable(_generator)))
+        # return typing_cast(FlpIt[TItem], FlpIt[TItem](_FactoryIterable(_generator)))
+        return FlpIt[TItem](_FactoryIterable(_generator))
 
     def select(self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
         """Projects each element into a new form."""
@@ -617,10 +625,36 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         raise MultipleMatchesError() if has_predicate else MultipleElementsError()
 
-
     def to_list(self) -> FlpList[TItem]:
         """Explicitly materializes the query into a FlpList."""
-        return FlpList(self)
+        return FlpList[TItem](self)
+
+    # =====================================================================
+    # 5. json serialization
+    # =====================================================================
+
+    @classmethod
+    def from_json[T](cls, data: str | bytes, item_type: type[T], jso: JsonSerializerOptions|None=None) -> FlpIt[T]:
+        return FlpIt[T](JsonConvert.deserialize(data, list[item_type], jso))
+
+    def to_json_bytes[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> bytes:
+        writer = BytesIO()
+        JsonConvert.serialize_to(self, item_type, writer, jso)
+        return writer.getvalue()
+
+    def to_json[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> str:
+        writer = StringIO()
+        JsonConvert.serialize_to(self, item_type, writer, jso)
+        return writer.getvalue()
+
+    def write_json[T](
+            self,
+            item_type: type[T],
+            output: BinaryIO,
+            jso: JsonSerializerOptions | None = None,
+    ) -> None:
+        JsonConvert.serialize_to(self, item_type, output, jso)
+
 
 from functools import partial
 
@@ -731,6 +765,8 @@ class FlpList(Collection[TItem], Generic[TItem]):
     | Fluent List
     A materialized list extending UserList that yields lazy FlpIt instances for query operations.
     """
+    __type_args__: ClassVar[tuple[Any, ...]]
+
     def __init__(self, source: Iterable[TItem] | _Sentinel=_SENTINEL):
         if source is None:
             raise SourceNoneError()
@@ -1001,7 +1037,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
         return self  # type: ignore[return-value]
 
     def where(self, predicate: Callable[[TItem], bool]) -> FlpIt[TItem]:
-        return FlpIt(self.__list.data).where(predicate)
+        return FlpIt[TItem](self.__list.data).where(predicate)
 
     def select(self, selector: Callable[[TItem], TResult]) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).select(selector)
@@ -1179,3 +1215,25 @@ class FlpList(Collection[TItem], Generic[TItem]):
     def to_list(self) -> FlpList[TItem]:
         """Explicitly returns a shallow copy instance to isolate mutations."""
         return FlpList(self.__list.data.copy())
+
+    # =====================================================================
+    # 5. json serialization
+    # =====================================================================
+
+    @classmethod
+    def from_json[T](cls, data: str | bytes, item_type: type[T], jso: JsonSerializerOptions|None=None) -> FlpList[T]:
+        return FlpList[T](JsonConvert.deserialize(data, list[item_type], jso))
+
+    def to_json_bytes[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> bytes:
+        return JsonConvert.serialize_bytes(self.__list.data, list[item_type], jso)
+
+    def to_json[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> str:
+        return JsonConvert.serialize(self.__list.data, list[item_type], jso)
+
+    def write_json[T](
+            self,
+            item_type: type[T],
+            output: BinaryIO,
+            jso: JsonSerializerOptions | None = None,
+    ) -> None:
+        JsonConvert.serialize_to(self, item_type, output, jso)