flpit 0.2.0.dev2__py3-none-any.whl → 0.2.1.dev4__py3-none-any.whl

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",
 ]
 

flpit/core/linq.py

@@ -1,5 +1,4 @@
-from __future__ import annotations
-from typing import SupportsIndex
+from flpit.io import StringWriter
 import decimal
 from decimal import Decimal, Overflow, Inexact
 
@@ -15,15 +14,22 @@ from typing import (
     Iterable,
     Iterator,
     Collection,
+    SupportsIndex,
     List,
     Set,
     Type,
     TypeVar,
+    ClassVar,
     Union,
     override,
     overload,
     cast as typing_cast,
+    GenericAlias
 )
+
+from flpit.io import MemoryByteWriter
+from flpit.json import JsonConvert, JsonSerializerOptions
+
 TItem = TypeVar("TItem")
 TResult = TypeVar("TResult")
 TKey = TypeVar("TKey")
@@ -39,38 +45,70 @@ class _Sentinel:
 _SENTINEL = _Sentinel()
 _MISSING = object()
 
+# =============================================================================
+# Invalid Operation Errors
+# =============================================================================
+class InvalidOperationError(ValueError):
+    pass
 
-class EmptySequenceError(ValueError):
+class EmptySequenceError(InvalidOperationError):
     def __init__(self):
         super().__init__("Sequence contains no elements")
 
-class NoMatchError(ValueError):
+class NoMatchError(InvalidOperationError):
     def __init__(self):
         super().__init__("Sequence contains no matching elements")
 
-class MultipleMatchesError(ValueError):
+class MultipleMatchesError(InvalidOperationError):
     def __init__(self):
         super().__init__("Sequence contains more than one matching element")
 
-class MultipleElementsError(ValueError):
+class MultipleElementsError(InvalidOperationError):
     def __init__(self):
         super().__init__("Sequence contains more than one element")
 
-class SourceNoneError(TypeError):
+
+# =============================================================================
+# Argument Errors
+# =============================================================================
+class ArgumentError(TypeError):
+    pass
+
+class ArgumentNullError(ArgumentError):
+    def __init__(self, argument: str):
+        super().__init__(f"Value cannot be None. (Argument '{argument}')")
+
+class SourceNoneError(ArgumentNullError):
+    def __init__(self):
+        super().__init__("source")
+
+class PredicateNoneError(ArgumentNullError):
+    def __init__(self):
+        super().__init__("predicate")
+
+class CollectionNoneError(ArgumentNullError):
     def __init__(self):
-        super().__init__("Value cannot be None. (Argument 'source')")
+        super().__init__("collection")
 
-class PredicateNoneError(TypeError):
+class SelectorNoneError(ArgumentNullError):
     def __init__(self):
-        super().__init__("Value cannot be None. (Argument 'predicate')")
+        super().__init__("keySelector")
 
-class CollectionNoneError(TypeError):
+class SecondNoneError(ArgumentNullError):
     def __init__(self):
-        super().__init__("Value cannot be None. (Argument 'collection')")
+        super().__init__("second")
 
-class SelectorNoneError(TypeError):
+class ArgumentOutOfRangeError(ArgumentError):
+    def __init__(self, argument: str, pattern:str="Index was out of range. Must be non-negative and less than the size of the collection."):
+        super().__init__(f"{pattern} (Parameter '{argument}')")
+
+class ArgumentNonNegError(ArgumentOutOfRangeError):
+    def __init__(self, argument:str):
+        super().__init__(argument, "Non-negative number required.")
+
+class ArgumentOutOfBoundsError(ArgumentError):
     def __init__(self):
-        super().__init__("Value cannot be None. (Parameter 'keySelector')")
+        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]:
@@ -191,6 +229,9 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
         return builtins.all(map(predicate, self))
 
     def concat(self, second: Iterable[TItem]) -> "FlpIt[TItem]":
+        if second is None:
+            raise SecondNoneError()
+
         def _generator() -> Iterator[TItem]:
             yield from self
             yield from second
@@ -211,8 +252,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."""
@@ -232,6 +273,18 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
 
         return FlpIt(_FactoryIterable(_generator))
 
+    def skip(self, count: int) -> "FlpIt[TItem]":
+        """
+        |Bypasses a specified number of elements from the start.
+        """
+        if count <= 0:
+            return self
+
+        def _generator() -> Iterator[TItem]:
+            yield from islice(iter(self), count, None)
+
+        return FlpIt(_FactoryIterable(_generator))
+
     def take(self, count: int) -> "FlpIt[TItem]":
         """
         |Returns a specified number of contiguous elements from the start.
