python-iterutils 0.2.10.1__tar.gz → 0.3.0__tar.gz

{python_iterutils-0.2.10.1 → python_iterutils-0.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-iterutils
-Version: 0.2.10.1
+Version: 0.3.0
 Summary: Python another itertools.
-Home-page: https://github.com/ChenyangGao/python-modules/tree/main/python-iterutils
 License: MIT
+License-File: LICENSE
 Keywords: iterable,iterutils
 Author: ChenyangGao
 Author-email: wosiwujm@gmail.com
@@ -16,13 +16,15 @@ Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Dist: python-asynctools (>=0.1.3.4)
-Requires-Dist: python-texttools (>=0.0.3)
-Requires-Dist: python-undefined (>=0.0.3)
+Requires-Dist: python-asynctools (>=0.1.4)
+Requires-Dist: python-texttools (>=0.0.6)
+Requires-Dist: python-undefined (>=0.0.4)
+Project-URL: Homepage, https://github.com/ChenyangGao/python-modules/tree/main/python-iterutils
 Project-URL: Repository, https://github.com/ChenyangGao/python-modules/tree/main/python-iterutils
 Description-Content-Type: text/markdown
 

python_iterutils-0.3.0/iterutils/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+# encoding: utf-8
+
+__author__ = "ChenyangGao <https://chenyanggao.github.io>"
+__version__ = (0, 3, 0)
+
+from .dynamic import *
+from .gen_step import *
+from .misc import *

python_iterutils-0.3.0/iterutils/dynamic.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# encoding: utf-8
+
+__all__ = ["dynamic_async", "dynamic_async_iter"]
+
+from asyncio import run as asyncio_run, to_thread
+from collections.abc import (
+    AsyncIterable, AsyncIterator, Awaitable, Callable, Iterable, Iterator, 
+)
+from inspect import isawaitable
+
+from argtools import has_keyword_arg
+from asynctools import ensure_async, in_async
+from decotools import optional
+
+
+async def _as_async[T](v: T, /) -> T:
+    return v
+
+
+async def _as_async_iter[T](
+    it: Iterable[T], 
+    /, 
+    threaded: bool = False, 
+) -> AsyncIterator[T]:
+    if threaded:
+        call = iter(it).__next__
+        try:
+            while True:
+                yield await to_thread(call)
+        except StopIteration:
+            pass
+    else:
+        for e in it:
+            yield e
+
+
+def _as_iter[T](
+    it: AsyncIterable[T], 
+    /, 
+    run: Callable = asyncio_run, 
+) -> Iterator[T]:
+    try:
+        call = aiter(it).__anext__
+        while True:
+            yield run(call())
+    except StopAsyncIteration:
+        pass
+
+
+@optional
+def dynamic_async[T](
+    func: Callable, 
+    /, 
+    run: Callable = asyncio_run, 
+    threaded: bool = False, 
+    async_: None | bool = None, 
+):
+    has_async_arg = has_keyword_arg(func, "async_")
+    def wrapper(*args, async_: None | bool = async_, **kwds):
+        if async_ is None:
+            async_ = in_async()
+        if has_async_arg:
+            kwds["async_"] = async_
+        if async_:
+            if threaded:
+                r = ensure_async(func, threaded=threaded)(*args, **kwds)
+            else:
+                r = func(*args, **kwds)
+                if not isawaitable(r):
+                    r = _as_async(r)
+        else:
+            r = func(*args, **kwds)
+            if isawaitable(r):
+                r = run(r)
+        return r
+    return wrapper
+
+
+@optional
+def dynamic_async_iter[T](
+    func: Callable[..., Iterable] | Callable[..., AsyncIterable], 
+    /, 
+    run: Callable = asyncio_run, 
+    threaded: bool = False, 
+    async_: None | bool = None, 
+):
+    has_async_arg = has_keyword_arg(func, "async_")
+    def wrapper(*args, async_: None | bool = async_, **kwds):
+        if async_ is None:
+            async_ = in_async()
+        if has_async_arg:
+            kwds["async_"] = async_
+        it = func(*args, **kwds)
+        if async_:
+            if not isinstance(it, AsyncIterable):
+                it = _as_async_iter(it, threaded=threaded)
+        elif isinstance(it, AsyncIterable):
+            it = _as_iter(it, run)
+        return it
+    return wrapper
+

python_iterutils-0.3.0/iterutils/gen_step.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+# encoding: utf-8
+
+__all__ = [
+    "iter_gen_step", "run_gen_step", "run_gen_step_iter", 
+    "as_gen_step", "with_iter_next", "Yield", "YieldFrom", 
+]
+
+from asyncio import CancelledError as AsyncCancelledError
+from collections.abc import (
+    AsyncGenerator, AsyncIterable, AsyncIterator, Awaitable, Callable, 
+    Coroutine, Generator, Iterable, Iterator, 
+)
+from concurrent.futures import CancelledError
+from contextlib import contextmanager, AbstractContextManager, AbstractAsyncContextManager
+from dataclasses import dataclass
+from inspect import isawaitable
+from sys import exc_info
+from typing import (
+   cast,  overload, runtime_checkable, Any, ContextManager, Literal, Protocol, 
+)
+
+from argtools import has_keyword_arg
+from asynctools import in_async
+from decotools import optional
+
+
+@runtime_checkable
+class SupportsBool(Protocol):
+    def __bool__(self, /) -> bool:
+        ...
+
+
+@dataclass(slots=True, frozen=True)
+class Yield:
+    """专供 `run_gen_step_iter`，说明值需要 yield 给用户
+    """
+    value: Any
+
+
+@dataclass(slots=True, frozen=True)
+class YieldFrom:
+    """专供 `run_gen_step_iter`，说明值需要解包后逐个 yield 给用户
+    """
+    value: Any
+
+
+def iter_gen_step_sync[Y](
+    gen: Generator[Y, None | Y, Y], 
+    /, 
+) -> Generator[Y, Any, Any]:
+    send = gen.send
+    try:
+        v = None
+        while True:
+            yield (v := send(v))
+    except StopIteration as e:
+        yield e.value
+    finally:
+        gen.close()
+
+
+async def iter_gen_step_async[Y](
+    gen: Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y], 
+    /, 
+) -> AsyncGenerator[Y, Any]:
+    send  = gen.send
+    throw = gen.throw
+    try:
+        r = send(None)
+        while True:
+            try:
+                yield (v := await r)
+            except BaseException as e:
+                r = throw(e)
+            else:
+                r = send(v)
+        raise AsyncCancelledError
+    except StopIteration as e:
+        v = e.value
+        if isawaitable(v):
+            v = await v
+        yield v
+    finally:
+        gen.close()
+
+
+@overload
+def iter_gen_step[Y](
+    gen: Generator[Y, None | Y, Y] | Callable[[], Generator[Y, None | Y, Y]], 
+    /, 
+    async_: Literal[False] = False, 
+) -> Generator[Y, Any, Any]:
+    ...
+@overload
+def iter_gen_step[Y](
+    gen: Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y] | Callable[[], Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y]], 
+    /, 
+    async_: Literal[True], 
+) -> AsyncGenerator[Y, Any]:
+    ...
+def iter_gen_step[Y](
+    gen: Generator[Y, None | Y, Y] | Callable[[], Generator[Y, None | Y, Y]] | Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y] | Callable[[], Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y]], 
+    /, 
+    async_: Literal[False, True] = False, 
+) -> Generator[Y, Any, Any] | AsyncGenerator[Y, Any]:
+    if not isinstance(gen, Generator):
+        gen = gen()
+    if async_:
+        gen = cast(Generator[Awaitable[Y], None | Y, Awaitable[Y] | Y], gen)
+        return iter_gen_step_async(gen)
+    else:
+        gen = cast(Generator[Y, None | Y, Y], gen)
+        return iter_gen_step_sync(gen)
+
+
+def run_gen_step_sync[Y, T](
+    gen: Generator[Y, None | Y, T], 
+    /, 
+    running: SupportsBool = True, 
+) -> T:
+    send = gen.send
+    try:
+        v = None
+        while running:
+            v = send(v)
+        raise CancelledError
+    except StopIteration as e:
+        return e.value
+    finally:
+        gen.close()
+
+
+async def run_gen_step_async[Y, T](
+    gen: Generator[Awaitable[Y], None | Y, Awaitable[T] | T], 
+    /, 
+    running: SupportsBool = True, 
+) -> T:
+    send  = gen.send
+    throw = gen.throw
+    try:
+        r = send(None)
+        while running:
+            try:
+                v = await r
+            except BaseException as e:
+                r = throw(e)
+            else:
+                r = send(v)
+        raise AsyncCancelledError
+    except StopIteration as e:
+        v = e.value
+        if isawaitable(v):
+            v = await v
+        return v
+    finally:
+        gen.close()
+
+
+@overload
+def run_gen_step[T](
+    gen: Generator[Any, Any, T] | Callable[[], Generator[Any, Any, T]], 
+    /, 
+    async_: Literal[False] = False, 
+    running: SupportsBool = True, 
+) -> T:
+    ...
+@overload
+def run_gen_step[T](
+    gen: Generator[Awaitable, Any, Awaitable[T] | T] | Callable[[], Generator[Awaitable, Any, Awaitable[T] | T]], 
+    /, 
+    async_: Literal[True], 
+    running: SupportsBool = True, 
+) -> Awaitable[T]:
+    ...
+def run_gen_step(
+    gen, 
+    /, 
+    async_: Literal[False, True] = False, 
+    running: SupportsBool = True, 
+):
+    if not isinstance(gen, Generator):
+        gen = gen()
+    if async_:
+        return run_gen_step_async(gen, running)
+    else:
+        return run_gen_step_sync(gen, running)
+
+
+def run_gen_step_iter_sync(
+    gen: Generator, 
+    /, 
+    running: SupportsBool = True, 
+) -> Iterator:
+    send = gen.send
+    try:
+        v: Any = None
+        while running:
+            v = send(v)
+            if isinstance(v, Yield):
+                v = v.value
+                yield v
+            elif isinstance(v, YieldFrom):
+                v = yield from v.value
+        raise CancelledError
+    except StopIteration as e:
+        return e.value
+    finally:
+        gen.close()
+
+
+async def run_gen_step_iter_async(
+    gen: Generator, 
+    /, 
+    running: SupportsBool = True, 
+) -> AsyncIterator:
+    send  = gen.send
+    throw = gen.throw
+    try:
+        v = send(None)
+        while running:
+            try:
+                if isinstance(v, Yield):
+                    yield_type = 1
+                    v = v.value
+                elif isinstance(v, YieldFrom):
+                    yield_type = 2
+                    v = v.value
+                else:
+                    yield_type = 0
+                if isawaitable(v):
+                    v = await v
+                match yield_type:
+                    case 1:
+                        yield v
+                    case 2:
+                        if isinstance(v, AsyncIterable):
+                            async for e in v:
+                                yield e
+                        else:
+                            for e in v:
+                                yield e
+            except BaseException as e:
+                v = throw(e)
+            else:
+                v = send(v)
+    except StopIteration as e:
+        v = e.value
+        if isawaitable(v):
+            v = await v
+        #return v
+    finally:
+        gen.close()
+
+
+@overload
+def run_gen_step_iter(
+    gen: Generator | Callable[[], Generator], 
+    /, 
+    async_: Literal[False] = False, 
+    running: SupportsBool = True, 
+) -> Iterator:
+    ...
+@overload
+def run_gen_step_iter(
+    gen: Generator | Callable[[], Generator], 
+    /, 
+    async_: Literal[True], 
+    running: SupportsBool = True, 
+) -> AsyncIterator:
+    ...
+def run_gen_step_iter(
+    gen: Generator | Callable[[], Generator], 
+    /, 
+    async_: Literal[False, True] = False, 
+    running: SupportsBool = True, 
+) -> Iterator | AsyncIterator:
+    if not isinstance(gen, Generator):
+        gen = gen()
+    if async_:
+        return run_gen_step_iter_async(gen, running)
+    else:
+        return run_gen_step_iter_sync(gen, running)
+
+
+@optional
+def as_gen_step(
+    func: Callable[..., Generator], 
+    /, 
+    async_: None | bool = None, 
+    is_iter: bool = False, 
+):
+    has_async_arg = has_keyword_arg(func, "async_")
+    if is_iter:
+        run: Callable = run_gen_step_iter
+    else:
+        run = run_gen_step
+    def wrapper(*args, async_: None | bool = async_, **kwds):
+        if async_ is None:
+            async_ = in_async()
+        if has_async_arg:
+            kwds["async_"] = async_
+        return run(func(*args, **kwds), async_)
+    return wrapper
+
+
+@overload
+def with_iter_next[T](
+    iterable: Iterable[T], 
+    /, 
+) -> ContextManager[Callable[[], T]]:
+    ...
+@overload
+def with_iter_next[T](
+    iterable: AsyncIterable[T], 
+    /, 
+) -> ContextManager[Callable[[], Awaitable[T]]]:
+    ...
+@contextmanager
+def with_iter_next[T](
+    iterable: Iterable[T] | AsyncIterable[T], 
+    /, 
+):
+    """包装迭代器，以供 `run_gen_step` 和 `run_gen_step_iter` 使用
+
+    .. code:: python
+
+        if async_:
+            async def process():
+                async for e in iterable:
+                    do_what_you_want(e)
+            return process()
+        else:
+            for e in iterable:
+                do_what_you_want(e)
+
+    大概相当于
+
+    .. code:: python
+
+        def gen_step():
+            with with_iter_next(iterable) as do_next:
+                while True:
+                    e = yield do_next()
+                    do_what_you_want(e)
+
+        run_gen_step(gen_step, async_)
+    """
+    if isinstance(iterable, AsyncIterable):
+        try:
+            yield aiter(iterable).__anext__
+        except StopAsyncIteration:
+            pass
+    else:
+        try:
+            yield iter(iterable).__next__
+        except StopIteration:
+            pass
+
+
+@overload
+def split_cm[T](
+    cm: AbstractContextManager[T], 
+    /, 
+) -> tuple[Callable[[], T], Callable[[], Any]]:
+    ...
+@overload
+def split_cm[T](
+    cm: AbstractAsyncContextManager[T], 
+    /, 
+) -> tuple[Callable[[], Coroutine[Any, Any, T]], Callable[[], Coroutine]]:
+    ...
+def split_cm[T](
+    cm: AbstractContextManager[T] | AbstractAsyncContextManager[T], 
+    /, 
+) -> (
+    tuple[Callable[[], T], Callable[[], Any]] | 
+    tuple[Callable[[], Coroutine[Any, Any, T]], Callable[[], Coroutine]]
+):
+    """拆分上下文管理器，以供 `run_gen_step` 和 `run_gen_step_iter` 使用
+
+    .. code:: python
+
+        if async_:
+            async def process():
+                async with cm as obj:
+                    do_what_you_want(obj)
+            return process()
+        else:
+            with cm as obj:
+                do_what_you_want(obj)
+
+    大概相当于
+
+    .. code:: python
+
+        def gen_step():
+            enter, exit = split_cm(cm)
+            obj = yield enter()
+            try:
+                do_what_you_want(obj)
+            finally:
+                yield exit()
+
+        run_gen_step(gen_step, async_)
+    """
+    if isinstance(cm, AbstractAsyncContextManager):
+        enter: Callable = cm.__aenter__
+        exit: Callable  = cm.__aexit__
+    else:
+        enter = cm.__enter__
+        exit  = cm.__exit__
+    return enter, lambda: exit(*exc_info())
+

