omlish 0.0.0.dev195__py3-none-any.whl → 0.0.0.dev197__py3-none-any.whl

omlish/io/{generators → coro}/stepped.py

@@ -4,8 +4,8 @@ from ... import check
 from ... import lang
 from ..buffers import ReadableListBuffer
 from .consts import DEFAULT_BUFFER_SIZE
-from .direct import BytesDirectGenerator
-from .direct import StrDirectGenerator
+from .direct import BytesDirectCoro
+from .direct import StrDirectCoro
 
 
 T = ta.TypeVar('T')
@@ -18,44 +18,44 @@ OF = ta.TypeVar('OF')
 OT = ta.TypeVar('OT')
 
 
-# Stepped generators accept a non-None input, then in response yield zero or more non-None outputs, until yielding None
-# to signal they need more input again.
-SteppedGenerator: ta.TypeAlias = ta.Generator[O | None, I | None, R]
+# Stepped coros accept a non-None input, then in response yield zero or more non-None outputs, until yielding None to
+# signal they need more input again.
+SteppedCoro: ta.TypeAlias = ta.Generator[O | None, I | None, R]
 
 # Conventionally, these are sent and themselves yield an empty value to signify termination.
-BytesSteppedGenerator: ta.TypeAlias = SteppedGenerator[bytes, bytes, R]
-StrSteppedGenerator: ta.TypeAlias = SteppedGenerator[str, str, R]
+BytesSteppedCoro: ta.TypeAlias = SteppedCoro[bytes, bytes, R]
+StrSteppedCoro: ta.TypeAlias = SteppedCoro[str, str, R]
 
-BytesToStrSteppedGenerator: ta.TypeAlias = SteppedGenerator[str, bytes, R]
-StrToBytesSteppedGenerator: ta.TypeAlias = SteppedGenerator[bytes, str, R]
+BytesToStrSteppedCoro: ta.TypeAlias = SteppedCoro[str, bytes, R]
+StrToBytesSteppedCoro: ta.TypeAlias = SteppedCoro[bytes, str, R]
 
 
 # Stepped reader generators emit either an int or None to request input, or emit some other kind of output.
-SteppedReaderGenerator: ta.TypeAlias = ta.Generator[int | None | O, I | None, R]
+SteppedReaderCoro: ta.TypeAlias = ta.Generator[int | None | O, I | None, R]
 
-BytesSteppedReaderGenerator: ta.TypeAlias = SteppedReaderGenerator[bytes, bytes, R]
-StrSteppedReaderGenerator: ta.TypeAlias = SteppedReaderGenerator[str, str, R]
+BytesSteppedReaderCoro: ta.TypeAlias = SteppedReaderCoro[bytes, bytes, R]
+StrSteppedReaderCoro: ta.TypeAlias = SteppedReaderCoro[str, str, R]
 
 
 ##
 
 
 @lang.autostart
