flpit 0.2.1.dev6__tar.gz → 0.2.1.dev8__tar.gz

{flpit-0.2.1.dev6 → flpit-0.2.1.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flpit
-Version: 0.2.1.dev6
+Version: 0.2.1.dev8
 Summary: Fluent LINQ for Python — flip your iterables
 Project-URL: Homepage, https://github.com/riemar/flpit
 Project-URL: Repository, https://github.com/riemar/flpit

{flpit-0.2.1.dev6 → flpit-0.2.1.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flpit"
-version = "0.2.1.dev6"
+version = "0.2.1.dev8"
 description = "Fluent LINQ for Python — flip your iterables"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -34,6 +34,7 @@ dev = [
     "pyright>=1.1.414",
     "pytest-benchmark>=5.3.0",
     "mypy>=2.4.0",
+    "httpx>=0.28.1",
 ]
 
 

{flpit-0.2.1.dev6 → flpit-0.2.1.dev8}/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,15 +66,15 @@ class JsonSerializerOptions:
 # Metadata Annotation Markers
 # ---------------------------------------------------------------------------
 
-class JsonIgnore:
+class JIgnore:
     def __class_getitem__[T](cls, item: type[T]) -> Any:
         return Annotated[item, cls]
 
-class JsonInclude:
+class JInclude:
     def __class_getitem__[T](cls, item: type[T]) -> Any:
         return Annotated[item, cls]
 
-class JsonProperty:
+class JProp:
     def __class_getitem__[T](cls, item: tuple[type[T], str]) -> Any:
         target_type, json_name = item
         return Annotated[target_type, cls(json_name)]
@@ -81,9 +82,24 @@ class JsonProperty:
     def __init__(self, name: str):
         self.name = name
 
-JIgnore = JsonIgnore
-JInclude = JsonInclude
-JProp = JsonProperty
+class Dummy:
+    def __getitem__[T](self, item: tuple[type[T], str]) -> Any:
+        target_type, json_name = item
+        return Annotated[target_type, self]
+
+    def __init__(self, name: str):
+        self.name = name
+
+# just alias it
+J = Annotated
+
+@dataclass
+class AnnotationModel:
+    internal_id: JProp[int, "any_arbitrary_string_you_want"]
+    display_name: J[str, JProp("")]
+    display_name_2: Dummy("name")[str]
+    secret: JIgnore[str] = ""
+    always_emit: JInclude[int] = 0
 
 # ---------------------------------------------------------------------
 # Generated type metadata
@@ -120,36 +136,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)
-
-    if policy == JsonNamingPolicy.upper:
-        result = "".join(t.upper() for t in tokens)
+    # Preserve all leading underscores.
+    prefix = name[: len(name) - len(name.lstrip("_"))]
+    clean_name = name[len(prefix):]
 
-    if policy == JsonNamingPolicy.pascal:
-        result = "".join(t.capitalize() 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.kebap:
-        result = "-".join(t.lower() 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.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 +206,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.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:

{flpit-0.2.1.dev6 → flpit-0.2.1.dev8}/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.
 
@@ -39,17 +39,36 @@ from collections import deque
 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, Callable, Coroutine, Generic, TypeVar, cast, Iterable, Final
 import functools
 
+import flpit
+
 T = TypeVar("T")
 _LOG = logging.getLogger("tinytask")
 _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 +84,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 +96,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 +281,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:
@@ -447,7 +472,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 +503,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(
@@ -599,7 +631,7 @@ class Task(Generic[T]):
         Accepts Task instances and raw awaitables (including coroutine objects)
         positionally or in one iterable. Raw awaitables are scheduled
         automatically. The winning task is returned even if it failed or was
-        cancelled; inspect/await that task to observe
+        canceled; inspect/await that task to observe
         its outcome. Losing tasks continue running. An empty input is invalid.
         If multiple tasks are already complete at observation time, input order
         breaks the tie deterministically.
@@ -612,6 +644,22 @@ class Task(Generic[T]):
             cls.run(_when_any_coroutine, normalized, name=name, token=token),
         )
 
+    @staticmethod
+    async def collect(*tasks: Task[Any] | list[Task[Any]]):
+        """
+        Yields tasks as they complete. Accepts either a list or loose positional tasks.
+        """
+        # FIX: If it's a list or tuple, extract and cast the FIRST element to a mutable list
+        if len(tasks) == 1 and isinstance(tasks[0], (list, tuple)):
+            pending = list(tasks[0])  # Converts the inner container into a fresh list
+        else:
+            pending = list(tasks)     # Converts the *tasks tuple into a fresh list
+
+        while pending:
+            finished_task = await Task.when_any(pending)
+            pending.remove(finished_task)  # Safe to call, because pending is ALWAYS a list!
+            yield finished_task
+
     @classmethod
     def delay(
             cls,
@@ -692,9 +740,14 @@ class Task(Generic[T]):
         if not self._completed.wait(timeout):
             raise TimeoutError(f"{self.name} did not complete before the timeout")
         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():
@@ -713,7 +766,7 @@ class Task(Generic[T]):
 
     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
@@ -731,7 +784,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(
@@ -799,6 +857,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.
 
@@ -979,6 +1196,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
@@ -1396,12 +1646,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:
@@ -1570,8 +1824,50 @@ def _shutdown_at_exit() -> None:
 atexit.register(_shutdown_at_exit)
 
 def task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
+    """
+    | Wraps sync functions and non-asyncio dependent coroutines to eagerly executed await-able tasks
+    """
     @functools.wraps(async_function)
     def wrapper(*args: Any, **kwargs: Any) -> Task[Any]:
         return Task.run(async_function, *args, **kwargs)
 
-    return wrapper
+    return wrapper
+
+
+def asyncio_task(async_function: Callable[..., Any]) -> Callable[..., Task[Any]]:
+    """
+    | 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.
+    """
+    import asyncio
+    @functools.wraps(async_function)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        with asyncio.Runner() as runner:
+            # Call the function with its arguments to generate the Coroutine object instance
+            coro = async_function(*args, **kwargs)
+            return runner.run(coro)
+
+    return task(wrapper)
+
+
+class _SyncBridge:
+    def __rshift__(self, ttwa: Task[T]) -> Any:
+        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()
+"""