python_iterutils-0.2.10.1/iterutils/__init__.py → python_iterutils-0.3.0/iterutils/misc.py

@@ -1,38 +1,31 @@
 #!/usr/bin/env python3
 # encoding: utf-8
 
-__author__ = "ChenyangGao <https://chenyanggao.github.io>"
-__version__ = (0, 2, 10)
 __all__ = [
-    "Yield", "YieldFrom", "GenStep", "GenStepIter", "iterable", 
-    "async_iterable", "run_gen_step", "run_gen_step_iter", 
-    "as_gen_step", "as_gen_step_iter", "split_cm", "with_iter_next", 
-    "map", "filter", "reduce", "zip", "chain", "chain_from_iterable", 
-    "chunked", "foreach", "async_foreach", "through", "async_through", 
-    "flatten", "async_flatten", "collect", "async_collect", 
-    "group_collect", "async_group_collect", "iter_unique", 
+    "iterable", "async_iterable", "map", "filter", "reduce", "zip", 
+    "chain", "chain_from_iterable", "chunked", "foreach", "async_foreach", 
+    "through", "async_through", "flatten", "async_flatten", "collect", 
+    "async_collect", "group_collect", "async_group_collect", "iter_unique", 
     "async_iter_unique", "wrap_iter", "wrap_aiter", "peek_iter", "peek_aiter", 
-    "acc_step", "cut_iter", "bfs_gen", "context", "backgroud_loop", 
+    "acc_step", "cut_iter", "context", "backgroud_loop", "gen_startup", 
+    "async_gen_startup", "do_iter", "do_aiter", "bfs_iter", "bfs_gen", 
 ]
 
 from asyncio import create_task, sleep as async_sleep
 from builtins import map as _map, filter as _filter, zip as _zip
 from collections import defaultdict, deque
 from collections.abc import (
-    AsyncIterable, AsyncIterator, Awaitable, Buffer, Callable, 
-    Collection, Container, Coroutine, Generator, Iterable, Iterator, 
-    Mapping, MutableMapping, MutableSet, MutableSequence, Sequence, 
-    ValuesView, 
-)
-from contextlib import (
-    asynccontextmanager, contextmanager, ExitStack, AsyncExitStack, 
-    AbstractContextManager, AbstractAsyncContextManager, 
+    AsyncGenerator, AsyncIterable, AsyncIterator, Awaitable, Buffer,
+    Callable, Collection, Container, Coroutine, Generator, Iterable, 
+    Iterator, Mapping, MutableMapping, MutableSet, MutableSequence, 
+    Sequence, ValuesView, 
 )
