omextra 0.0.0.dev488__tar.gz

omextra-0.0.0.dev488/LICENSE

@@ -0,0 +1,21 @@
+Copyright 2023- wrmsr
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products
+derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

omextra-0.0.0.dev488/MANIFEST.in

@@ -0,0 +1 @@
+global-exclude **/conftest.py

omextra-0.0.0.dev488/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: omextra
+Version: 0.0.0.dev488
+Summary: omextra
+Author: wrmsr
+License-Expression: BSD-3-Clause
+Project-URL: source, https://github.com/wrmsr/omlish
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: omlish==0.0.0.dev488
+Dynamic: license-file
+
+# Overview
+
+Core-like code not appropriate for inclusion in `omlish` for one reason or another. A bit like
+[`golang.org/x`](https://pkg.go.dev/golang.org/x) but even less suitable for production use.
+
+Code here is usually in the process of either moving out of or moving into `omlish` proper, or being demoted to the
+unpublished `x` root dir, or just being deleted.
+
+# Notable packages
+
+- **[text.antlr](https://github.com/wrmsr/omlish/blob/master/omextra/text/antlr)** -
+  [ANTLR](https://www.antlr.org/)-related code. The codebase is generally moving away from antlr in favor of an internal
+  [abnf engine](https://github.com/wrmsr/omlish/blob/master/omextra/text/abnf), but I have other projects that need the
+  full power of antlr, so it may remain as an optional dep for utility code (much like sqlalchemy).

omextra-0.0.0.dev488/README.md

@@ -0,0 +1,14 @@
+# Overview
+
+Core-like code not appropriate for inclusion in `omlish` for one reason or another. A bit like
+[`golang.org/x`](https://pkg.go.dev/golang.org/x) but even less suitable for production use.
+
+Code here is usually in the process of either moving out of or moving into `omlish` proper, or being demoted to the
+unpublished `x` root dir, or just being deleted.
+
+# Notable packages
+
+- **[text.antlr](https://github.com/wrmsr/omlish/blob/master/omextra/text/antlr)** -
+  [ANTLR](https://www.antlr.org/)-related code. The codebase is generally moving away from antlr in favor of an internal
+  [abnf engine](https://github.com/wrmsr/omlish/blob/master/omextra/text/abnf), but I have other projects that need the
+  full power of antlr, so it may remain as an optional dep for utility code (much like sqlalchemy).

omextra-0.0.0.dev488/omextra/.omlish-manifests.json

@@ -0,0 +1,14 @@
+[
+  {
+    "module": ".text.antlr.cli.__main__",
+    "attr": "_CLI_MODULE",
+    "file": "omextra/text/antlr/cli/__main__.py",
+    "line": 1,
+    "value": {
+      "!omdev.cli.types.CliModule": {
+        "name": "antlr",
+        "module": "omextra.text.antlr.cli.__main__"
+      }
+    }
+  }
+]

omextra-0.0.0.dev488/omextra/__about__.py

@@ -0,0 +1,31 @@
+from omlish.__about__ import ProjectBase
+from omlish.__about__ import SetuptoolsBase
+from omlish.__about__ import __version__
+
+
+class Project(ProjectBase):
+    name = 'omextra'
+    description = 'omextra'
+
+    dependencies = [
+        # FIXME: text.antlr.cli deps omdev.cache.data, yet this lib is 'under' omdev.
+        # f'omdev == {__version__}',
+
+        f'omlish == {__version__}',
+    ]
+
+    optional_dependencies: dict = {
+    }
+
+    entry_points = {
+        'omlish.manifests': {name: name},
+    }
+
+
+class Setuptools(SetuptoolsBase):
+    cext = True
+
+    find_packages = {
+        'include': [Project.name, f'{Project.name}.*'],
+        'exclude': [*SetuptoolsBase.find_packages['exclude']],
+    }

omextra-0.0.0.dev488/omextra/asyncs/bluelet/LICENSE

@@ -0,0 +1,6 @@
+Based on bluelet ( https://github.com/sampsyo/bluelet ) by Adrian Sampson, original license:
+
+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.

omextra-0.0.0.dev488/omextra/asyncs/bluelet/all.py

@@ -0,0 +1,67 @@
+# ruff: noqa: I001
+from .api import (  # noqa
+    bluelet,
+)
+
+from .core import (  # noqa
+    BlueletCoro as Coro,
+    BlueletExcInfo as ExcInfo,
+    CoreBlueletEvent as CoreEvent,
+    DelegationBlueletEvent as DelegationEvent,
+    ExceptionBlueletEvent as ExceptionEvent,
+    JoinBlueletEvent as JoinEvent,
+    KillBlueletEvent as KillEvent,
+    ReturnBlueletEvent as ReturnEvent,
+    SleepBlueletEvent as SleepEvent,
+    SpawnBlueletEvent as SpawnEvent,
+    ValueBlueletEvent as ValueEvent,
+)
+
+from .events import (  # noqa
+    BlueletEvent as Event,
+    BlueletFuture as Future,
+    BlueletHasFileno as HasFileno,
+    BlueletWaitable as Waitable,
+    BlueletWaitables as Waitables,
+    WaitableBlueletEvent as WaitableEvent,
+)
+
+from .files import (  # noqa
+    FileBlueletEvent as FileEvent,
+    ReadBlueletEvent as ReadEvent,
+    WriteBlueletEvent as WriteEvent,
+)
+
+from .runner import (  # noqa
+    BlueletCoroException as CoroException,
+)
+
+from .sockets import (  # noqa
+    AcceptBlueletEvent as AcceptEvent,
+    BlueletConnection as Connection,
+    BlueletListener as Listener,
+    ReceiveBlueletEvent as ReceiveEvent,
+    SendBlueletEvent as SendEvent,
+    SocketBlueletEvent as SocketEvent,
+    SocketClosedBlueletError as SocketClosedError,
+)
+
+
+##
+
+
+call = bluelet.call
+end = bluelet.end
+join = bluelet.join
+kill = bluelet.kill
+null = bluelet.null
+sleep = bluelet.sleep
+spawn = bluelet.spawn
+
+read = bluelet.read
+write = bluelet.write
+
+run = bluelet.run
+
+connect = bluelet.connect
+server = bluelet.server

omextra-0.0.0.dev488/omextra/asyncs/bluelet/api.py

@@ -0,0 +1,23 @@
+# ruff: noqa: UP006 UP007 UP045
+# @omlish-lite
+# Based on bluelet ( https://github.com/sampsyo/bluelet ) by Adrian Sampson, original license:
+# 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.
+from .core import _CoreBlueletApi
+from .files import _FilesBlueletApi
+from .runner import _RunnerBlueletApi
+from .sockets import _SocketsBlueletApi
+
+
+class BlueletApi(
+    _RunnerBlueletApi,
+    _SocketsBlueletApi,
+    _FilesBlueletApi,
+    _CoreBlueletApi,
+):
+    pass
+
+
+bluelet = BlueletApi()

omextra-0.0.0.dev488/omextra/asyncs/bluelet/core.py

@@ -0,0 +1,179 @@
+# ruff: noqa: UP006 UP007 UP043 UP045
+# @omlish-lite
+# Based on bluelet ( https://github.com/sampsyo/bluelet ) by Adrian Sampson, original license:
+# 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 dataclasses as dc
+import time
+import types
+import typing as ta
+
+from omlish.lite.abstract import Abstract
+
+from .events import BlueletEvent
+from .events import BlueletFuture
+from .events import WaitableBlueletEvent
+
+
+T = ta.TypeVar('T')
+
+BlueletExcInfo = ta.Tuple[ta.Type[BaseException], BaseException, types.TracebackType]  # ta.TypeAlias
+
+BlueletCoro = ta.Generator[ta.Union['BlueletEvent', 'BlueletCoro'], ta.Any, None]  # ta.TypeAlias
+
+BlueletSpawnable = ta.Union[BlueletCoro, ta.Awaitable]  # ta.TypeAlias
+
+
+##
+
+
+@dc.dataclass(frozen=True, eq=False)
+class _BlueletAwaitableDriver:
+    a: ta.Awaitable
+
+    def __call__(self) -> BlueletCoro:
+        g = self.a.__await__()
+        gi = iter(g)
+        while True:
+            try:
+                f = gi.send(None)
+            except StopIteration as e:
+                yield ReturnBlueletEvent(e.value)
+                break
+            else:
+                if not isinstance(f, BlueletFuture):
+                    raise TypeError(f)
+                res = yield f.event
+                f.done = True
+                f.result = res
+
+
+##
+
+
+class CoreBlueletEvent(BlueletEvent, Abstract):
+    pass
+
+
+@dc.dataclass(frozen=True, eq=False)
+class ValueBlueletEvent(CoreBlueletEvent, ta.Generic[T]):
+    """An event that does nothing but return a fixed value."""
+
+    value: T
+
+
+@dc.dataclass(frozen=True, eq=False)
+class ExceptionBlueletEvent(CoreBlueletEvent):
+    """Raise an exception at the yield point. Used internally."""
+
+    exc_info: BlueletExcInfo
+
+
+@dc.dataclass(frozen=True, eq=False)
+class SpawnBlueletEvent(CoreBlueletEvent):
+    """Add a new coroutine coro to the scheduler."""
+
+    spawned: BlueletSpawnable
+
+
+@dc.dataclass(frozen=True, eq=False)
+class JoinBlueletEvent(CoreBlueletEvent):
+    """Suspend the coro until the specified child coro has completed."""
+
+    child: BlueletCoro
+
+
+@dc.dataclass(frozen=True, eq=False)
+class KillBlueletEvent(CoreBlueletEvent):
+    """Unschedule a child coro."""
+
+    child: BlueletCoro
+
+
+@dc.dataclass(frozen=True, eq=False)
+class DelegationBlueletEvent(CoreBlueletEvent):
+    """
+    Suspend execution of the current coro, start a new coro and, once the child coro finished, return control to
+    the parent coro.
+    """
+
+    spawned: BlueletCoro
+
+
+@dc.dataclass(frozen=True, eq=False)
+class ReturnBlueletEvent(CoreBlueletEvent, ta.Generic[T]):
+    """Return a value the current coro's delegator at the point of delegation. Ends the current (delegate) coro."""
+
+    value: ta.Optional[T]
+
+
+@dc.dataclass(frozen=True, eq=False)
+class SleepBlueletEvent(WaitableBlueletEvent, CoreBlueletEvent):
+    """Suspend the coro for a given duration."""
+
+    wakeup_time: float
+
+    def time_left(self) -> float:
+        return max(self.wakeup_time - time.time(), 0.)
+
+
+##
+
+
+class _CoreBlueletApi:
+    def value(self, v: T) -> ValueBlueletEvent[T]:
+        """Event: yield a value."""
+
+        return ValueBlueletEvent(v)
+
+    def null(self) -> ValueBlueletEvent[None]:
+        """Event: yield to the scheduler without doing anything special."""
+
+        return ValueBlueletEvent(None)
+
+    def spawn(self, spawned: BlueletSpawnable) -> SpawnBlueletEvent:
+        """Event: add another coroutine to the scheduler. Both the parent and child coroutines run concurrently."""
+
+        if isinstance(spawned, types.CoroutineType):
+            spawned = _BlueletAwaitableDriver(spawned)()
+
+        if not isinstance(spawned, types.GeneratorType):
+            raise TypeError(f'{spawned} is not spawnable')
+
+        return SpawnBlueletEvent(spawned)
+
+    def join(self, coro: BlueletCoro) -> JoinBlueletEvent:
+        """Suspend the coro until another, previously `spawn`ed coro completes."""
+
+        return JoinBlueletEvent(coro)
+
+    def kill(self, coro: BlueletCoro) -> KillBlueletEvent:
+        """Halt the execution of a different `spawn`ed coro."""
+
+        return KillBlueletEvent(coro)
+
+    def call(self, spawned: BlueletSpawnable) -> DelegationBlueletEvent:
+        """
+        Event: delegate to another coroutine. The current coroutine is resumed once the sub-coroutine finishes. If the
+        sub-coroutine returns a value using end(), then this event returns that value.
+        """
+
+        if isinstance(spawned, types.CoroutineType):
+            spawned = _BlueletAwaitableDriver(spawned)()
+
+        if not isinstance(spawned, types.GeneratorType):
+            raise TypeError(f'{spawned} is not spawnable')
+
+        return DelegationBlueletEvent(spawned)
+
+    def end(self, value: ta.Optional[T] = None) -> ReturnBlueletEvent[T]:
+        """Event: ends the coroutine and returns a value to its delegator."""
+
+        return ReturnBlueletEvent(value)
+
+    def sleep(self, duration: float) -> SleepBlueletEvent:
+        """Event: suspend the coro for ``duration`` seconds."""
+
+        return SleepBlueletEvent(time.time() + duration)

omextra-0.0.0.dev488/omextra/asyncs/bluelet/events.py

@@ -0,0 +1,79 @@
+# ruff: noqa: UP007 UP045
+# @omlish-lite
+# Based on bluelet ( https://github.com/sampsyo/bluelet ) by Adrian Sampson, original license:
+# 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 dataclasses as dc
+import typing as ta
+
+from omlish.lite.abstract import Abstract
+
+
+R = ta.TypeVar('R')
+
+BlueletEventT = ta.TypeVar('BlueletEventT', bound='BlueletEvent')
+
+BlueletWaitable = ta.Union[int, 'BlueletHasFileno']  # ta.TypeAlias
+
+
+##
+
+
+class BlueletEvent(Abstract):
+    """
+    Just a base class identifying Bluelet events. An event is an object yielded from a Bluelet coro coroutine to
+    suspend operation and communicate with the scheduler.
+    """
+
+    def __await__(self):
+        return BlueletFuture(self).__await__()
+
+
+##
+
+
+class BlueletHasFileno(ta.Protocol):
+    def fileno(self) -> int: ...
+
+
+@dc.dataclass(frozen=True)
+class BlueletWaitables:
+    r: ta.Sequence[BlueletWaitable] = ()
+    w: ta.Sequence[BlueletWaitable] = ()
+    x: ta.Sequence[BlueletWaitable] = ()
+
+
+class WaitableBlueletEvent(BlueletEvent, Abstract):
+    """
+    A waitable event is one encapsulating an action that can be waited for using a select() call. That is, it's an event
+    with an associated file descriptor.
+    """
+
+    def waitables(self) -> BlueletWaitables:
+        """
+        Return "waitable" objects to pass to select(). Should return three iterables for input readiness, output
+        readiness, and exceptional conditions (i.e., the three lists passed to select()).
+        """
+        return BlueletWaitables()
+
+    def fire(self) -> ta.Any:
+        """Called when an associated file descriptor becomes ready (i.e., is returned from a select() call)."""
+
+
+##
+
+
+@dc.dataclass(eq=False)
+class BlueletFuture(ta.Generic[BlueletEventT, R]):
+    event: BlueletEventT
+    done: bool = False
+    result: ta.Optional[R] = None
+
+    def __await__(self):
+        if not self.done:
+            yield self
+        if not self.done:
+            raise RuntimeError("await wasn't used with event future")
+        return self.result

omextra-0.0.0.dev488/omextra/asyncs/bluelet/files.py

@@ -0,0 +1,81 @@
+# ruff: noqa: UP006 UP007 UP045
+# @omlish-lite
+# Based on bluelet ( https://github.com/sampsyo/bluelet ) by Adrian Sampson, original license:
+# 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 dataclasses as dc
+import typing as ta
+
+from omlish.lite.abstract import Abstract
+
+from .core import DelegationBlueletEvent
+from .core import ReturnBlueletEvent
+from .events import BlueletEvent
+from .events import BlueletWaitables
+from .events import WaitableBlueletEvent
+
+
+##
+
+
+class FileBlueletEvent(BlueletEvent, Abstract):
+    pass
+
+
+@dc.dataclass(frozen=True, eq=False)
+class ReadBlueletEvent(WaitableBlueletEvent, FileBlueletEvent):
+    """Reads from a file-like object."""
+
+    fd: ta.IO
+    bufsize: int
+
+    def waitables(self) -> BlueletWaitables:
+        return BlueletWaitables(r=[self.fd])
+
+    def fire(self) -> bytes:
+        return self.fd.read(self.bufsize)
+
+
+@dc.dataclass(frozen=True, eq=False)
+class WriteBlueletEvent(WaitableBlueletEvent, FileBlueletEvent):
+    """Writes to a file-like object."""
+
+    fd: ta.IO
+    data: bytes
+
+    def waitables(self) -> BlueletWaitables:
+        return BlueletWaitables(w=[self.fd])
+
+    def fire(self) -> None:
+        self.fd.write(self.data)
+
+
+##
+
+
+class _FilesBlueletApi:
+    def read(self, fd: ta.IO, bufsize: ta.Optional[int] = None) -> BlueletEvent:
+        """Event: read from a file descriptor asynchronously."""
+
+        if bufsize is None:
+            # Read all.
+            def reader():
+                buf = []
+                while True:
+                    data = yield self.read(fd, 1024)
+                    if not data:
+                        break
+                    buf.append(data)
+                yield ReturnBlueletEvent(''.join(buf))
+
+            return DelegationBlueletEvent(reader())
+
+        else:
+            return ReadBlueletEvent(fd, bufsize)
+
+    def write(self, fd: ta.IO, data: bytes) -> BlueletEvent:
+        """Event: write to a file descriptor asynchronously."""
+
+        return WriteBlueletEvent(fd, data)