omdev 0.0.0.dev225__tar.gz → 0.0.0.dev226__tar.gz

{omdev-0.0.0.dev225/omdev.egg-info → omdev-0.0.0.dev226}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: omdev
-Version: 0.0.0.dev225
+Version: 0.0.0.dev226
 Summary: omdev
 Author: wrmsr
 License: BSD-3-Clause
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Operating System :: POSIX
 Requires-Python: >=3.12
 License-File: LICENSE
-Requires-Dist: omlish==0.0.0.dev225
+Requires-Dist: omlish==0.0.0.dev226
 Provides-Extra: all
 Requires-Dist: black~=24.10; extra == "all"
 Requires-Dist: pycparser~=2.22; extra == "all"

{omdev-0.0.0.dev225 → omdev-0.0.0.dev226}/omdev/scripts/ci.py

@@ -64,9 +64,6 @@ T = ta.TypeVar('T')
 # ../../omlish/asyncs/asyncio/asyncio.py
 CallableT = ta.TypeVar('CallableT', bound=ta.Callable)
 
-# ../../omlish/asyncs/asyncio/timeouts.py
-AwaitableT = ta.TypeVar('AwaitableT', bound=ta.Awaitable)
-
 # ../../omlish/lite/check.py
 SizedT = ta.TypeVar('SizedT', bound=ta.Sized)
 CheckMessage = ta.Union[str, ta.Callable[..., ta.Optional[str]], None]  # ta.TypeAlias
@@ -75,9 +72,15 @@ CheckOnRaiseFn = ta.Callable[[Exception], None]  # ta.TypeAlias
 CheckExceptionFactory = ta.Callable[..., Exception]  # ta.TypeAlias
 CheckArgsRenderer = ta.Callable[..., ta.Optional[str]]  # ta.TypeAlias
 
+# ../../omlish/lite/timeouts.py
+TimeoutLike = ta.Union['Timeout', 'Timeout.Default', ta.Iterable['TimeoutLike'], float]  # ta.TypeAlias
+
 # ../../omlish/argparse/cli.py
 ArgparseCmdFn = ta.Callable[[], ta.Optional[int]]  # ta.TypeAlias
 
+# ../../omlish/asyncs/asyncio/timeouts.py
+AwaitableT = ta.TypeVar('AwaitableT', bound=ta.Awaitable)
+
 # ../../omlish/lite/contextmanagers.py
 ExitStackedT = ta.TypeVar('ExitStackedT', bound='ExitStacked')
 AsyncExitStackedT = ta.TypeVar('AsyncExitStackedT', bound='AsyncExitStacked')