+from contextlib import asynccontextmanager, contextmanager, ExitStack, AsyncExitStack
 from copy import copy
-from dataclasses import dataclass
+from functools import update_wrapper
 from itertools import batched, chain as _chain, pairwise
-from inspect import iscoroutinefunction, signature
-from sys import _getframe, exc_info
+from inspect import iscoroutinefunction
+from sys import _getframe
 from _thread import start_new_thread
 from time import sleep, time
 from types import FrameType
@@ -48,36 +41,6 @@ from texttools import format_time
 from undefined import undefined
 
 
-@dataclass(slots=True, frozen=True, unsafe_hash=True)
-class Yield:
-    """专供 `run_gen_step_iter`，说明值需要 yield 给用户
-    """
-    value: Any
-
-
-@dataclass(slots=True, frozen=True, unsafe_hash=True)
-class YieldFrom:
-    """专供 `run_gen_step_iter`，说明值需要解包后逐个 yield 给用户
-    """
-    value: Any
-
-
-@dataclass(slots=True, frozen=True, unsafe_hash=True)
-class GenStep:
-    """专供 `run_gen_step` 和 `run_gen_step_iter`，说明值需要进一步提取
-    """
-    value: Generator
-    max_depth: int = 0
-
-
-@dataclass(slots=True, frozen=True, unsafe_hash=True)
-class GenStepIter:
-    """专供 `run_gen_step_iter`，说明值需要进一步提取
-    """
-    value: Generator
-    max_depth: int = 0
-
-
 iterable = Iterable.__instancecheck__
 async_iterable = AsyncIterable.__instancecheck__
 isawaitable = Awaitable.__instancecheck__
