flpit 0.2.0__tar.gz → 0.2.1.dev3__tar.gz

{flpit-0.2.0 → flpit-0.2.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.0
+Version: 0.2.1.dev3
 Summary: Fluent LINQ for Python — flip your iterables
 Project-URL: Homepage, https://github.com/riemar/flpit
 License: MIT
@@ -16,7 +16,8 @@ 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

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

@@ -1,9 +1,9 @@
 [project]
 name = "flpit"
-version = "0.2.0"
+version = "0.2.1.dev3"
 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 = [
@@ -18,7 +18,9 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed"
 ]
-dependencies = []
+dependencies = [
+    "msgspec>=0.22.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/riemar/flpit"

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

@@ -1,5 +1,3 @@
-from __future__ import annotations
-from typing import SupportsIndex
 import decimal
 from decimal import Decimal, Overflow, Inexact
 
@@ -15,15 +13,21 @@ from typing import (
     Iterable,
     Iterator,
     Collection,
+    SupportsIndex,
     List,
     Set,
     Type,
     TypeVar,
+    ClassVar,
     Union,
     override,
     overload,
     cast as typing_cast,
+    GenericAlias
 )
+
+from flpit.json import JsonSerializerOptions, decode_dataclass, encode_dataclass
+
 TItem = TypeVar("TItem")
 TResult = TypeVar("TResult")
 TKey = TypeVar("TKey")
@@ -246,8 +250,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 +621,10 @@ 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)
+
 
 from functools import partial
 
@@ -731,6 +735,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 +1007,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 +1185,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](decode_dataclass(data, list[item_type], jso))
+
+    def to_json_bytes[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> bytes:
+        return encode_dataclass(self.__list.data, list[item_type], jso)
+
+    def to_json[T](self, item_type: type[T], jso: JsonSerializerOptions|None=None) -> str:
+        return self.to_json_bytes(item_type, jso).decode(encoding="utf-8")
+
+

flpit-0.2.1.dev3/src/flpit/json.py

@@ -0,0 +1,427 @@
+from typing import Annotated
+import dataclasses
+import re
+import sys
+import types
+import typing
+
+import threading
+from dataclasses import MISSING, dataclass
+from functools import lru_cache
+from typing import Any, ForwardRef, get_args, get_origin, get_type_hints
+from hashlib import blake2s
+
+import msgspec
+
+from enum import StrEnum
+
+class JsonNamingPolicy(StrEnum):
+    lower_case = "lower"
+    upper_case = "upper"
+    camel_case = "camel"
+    pascal_case = "pascal"
+    kebap_case = "kebab"
+
+
+@dataclass(slots=True, frozen=True)
+class JsonSerializerOptions:
+    naming_policy: JsonNamingPolicy = JsonNamingPolicy.camel_case
+    write_indented: bool = False
+    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 = self.naming_policy.value
+        return blake2s(settings.encode(), 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)
+
+
+# ---------------------------------------------------------------------
+# Module and annotation utilities
+# ---------------------------------------------------------------------
+
+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 _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):
+            if not field.init:
+                continue
+
+            pending.extend(
+                _nested_dataclasses(info.hints[field.name])
+            )
+
+    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],
+) -> list[tuple[Any, ...]]:
+    definitions: list[tuple[Any, ...]] = []
+
+    for field in dataclasses.fields(info.source):
+        if not field.init:
+            continue
+
+        annotation = _rewrite_type(
+            info.hints[field.name],
+            info,
+            graph,
+        )
+
+        if field.default is not MISSING:
+            spec = (field.name, annotation, field.default)
+
+        elif field.default_factory is not MISSING:
+            spec = (
+                field.name,
+                annotation,
+                msgspec.field(
+                    default_factory=field.default_factory
+                ),
+            )
+
+        # for now... no enforcing of explicit null in json
+        elif _allows_none(info.hints[field.name]):
+            spec = (field.name, annotation, None)
+
+        else:
+            spec = (field.name, annotation)
+
+        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)
+        )
+    # pyrefly: ignore [implicit-any-lambda]
+    } | {  "__class__": property(lambda self, cls=source: cls) }
+
+def _build_graph(
+        roots: tuple[type, ...],
+        jso: JsonSerializerOptions,
+) -> dict[type, _WireType]:
+    graph = _discover_graph(roots)
+
+    for wt in graph.values():
+        wt.struct = msgspec.defstruct(
+            wt.class_name,
+            _struct_fields(wt, graph),
+            module=wt.module_name,
+            namespace=_behavior_namespace(wt.source),
+            rename=jso.naming_policy.value,
+            kw_only=True,
+            omit_defaults=True, # don't render nulls
+            forbid_unknown_fields=False, # ensure ignoring unknow fields!
+        )
+
+    _register_forward_refs(graph)
+
+    for wt in graph.values():
+        msgspec.inspect.type_info(wt.struct)
+
+    # Publish the readable generated class names.
+    for wt in graph.values():
+        setattr(wt.namespace, wt.class_name, wt.struct)
+
+    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)
+
+def _cached_graph(roots:tuple[object, ...], jso: JsonSerializerOptions):
+    with _registry_lock:
+        _jso_registry[jso.fingerprint] = jso
+
+    return _wrapped_lru(roots, jso.fingerprint)
+
+def wire_type_for(
+        target_type: type,
+        jso: JsonSerializerOptions,
+):
+    roots = tuple(_nested_dataclasses(target_type))
+
+    if not roots:
+        raise TypeError(
+            "Only @dataclass are supported!, "
+            f"got {target_type!r}"
+        )
+
+    # Normalize the root set so User and list[User] share the graph.
+    graph_roots = tuple(sorted(set(roots), key=id))
+
+    graph = _cached_graph(
+        graph_roots,
+        jso,
+    )
+
+    return _rewrite_type(
+        target_type,
+        graph[roots[0]],
+        graph,
+        resolve=True,
+    )
+
+
+def decode_dataclass(
+        data: bytes | str,
+        target: type,
+        jso: JsonSerializerOptions|None=None
+):
+    if jso is None:
+        jso = JsonSerializerOptions()
+
+    wire_type = wire_type_for(target, jso)
+    parsed = msgspec.json.decode(data, type=wire_type)
+
+    if jso.native:
+        return parsed
+
+    return msgspec.convert(
+        parsed,
+        target,
+        from_attributes=True,
+    )
+
+def encode_dataclass[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 msgspec.json.encode(wire_obj)
+