-def flatmap_stepped_generator(
+def flatmap_stepped_coro(
         fn: ta.Callable[[list[OF]], OT],
-        g: SteppedGenerator[OF, I, R],
+        g: SteppedCoro[OF, I, R],
         *,
         terminate: ta.Callable[[OF], bool] | None = None,
 ) -> ta.Generator[OT, I, lang.Maybe[R]]:
     """
-    Given a stepped generator and a function taking a list, returns a direct (1:1) generator which accepts input, builds
-    a list of yielded generator output, calls the given function with that list, and yields the result.
+    Given a stepped coro and a function taking a list, returns a direct (1:1) coro which accepts input, builds a list of
+    yielded coro output, calls the given function with that list, and yields the result.
 
     An optional terminate function may be provided which will cause this function to return early if it returns true for
     an encountered yielded value. The encountered value causing termination will be included in the list sent to the
     given fn.
 
-    Returns a Maybe of either the given generator's return value or empty if the terminator was encountered.
+    Returns a Maybe of either the given coro's return value or empty if the terminator was encountered.
     """
 
     l: list[OF]
@@ -110,37 +110,37 @@ def _is_empty(o: T) -> bool:
     return len(o) < 1  # type: ignore
 
 
-def joined_bytes_stepped_generator(g: BytesSteppedGenerator[R]) -> BytesDirectGenerator[R]:
-    return flatmap_stepped_generator(_join_bytes, g, terminate=_is_empty)
+def joined_bytes_stepped_coro(g: BytesSteppedCoro[R]) -> BytesDirectCoro[R]:
+    return flatmap_stepped_coro(_join_bytes, g, terminate=_is_empty)
 
 
-def joined_str_stepped_generator(g: StrSteppedGenerator[R]) -> StrDirectGenerator[R]:
-    return flatmap_stepped_generator(_join_str, g, terminate=_is_empty)
+def joined_str_stepped_coro(g: StrSteppedCoro[R]) -> StrDirectCoro[R]:
+    return flatmap_stepped_coro(_join_str, g, terminate=_is_empty)
 
 
 ##
 
 
-def read_into_bytes_stepped_generator(
-        g: BytesSteppedGenerator,
+def read_into_bytes_stepped_coro(
+        g: BytesSteppedCoro,
         f: ta.IO,
         *,
         read_size: int = DEFAULT_BUFFER_SIZE,
 ) -> ta.Iterator[bytes]:
     yield from lang.genmap(  # type: ignore[misc]
-        joined_bytes_stepped_generator(g),
+        joined_bytes_stepped_coro(g),
         lang.readiter(f, read_size),
     )
 
 
-def read_into_str_stepped_generator(
-        g: StrSteppedGenerator,
+def read_into_str_stepped_coro(
+        g: StrSteppedCoro,
         f: ta.TextIO,
         *,
         read_size: int = DEFAULT_BUFFER_SIZE,
 ) -> ta.Iterator[str]:
     yield from lang.genmap(
-        joined_str_stepped_generator(g),
+        joined_str_stepped_coro(g),
         lang.readiter(f, read_size),
     )
 
@@ -149,7 +149,7 @@ def read_into_str_stepped_generator(
 
 
 @lang.autostart
-def buffer_bytes_stepped_reader_generator(g: BytesSteppedReaderGenerator) -> BytesSteppedGenerator:
+def buffer_bytes_stepped_reader_coro(g: BytesSteppedReaderCoro) -> BytesSteppedCoro:
     i: bytes | None
     o = g.send(None)
     rlb = ReadableListBuffer()

omlish/multiprocessing/__init__.py

@@ -0,0 +1,32 @@
+# ruff: noqa: I001
+import typing as _ta
+
+from .. import lang as _lang
+
+
+from .death import (  # noqa
+    BaseDeathpact,
+    Deathpact,
+    NopDeathpact,
+    PipeDeathpact,
+)
+
+from .proxies import (  # noqa
+    DummyValueProxy,
+    ValueProxy,
+)
+
+if _ta.TYPE_CHECKING:
+    from .spawn import (  # noqa
+        ExtrasSpawnContext,
+        ExtrasSpawnPosixPopen,
+        ExtrasSpawnProcess,
+        SpawnExtras,
+    )
+else:
+    _lang.proxy_init(globals(), '.spawn', [
+        'ExtrasSpawnContext',
+        'ExtrasSpawnPosixPopen',
+        'ExtrasSpawnProcess',
+        'SpawnExtras',
+    ])

omlish/{multiprocessing.py → multiprocessing/death.py}

@@ -1,96 +1,11 @@
 import abc
-import dataclasses as dc
-import multiprocessing as mp
-import multiprocessing.popen_spawn_posix
 import os
 import signal
 import sys
 import time
 import typing as ta
 
-from . import check
-from . import lang
-from . import libc
-
-
-T = ta.TypeVar('T')
-
-
-##
-
-
-@ta.runtime_checkable
-class ValueProxy(ta.Protocol[T]):
-    # value = property(get, set)
-
-    def get(self) -> T:
-        ...
-
-    def set(self, value: T) -> None:
-        ...
-
-
-@dc.dataclass()
-@lang.protocol_check(ValueProxy)
-class DummyValueProxy(ValueProxy[T]):
-    value: T
-
-    def get(self) -> T:
-        return self.value
-
-    def set(self, value: T) -> None:
-        self.value = value
-
-
-##
-
-
-@dc.dataclass(frozen=True, kw_only=True)
-class SpawnExtras:
-    pass_fds: ta.AbstractSet[int] | None = None
-    deathsig: int | None = None
-
-
-class ExtrasSpawnPosixPopen(mp.popen_spawn_posix.Popen):
-    def __init__(self, process_obj: 'ExtrasSpawnProcess', *, extras: SpawnExtras) -> None:
-        self.__extras = extras
-        self.__pass_fds = extras.pass_fds
-        super().__init__(process_obj)
-
-    def _launch(self, process_obj: 'ExtrasSpawnProcess') -> None:
-        if self.__pass_fds:
-            for fd in self.__pass_fds:
-                self.duplicate_for_child(fd)
-            self._extra_fds = None
-
-        super()._launch(process_obj)  # type: ignore  # noqa
-
-
-class ExtrasSpawnProcess(mp.context.SpawnProcess):
-    def __init__(self, *args: ta.Any, extras: SpawnExtras, **kwargs: ta.Any) -> None:
-        self.__extras = extras
-        super().__init__(*args, **kwargs)
-
-    def _Popen(self, process_obj: 'ExtrasSpawnProcess') -> ExtrasSpawnPosixPopen:  # type: ignore  # noqa
-        return ExtrasSpawnPosixPopen(
-            check.isinstance(process_obj, ExtrasSpawnProcess),
-            extras=self.__extras,
-        )
-
-    def run(self) -> None:
-        if self.__extras.deathsig is not None and sys.platform == 'linux':
-            libc.prctl(libc.PR_SET_PDEATHSIG, self.__extras.deathsig, 0, 0, 0, 0)
-
-        super().run()
-
-
-class ExtrasSpawnContext(mp.context.SpawnContext):
-    def __init__(self, extras: SpawnExtras = SpawnExtras()) -> None:
-        self.__extras = extras
-        super().__init__()
-
-    def Process(self, *args: ta.Any, **kwargs: ta.Any):  # type: ignore  # noqa
-        return ExtrasSpawnProcess(*args, extras=self.__extras, **kwargs)
+from .. import check
 
 
 ##
@@ -107,7 +22,7 @@ class NopDeathpact(Deathpact):
         pass
 
 
-#
+##
 
 
 class BaseDeathpact(Deathpact, abc.ABC):
@@ -163,7 +78,7 @@ class BaseDeathpact(Deathpact, abc.ABC):
             self._last_check_t = time.monotonic()
 
 
-#
+##
 
 
 class PipeDeathpact(BaseDeathpact):

omlish/multiprocessing/proxies.py

@@ -0,0 +1,30 @@
+import dataclasses as dc
+import typing as ta
+
+from .. import lang
+
+
+T = ta.TypeVar('T')
+
+
+@ta.runtime_checkable
+class ValueProxy(ta.Protocol[T]):
+    # value = property(get, set)
+
+    def get(self) -> T:
+        ...
+
+    def set(self, value: T) -> None:
+        ...
+
+
+@dc.dataclass()
+@lang.protocol_check(ValueProxy)
+class DummyValueProxy(ValueProxy[T]):
+    value: T
+
+    def get(self) -> T:
+        return self.value
+
+    def set(self, value: T) -> None:
+        self.value = value

omlish/multiprocessing/spawn.py

@@ -0,0 +1,59 @@
+import dataclasses as dc
+import multiprocessing as mp
+import multiprocessing.popen_spawn_posix
+import sys
+import typing as ta
+
+from .. import check
+from .. import libc
+
+
+T = ta.TypeVar('T')
+
+
+@dc.dataclass(frozen=True, kw_only=True)
+class SpawnExtras:
+    pass_fds: ta.AbstractSet[int] | None = None
+    deathsig: int | None = None
+
+
+class ExtrasSpawnPosixPopen(mp.popen_spawn_posix.Popen):
+    def __init__(self, process_obj: 'ExtrasSpawnProcess', *, extras: SpawnExtras) -> None:
+        self.__extras = extras
+        self.__pass_fds = extras.pass_fds
+        super().__init__(process_obj)
+
+    def _launch(self, process_obj: 'ExtrasSpawnProcess') -> None:
+        if self.__pass_fds:
+            for fd in self.__pass_fds:
+                self.duplicate_for_child(fd)
+            self._extra_fds = None
+
+        super()._launch(process_obj)  # type: ignore  # noqa
+
+
+class ExtrasSpawnProcess(mp.context.SpawnProcess):
+    def __init__(self, *args: ta.Any, extras: SpawnExtras, **kwargs: ta.Any) -> None:
+        self.__extras = extras
+        super().__init__(*args, **kwargs)
+
+    def _Popen(self, process_obj: 'ExtrasSpawnProcess') -> ExtrasSpawnPosixPopen:  # type: ignore  # noqa
+        return ExtrasSpawnPosixPopen(
+            check.isinstance(process_obj, ExtrasSpawnProcess),
+            extras=self.__extras,
+        )
+
+    def run(self) -> None:
+        if self.__extras.deathsig is not None and sys.platform == 'linux':
+            libc.prctl(libc.PR_SET_PDEATHSIG, self.__extras.deathsig, 0, 0, 0, 0)
+
+        super().run()
+
+
+class ExtrasSpawnContext(mp.context.SpawnContext):
+    def __init__(self, extras: SpawnExtras = SpawnExtras()) -> None:
+        self.__extras = extras
+        super().__init__()
+
+    def Process(self, *args: ta.Any, **kwargs: ta.Any):  # type: ignore  # noqa
+        return ExtrasSpawnProcess(*args, extras=self.__extras, **kwargs)

omlish/os/atomics.py

@@ -6,8 +6,8 @@ import shutil
 import tempfile
 import typing as ta
 
-from omlish.lite.check import check
-from omlish.lite.strings import attr_repr
+from ..lite.check import check
+from ..lite.strings import attr_repr
 
 
 AtomicPathSwapKind = ta.Literal['dir', 'file']

omlish/outcome.py

@@ -0,0 +1,250 @@
+# https://github.com/python-trio/outcome/tree/6a3192f306ead4900a33fa8c47e5af5430e37692
+#
+# The MIT License (MIT)
+#
+# 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.
+import abc
+import dataclasses as dc
+import typing as ta
+
+from . import check
+
+
+ValueT_co = ta.TypeVar('ValueT_co', covariant=True)
+ResultT = ta.TypeVar('ResultT')
+ArgsT = ta.ParamSpec('ArgsT')
+
+
+##
+
+
+class AlreadyUsedError(RuntimeError):
+    """An Outcome can only be unwrapped once."""
+
+
+def _remove_tb_frames(exc: BaseException, n: int) -> BaseException:
+    tb: ta.Any = exc.__traceback__
+    for _ in range(n):
+        check.not_none(tb)
+        tb = tb.tb_next
+    return exc.with_traceback(tb)
+
+
+##
+
+
+@ta.overload
+def capture(
+        sync_fn: ta.Callable[ArgsT, ta.NoReturn],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> 'Error':
+    ...
+
+
+@ta.overload
+def capture(
+        sync_fn: ta.Callable[ArgsT, ResultT],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> ta.Union['Value[ResultT]', 'Error']:
+    ...
+
+
+def capture(
+        sync_fn: ta.Callable[ArgsT, ResultT],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> ta.Union['Value[ResultT]', 'Error']:
+    """
+    Run ``sync_fn(*args, **kwargs)`` and capture the result.
+
+    Returns:
+      Either a :class:`Value` or :class:`Error` as appropriate.
+    """
+
+    try:
+        return Value(sync_fn(*args, **kwargs))
+
+    except BaseException as exc:  # noqa
+        exc = _remove_tb_frames(exc, 1)
+        return Error(exc)
+
+
+#
+
+
+@ta.overload
+async def acapture(
+        async_fn: ta.Callable[ArgsT, ta.Awaitable[ta.NoReturn]],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> 'Error':
+    ...
+
+
+@ta.overload
+async def acapture(
+        async_fn: ta.Callable[ArgsT, ta.Awaitable[ResultT]],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> ta.Union['Value[ResultT]', 'Error']:
+    ...
+
+
+async def acapture(
+        async_fn: ta.Callable[ArgsT, ta.Awaitable[ResultT]],
+        *args: ArgsT.args,
+        **kwargs: ArgsT.kwargs,
+) -> ta.Union['Value[ResultT]', 'Error']:
+    """
+    Run ``await async_fn(*args, **kwargs)`` and capture the result.
+
+    Returns:
+      Either a :class:`Value` or :class:`Error` as appropriate.
+    """
+
+    try:
+        return Value(await async_fn(*args, **kwargs))
+
+    except BaseException as exc:  # noqa
+        exc = _remove_tb_frames(exc, 1)
+        return Error(exc)
+
+
+##
+
+
+@dc.dataclass(repr=False, init=False, slots=True, frozen=True, order=True)
+class Outcome(abc.ABC, ta.Generic[ValueT_co]):
+    """
+    An abstract class representing the result of a Python computation.
+
+    This class has two concrete subclasses: :class:`Value` representing a value, and :class:`Error` representing an
+    exception.
+
+    In addition to the methods described below, comparison operators on :class:`Value` and :class:`Error` objects
+    (``==``, ``<``, etc.) check that the other object is also a :class:`Value` or :class:`Error` object respectively,
+    and then compare the contained objects.
+
+    :class:`Outcome` objects are hashable if the contained objects are hashable.
+    """
+
+    _unwrapped: bool = dc.field(default=False, compare=False, init=False)
+
+    def _set_unwrapped(self) -> None:
+        if self._unwrapped:
+            raise AlreadyUsedError
+        object.__setattr__(self, '_unwrapped', True)
+
+    @abc.abstractmethod
+    def unwrap(self) -> ValueT_co:
+        """
+        Return or raise the contained value or exception.
+
+        These two lines of code are equivalent::
+
+           x = fn(*args)
+           x = outcome.capture(fn, *args).unwrap()
+        """
+
+    @abc.abstractmethod
+    def send(self, gen: ta.Generator[ResultT, ValueT_co, object]) -> ResultT:
+        """
+        Send or throw the contained value or exception into the given generator object.
+
+        Args:
+          gen: A generator object supporting ``.send()`` and ``.throw()`` methods.
+        """
+
+    @abc.abstractmethod
+    async def asend(self, agen: ta.AsyncGenerator[ResultT, ValueT_co]) -> ResultT:
+        """
+        Send or throw the contained value or exception into the given async generator object.
+
+        Args:
+          agen: An async generator object supporting ``.asend()`` and ``.athrow()`` methods.
+        """
+
+
+@ta.final
+@dc.dataclass(frozen=True, repr=False, slots=True, order=True)
+class Value(Outcome[ValueT_co], ta.Generic[ValueT_co]):
+    """Concrete :class:`Outcome` subclass representing a regular value."""
+
+    value: ValueT_co
+
+    def __repr__(self) -> str:
+        return f'Value({self.value!r})'
+
+    def unwrap(self) -> ValueT_co:
+        self._set_unwrapped()
+        return self.value
+
+    def send(self, gen: ta.Generator[ResultT, ValueT_co, object]) -> ResultT:
+        self._set_unwrapped()
+        return gen.send(self.value)
+
+    async def asend(self, agen: ta.AsyncGenerator[ResultT, ValueT_co]) -> ResultT:
+        self._set_unwrapped()
+        return await agen.asend(self.value)
+
+
+@ta.final
+@dc.dataclass(frozen=True, repr=False, slots=True, order=True)
+class Error(Outcome[ta.NoReturn]):
+    """Concrete :class:`Outcome` subclass representing a raised exception."""
+
+    error: BaseException
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.error, BaseException):
+            raise TypeError(self.error)
+
+    def __repr__(self) -> str:
+        return f'Error({self.error!r})'
+
+    def unwrap(self) -> ta.NoReturn:
+        self._set_unwrapped()
+
+        # Tracebacks show the 'raise' line below out of context, so let's give this variable a name that makes sense out
+        # of context.
+        captured_error = self.error
+
+        try:
+            raise captured_error
+
+        finally:
+            # We want to avoid creating a reference cycle here. Python does collect cycles just fine, so it wouldn't be
+            # the end of the world if we did create a cycle, but the cyclic garbage collector adds latency to Python
+            # programs, and the more cycles you create, the more often it runs, so it's nicer to avoid creating them in
+            # the first place. For more details see:
+            #
+            #    https://github.com/python-trio/trio/issues/1770
+            #
+            # In particular, by deleting this local variables from the 'unwrap' methods frame, we avoid the
+            # 'captured_error' object's __traceback__ from indirectly referencing 'captured_error'.
+            del captured_error, self
+
+    def send(self, gen: ta.Generator[ResultT, ta.NoReturn, object]) -> ResultT:
+        self._set_unwrapped()
+        return gen.throw(self.error)
+
+    async def asend(self, agen: ta.AsyncGenerator[ResultT, ta.NoReturn]) -> ResultT:
+        self._set_unwrapped()
+        return await agen.athrow(self.error)
+
+
+# A convenience alias to a union of both results, allowing exhaustiveness checking.
+Maybe = Value[ValueT_co] | Error

omlish/sockets/server.py

@@ -4,8 +4,7 @@ import socket
 import socketserver
 import typing as ta
 
-from omlish.lite.check import check
-
+from ..lite.check import check
 from .addresses import SocketAddress
 from .handlers import SocketHandlerFactory
 

omlish/term/vt100/terminal.py

@@ -2,7 +2,7 @@ import dataclasses as dc
 import string
 import typing as ta
 
-from omlish.lite.check import check
+from ...lite.check import check
 
 
 T = ta.TypeVar('T')

omlish/testing/pytest/__init__.py

@@ -2,10 +2,6 @@ from .helpers import (  # noqa
     assert_raises_star,
 )
 
-from .marks import (  # noqa
-    drain_asyncio,
-)
-
 from . import skip  # noqa
 
 # Imported for convenience in things that import this but not lang.

omlish/testing/pytest/plugins/asyncs/__init__.py

@@ -0,0 +1 @@
+from .plugin import AsyncsPlugin  # noqa

omlish/testing/pytest/plugins/asyncs/backends/__init__.py

@@ -0,0 +1,16 @@
+import typing as _ta
+
+from .asyncio import AsyncioAsyncsBackend  # noqa
+from .base import AsyncsBackend  # noqa
+from .trio import TrioAsyncsBackend  # noqa
+from .trio_asyncio import TrioAsyncioAsyncsBackend  # noqa
+
+
+##
+
+
+ASYNC_BACKENDS: _ta.Collection[type[AsyncsBackend]] = [
+    AsyncioAsyncsBackend,
+    TrioAsyncioAsyncsBackend,
+    TrioAsyncsBackend,
+]