stdlibx-streams 0.1.0__tar.gz

stdlibx_streams-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucino772
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stdlibx_streams-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: stdlibx-streams
+Version: 0.1.0
+Summary: stdlibx-streams
+Author: Lucino772
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.10.0,<5
+Requires-Python: >=3.9.25
+Project-URL: Documentation, http://stdlibx.lucapalmi.com/
+Project-URL: Repository, https://github.com/Lucino772/stdlibx
+Description-Content-Type: text/markdown
+
+[![docs](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml/badge.svg?branch=main)](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml)
+
+# stdlibx
+**stdlibx** is a collection of small, focused Python utilities that simplify common programming patterns and help you write clearer, more composable code.
+
+It provides practical tools for handling optional values, explicit error management, cancellation, composition, configuration, pattern matching, and reactive flows.
+
+## Documentation
+Checkout the [documentation](http://stdlibx.lucapalmi.com/)
+
+## Licence
+This project uses a **MIT** Licence [view](https://github.com/Lucino772/stdlibx/blob/main/LICENSE)

stdlibx_streams-0.1.0/README.md

@@ -0,0 +1,12 @@
+[![docs](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml/badge.svg?branch=main)](https://github.com/Lucino772/stdlibx/actions/workflows/deploy-docs.yaml)
+
+# stdlibx
+**stdlibx** is a collection of small, focused Python utilities that simplify common programming patterns and help you write clearer, more composable code.
+
+It provides practical tools for handling optional values, explicit error management, cancellation, composition, configuration, pattern matching, and reactive flows.
+
+## Documentation
+Checkout the [documentation](http://stdlibx.lucapalmi.com/)
+
+## Licence
+This project uses a **MIT** Licence [view](https://github.com/Lucino772/stdlibx/blob/main/LICENSE)

stdlibx_streams-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "stdlibx-streams"
+version = "0.1.0"
+description = "stdlibx-streams"
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+readme = "README.md"
+authors = [
+    { name = "Lucino772" }
+]
+requires-python = ">=3.9.25"
+dependencies = [
+    "typing_extensions>=4.10.0,<5"
+]
+
+[project.urls]
+Documentation = "http://stdlibx.lucapalmi.com/"
+Repository = "https://github.com/Lucino772/stdlibx"
+
+[tool.uv.build-backend]
+module-name = "stdlibx.streams"
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"

stdlibx_streams-0.1.0/src/stdlibx/streams/__init__.py

@@ -0,0 +1,5 @@
+from stdlibx.streams._subject import Subject
+from stdlibx.streams._types import Disposable, Observable, Observer
+from stdlibx.streams.utils import as_observable
+
+__all__ = ["Disposable", "Observable", "Observer", "Subject", "as_observable"]

stdlibx_streams-0.1.0/src/stdlibx/streams/_abc.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from stdlibx.streams._types import Disposable, Observable, Operation
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+class ObservableBase(Generic[T]):
+    def __init__(self) -> None:
+        self._subscribers: list[Callable[[T], None]] = []
+
+    def apply(self, func: Operation[Observable[T], U]) -> U:
+        return func(self)
+
+    def __or__(self, func: Operation[Observable[T], U]) -> U:
+        return self.apply(func)
+
+    def subscribe(self, func: Callable[[T], None]) -> Disposable:
+        self._subscribers.append(func)
+        return _FuncDisposable(lambda: self._subscribers.remove(func))
+
+
+class _FuncDisposable:
+    def __init__(self, func: Callable[[], None]) -> None:
+        self.__func = func
+        self.__disposed = False
+
+    def dispose(self) -> None:
+        if self.__disposed:
+            return
+
+        self.__func()
+        self.__disposed = True

stdlibx_streams-0.1.0/src/stdlibx/streams/_subject.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, cast
+
+from stdlibx.streams._abc import ObservableBase
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from stdlibx.streams._types import Disposable
+
+T = TypeVar("T")
+
+
+class Subject(ObservableBase[T]):
+    def __init__(self, initial: T, /) -> None:
+        super().__init__()
+
+        self.__value = initial
+
+    def subscribe(self, func: Callable[[T], None]) -> Disposable:
+        func(self.__value)
+        return super().subscribe(func)
+
+    def push(self, val: T | Callable[[T], T]) -> None:
+        if callable(val):
+            self.__value = cast("T", val(self.__value))
+        else:
+            self.__value = cast("T", val)
+
+        for subscriber in self._subscribers:
+            subscriber(self.__value)

stdlibx_streams-0.1.0/src/stdlibx/streams/_types.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Callable, Protocol, TypeVar, runtime_checkable
+
+from typing_extensions import TypeAlias
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+Operation: TypeAlias = Callable[[T], U]
+
+
+T_co = TypeVar("T_co", covariant=True)
+U_contra = TypeVar("U_contra", contravariant=True)
+
+
+class Disposable(Protocol):
+    def dispose(self) -> None: ...
+
+
+@runtime_checkable
+class Observable(Protocol[T_co]):
+    def apply(self, func: Operation[Observable[T_co], U_contra]) -> U_contra: ...
+
+    def __or__(self, func: Operation[Observable[T_co], U_contra]) -> U_contra: ...
+
+    def subscribe(self, func: Callable[[T_co], None]) -> Disposable: ...
+
+
+class Observer(Protocol[U_contra]):
+    def push(self, val: U_contra) -> None: ...
+
+
+Subscriber: TypeAlias = Callable[[Observer[T]], Disposable]

stdlibx_streams-0.1.0/src/stdlibx/streams/fn/__init__.py

@@ -0,0 +1,23 @@
+from stdlibx.streams.fn.base import (
+    as_tuple,
+    combine,
+    distinct,
+    for_,
+    if_,
+    is_,
+    is_not_none,
+    map_,
+    start_with,
+)
+
+__all__ = [
+    "as_tuple",
+    "combine",
+    "distinct",
+    "for_",
+    "if_",
+    "is_",
+    "is_not_none",
+    "map_",
+    "start_with",
+]

stdlibx_streams-0.1.0/src/stdlibx/streams/fn/base.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import operator
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    TypeVar,
+    Union,
+)
+
+from stdlibx.streams import methods
+from typing_extensions import TypeGuard, TypeVarTuple, Unpack
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from stdlibx.streams._types import (
+        Observable,
+        Operation,
+    )
+
+T = TypeVar("T")
+U = TypeVar("U")
+Ts = TypeVarTuple("Ts")
+
+
+def map_(func: Callable[[T], U]) -> Operation[Observable[T], Observable[U]]:
+    return partial(methods.map_, func=func)
+
+
+def if_(func: Callable[[T], bool]) -> Operation[Observable[T], Observable[T]]:
+    return partial(methods.if_, func=func)
+
+
+def is_(
+    func: Callable[[Union[T, U]], TypeGuard[U]],
+) -> Operation[Observable[Union[T, U]], Observable[U]]:
+    return partial(methods.is_, func=func)
+
+
+def is_not_none() -> Operation[Observable[Union[T, None]], Observable[T]]:
+    return methods.is_not_none
+
+
+def as_tuple() -> Operation[Observable[T], Observable[tuple[T]]]:
+    return methods.as_tuple
+
+
+def combine(
+    other: Observable[U],
+) -> Operation[Observable[tuple[Unpack[Ts]]], Observable[tuple[Unpack[Ts], U]]]:
+    return partial(methods.combine, other=other)
+
+
+def start_with(value: T) -> Operation[Observable[T], Observable[T]]:
+    return partial(methods.start_with, value=value)
+
+
+def for_(
+    func: Callable[[T], U],
+) -> Operation[Observable[Iterable[T]], Observable[Iterable[U]]]:
+    return partial(methods.for_, func=func)
+
+
+def distinct(
+    equal_fn: Callable[[T, T], bool] = operator.eq,
+) -> Operation[Observable[T], Observable[T]]:
+    return partial(methods.distinct, equal_fn=equal_fn)

stdlibx_streams-0.1.0/src/stdlibx/streams/methods/__init__.py

@@ -0,0 +1,23 @@
+from stdlibx.streams.methods.base import (
+    as_tuple,
+    combine,
+    distinct,
+    for_,
+    if_,
+    is_,
+    is_not_none,
+    map_,
+    start_with,
+)
+
+__all__ = [
+    "as_tuple",
+    "combine",
+    "distinct",
+    "for_",
+    "if_",
+    "is_",
+    "is_not_none",
+    "map_",
+    "start_with",
+]

stdlibx_streams-0.1.0/src/stdlibx/streams/methods/base.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import operator
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    Generic,
+    TypeVar,
+    Union,
+)
+
+from typing_extensions import TypeGuard, TypeVarTuple, Unpack
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+
+    from stdlibx.streams._types import (
+        Disposable,
+        Observable,
+        Observer,
+        Operation,
+        Subscriber,
+    )
+
+T = TypeVar("T")
+U = TypeVar("U")
+Ts = TypeVarTuple("Ts")
+
+
+def map_(source: Observable[T], func: Callable[[T], U]) -> Observable[U]:
+    def _subscribe(other: Observer[U]) -> Disposable:
+        return source.subscribe(lambda val: other.push(func(val)))
+
+    return _Observable(_subscribe)
+
+
+def if_(source: Observable[T], func: Callable[[T], bool]) -> Observable[T]:
+    def _subscribe(other: Observer[T]) -> Disposable:
+        return source.subscribe(
+            lambda val: other.push(val) if func(val) is True else None
+        )
+
+    return _Observable(_subscribe)
+
+
+def is_(
+    source: Observable[Union[T, U]], func: Callable[[Union[T, U]], TypeGuard[U]]
+) -> Observable[U]:
+    def _subscribe(other: Observer[U]) -> Disposable:
+        return source.subscribe(lambda val: other.push(val) if func(val) else None)
+
+    return _Observable(_subscribe)
+
+
+def is_not_none(source: Observable[Union[T, None]]) -> Observable[T]:
+    return is_(source, lambda val: val is not None)  # type: ignore
+
+
+def as_tuple(source: Observable[T]) -> Observable[tuple[T]]:
+    return map_(source, lambda v: (v,))
+
+
+def combine(
+    source: Observable[tuple[Unpack[Ts]]], other: Observable[U]
+) -> Observable[tuple[Unpack[Ts], U]]:
+    values = {}
+
+    def _update(observer: Observer[tuple[Unpack[Ts]]], **kwargs) -> None:
+        nonlocal values
+        values.update(kwargs)
+
+        if ("first" not in values) or ("second" not in values):
+            return
+
+        if isinstance(values["first"], tuple):
+            observer.push((*values["first"], values["second"]))  # type: ignore
+        else:
+            observer.push((values["first"], values["second"]))  # type: ignore
+
+    def _subscribe(observer: Observer[tuple]) -> Disposable:
+        _updater = partial(_update, observer)
+        return _CompositeDisposable(
+            [
+                source.subscribe(lambda v: _updater(first=v)),
+                other.subscribe(lambda v: _updater(second=v)),
+            ]
+        )
+
+    return _Observable(_subscribe)
+
+
+def start_with(source: Observable[T], value: T) -> Observable[T]:
+    def _subscribe(other: Observer[T]) -> Disposable:
+        other.push(value)
+        return source.subscribe(other.push)
+
+    return _Observable(_subscribe)
+
+
+def for_(
+    source: Observable[Iterable[T]], func: Callable[[T], U]
+) -> Observable[Iterable[U]]:
+    return map_(source, lambda items: [func(item) for item in items])
+
+
+def distinct(
+    source: Observable[T], equal_fn: Callable[[T, T], bool] = operator.eq
+) -> Observable[T]:
+    def _subscribe(other: Observer[T]) -> Disposable:
+        curr_val: "Union[T, None]" = None
+
+        def _subscriber(other: Observer[T], val: T) -> None:
+            nonlocal curr_val
+            if curr_val is None or equal_fn(curr_val, val) is False:
+                other.push(val)
+                curr_val = val
+
+        return source.subscribe(partial(_subscriber, other))
+
+    return _Observable(_subscribe)
+
+
+class _Observable(Generic[T]):
+    def __init__(self, subscribe: Subscriber[T]) -> None:
+        self.__subscribe = subscribe
+
+    def apply(self, func: Operation[Observable[T], U]) -> U:
+        return func(self)
+
+    def __or__(self, func: Operation[Observable[T], U]) -> U:
+        return self.apply(func)
+
+    def subscribe(self, func: Callable[[T], None]) -> Disposable:
+        return self.__subscribe(_CallbackObserver(func))
+
+
+class _CallbackObserver(Generic[T]):
+    def __init__(self, func: Callable[[T], None]) -> None:
+        self.__func = func
+
+    def push(self, val: T) -> None:
+        self.__func(val)
+
+
+class _CompositeDisposable:
+    def __init__(self, disposables: list[Disposable]) -> None:
+        self.__disposables = disposables
+
+    def dispose(self) -> None:
+        for disposable in self.__disposables:
+            disposable.dispose()

stdlibx_streams-0.1.0/src/stdlibx/streams/utils.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TypeVar
+
+from stdlibx.streams._subject import Subject
+from stdlibx.streams._types import Observable
+
+T = TypeVar("T")
+
+
+def as_observable(value: Observable[T] | T) -> Observable[T]:
+    if isinstance(value, Observable):
+        return value
+    return Subject(value)