@@ -106,406 +69,6 @@ def _get_async[T](back: int = 2, /, *, default: Literal[False] | T = False) -> b
     return _coalesce(iter_frams(), default)
 
 
-def _run_gen_step(
-    gen: Generator, 
-    /, 
-    drive_generator: int = 0, 
-):
-    send  = gen.send
-    throw = gen.throw
-    dgen  = drive_generator if drive_generator < 0 else drive_generator - 1
-    try:
-        value: Any = send(None)
-        while True:
-            try:
-                if isinstance(value, GenStep):
-                    value = _run_gen_step(value.value, value.max_depth)
-                elif drive_generator and isinstance(value, Generator):
-                    value = _run_gen_step(value, dgen)
-            except BaseException as e:
-                value = throw(e)
-            else:
-                value = send(value)
-    except StopIteration as e:
-        value = e.value
-        if isinstance(value, GenStep):
-            value = _run_gen_step(value.value, value.max_depth)
-        elif drive_generator and isinstance(value, Generator):
-            value = _run_gen_step(value, dgen)
-        return value
-    finally:
-        gen.close()
-
-
-async def _run_gen_step_async(
-    gen: Generator, 
-    /, 
-    drive_generator: int = 0, 
-):
-    send  = gen.send
-    throw = gen.throw
-    dgen = drive_generator if drive_generator < 0 else drive_generator - 1
-    try:
-        value: Any = send(None)
-        while True:
-            try:
-                if isawaitable(value):
-                    value = await value
-                elif isinstance(value, GenStep):
-                    value = await _run_gen_step_async(value.value, value.max_depth)
-                elif drive_generator and isinstance(value, Generator):
-                    value = await _run_gen_step_async(value, dgen)
-            except BaseException as e:
-                value = throw(e)
-            else:
-                value = send(value)
-    except StopIteration as e:
-        value = e.value
-        if isawaitable(value):
-            value = await value
-        elif isinstance(value, GenStep):
-            value = await _run_gen_step_async(value.value, value.max_depth)
-        elif drive_generator and isinstance(value, Generator):
-            value = await _run_gen_step_async(value, dgen)
-        return value
-    finally:
-        gen.close()
-
-
-def run_gen_step[**Args](
-    gen_step: Generator | Callable[Args, Generator], 
-    async_: None | Literal[False, True] = None, 
-    /, 
-    *args: Args.args, 
-    **kwds: Args.kwargs, 
-):
-    """驱动生成器运行，并返回其结果
-    """
-    if async_ is None:
-        async_ = _get_async()
-    if not isinstance(gen_step, Generator):
-        params = signature(gen_step).parameters
-        if ((param := params.get("async_")) and 
-            (param.kind in (param.POSITIONAL_OR_KEYWORD, param.KEYWORD_ONLY))
-        ):
-            kwds.setdefault("async_", async_)
-        gen_step = gen_step(*args, **kwds)
-    if async_:
-        return _run_gen_step_async(gen_step)
-    else:
-        return _run_gen_step(gen_step)
-
-
-def _run_gen_step_iter(
-    gen: Generator, 
-    /, 
-    drive_generator: int = 0, 
-) -> Iterator:
-    send  = gen.send
-    throw = gen.throw
-    dgen  = drive_generator if drive_generator < 0 else drive_generator - 1
-    try:
-        value: Any = send(None)
-        while True:
-            try:
-                val_type = type(value)
-                if issubclass(val_type, (Yield, YieldFrom)):
-                    value = value.value
-                if isinstance(value, GenStepIter):
-                    yield from _run_gen_step_iter(value.value, value.max_depth)
-                else:
-                    if isinstance(value, GenStep):
-                        value = _run_gen_step(value.value, value.max_depth)
-                    elif drive_generator and isinstance(value, Generator):
-                        value = _run_gen_step(value, dgen)
-                    if val_type is Yield:
-                        yield value
-                    elif val_type is YieldFrom:
-                        yield from value
-            except BaseException as e:
-                value = throw(e)
-            else:
-                value = send(value)
-    except StopIteration as e:
-        value = e.value
-        val_type = type(value)
-        if issubclass(val_type, (Yield, YieldFrom)):
-            value = value.value
-        elif isinstance(value, GenStepIter):
-            yield from _run_gen_step_iter(value.value, value.max_depth)
-        elif isinstance(value, GenStep):
-            value = _run_gen_step(value.value, value.max_depth)
-        elif drive_generator and isinstance(value, Generator):
-            value = _run_gen_step(value, dgen)
-        if val_type is Yield:
-            yield value
-        elif val_type is YieldFrom:
-            yield from value
-    finally:
-        gen.close()
-
-
-async def _run_gen_step_async_iter(
-    gen: Generator, 
-    /, 
-    drive_generator: int = 0, 
-) -> AsyncIterator:
-    send  = gen.send
-    throw = gen.throw
-    dgen = drive_generator if drive_generator < 0 else drive_generator - 1
-    try:
-        value: Any = send(None)
-        while True:
-            try:
-                val_type = type(value)
-                if issubclass(val_type, (Yield, YieldFrom)):
-                    value = value.value
-                if isawaitable(value):
-                    value = await value
-                elif isinstance(value, GenStepIter):
-                    async for el in _run_gen_step_async_iter(value.value, value.max_depth):
-                        yield el
-                elif isinstance(value, GenStep):
-                    value = await _run_gen_step_async(value.value, value.max_depth)
-                elif drive_generator and isinstance(value, Generator):
-                    value = await _run_gen_step_async(value, dgen)
-                if val_type is Yield:
-                    yield value
-                elif val_type is YieldFrom:
-                    if isinstance(value, AsyncIterable):
-                        async for el in value:
-                            yield el
-                    else:
-                        for el in value:
-                            yield el
-            except BaseException as e:
-                value = throw(e)
-            else:
-                value = send(value)
-    except StopIteration as e:
-        value = e.value
-        val_type = type(value)
-        if issubclass(val_type, (Yield, YieldFrom)):
-            value = value.value
-        if isawaitable(value):
-            value = await value
-        if isinstance(value, GenStepIter):
-            async for el in _run_gen_step_async_iter(value.value, value.max_depth):
-                yield el
-        else:
-            if isinstance(value, GenStep):
-                value = await _run_gen_step_async(value.value, value.max_depth)
-            elif drive_generator and isinstance(value, Generator):
-                value = await _run_gen_step_async(value, dgen)
-            if val_type is Yield:
-                yield value
-            elif val_type is YieldFrom:
-                if isinstance(value, AsyncIterable):
-                    async for el in value:
-                        yield el
-                else:
-                    for el in value:
-                        yield el
-    finally:
-        gen.close()
-
-
-@overload
-def run_gen_step_iter[**Args](
-    gen_step: Generator | Callable[Args, Generator], 
-    async_: None = None, 
-    /, 
-    *args: Args.args, 
-    **kwds: Args.kwargs, 
-) -> Iterator | AsyncIterator:
-    ...
-@overload
-def run_gen_step_iter[**Args](
-    gen_step: Generator | Callable[Args, Generator], 
-    async_: Literal[False] = False, 
-    /, 
-    *args: Args.args, 
-    **kwds: Args.kwargs, 
-) -> Iterator:
-    ...
-@overload
-def run_gen_step_iter[**Args](
-    gen_step: Generator | Callable[Args, Generator], 
-    async_: Literal[True], 
-    /, 
-    *args: Args.args, 
-    **kwds: Args.kwargs, 
-) -> AsyncIterator:
-    ...
-def run_gen_step_iter[**Args](
-    gen_step: Generator | Callable[Args, Generator], 
-    async_: None | Literal[False, True] = None, 
-    /, 
-    *args: Args.args, 
-    **kwds: Args.kwargs, 
-) -> Iterator | AsyncIterator:
-    """驱动生成器运行，并从中返回可迭代而出的值
-    """
-    if async_ is None:
-        async_ = _get_async()
-    if not isinstance(gen_step, Generator):
-        params = signature(gen_step).parameters
-        if ((param := params.get("async_")) and 
-            (param.kind in (param.POSITIONAL_OR_KEYWORD, param.KEYWORD_ONLY))
-        ):
-            kwds.setdefault("async_", async_)
-        gen_step = gen_step(*args, **kwds)
-    if async_:
-        return _run_gen_step_async_iter(gen_step)
-    else:
-        return _run_gen_step_iter(gen_step)
-
-
-def as_gen_step[**Args](
-    gen_step: Callable[Args, Generator], 
-    /, 
-) -> Callable[Args, Any]:
-    default_async = _get_async(default=None)
-    def wrapper(*args: Args.args, **kwds: Args.kwargs):
-        return run_gen_step(
-            gen_step, 
-            _coalesce((
-                kwds.pop("async_", None), 
-                _get_async(default=default_async), 
-            )), 
-            *args, 
-            **kwds, 
-        )
-    return wrapper
-
-
-def as_gen_step_iter[**Args](
-    gen_step: Callable[Args, Generator], 
-    /, 
-) -> Callable[Args, Iterable | AsyncIterable]:
-    default_async = _get_async(default=None)
-    def wrapper(*args: Args.args, **kwds: Args.kwargs):
-        return run_gen_step_iter(
-            gen_step, 
-            _coalesce((
-                kwds.pop("async_", None), 
-                _get_async(default=default_async), 
-            )), 
-            *args, 
-            **kwds, 
-        )
-    return wrapper
-
-
-@overload
-def split_cm[T](
-    cm: AbstractContextManager[T], 
-    /, 
-) -> tuple[Callable[[], T], Callable[[], Any]]:
-    ...
-@overload
-def split_cm[T](
-    cm: AbstractAsyncContextManager[T], 
-    /, 
-) -> tuple[Callable[[], Coroutine[Any, Any, T]], Callable[[], Coroutine]]:
-    ...
-def split_cm[T](
-    cm: AbstractContextManager[T] | AbstractAsyncContextManager[T], 
-    /, 
-) -> (
-    tuple[Callable[[], T], Callable[[], Any]] | 
-    tuple[Callable[[], Coroutine[Any, Any, T]], Callable[[], Coroutine]]
-):
-    """拆分上下文管理器，以供 `run_gen_step` 和 `run_gen_step_iter` 使用
-
-    .. code:: python
-
-        if async_:
-            async def process():
-                async with cm as obj:
-                    do_what_you_want()
-            return process()
-        else:
-            with cm as obj:
-                do_what_you_want()
-
-    大概相当于
-
-    .. code:: python
-
-        def gen_step():
-            enter, exit = split_cm(cm)
-            obj = yield enter()
-            try:
-                do_what_you_want()
-            finally:
-                yield exit()
-
-        run_gen_step(gen_step, async_)
-    """
-    if isinstance(cm, AbstractAsyncContextManager):
-        enter: Callable = cm.__aenter__
-        exit: Callable  = cm.__aexit__
-    else:
-        enter = cm.__enter__
-        exit  = cm.__exit__
-    return enter, lambda: exit(*exc_info())
-
-
-@overload
-def with_iter_next[T](
-    iterable: Iterable[T], 
-    /, 
-) -> ContextManager[Callable[[], T]]:
-    ...
-@overload
-def with_iter_next[T](
-    iterable: AsyncIterable[T], 
-    /, 
-) -> ContextManager[Callable[[], Awaitable[T]]]:
-    ...
-@contextmanager
-def with_iter_next[T](
-    iterable: Iterable[T] | AsyncIterable[T], 
-    /, 
-):
-    """包装迭代器，以供 `run_gen_step` 和 `run_gen_step_iter` 使用
-
-    .. code:: python
-
-        if async_:
-            async def process():
-                async for e in iterable:
-                    do_what_you_want()
-            return process()
-        else:
-            for e in iterable:
-                do_what_you_want()
-
-    大概相当于
-
-    .. code:: python
-
-        def gen_step():
-            with with_iter_next(iterable) as do_next:
-                while True:
-                    e = yield do_next()
-                    do_what_you_want()
-
-        run_gen_step(gen_step, async_)
-    """
-    if isinstance(iterable, AsyncIterable):
-        try:
-            yield aiter(iterable).__anext__
-        except StopAsyncIteration:
-            pass
-    else:
-        try:
-            yield iter(iterable).__next__
-        except StopIteration:
-            pass
-
-
 def map(
     function: None | Callable, 
     iterable: Iterable | AsyncIterable, 
@@ -631,14 +194,40 @@ def chain_from_iterable[T](
     ...
 @overload
 def chain_from_iterable[T](
-    iterables: Iterable[Iterable[T] | AsyncIterable[T]] | AsyncIterable[Iterable[T] | AsyncIterable[T]], 
+    iterables: (
+        AsyncIterable[Iterable[T]] | 
+        AsyncIterable[AsyncIterable[T]] | 
+        AsyncIterable[Iterable[T] | AsyncIterable[T]]
+    ), 
+    threaded: bool = False, 
+    *, 
+    async_: bool = False, 
+) -> AsyncIterator[T]:
+    ...
+@overload
+def chain_from_iterable[T](
+    iterables: (
+        Iterable[Iterable[T]] | 
+        Iterable[AsyncIterable[T]] | 
+        Iterable[Iterable[T] | AsyncIterable[T]] | 
+        AsyncIterable[Iterable[T]] | 
+        AsyncIterable[AsyncIterable[T]] | 
+        AsyncIterable[Iterable[T] | AsyncIterable[T]]
+    ), 
     threaded: bool = False, 
     *, 
     async_: Literal[True], 
 ) -> AsyncIterator[T]:
     ...
 def chain_from_iterable[T](
-    iterables: Iterable[Iterable[T]] | Iterable[Iterable[T] | AsyncIterable[T]] | AsyncIterable[Iterable[T] | AsyncIterable[T]], 
+    iterables: (
+        Iterable[Iterable[T]] | 
+        Iterable[AsyncIterable[T]] | 
+        Iterable[Iterable[T] | AsyncIterable[T]] | 
+        AsyncIterable[Iterable[T]] | 
+        AsyncIterable[AsyncIterable[T]] | 
+        AsyncIterable[Iterable[T] | AsyncIterable[T]]
+    ), 
     threaded: bool = False, 
     *, 
     async_: Literal[False, True] = False, 
@@ -1264,48 +853,6 @@ def cut_iter(
         yield stop, stop - start
 
 
-@overload
-def bfs_gen[T](
-    initial: T, 
-    /, 
-    unpack_iterator: Literal[False] = False, 
-) -> Generator[T, T | None, None]:
-    ...
-@overload
-def bfs_gen[T](
-    initial: T | Iterator[T], 
-    /, 
-    unpack_iterator: Literal[True], 
-) -> Generator[T, T | None, None]:
-    ...
-def bfs_gen[T](
-    initial: T | Iterator[T], 
-    /, 
-    unpack_iterator: bool = False, 
-) -> Generator[T, T | None, None]:
-    """辅助函数，返回生成器，用来简化广度优先遍历
-    """
-    dq: deque[T] = deque()
-    push, pushmany, pop = dq.append, dq.extend, dq.popleft
-    if isinstance(initial, Iterator) and unpack_iterator:
-        pushmany(initial)
-    else:
-        push(initial) # type: ignore
-    while dq:
-        args: None | T = yield (val := pop())
-        if unpack_iterator:
-            while args is not None:
-                if isinstance(args, Iterator):
-                    pushmany(args)
-                else:
-                    push(args)
-                args = yield val
-        else:
-            while args is not None:
-                push(args)
-                args = yield val
-
-
 @overload
 def context[T](
     func: Callable[..., T], 
@@ -1445,3 +992,71 @@ def backgroud_loop(
                     print("\r\x1b[K", end="")
         return ctx()
 
+
+def gen_startup[**Args, G: Generator](func: Callable[Args, G], /):
+    def wrapper(*args: Args.args, **kwds: Args.kwargs) -> G:
+        gen = func(*args, **kwds)
+        next(gen)
+        return gen
+    return update_wrapper(wrapper, func)
+
+
+def async_gen_startup[**Args, G: AsyncGenerator](func: Callable[Args, G], /):
+    async def wrapper(*args: Args.args, **kwds: Args.kwargs) -> G:
+        gen = func(*args, **kwds)
+        await anext(gen)
+        return gen
+    return update_wrapper(wrapper, func)
+
+
+def do_iter[T](
+    func: Callable[[], T] | Iterable[T], 
+    /, 
+    sentinel=undefined, 
+    sentinel_excs: type[BaseException] | tuple[type[BaseException], ...] = (), 
+) -> Iterator[T]:
+    try:
+        yield from iter(func if callable(func) else iter(func).__next__, sentinel)
+    except sentinel_excs:
+        pass
+
+
+async def do_aiter[T](
+    func: Callable[[], T] | Callable[[], Awaitable[T]] | Iterable[T] | AsyncIterable[T],  
+    /, 
+    sentinel=undefined, 
+    sentinel_excs: type[BaseException] | tuple[type[BaseException], ...] = (), 
+) -> AsyncIterator[T]:
+    if callable(func):
+        func = ensure_async(func)
+    else:
+        func = ensure_aiter(func).__anext__
+    try:
+        while True:
+            v = await func()
+            if v is sentinel:
+                break
+            yield v
+    except StopAsyncIteration:
+        pass
+    except sentinel_excs:
+        pass
+
+
+def bfs_iter[T](*initials: T) -> tuple[Iterator[T], Callable[[T], None]]:
+    dq = deque(initials)
+    return do_iter(dq.popleft, sentinel_excs=IndexError), dq.append
+
+
+@gen_startup
+def bfs_gen[T](*initials) -> Generator[None | T, T | None, None]:
+    dq = deque(initials)
+    push, pop = dq.append, dq.popleft
+    try:
+        p = yield None
+        while True:
+            p = yield (pop() if p is None else push(p))
+    except IndexError:
+        pass
+
+# TODO: 这个模块添加了很多不必要的函数，需要进行移除

{python_iterutils-0.2.10.1 → python_iterutils-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-iterutils"
-version = "0.2.10.1"
+version = "0.3.0"
 description = "Python another itertools."
 authors = ["ChenyangGao <wosiwujm@gmail.com>"]
 license = "MIT"
@@ -27,9 +27,9 @@ include = [
 
 [tool.poetry.dependencies]
 python = "^3.12"
-python-asynctools = ">=0.1.3.4"
-python-texttools = ">=0.0.3"
-python-undefined = ">=0.0.3"
+python-asynctools = ">=0.1.4"
+python-texttools = ">=0.0.6"
+python-undefined = ">=0.0.4"
 
 [build-system]
 requires = ["poetry-core"]