@@ -528,11 +581,13 @@ class FlpIt(Iterable[TItem], Generic[TItem]):
     def element_at(self, index: int) -> TItem:
         """Returns the element at a specified index in a sequence."""
         if index < 0:
-            raise IndexError("Index out of range")
+            raise ArgumentOutOfRangeError("index")
+
         for i, item in enumerate(self):
             if i == index:
                 return item
-        raise IndexError("Index out of range")
+
+        raise ArgumentOutOfRangeError("index")
 
     def first(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
         """Returns the first element matching a predicate, or raises ValueError."""
@@ -568,10 +623,28 @@ 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 = MemoryByteWriter()
+        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 = StringWriter()
+        JsonConvert.serialize_to(self, item_type, writer, jso)
+        return writer.getvalue()
+
 
 from functools import partial
 
@@ -682,6 +755,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()
@@ -830,7 +905,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
 
     def insert(self, index: int, item: TItem) -> None:
         if index < 0 or index > len(self.__list.data):
-            raise IndexError(f"Index {index} is out of range.")
+            raise ArgumentOutOfRangeError("index")
 
         self.__list.data.insert(index, item)
 
@@ -839,7 +914,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
             raise CollectionNoneError()
 
         if index < 0 or index > len(self.__list.data):
-            raise IndexError(f"Index {index} is out of range.")
+            raise ArgumentOutOfRangeError("index")
 
         self.__list.data[index:index] = list(collection)
 
@@ -865,22 +940,22 @@ class FlpList(Collection[TItem], Generic[TItem]):
         return original_length - len(self.__list.data)
 
     def remove_at(self, index: int) -> None:
-        if index < 0 or index > len(self.__list.data):
-            raise IndexError(f"Index {index} is out of range.")
+        if index < 0 or index >= len(self.__list.data):
+            raise ArgumentOutOfRangeError("index")
 
         del self.__list.data[index]
 
     def remove_range(self, index: int, count: int) -> None:
         size = len(self.__list.data)
 
-        if index < 0 or index > size:
-            raise IndexError("index")
+        if index < 0:
+            raise ArgumentNonNegError("index")
 
         if count < 0:
-            raise IndexError("count")
+            raise ArgumentNonNegError("count")
 
         if count > size - index:
-            raise IndexError("The range is invalid.")
+            raise ArgumentOutOfBoundsError()
 
         del self.__list.data[index : index + count]
 
@@ -899,17 +974,13 @@ class FlpList(Collection[TItem], Generic[TItem]):
 
         # Apply your List<T>-compatible argument validation here.
         if index < 0 or index > size:
-            raise IndexError("Non-negative number required.")
+            raise ArgumentNonNegError("index")
 
         if count < 0:
-            raise IndexError("Non-negative number required.")
+            raise ArgumentNonNegError("count")
 
         if index + count > size:
-            raise IndexError(
-                "Offset and length were out of bounds for the array or "
-                "count is greater than the number of elements from index "
-                "to the end of the source collection."
-            )
+            raise ArgumentOutOfBoundsError()
 
         self.__list.data[index:index + count] = reversed(
             self.__list.data[index:index + count]
@@ -948,12 +1019,15 @@ class FlpList(Collection[TItem], Generic[TItem]):
         """Prepends an element to the sequence lazily, returning a FlpIt without mutating this list."""
         return FlpIt(self.__list.data).prepend(element)
 
+    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 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)
@@ -963,6 +1037,9 @@ class FlpList(Collection[TItem], Generic[TItem]):
     ) -> FlpIt[TResult]:
         return FlpIt(self.__list.data).select_many(selector)
 
+    def skip(self, count: int) -> FlpIt[TItem]:
+        return FlpIt(self.__list.data).skip(count)
+
     def take(self, count: int) -> FlpIt[TItem]:
         return FlpIt(self.__list.data).take(count)
 
@@ -1076,7 +1153,7 @@ class FlpList(Collection[TItem], Generic[TItem]):
 
     def element_at(self, index: int) -> TItem:
         if index < 0 or index >= len(self.__list.data):
-            raise IndexError("Index out of range")
+            raise ArgumentOutOfRangeError("index")
         return self.__list.data[index]
 
     def first(self, predicate: Callable[[TItem], bool] | _Sentinel = _SENTINEL) -> TItem:
