maxframe 2.4.0rc1__cp312-cp312-win32.whl

maxframe/lib/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

maxframe/lib/aio/__init__.py

@@ -0,0 +1,27 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import contextlib
+import sys
+
+from .file import AioFileObject, AioFilesystem
+from .isolation import Isolation, get_isolation, new_isolation, stop_isolation
+from .lru import alru_cache
+from .parallelism import AioEvent
+
+if sys.version_info[:2] < (3, 9):
+    from ._threads import to_thread
+
+    asyncio.to_thread = to_thread

maxframe/lib/aio/_runners.py

@@ -0,0 +1,162 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""
+Backport of the asyncio.runners module from Python 3.7.
+"""
+# Source:
+# https://github.com/python/cpython/blob/a4afcdfa55ddffa4b9ae3b0cf101628c7bff4102/Lib/asyncio/runners.py
+
+# Modifications:
+# * removed relative imports of .coroutines, .events, .tasks
+# * replaced `coroutines`, `events`, `tasks` with `asyncio`.
+# * replaced `tasks.all_tasks` with `asyncio.Task.all_tasks` because it is
+#   backwards compatible.
+# * Use private function `asyncio.events._get_running_loop` directly in
+#   Python 3.6
+
+import asyncio
+import weakref
+from typing import Any, Awaitable, Coroutine, TypeVar, Union
+
+try:
+    from asyncio import get_running_loop  # noqa Python >=3.7
+except ImportError:  # pragma: no cover
+    from asyncio.events import _get_running_loop as get_running_loop  # pragma: no cover
+
+__all__ = ("run", "get_running_loop")
+_T = TypeVar("_T")
+
+
+def _patch_loop(loop):
+    """
+    This function is designed to work around https://bugs.python.org/issue36607
+
+    It's job is to keep a thread safe variable tasks up to date with any tasks that
+    are created for the given loop. This then lets you cancel them as _all_tasks
+    was intended for.
+
+    We also need to patch the {get,set}_task_factory functions because we can't allow
+    Other users of it to overwrite our factory function. This function will pretend
+    like there is no factory set but in reality our factory is always set and we will
+    call the provided one set
+    """
+    tasks = weakref.WeakSet()
+
+    task_factory = [None]
+
+    def _set_task_factory(factory):
+        task_factory[0] = factory
+
+    def _get_task_factory():
+        return task_factory[0]
+
+    def _safe_task_factory(loop, coro):
+        if task_factory[0] is None:
+            # These lines are copied from the standard library because they don't have
+            # this inside a default factory function for me to call.
+            # https://github.com/python/cpython/blob/3.6/Lib/asyncio/base_events.py#L304
+            task = asyncio.Task(coro, loop=loop)
+            if task._source_traceback:
+                del task._source_traceback[-1]  # pragma: no cover
+        else:
+            task = task_factory[0](loop, coro)
+        tasks.add(task)
+        return task
+
+    loop.set_task_factory(_safe_task_factory)
+    loop.set_task_factory = _set_task_factory
+    loop.get_task_factory = _get_task_factory
+
+    return tasks
+
+
+def run(
+    main: Union[Coroutine[Any, None, _T], Awaitable[_T]], *, debug: bool = False
+) -> _T:
+    """Run a coroutine.
+
+    This function runs the passed coroutine, taking care of
+    managing the asyncio event loop and finalizing asynchronous
+    generators.
+
+    This function cannot be called when another asyncio event loop is
+    running in the same thread.
+
+    If debug is True, the event loop will be run in debug mode.
+
+    This function always creates a new event loop and closes it at the end.
+    It should be used as a main entry point for asyncio programs, and should
+    ideally only be called once.
+
+    Example:
+
+        async def main():
+            await asyncio.sleep(1)
+            print('hello')
+
+        asyncio.run(main())
+    """
+    # Python 3.7+ raises RuntimeError while <3.6 returns None
+    try:
+        loop = get_running_loop()
+    except RuntimeError:
+        loop = None
+    if loop is not None:
+        raise RuntimeError("asyncio.run() cannot be called from a running event loop")
+
+    if not asyncio.iscoroutine(main):
+        raise ValueError("a coroutine was expected, got {!r}".format(main))
+
+    loop = asyncio.new_event_loop()
+    tasks = _patch_loop(loop)
+
+    try:
+        asyncio.set_event_loop(loop)
+        loop.set_debug(debug)
+        return loop.run_until_complete(main)
+    finally:
+        try:
+            _cancel_all_tasks(loop, tasks)
+            loop.run_until_complete(loop.shutdown_asyncgens())
+        finally:
+            asyncio.set_event_loop(None)  # type: ignore
+            loop.close()
+
+
+def _cancel_all_tasks(loop, tasks):
+    to_cancel = [task for task in tasks if not task.done()]
+
+    if not to_cancel:
+        return
+
+    for task in to_cancel:
+        task.cancel()
+
+    loop.run_until_complete(
+        asyncio.gather(*to_cancel, loop=loop, return_exceptions=True)
+    )
+
+    for task in to_cancel:
+        if task.cancelled():
+            continue
+        if task.exception() is not None:
+            loop.call_exception_handler(
+                {
+                    "message": "unhandled exception during asyncio.run() shutdown",
+                    "exception": task.exception(),
+                    "task": task,
+                }
+            )

maxframe/lib/aio/_threads.py

@@ -0,0 +1,35 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import contextvars
+import functools
+from asyncio import events
+
+__all__ = ("to_thread",)
+
+
+async def to_thread(func, *args, **kwargs):
+    """Asynchronously run function *func* in a separate thread.
+
+    Any *args and **kwargs supplied for this function are directly passed
+    to *func*. Also, the current :class:`contextvars.Context` is propagated,
+    allowing context variables from the main thread to be accessed in the
+    separate thread.
+
+    Return a coroutine that can be awaited to get the eventual result of *func*.
+    """
+    loop = events.get_running_loop()
+    ctx = contextvars.copy_context()
+    func_call = functools.partial(ctx.run, func, *args, **kwargs)
+    return await loop.run_in_executor(None, func_call)

maxframe/lib/aio/base.py

@@ -0,0 +1,82 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import asyncio
+import functools
+from concurrent.futures import Executor
+from typing import Any, Type
+
+
+def _make_delegate_method(attr):
+    async def method(self, *args, **kwargs):
+        func = functools.partial(getattr(self._file, attr), *args, **kwargs)
+        return await self._loop.run_in_executor(self._executor, func)
+
+    return method
+
+
+def _make_proxy_method(attr):
+    def method(self, *args, **kwargs):
+        return getattr(self._file, attr)(*args, **kwargs)
+
+    return method
+
+
+def _make_proxy_property(attr):
+    def proxy_property(self):
+        return getattr(self._file, attr)
+
+    return property(proxy_property)
+
+
+def delegate_to_executor(*attrs):
+    def wrap_cls(cls: Type):
+        for attr in attrs:
+            setattr(cls, attr, _make_delegate_method(attr))
+        return cls
+
+    return wrap_cls
+
+
+def proxy_method_directly(*attrs):
+    def wrap_cls(cls: Type):
+        for attr in attrs:
+            setattr(cls, attr, _make_proxy_method(attr))
+        return cls
+
+    return wrap_cls
+
+
+def proxy_property_directly(*attrs):
+    def wrap_cls(cls):
+        for attr in attrs:
+            setattr(cls, attr, _make_proxy_property(attr))
+        return cls
+
+    return wrap_cls
+
+
+class AioBase:
+    def __init__(
+        self, file: Any, loop: asyncio.BaseEventLoop = None, executor: Executor = None
+    ):
+        if loop is None:
+            loop = asyncio.get_event_loop()
+        if isinstance(file, AioBase):
+            file = file._file
+
+        self._file = file
+        self._loop = loop
+        self._executor = executor

maxframe/lib/aio/file.py

@@ -0,0 +1,85 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import functools
+
+from .base import (
+    AioBase,
+    delegate_to_executor,
+    proxy_method_directly,
+    proxy_property_directly,
+)
+
+
+@delegate_to_executor(
+    "close",
+    "flush",
+    "isatty",
+    "read",
+    "read1",
+    "readinto",
+    "readline",
+    "readlines",
+    "seek",
+    "seekable",
+    "tell",
+    "truncate",
+    "writable",
+    "write",
+    "writelines",
+)
+@proxy_method_directly("fileno", "readable")
+@proxy_property_directly("closed", "name", "mode")
+class AioFileObject(AioBase):
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        """Simulate normal file iteration."""
+        line = await self.readline()
+        if line:
+            return line
+        else:
+            raise StopAsyncIteration
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+        self._file = None
+
+
+@delegate_to_executor(
+    "cat",
+    "ls",
+    "delete",
+    "disk_usage",
+    "stat",
+    "rm",
+    "mv",
+    "rename",
+    "mkdir",
+    "exists",
+    "isdir",
+    "isfile",
+    "read_parquet",
+    "walk",
+)
+@proxy_property_directly("pathsep")
+class AioFilesystem(AioBase):
+    async def open(self, *args, **kwargs):
+        func = functools.partial(self._file.open, *args, **kwargs)
+        file = await self._loop.run_in_executor(self._executor, func)
+        return AioFileObject(file)

maxframe/lib/aio/isolation.py

@@ -0,0 +1,100 @@
+# Copyright 1999-2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import asyncio
+import atexit
+import itertools
+import threading
+from typing import Dict, Optional
+
+
+class Isolation:
+    _counter = itertools.count().__next__
+
+    loop: asyncio.AbstractEventLoop
+    _stopped: Optional[asyncio.Event]
+    _thread: Optional[threading.Thread]
+
+    def __init__(self, loop: asyncio.AbstractEventLoop, threaded: bool = True):
+        self.loop = loop
+        self._threaded = threaded
+
+        self._stopped = None
+        self._thread = None
+        self._thread_ident = None
+
+    def _run(self):
+        asyncio.set_event_loop(self.loop)
+        self._stopped = asyncio.Event()
+        self.loop.run_until_complete(self._stopped.wait())
+
+    def start(self):
+        if self._threaded:
+            self._thread = thread = threading.Thread(
+                name=f"IsolationThread-{self._counter()}", target=self._run
+            )
+            thread.daemon = True
+            thread.start()
+            self._thread_ident = thread.ident
+
+    @property
+    def thread_ident(self):
+        return self._thread_ident
+
+    async def _stop(self):
+        self._stopped.set()
+
+    def stop(self):
+        if self._threaded:
+            asyncio.run_coroutine_threadsafe(self._stop(), self.loop).result()
+            self._thread.join()
+
+
+_name_to_isolation: Dict[str, Isolation] = dict()
+
+
+DEFAULT_ISOLATION = "oscar"
+
+
+def new_isolation(
+    name: str = DEFAULT_ISOLATION,
+    loop: asyncio.AbstractEventLoop = None,
+    threaded: bool = True,
+) -> Isolation:
+    if name in _name_to_isolation:
+        return _name_to_isolation[name]
+
+    if loop is None:
+        loop = asyncio.new_event_loop()
+
+    isolation = Isolation(loop, threaded=threaded)
+    isolation.start()
+    _name_to_isolation[name] = isolation
+    return isolation
+
+
+def get_isolation(name: str = DEFAULT_ISOLATION):
+    isolation = _name_to_isolation[name]
+    if isolation.loop.is_closed():  # pragma: no cover
+        _name_to_isolation.pop(name)
+        raise KeyError(name)
+    return isolation
+
+
+def stop_isolation(name: str = DEFAULT_ISOLATION):
+    if name in _name_to_isolation:
+        return _name_to_isolation.pop(name).stop()
+
+
+atexit.register(stop_isolation)