flpit 0.2.0.dev2__tar.gz → 0.2.1__tar.gz

flpit-0.2.0.dev2/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
@@ -349,16 +434,18 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | ├── test_all.py                                |          80 |
 | ├── test_any.py                                |          90 |
 | ├── test_average.py                            |         572 |
+| ├── test_concat.py                             |          64 |
 | ├── test_count.py                              |          37 |
 | ├── test_generic_list.py                       |          95 |
 | ├── test_last.py                               |          29 |
 | ├── test_order_by.py                           |         100 |
 | ├── test_order_descending_by.py                |          45 |
+| ├── test_skip.py                               |          75 |
 | ├── test_sum.py                                |         134 |
 | ├── test_take.py                               |          39 |
 | ├── test_then_by.py                            |          40 |
 | └── test_then_descending_by.py                 |          34 |
 ----------------------------------------------------------------
-| GRAND TOTALS                                   |        1295 |
+| GRAND TOTALS                                   |        1434 |
 ================================================================
 ```

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

@@ -1,23 +1,3 @@
-Metadata-Version: 2.5
-Name: flpit
-Version: 0.2.0.dev2
-Summary: Fluent LINQ for Python — flip your iterables
-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**
@@ -150,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:
@@ -345,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
@@ -369,16 +410,18 @@ Distributed under the MIT License. See `LICENSE` for more information.
 | ├── test_all.py                                |          80 |
 | ├── test_any.py                                |          90 |
 | ├── test_average.py                            |         572 |
+| ├── test_concat.py                             |          64 |
 | ├── test_count.py                              |          37 |
 | ├── test_generic_list.py                       |          95 |
 | ├── test_last.py                               |          29 |
 | ├── test_order_by.py                           |         100 |
 | ├── test_order_descending_by.py                |          45 |
+| ├── test_skip.py                               |          75 |
 | ├── test_sum.py                                |         134 |
 | ├── test_take.py                               |          39 |
 | ├── test_then_by.py                            |          40 |
 | └── test_then_descending_by.py                 |          34 |
 ----------------------------------------------------------------
-| GRAND TOTALS                                   |        1295 |
+| GRAND TOTALS                                   |        1434 |
 ================================================================
 ```

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

@@ -1,9 +1,9 @@
 [project]
 name = "flpit"
-version = "0.2.0.dev2"
+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,14 +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 = [
@@ -28,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.dev2 → flpit-0.2.1}/src/flpit/__init__.py

@@ -5,33 +5,59 @@ from __future__ import annotations
 from importlib.metadata import version
 __version__ = version("flpit")
 
-import builtins
-from typing import Iterable as _Iterable, TypeVar
-
 from flpit import flp
 from flpit.core.linq import (
     FlpIt,
     FlpList,
     Grouping,
     OrderedIt,
+
+    #====================
+    # InvalidOperationException
+    #====================
+    InvalidOperationError,
     EmptySequenceError,
     NoMatchError,
     MultipleElementsError,
     MultipleMatchesError,
+
+    #====================
+    # ArgumentExceptions
+    #====================
+    ArgumentError,
+    ArgumentNullError,
     SourceNoneError,
     PredicateNoneError,
+    CollectionNoneError,
+    SelectorNoneError,
+    SecondNoneError,
+    ArgumentOutOfRangeError,
+    ArgumentNonNegError,
+    ArgumentOutOfBoundsError
 )
 
 __all__ = [
+    "flp",
     "FlpIt",
     "FlpList",
     "Grouping",
     "OrderedIt",
+
+    "InvalidOperationError",
     "EmptySequenceError",
     "NoMatchError",
     "MultipleElementsError",
     "MultipleMatchesError",
+
+    "ArgumentError",
+    "ArgumentNullError",
     "SourceNoneError",
     "PredicateNoneError",
+    "CollectionNoneError",
+    "SelectorNoneError",
+    "SecondNoneError",
+    "ArgumentOutOfRangeError",
+    "ArgumentNonNegError",
+    "ArgumentOutOfBoundsError",
 ]