@@ -1128,3 +1205,19 @@ 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)
+
+

flpit/io.py

@@ -0,0 +1,212 @@
+from types import TracebackType
+from abc import ABC, abstractmethod
+from io import StringIO, TextIOWrapper
+from typing import Any, BinaryIO, Iterable
+
+import msgspec
+
+
+# ---------- Text layer ----------
+
+class StringBuilder:
+    __slots__ = ("_buffer", "_length")
+
+    def __init__(self, initial_value: str = ""):
+        self._buffer = StringIO()
+        self._length = 0
+        self.append(initial_value)
+
+    def append(self, text: str) -> "StringBuilder":
+        self._buffer.write(text)
+        self._length += len(text)
+        return self
+
+    def append_line(self, text: str = "") -> "StringBuilder":
+        return self.append(text).append("\n")
+
+    def clear(self) -> None:
+        self._buffer.seek(0)
+        self._buffer.truncate(0)
+        self._length = 0
+
+    @property
+    def length(self) -> int:
+        return self._length
+
+    def to_string(self) -> str:
+        return self._buffer.getvalue()
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+
+class TextWriter(ABC):
+    @abstractmethod
+    def write(self, text: str) -> int:
+        ...
+
+    def write_line(self, text: str = "") -> None:
+        self.write(text)
+        self.write("\n")
+
+    @abstractmethod
+    def flush(self) -> None:
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        ...
+
+    def __enter__(self):
+        return self
+
+    def __exit__(
+            self,
+            exc_type: type[BaseException] | None,
+            exc_val: BaseException | None,
+            exc_tb: TracebackType | None,
+    ) -> bool | None:
+        self.close()
+
+
+class StringWriter(TextWriter):
+    def __init__(self):
+        self._builder = StringBuilder()
+        self._closed = False
+
+    def write(self, text: str) -> int:
+        if self._closed:
+            raise ValueError("Writer is closed")
+        self._builder.append(text)
+        return len(text)
+
+    def flush(self) -> None:
+        if self._closed:
+            raise ValueError("Writer is closed")
+
+    def close(self) -> None:
+        self._closed = True
+
+    def getvalue(self) -> str:
+        return self._builder.to_string()
+
+
+class StreamWriter(TextWriter):
+    """Text writer over a binary stream; closing it closes the stream."""
+
+    def __init__(self, stream: BinaryIO, encoding: str = "utf-8"):
+        self._stream = TextIOWrapper(stream, encoding=encoding)
+
+    def write(self, text: str) -> int:
+        return self._stream.write(text)
+
+    def flush(self) -> None:
+        self._stream.flush()
+
+    def close(self) -> None:
+        self._stream.close()
+
+#===================================
+# ---------- Binary layer ----------
+#===================================
+
+class ByteWriter(ABC):
+    """write() must consume or copy the supplied bytes before returning."""
+
+    @abstractmethod
+    def write(self, data: bytes | bytearray | memoryview) -> None:
+        ...
+
+    @abstractmethod
+    def flush(self) -> None:
+        ...
+
+class MemoryByteWriter(ByteWriter):
+    def __init__(self):
+        self._buffer = bytearray()
+
+    def write(self, data: bytes | bytearray | memoryview) -> None:
+        self._buffer.extend(data)
+
+    def flush(self) -> None:
+        pass
+
+    def getvalue(self) -> bytes:
+        return bytes(self._buffer)
+
+
+class StreamByteWriter(ByteWriter):
+    """Adapter for a Python binary stream. The caller owns the stream."""
+
+    def __init__(self, stream: BinaryIO):
+        self._stream = stream
+
+    def write(self, data: bytes | bytearray | memoryview) -> None:
+        view = memoryview(data)
+
+        while view:
+            count = self._stream.write(view)
+            if count is None or count <= 0:
+                raise OSError("Stream failed to write data")
+            view = view[count:]
+
+    def flush(self) -> None:
+        self._stream.flush()
+
+
+class BufferedByteWriter(ByteWriter):
+    """Adds explicit, bounded-size output buffering to another writer."""
+
+    def __init__(self, destination: ByteWriter, chunk_size: int = 1 << 20):
+        if chunk_size < 1:
+            raise ValueError("chunk_size must be positive")
+
+        self._destination = destination
+        self._chunk_size = chunk_size
+        self._buffer = bytearray()
+
+    def write(self, data: bytes | bytearray | memoryview) -> None:
+        view = memoryview(data)
+
+        while view:
+            count = min(
+                self._chunk_size - len(self._buffer),
+                len(view),
+                )
+            self._buffer.extend(view[:count])
+            view = view[count:]
+
+            if len(self._buffer) == self._chunk_size:
+                self._flush_buffer()
+
+    def _flush_buffer(self) -> None:
+        if self._buffer:
+            self._destination.write(self._buffer)
+            self._buffer.clear()
+
+    def flush(self) -> None:
+        self._flush_buffer()
+        self._destination.flush()
+
+
+# ---------- JSON serialization policy ----------
+
+def write_json_array(
+        items: Iterable[Any],
+        output: ByteWriter,
+) -> None:
+    encoder = msgspec.json.Encoder()
+    scratch = bytearray()
+    first = True
+
+    output.write(b"[")
+
+    for item in items:
+        if not first:
+            output.write(b",")
+
+        encoder.encode_into(item, scratch)
+        output.write(scratch)
+        first = False
+
+    output.write(b"]")