@@ -245,19 +248,6 @@ async def asyncio_wait_concurrent(
     return [task.result() for task in done]
 
 
-########################################
-# ../../../omlish/asyncs/asyncio/timeouts.py
-
-
-def asyncio_maybe_timeout(
-        fut: AwaitableT,
-        timeout: ta.Optional[float] = None,
-) -> AwaitableT:
-    if timeout is not None:
-        fut = asyncio.wait_for(fut, timeout)  # type: ignore
-    return fut
-
-
 ########################################
 # ../../../omlish/lite/cached.py
 
@@ -1057,6 +1047,205 @@ def format_num_bytes(num_bytes: int) -> str:
     return f'{num_bytes / 1024 ** (len(FORMAT_NUM_BYTES_SUFFIXES) - 1):.2f}{FORMAT_NUM_BYTES_SUFFIXES[-1]}'
 
 
+########################################
+# ../../../omlish/lite/timeouts.py
+"""
+TODO:
+ - Event (/ Predicate)
+"""
+
+
+##
+
+
+class Timeout(abc.ABC):
+    @property
+    @abc.abstractmethod
+    def can_expire(self) -> bool:
+        """Indicates whether or not this timeout will ever expire."""
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def expired(self) -> bool:
+        """Return whether or not this timeout has expired."""
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def remaining(self) -> float:
+        """Returns the time (in seconds) remaining until the timeout expires. May be negative and/or infinite."""
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __call__(self) -> float:
+        """Returns the time (in seconds) remaining until the timeout expires, or raises if the timeout has expired."""
+
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def or_(self, o: ta.Any) -> ta.Any:
+        """Evaluates time remaining via remaining() if this timeout can expire, otherwise returns `o`."""
+
+        raise NotImplementedError
+
+    #
+
+    @classmethod
+    def _now(cls) -> float:
+        return time.time()
+
+    #
+
+    class Default:
+        def __new__(cls, *args, **kwargs):  # noqa
+            raise TypeError
+
+    class _NOT_SPECIFIED:  # noqa
+        def __new__(cls, *args, **kwargs):  # noqa
+            raise TypeError
+
+    @classmethod
+    def of(
+            cls,
+            obj: ta.Optional[TimeoutLike],
+            default: ta.Union[TimeoutLike, ta.Type[_NOT_SPECIFIED]] = _NOT_SPECIFIED,
+    ) -> 'Timeout':
+        if obj is None:
+            return InfiniteTimeout()
+
+        elif isinstance(obj, Timeout):
+            return obj
+
+        elif isinstance(obj, (float, int)):
+            return DeadlineTimeout(cls._now() + obj)
+
+        elif isinstance(obj, ta.Iterable):
+            return CompositeTimeout(*[Timeout.of(c) for c in obj])
+
+        elif obj is Timeout.Default:
+            if default is Timeout._NOT_SPECIFIED or default is Timeout.Default:
+                raise RuntimeError('Must specify a default timeout')
+
+            else:
+                return Timeout.of(default)  # type: ignore[arg-type]
+
+        else:
+            raise TypeError(obj)
+
+    @classmethod
+    def of_deadline(cls, deadline: float) -> 'DeadlineTimeout':
+        return DeadlineTimeout(deadline)
+
+    @classmethod
+    def of_predicate(cls, expired_fn: ta.Callable[[], bool]) -> 'PredicateTimeout':
+        return PredicateTimeout(expired_fn)
+
+
+class DeadlineTimeout(Timeout):
+    def __init__(
+            self,
+            deadline: float,
+            exc: ta.Union[ta.Type[BaseException], BaseException] = TimeoutError,
+    ) -> None:
+        super().__init__()
+
+        self.deadline = deadline
+        self.exc = exc
+
+    @property
+    def can_expire(self) -> bool:
+        return True
+
+    def expired(self) -> bool:
+        return not (self.remaining() > 0)
+
+    def remaining(self) -> float:
+        return self.deadline - self._now()
+
+    def __call__(self) -> float:
+        if (rem := self.remaining()) > 0:
+            return rem
+        raise self.exc
+
+    def or_(self, o: ta.Any) -> ta.Any:
+        return self()
+
+
+class InfiniteTimeout(Timeout):
+    @property
+    def can_expire(self) -> bool:
+        return False
+
+    def expired(self) -> bool:
+        return False
+
+    def remaining(self) -> float:
+        return float('inf')
+
+    def __call__(self) -> float:
+        return float('inf')
+
+    def or_(self, o: ta.Any) -> ta.Any:
+        return o
+
+
+class CompositeTimeout(Timeout):
+    def __init__(self, *children: Timeout) -> None:
+        super().__init__()
+
+        self.children = children
+
+    @property
+    def can_expire(self) -> bool:
+        return any(c.can_expire for c in self.children)
+
+    def expired(self) -> bool:
+        return any(c.expired() for c in self.children)
+
+    def remaining(self) -> float:
+        return min(c.remaining() for c in self.children)
+
+    def __call__(self) -> float:
+        return min(c() for c in self.children)
+
+    def or_(self, o: ta.Any) -> ta.Any:
+        if self.can_expire:
+            return self()
+        return o
+
+
+class PredicateTimeout(Timeout):
+    def __init__(
+            self,
+            expired_fn: ta.Callable[[], bool],
+            exc: ta.Union[ta.Type[BaseException], BaseException] = TimeoutError,
+    ) -> None:
+        super().__init__()
+
+        self.expired_fn = expired_fn
+        self.exc = exc
+
+    @property
+    def can_expire(self) -> bool:
+        return True
+
+    def expired(self) -> bool:
+        return self.expired_fn()
+
+    def remaining(self) -> float:
+        return float('inf')
+
+    def __call__(self) -> float:
+        if not self.expired_fn():
+            return float('inf')
+        raise self.exc
+
+    def or_(self, o: ta.Any) -> ta.Any:
+        return self()
+
+
 ########################################
 # ../../../omlish/logs/filters.py
 
@@ -1814,6 +2003,19 @@ class ArgparseCli:
             return fn()
 
 
+########################################
+# ../../../omlish/asyncs/asyncio/timeouts.py
+
+
+def asyncio_maybe_timeout(
+        fut: AwaitableT,
+        timeout: ta.Optional[TimeoutLike] = None,
+) -> AwaitableT:
+    if timeout is not None:
+        fut = asyncio.wait_for(fut, Timeout.of(timeout)())  # type: ignore
+    return fut
+
+
 ########################################
 # ../../../omlish/lite/contextmanagers.py
 
@@ -3147,17 +3349,43 @@ class SubprocessRunOutput(ta.Generic[T]):
 class SubprocessRun:
     cmd: ta.Sequence[str]
     input: ta.Any = None
-    timeout: ta.Optional[float] = None
+    timeout: ta.Optional[TimeoutLike] = None
     check: bool = False
     capture_output: ta.Optional[bool] = None
     kwargs: ta.Optional[ta.Mapping[str, ta.Any]] = None
 
+    #
+
+    _FIELD_NAMES: ta.ClassVar[ta.FrozenSet[str]]
+
+    def replace(self, **kwargs: ta.Any) -> 'SubprocessRun':
+        if not kwargs:
+            return self
+
+        field_kws = {}
+        extra_kws = {}
+        for k, v in kwargs.items():
+            if k in self._FIELD_NAMES:
+                field_kws[k] = v
+            else:
+                extra_kws[k] = v
+
+        return dc.replace(self, **{
+            **dict(kwargs={
+                **(self.kwargs or {}),
+                **extra_kws,
+            }),
+            **field_kws,  # passing a kwarg named 'kwargs' intentionally clobbers
+        })
+
+    #
+
     @classmethod
     def of(
             cls,
             *cmd: str,
             input: ta.Any = None,  # noqa
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
             check: bool = False,  # noqa
             capture_output: ta.Optional[bool] = None,
             **kwargs: ta.Any,
@@ -3178,20 +3406,25 @@ class SubprocessRun:
     def run(
             self,
             subprocesses: ta.Optional[ta.Any] = None,  # AbstractSubprocesses
+            **kwargs: ta.Any,
     ) -> SubprocessRunOutput:
         if subprocesses is None:
             subprocesses = self._DEFAULT_SUBPROCESSES
-        return check.not_none(subprocesses).run_(self)  # type: ignore[attr-defined]
+        return check.not_none(subprocesses).run_(self.replace(**kwargs))  # type: ignore[attr-defined]
 
     _DEFAULT_ASYNC_SUBPROCESSES: ta.ClassVar[ta.Optional[ta.Any]] = None  # AbstractAsyncSubprocesses
 
     async def async_run(
             self,
             async_subprocesses: ta.Optional[ta.Any] = None,  # AbstractAsyncSubprocesses
+            **kwargs: ta.Any,
     ) -> SubprocessRunOutput:
         if async_subprocesses is None:
             async_subprocesses = self._DEFAULT_ASYNC_SUBPROCESSES
-        return await check.not_none(async_subprocesses).run_(self)  # type: ignore[attr-defined]
+        return await check.not_none(async_subprocesses).run_(self.replace(**kwargs))  # type: ignore[attr-defined]
+
+
+SubprocessRun._FIELD_NAMES = frozenset(fld.name for fld in dc.fields(SubprocessRun))  # noqa
 
 
 ##
@@ -3208,11 +3441,19 @@ class SubprocessRunnable(abc.ABC, ta.Generic[T]):
 
     #
 
-    def run(self, subprocesses: ta.Optional[ta.Any] = None) -> T:  # AbstractSubprocesses
-        return self.handle_run_output(self.make_run().run(subprocesses))
+    def run(
+            self,
+            subprocesses: ta.Optional[ta.Any] = None,  # AbstractSubprocesses
+            **kwargs: ta.Any,
+    ) -> T:
+        return self.handle_run_output(self.make_run().run(subprocesses, **kwargs))
 
-    async def async_run(self, async_subprocesses: ta.Optional[ta.Any] = None) -> T:  # AbstractAsyncSubprocesses
-        return self.handle_run_output(await self.make_run().async_run(async_subprocesses))
+    async def async_run(
+            self,
+            async_subprocesses: ta.Optional[ta.Any] = None,  # AbstractAsyncSubprocesses
+            **kwargs: ta.Any,
+    ) -> T:
+        return self.handle_run_output(await self.make_run().async_run(async_subprocesses, **kwargs))
 
 
 ########################################
@@ -4320,6 +4561,11 @@ class BaseSubprocesses(abc.ABC):  # noqa
 
         #
 
+        if 'timeout' in kwargs:
+            kwargs['timeout'] = Timeout.of(kwargs['timeout']).or_(None)
+
+        #
+
         return cmd, dict(
             env=env,
             shell=shell,
@@ -4465,7 +4711,7 @@ class AbstractAsyncSubprocesses(BaseSubprocesses):
             self,
             *cmd: str,
             input: ta.Any = None,  # noqa
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
             check: bool = False,
             capture_output: ta.Optional[bool] = None,
             **kwargs: ta.Any,
@@ -4542,6 +4788,11 @@ class AbstractAsyncSubprocesses(BaseSubprocesses):
 
 ########################################
 # ../../../omlish/subprocesses/sync.py
+"""
+TODO:
+ - popen
+ - route check_calls through run_?
+"""
 
 
 ##
@@ -4556,7 +4807,7 @@ class AbstractSubprocesses(BaseSubprocesses, abc.ABC):
             self,
             *cmd: str,
             input: ta.Any = None,  # noqa
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
             check: bool = False,
             capture_output: ta.Optional[bool] = None,
             **kwargs: ta.Any,
@@ -4867,7 +5118,7 @@ class AsyncioProcessCommunicator:
     async def communicate(
             self,
             input: ta.Any = None,  # noqa
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
     ) -> Communication:
         return await asyncio_maybe_timeout(self._communicate(input), timeout)
 
@@ -4880,7 +5131,7 @@ class AsyncioSubprocesses(AbstractAsyncSubprocesses):
             self,
             proc: asyncio.subprocess.Process,
             input: ta.Any = None,  # noqa
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
     ) -> ta.Tuple[ta.Optional[bytes], ta.Optional[bytes]]:
         return await AsyncioProcessCommunicator(proc).communicate(input, timeout)  # noqa
 
@@ -4891,7 +5142,7 @@ class AsyncioSubprocesses(AbstractAsyncSubprocesses):
             self,
             *cmd: str,
             shell: bool = False,
-            timeout: ta.Optional[float] = None,
+            timeout: ta.Optional[TimeoutLike] = None,
             **kwargs: ta.Any,
     ) -> ta.AsyncGenerator[asyncio.subprocess.Process, None]:
         with self.prepare_and_wrap( *cmd, shell=shell, **kwargs) as (cmd, kwargs):  # noqa