flpit/json.py

@@ -0,0 +1,632 @@
+from collections.abc import Iterable
+import dataclasses
+import re
+import sys
+import threading
+import types
+import typing
+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, cast as typing_cast
+
+import msgspec
+
+from flpit.io import ByteWriter, TextWriter
+
+
+class JsonNamingPolicy(StrEnum):
+    lower = "lower" # pyrefly: ignore [bad-override-mutable-attribute]
+    upper = "upper" # pyrefly: ignore [bad-override-mutable-attribute]
+    camel = "camel"
+    pascal = "pascal"
+    kebap = "kebab"
+
+
+class JsonDefaultHandling(StrEnum):
+    include = "include"
+    exclude = "exclude"
+
+class JsonUnknownFieldHandling(StrEnum):
+    allow = "allow"
+    disallow = "disallow"
+
+
+@dataclass(slots=True, frozen=True)
+class JsonSerializerOptions:
+    naming_policy: JsonNamingPolicy = JsonNamingPolicy.camel
+    default_handling: JsonDefaultHandling = JsonDefaultHandling.exclude
+    unknown_field_handling: JsonUnknownFieldHandling = JsonUnknownFieldHandling.allow
+
+    # write_indented: bool = False # will be supported later
+    native: bool = False
+    """
+    | Set to true for the native speed of msgspec
+    
+    !! only set to true if you know what you are doing !!
+    You'll receive the msgspec.msgstruct object that will try to do it's best to behave like your dataclass.
+    But remember !! "It's NOT your dataclass" !!
+    """
+
+    @property
+    def fingerprint(self) -> str:
+        """
+        Identifies a unique jso instance for building a struct
+        !! All parts of a jso that don't influence the defstruct MUST be ignored!
+        """
+        settings = (f"jpn-{self.naming_policy.value}:"
+                   f"dh-{self.default_handling}:"
+                   f"ufh-{self.unknown_field_handling}:"
+                   ).encode("utf-8")
+        return blake2s(settings, digest_size=6).hexdigest()
+
+# ---------------------------------------------------------------------------
+# Metadata Annotation Markers
+# ---------------------------------------------------------------------------
+
+class JsonIgnore:
+    def __class_getitem__[T](cls, item: type[T]) -> Any:
+        return 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)]
+
+    def __init__(self, name: str):
+        self.name = name
+
+JIgnore = JsonIgnore
+JInclude = JsonInclude
+JProp = JsonProperty
+
+# ---------------------------------------------------------------------
+# Generated type metadata
+# ---------------------------------------------------------------------
+
+@dataclass(slots=True, eq=False)
+class _WireType:
+    source: type
+    """The source type to build a msgspec.struct for"""
+    hints: dict[str, Any]
+    namespace: types.ModuleType
+    """the name space we are targeting"""
+    struct: type | None = None
+
+    @property
+    def module_name(self: _WireType) -> str:
+        return self.namespace.__name__
+
+    @property
+    def class_name(self: _WireType) -> str:
+        return self.source.__name__
+
+    @property
+    def ref_name(self: _WireType) -> str:
+        identity = (
+            f"{self.source.__module__}_{self.source.__qualname__}"
+        )
+        return "_ref_" + re.sub(r"\W", "_", identity)
+
+
+# ---------------------------------------------------------------------
+# Never imagined this would be required to have a proper lib behavior
+# ---------------------------------------------------------------------
+
+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.
+    """
+    # 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:
+        return name
+
+    if policy == JsonNamingPolicy.lower:
+        result = "".join(t.lower() for t in tokens)
+
+    if policy == JsonNamingPolicy.upper:
+        result = "".join(t.upper() for t in tokens)
+
+    if policy == JsonNamingPolicy.pascal:
+        result = "".join(t.capitalize() for t in tokens)
+
+    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:])
+
+    else:
+        result = clean_name
+
+    return prefix + result
+
+
+
+def _generated_module(source: type) -> types.ModuleType:
+    """Generates the required module definition for our runtime only dynamic msgspec.struct"""
+    name = f"flpit.json._generated.{source.__module__}"
+
+    module = sys.modules.get(name)
+    if module is None:
+        module = types.ModuleType(name)
+        sys.modules[name] = module
+
+    return module
+
+
+def _is_dataclass_type(tp: Any) -> bool:
+    return isinstance(tp, type) and dataclasses.is_dataclass(tp)
+
+
+def _field_directives(
+        annotation: Any,
+) -> tuple[Any, bool, bool, str | None]:
+    """Extract JIgnore, JInclude, and JProp directives from a field annotation."""
+
+    if get_origin(annotation) is not typing.Annotated:
+        return annotation, False, False, None
+
+    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)
+    json_name = next(
+        (item.name for item in metadata if isinstance(item, JsonProperty)),
+        None,
+    )
+    remaining = tuple(
+        item
+        for item in metadata
+        if item is not JsonIgnore
+        and item is not JsonInclude
+        and not isinstance(item, JsonProperty)
+    )
+
+    if remaining:
+        base_type = Annotated[(base_type, *remaining)]
+
+    return base_type, ignored, included, json_name
+
+
+def _get_property_directive(prop_func: Callable[[Any, Any], None] | Callable[[Any], Any] | None):
+    if prop_func is not None:
+        getter_hints = get_type_hints(prop_func, include_extras=True)
+        source_annotation = getter_hints.get("return", Any)
+    else:
+        source_annotation = Any
+
+    return  _field_directives(source_annotation)
+
+
+def _nested_dataclasses(tp: Any):
+    """Yield dataclass types referenced by an annotation."""
+    if _is_dataclass_type(tp):
+        yield tp
+        return
+
+    if isinstance(tp, (list, tuple)):
+        for item in tp:
+            yield from _nested_dataclasses(item)
+        return
+
+    origin = get_origin(tp)
+
+    if origin is typing.Annotated:
+        yield from _nested_dataclasses(get_args(tp)[0])
+        return
+
+    if origin is typing.Literal:
+        return
+
+    for arg in get_args(tp):
+        yield from _nested_dataclasses(arg)
+
+
+def _rewrite_type(
+        tp: Any,
+        owner: _WireType,
+        graph: dict[type, _WireType],
+        *,
+        resolve: bool = False,
+) -> Any:
+    """Replace source dataclasses with generated Structs or ForwardRefs."""
+    if tp is getattr(typing, "Self", None):
+        info = owner
+        return info.struct if resolve else ForwardRef(info.ref_name)
+
+    if _is_dataclass_type(tp):
+        info = graph[tp]
+        return info.struct if resolve else ForwardRef(info.ref_name)
+
+    if isinstance(tp, list):
+        return [
+            _rewrite_type(item, owner, graph, resolve=resolve)
+            for item in tp
+        ]
+
+    if isinstance(tp, tuple):
+        return tuple(
+            _rewrite_type(item, owner, graph, resolve=resolve)
+            for item in tp
+        )
+
+    origin = get_origin(tp)
+
+    if origin is None or origin is typing.Literal:
+        return tp
+
+    args = get_args(tp)
+
+    if origin is typing.Annotated:
+        base = _rewrite_type(
+            args[0], owner, graph, resolve=resolve
+        )
+        return typing.Annotated[(base, *args[1:])]
+
+    rewritten: tuple[Any, ...] = tuple(
+        _rewrite_type(arg, owner, graph, resolve=resolve)
+        for arg in args
+    )
+
+    if origin in (typing.Union, types.UnionType):
+        union: Any = typing.Union # with all the magic here, there's no way to make typing really happy
+        return union[rewritten]
+
+    params = rewritten[0] if len(rewritten) == 1 else rewritten
+
+    try:
+        return origin[params]
+    except (TypeError, AttributeError) as exc:
+        copier = getattr(tp, "copy_with", None)
+        if copier is not None:
+            return copier(rewritten)
+
+        raise TypeError(
+            f"Cannot rewrite annotation {tp!r}"
+        ) from exc
+
+
+# ---------------------------------------------------------------------
+# Graph discovery
+# ---------------------------------------------------------------------
+
+
+def _discover_graph(
+        roots: tuple[type, ...],
+) -> dict[type, _WireType]:
+    """Discover reachable dataclasses and resolve their annotations."""
+    graph: dict[type, _WireType] = {}
+    pending = list(roots)
+
+    while pending:
+        source = pending.pop()
+
+        if source in graph:
+            continue
+
+        info = _WireType(
+            source=source,
+            hints=get_type_hints(source, include_extras=True),
+            namespace=_generated_module(source),
+        )
+        graph[source] = info
+
+        for field in dataclasses.fields(source):
+            annotation, ignored, included, _ = _field_directives(
+                info.hints[field.name]
+            )
+            if ignored:
+                continue
+
+            pending.extend(_nested_dataclasses(annotation))
+
+    return graph
+
+
+def _allows_none(tp: Any) -> bool:
+    if get_origin(tp) is typing.Annotated:
+        tp = get_args(tp)[0]
+
+    return type(None) in get_args(tp)
+
+# ---------------------------------------------------------------------
+# Struct construction
+# ---------------------------------------------------------------------
+
+
+def _struct_fields(
+        info: _WireType,
+        graph: dict[type, _WireType],
+        jso: JsonSerializerOptions,
+) -> list[tuple[Any, ...]]:
+    definitions: list[tuple[Any, ...]] = []
+    dataclass_fields = {f.name for f in dataclasses.fields(info.source)}
+
+    # 1. Process regular fields (regardless of init=True or init=False)
+    for field in dataclasses.fields(info.source):
+        source_annotation = info.hints[field.name]
+        annotation, ignored, included, json_name = _field_directives(source_annotation)
+
+        if ignored:
+            continue
+
+        # If the field starts with an underscore, it MUST have JInclude or JProp attached!
+        if field.name.startswith("_") and not (included or json_name is not None):
+            continue
+
+        annotation = _rewrite_type(annotation, info, graph)
+        wire_name = json_name if json_name is not None else _apply_naming_policy(field.name, jso.naming_policy)
+
+        # Resolve structural field default values cleanly
+        if field.default is not MISSING:
+            default_val = field.default
+            has_default = True
+        elif field.default_factory is not MISSING:
+            default_val = msgspec.field(default_factory=field.default_factory)
+            has_default = True
+        elif _allows_none(annotation):
+            default_val = None
+            has_default = True
+        else:
+            default_val = MISSING
+            has_default = False
+
+        field_options: dict[str, Any] = {"name": wire_name}
+        if has_default:
+            if field.default_factory is not MISSING:
+                field_options["default_factory"] = field.default_factory
+            else:
+                field_options["default"] = default_val
+
+        spec = (field.name, annotation, msgspec.field(**field_options))
+        definitions.append(spec)
+
+    # 2. Process properties automatically
+    for name, value in vars(info.source).items():
+        if isinstance(value, property) and name not in dataclass_fields:
+            # Extract the type annotation directly from the getter function signature
+            if value.fset is not None:
+                _, _, included, json_name = _get_property_directive(value.fset)
+
+                if included or json_name is not None:
+                    raise ValueError(
+                        f"{info.source.__qualname__}.{name}: "
+                        "fplit.json with msgspec backend doesn't support "
+                        "JProp/JInclude on property setters"
+                    )
+
+            annotation, ignored, included, json_name = _get_property_directive(value.fget)
+
+            if not included and json_name is None:
+                continue
+
+            annotation = _rewrite_type(annotation, info, graph)
+            wire_name = json_name if json_name is not None else _apply_naming_policy(name, jso.naming_policy)
+
+            # Map the field into the C-struct. Default to None so the inbound parser never complains.
+            spec = (name, annotation, msgspec.field(name=wire_name, default=None))
+            definitions.append(spec)
+
+
+    return definitions
+
+
+def _register_forward_refs(
+        graph: dict[type, _WireType],
+) -> None:
+    """Expose every graph reference in each participating module."""
+    namespaces = []
+
+    for info in graph.values():
+        if not any(info.namespace is ns for ns in namespaces):
+            namespaces.append(info.namespace)
+
+    for namespace in namespaces:
+        for info in graph.values():
+            setattr(namespace, info.ref_name, info.struct)
+
+
+def _behavior_namespace(source: type) -> dict[str, Any]:
+    return {
+        name: value
+        for name, value in vars(source).items()
+        if (
+                not name.startswith("__")
+                and (callable(value) or isinstance(value, property))
+        )
+        # pyrefly: ignore [implicit-any-lambda]
+    } | {  "__class__": property(lambda self, cls=source: cls) }
+
+
+def _create_structs(
+        graph: dict[type, _WireType],
+        jso: JsonSerializerOptions,
+) -> None:
+    """Create the generated msgspec structs for every node in the graph."""
+    for wt in graph.values():
+        fields = _struct_fields(wt, graph, jso)
+        wt.struct = msgspec.defstruct(
+            wt.class_name,
+            fields,
+            module=wt.module_name,
+            namespace=_behavior_namespace(wt.source),
+            rename=None,
+            kw_only=False,
+            omit_defaults=jso.default_handling.value == JsonDefaultHandling.exclude,
+            forbid_unknown_fields=jso.unknown_field_handling.value == JsonUnknownFieldHandling.disallow,
+        )
+
+
+def _validate_structs(graph: dict[type, _WireType]) -> None:
+    """Force msgspec to inspect each generated struct after refs are registered."""
+    for wt in graph.values():
+        msgspec.inspect.type_info(wt.struct)
+
+
+def _publish_structs(graph: dict[type, _WireType]) -> None:
+    # Publish the readable generated class names.
+    for wt in graph.values():
+        setattr(wt.namespace, wt.class_name, wt.struct)
+
+
+def _build_graph(
+        roots: tuple[type, ...],
+        jso: JsonSerializerOptions,
+) -> dict[type, _WireType]:
+    graph = _discover_graph(roots)
+    _create_structs(graph, jso)
+    _register_forward_refs(graph)
+    _validate_structs(graph)
+    _publish_structs(graph)
+    return graph
+
+
+# ---------------------------------------------------------------------
+# Cache and public API
+# ---------------------------------------------------------------------
+
+# we must only build new when the
+_jso_registry: dict[str, JsonSerializerOptions] = {}
+_registry_lock = threading.Lock()
+
+
+@lru_cache(maxsize=None)
+def _wrapped_lru(roots: tuple[type, ...], jso_id: str):
+    with _registry_lock:
+        jso = _jso_registry[jso_id]
+
+    return _build_graph(roots, jso)
+
+
+@lru_cache(maxsize=None)
+def _cached_wire_type(target_type: object, jso_id: str):
+    roots = tuple(_nested_dataclasses(target_type))
+
+    if not roots:
+        raise TypeError(
+            "Only @dataclass are supported!, "
+            f"got {target_type!r}"
+        )
+
+    graph_roots = tuple(sorted(set(roots), key=id))
+    graph = _wrapped_lru(graph_roots, jso_id)
+
+    return _rewrite_type(
+        target_type,
+        graph[roots[0]],
+        graph,
+        resolve=True,
+    )
+
+
+def wire_type_for(target_type: type, jso: JsonSerializerOptions) -> type:
+    jso_id = jso.fingerprint
+
+    with _registry_lock:
+        _jso_registry[jso_id] = jso
+
+    return _cached_wire_type(target_type, jso_id)
+
+
+@lru_cache(maxsize=256)
+def _get_decoder(wire_type: Any):
+    return msgspec.json.Decoder(type=wire_type)
+
+
+_JSON_ENCODER = msgspec.json.Encoder()
+
+
+class JsonConvert:
+
+    @staticmethod
+    def deserialize[T](
+            data: bytes | str,
+            target: type[T],
+            jso: JsonSerializerOptions | None = None
+    ) -> T:
+        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
+
+        result = msgspec.convert(
+            parsed,
+            target,
+            from_attributes=True,
+        )
+
+        return result
+
+    @staticmethod
+    def serialize[T](
+            data: Any,
+            target: type[T],
+            jso: JsonSerializerOptions | None = None
+    ) -> str:
+        return JsonConvert.serialize_bytes(data, target, jso).decode("utf-8")
+
+    @staticmethod
+    def serialize_bytes[T](
+            data: Any,
+            target: type[T],
+            jso: JsonSerializerOptions | None = None
+    ) -> bytes:
+        if jso is None:
+            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)
+
+    @staticmethod
+    def serialize_to[T](
+            it: Iterable[T],
+            target: type[T],
+            output: ByteWriter | TextWriter,
+            jso: JsonSerializerOptions | None = None
+    ) -> None:
+        if jso is None:
+            jso = JsonSerializerOptions()
+
+        if isinstance(output, ByteWriter):
+            write = output.write
+        elif isinstance(output, TextWriter):
+            def write(data: bytes | bytearray) -> int:
+                return output.write(data.decode("utf-8"))
+        else:
+            raise TypeError("output must be ByteWriter or TextWriter")
+
+        first = True
+        wire_type = wire_type_for(target, jso)
+
+        write(b"[")
+
+        for item in iter(it):
+            if not first:
+                write(b",")
+
+            wire_obj = msgspec.convert(item, wire_type, from_attributes=True)
+            write(_JSON_ENCODER.encode(wire_obj))
+            first = False
+
+        write(b']')
+
+

{flpit-0.2.0.dev2.dist-info → flpit-0.2.1.dev4.dist-info}/METADATA

@@ -1,7 +1,9 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.0.dev2
+Version: 0.2.1.dev4
 Summary: Fluent LINQ for Python — flip your iterables
+Project-URL: Homepage, https://github.com/riemar/flpit
+Project-URL: Repository, https://github.com/riemar/flpit
 License: MIT
 License-File: LICENSE
 Keywords: fluent,generators,iterable,lazy-evaluation,linq,pipeline,pyrefly,type-safe
@@ -9,13 +11,13 @@ 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
+Requires-Python: >=3.12
+Requires-Dist: msgspec>=0.22.0
 Description-Content-Type: text/markdown
 
 # FlpIt
@@ -369,16 +371,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.1.dev4.dist-info/RECORD

@@ -0,0 +1,12 @@
+flp/__init__.py,sha256=reAHhZtYt0f2LHeIYJbklta6Vatr6yeQCL1R-9TTyY0,688
+flpit/__init__.py,sha256=tx4tkpLxoKQTP7wu2PyUtQtLs9_pWHbx1jHh4Vdsrus,1275
+flpit/flp.py,sha256=i-FbnMeO92cxNRssYsgdlm2UGjILpveXgYUT468fWvY,999
+flpit/io.py,sha256=ATXt0H7DpKt9aC7-td5FhR601alVDsAPZ1tFJ9tVYvM,5259
+flpit/json.py,sha256=Ujlk8jo6kCIaVwhYRwDV17PQ6rmCVa8G9IjPz_Tvfsw,19115
+flpit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flpit/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+flpit/core/linq.py,sha256=h2KKK9wP77cGFKsqDtCRlulSlhKj40DCVZj4D9tpK2s,41049
+flpit-0.2.1.dev4.dist-info/METADATA,sha256=1O1rnsiWRbdz8f1bJbgKMrgCyDK9wlbsNmwz-IF9epk,13047
+flpit-0.2.1.dev4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+flpit-0.2.1.dev4.dist-info/licenses/LICENSE,sha256=bi5Vg_YP3Oq3jaOMQT4b7WZu0NfBcZr-nRyOExUKJrQ,1063
+flpit-0.2.1.dev4.dist-info/RECORD,,

flpit-0.2.0.dev2.dist-info/RECORD

@@ -1,10 +0,0 @@
-flp/__init__.py,sha256=reAHhZtYt0f2LHeIYJbklta6Vatr6yeQCL1R-9TTyY0,688
-flpit/__init__.py,sha256=T8tdJmfJiYiBuUszbACGan0U1meuBQa7IQpfIncADLA,705
-flpit/flp.py,sha256=i-FbnMeO92cxNRssYsgdlm2UGjILpveXgYUT468fWvY,999
-flpit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-flpit/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-flpit/core/linq.py,sha256=S4rbqA4UTIze_NOeSKLJMm1gWcWWS_voHdHhEVmlZ8U,37560
-flpit-0.2.0.dev2.dist-info/METADATA,sha256=IgRIlar-JXbxGK2Dt1Jcj8Sbf_GZNmp6X3yl9JjLJaU,12813
-flpit-0.2.0.dev2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-flpit-0.2.0.dev2.dist-info/licenses/LICENSE,sha256=bi5Vg_YP3Oq3jaOMQT4b7WZu0NfBcZr-nRyOExUKJrQ,1063
-flpit-0.2.0.dev2.dist-info/RECORD,,