wool 0.1rc9__py3-none-any.whl → 0.1rc11__py3-none-any.whl

wool/_cli.py

@@ -1,262 +0,0 @@
-import asyncio
-import importlib
-import logging
-from contextlib import contextmanager
-from functools import partial
-from multiprocessing import cpu_count
-from time import perf_counter
-
-import click
-
-import wool
-from wool._pool import WorkerPool
-from wool._session import WorkerPoolSession
-from wool._task import task
-
-DEFAULT_PORT = 48800
-
-
-# PUBLIC
-class WorkerPoolCommand(click.core.Command):
-    """
-    Custom Click command class for worker pool commands.
-
-    :param default_host: Default host address.
-    :param default_port: Default port number.
-    :param default_authkey: Default authentication key.
-    """
-
-    def __init__(
-        self,
-        *args,
-        default_host="localhost",
-        default_port=0,
-        default_authkey=b"",
-        **kwargs,
-    ):
-        params = kwargs.pop("params", [])
-        params = [
-            click.Option(["--host", "-h"], type=str, default=default_host),
-            click.Option(["--port", "-p"], type=int, default=default_port),
-            click.Option(
-                ["--authkey", "-a"],
-                type=str,
-                default=default_authkey,
-                callback=to_bytes,
-            ),
-            *params,
-        ]
-        super().__init__(*args, params=params, **kwargs)
-
-
-@contextmanager
-def timer():
-    """
-    Context manager to measure the execution time of a code block.
-
-    :return: A function to retrieve the elapsed time.
-    """
-    start = end = perf_counter()
-    yield lambda: end - start
-    end = perf_counter()
-
-
-def to_bytes(context: click.Context, parameter: click.Parameter, value: str):
-    """
-    Convert the given value to bytes.
-
-    :param context: Click context.
-    :param parameter: Click parameter.
-    :param value: Value to convert.
-    :return: The converted value in bytes.
-    """
-    if value is None:
-        return b""
-    return value.encode("utf-8")
-
-
-def assert_nonzero(
-    context: click.Context, parameter: click.Parameter, value: int
-) -> int:
-    """
-    Assert that the given value is non-zero.
-
-    :param context: Click context.
-    :param parameter: Click parameter.
-    :param value: Value to check.
-    :return: The original value if it is non-zero.
-    """
-    if value is None:
-        return value
-    assert value >= 0
-    return value
-
-
-def debug(ctx, param, value):
-    """
-    Enable debugging mode with a specified port.
-
-    :param ctx: The Click context object.
-    :param param: The parameter being handled.
-    :param value: The port number for the debugger.
-    """
-    if not value or ctx.resilient_parsing:
-        return
-
-    import debugpy
-
-    debugpy.listen(5678)
-    click.echo("Waiting for debugger to attach...")
-    debugpy.wait_for_client()
-    click.echo("Debugger attached")
-
-
-@click.group()
-@click.option(
-    "--debug",
-    "-d",
-    callback=debug,
-    expose_value=False,
-    help=(
-        "Run with debugger listening on the specified port. Execution will "
-        "block until the debugger is attached."
-    ),
-    is_eager=True,
-    type=int,
-)
-@click.option(
-    "--verbosity",
-    "-v",
-    count=True,
-    default=3,
-    help="Verbosity level for logging.",
-    type=int,
-)
-def cli(verbosity: int):
-    """
-    CLI command group with options for verbosity, debugging, and version.
-
-    :param verbosity: Verbosity level for logging.
-    """
-    match verbosity:
-        case 4:
-            wool.__log_level__ = logging.DEBUG
-        case 3:
-            wool.__log_level__ = logging.INFO
-        case 2:
-            wool.__log_level__ = logging.WARNING
-        case 1:
-            wool.__log_level__ = logging.ERROR
-
-    logging.getLogger().setLevel(wool.__log_level__)
-    logging.info(
-        f"Set log level to {logging.getLevelName(wool.__log_level__)}"
-    )
-
-
-@cli.group()
-def pool():
-    """
-    CLI command group for managing worker pools.
-    """
-    pass
-
-
-@pool.command(cls=partial(WorkerPoolCommand, default_port=DEFAULT_PORT))
-@click.option(
-    "--breadth", "-b", type=int, default=cpu_count(), callback=assert_nonzero
-)
-@click.option(
-    "modules",
-    "--module",
-    "-m",
-    multiple=True,
-    type=str,
-    help=(
-        "Python module containing workerpool task definitions to be executed "
-        "by this pool."
-    ),
-)
-def up(host, port, authkey, breadth, modules):
-    """
-    Start a worker pool with the specified configuration.
-
-    :param host: The host address for the worker pool.
-    :param port: The port number for the worker pool.
-    :param authkey: The authentication key for the worker pool.
-    :param breadth: The number of worker processes in the pool.
-    :param modules: Python modules containing task definitions.
-    """
-    for module in modules:
-        importlib.import_module(module)
-    if not authkey:
-        logging.warning("No authkey specified")
-    workerpool = WorkerPool(
-        address=(host, port),
-        breadth=breadth,
-        authkey=authkey,
-        log_level=wool.__log_level__,
-    )
-    workerpool.start()
-    workerpool.join()
-
-
-@pool.command(cls=partial(WorkerPoolCommand, default_port=DEFAULT_PORT))
-@click.option(
-    "--wait",
-    "-w",
-    is_flag=True,
-    default=False,
-    help="Wait for in-flight tasks to complete before shutting down.",
-)
-def down(host, port, authkey, wait):
-    """
-    Shut down the worker pool.
-
-    :param host: The host address of the worker pool.
-    :param port: The port number of the worker pool.
-    :param authkey: The authentication key for the worker pool.
-    :param wait: Whether to wait for in-flight tasks to complete.
-    """
-    assert port
-    if not host:
-        host = "localhost"
-    if not authkey:
-        authkey = b""
-    with WorkerPoolSession(address=(host, port), authkey=authkey) as client:
-        client.stop(wait=wait)
-
-
-@cli.command(cls=partial(WorkerPoolCommand, default_port=DEFAULT_PORT))
-def ping(host, port, authkey):
-    """
-    Ping the worker pool to check connectivity.
-
-    :param host: The host address of the worker pool.
-    :param port: The port number of the worker pool.
-    :param authkey: The authentication key for the worker pool.
-    """
-    assert port
-    if not host:
-        host = "localhost"
-    if not authkey:
-        authkey = b""
-
-    async def _():
-        with timer() as t:
-            await _ping()
-
-        print(f"Ping: {int((t() * 1000) + 0.5)} ms")
-
-    with WorkerPoolSession(address=(host, port), authkey=authkey):
-        asyncio.get_event_loop().run_until_complete(_())
-
-
-@task
-async def _ping():
-    """
-    Asynchronous task to log a ping message.
-
-    :return: None
-    """
-    logging.debug("Ping!")

wool/_event.py

@@ -1,109 +0,0 @@
-from __future__ import annotations
-
-import logging
-from time import perf_counter_ns
-from typing import TYPE_CHECKING
-from typing import Literal
-
-from wool._typing import PassthroughDecorator
-
-if TYPE_CHECKING:
-    from wool._task import Task
-    from wool._task import TaskEventCallback
-
-
-# PUBLIC
-class TaskEvent:
-    """
-    Represents an event related to a Wool task, such as creation, queuing,
-    scheduling, starting, stopping, or completion.
-
-    Task events are emitted during the lifecycle of a task. These events can
-    be used to track task execution and measure performance, such as CPU
-    utilization.
-
-    :param type: The type of the task event.
-    :param task: The task associated with the event.
-    """
-
-    type: TaskEventType
-    task: Task
-
-    _handlers: dict[str, list[TaskEventCallback]] = {}
-
-    def __init__(self, type: TaskEventType, /, task: Task) -> None:
-        """
-        Initialize a WoolTaskEvent instance.
-
-        :param type: The type of the task event.
-        :param task: The task associated with the event.
-        """
-        self.type = type
-        self.task = task
-
-    @classmethod
-    def handler(
-        cls, *event_types: TaskEventType
-    ) -> PassthroughDecorator[TaskEventCallback]:
-        """
-        Register a handler function for specific task event types.
-
-        :param event_types: The event types to handle.
-        :return: A decorator to register the handler function.
-        """
-
-        def _handler(
-            fn: TaskEventCallback,
-        ) -> TaskEventCallback:
-            for event_type in event_types:
-                cls._handlers.setdefault(event_type, []).append(fn)
-            return fn
-
-        return _handler
-
-    def emit(self):
-        """
-        Emit the task event, invoking all registered handlers for the event
-        type.
-
-        Handlers are called with the event instance and a timestamp.
-
-        :raises Exception: If any handler raises an exception.
-        """
-        logging.debug(
-            f"Emitting {self.type} event for "
-            f"task {self.task.id} "
-            f"({self.task.callable.__qualname__})"
-        )
-        if handlers := self._handlers.get(self.type):
-            timestamp = perf_counter_ns()
-            for handler in handlers:
-                handler(self, timestamp)
-
-
-# PUBLIC
-TaskEventType = Literal[
-    "task-created",
-    "task-queued",
-    "task-scheduled",
-    "task-started",
-    "task-stopped",
-    "task-completed",
-]
-"""
-Defines the types of events that can occur during the lifecycle of a Wool 
-task.
-
-- "task-created": 
-    Emitted when a task is created.
-- "task-queued": 
-    Emitted when a task is added to the queue.
-- "task-scheduled": 
-    Emitted when a task is scheduled for execution in a worker's event loop.
-- "task-started": 
-    Emitted when a task starts execution.
-- "task-stopped": 
-    Emitted when a task stops execution.
-- "task-completed": 
-    Emitted when a task completes execution.
-"""

wool/_future.py

@@ -1,171 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import concurrent.futures
-import logging
-from typing import Any
-from typing import Generator
-from typing import Generic
-from typing import TypeVar
-from typing import cast
-
-from wool._utils import Undefined
-from wool._utils import UndefinedType
-
-T = TypeVar("T")
-
-
-# PUBLIC
-class Future(Generic[T]):
-    """
-    A future object representing the result of an asynchronous operation.
-
-    WoolFuture provides methods to retrieve the result or exception of an
-    asynchronous operation, set the result or exception, and await its
-    completion.
-
-    :param T: The type of the result.
-    """
-
-    def __init__(self) -> None:
-        """
-        Initialize a WoolFuture instance.
-        """
-        self._result: T | UndefinedType = Undefined
-        self._exception: (
-            BaseException | type[BaseException] | UndefinedType
-        ) = Undefined
-        self._done: bool = False
-        self._cancelled: bool = False
-
-    def __await__(self) -> Generator[Any, None, T]:
-        """
-        Await the completion of the future.
-
-        :return: The result of the future.
-        """
-
-        async def _():
-            while not self.done():
-                await asyncio.sleep(0)
-            else:
-                return self.result()
-
-        return _().__await__()
-
-    def result(self) -> T:
-        """
-        Retrieve the result of the future.
-
-        :return: The result of the future.
-        :raises BaseException: If the future completed with an exception.
-        :raises asyncio.InvalidStateError: If the future is not yet completed.
-        """
-        if self._exception is not Undefined:
-            assert (
-                isinstance(self._exception, BaseException)
-                or isinstance(self._exception, type)
-                and issubclass(self._exception, BaseException)
-            )
-            raise self._exception
-        elif self._result is not Undefined:
-            return cast(T, self._result)
-        else:
-            raise asyncio.InvalidStateError
-
-    def set_result(self, result: T) -> None:
-        """
-        Set the result of the future.
-
-        :param result: The result to set.
-        :raises asyncio.InvalidStateError: If the future is already completed.
-        """
-        if self.done():
-            raise asyncio.InvalidStateError
-        else:
-            self._result = result
-            self._done = True
-
-    def exception(self) -> BaseException | type[BaseException]:
-        """
-        Retrieve the exception of the future, if any.
-
-        :return: The exception of the future.
-        :raises asyncio.InvalidStateError: If the future is not yet completed
-            or has no exception.
-        """
-        if self.done() and self._exception is not Undefined:
-            return cast(BaseException | type[BaseException], self._exception)
-        else:
-            raise asyncio.InvalidStateError
-
-    def set_exception(
-        self, exception: BaseException | type[BaseException]
-    ) -> None:
-        """
-        Set the exception of the future.
-
-        :param exception: The exception to set.
-        :raises asyncio.InvalidStateError: If the future is already completed.
-        """
-        if self.done():
-            raise asyncio.InvalidStateError
-        else:
-            self._exception = exception
-            self._done = True
-
-    def done(self) -> bool:
-        """
-        Check if the future is completed.
-
-        :return: True if the future is completed, False otherwise.
-        """
-        return self._done
-
-    def cancel(self) -> None:
-        """
-        Cancel the future.
-
-        :raises asyncio.InvalidStateError: If the future is already completed.
-        """
-        if self.done():
-            raise asyncio.InvalidStateError
-        else:
-            self._cancelled = True
-            self._done = True
-
-    def cancelled(self) -> bool:
-        """
-        Check if the future was cancelled.
-
-        :return: True if the future was cancelled, False otherwise.
-        """
-        return self._cancelled
-
-
-async def poll(future: Future, task: concurrent.futures.Future) -> None:
-    while True:
-        if future.cancelled():
-            task.cancel()
-            return
-        elif future.done():
-            return
-        else:
-            await asyncio.sleep(0)
-
-
-def fulfill(future: Future):
-    def callback(task: concurrent.futures.Future):
-        try:
-            result = task.result()
-        except concurrent.futures.CancelledError:
-            if not future.done():
-                future.cancel()
-        except BaseException as e:
-            logging.exception(e)
-            future.set_exception(e)
-        else:
-            if not future.done():
-                future.set_result(result)
-
-    return callback

wool/_logging.py

@@ -1,44 +0,0 @@
-import logging
-import os
-
-
-def grey(text: str) -> str:
-    return f"\x1b[90m{text}\x1b[0m"
-
-
-def italic(text: str) -> str:
-    return f"\x1b[3m{text}\x1b[0m"
-
-
-class WoolLogFilter(logging.Filter):
-    def filter(self, record: logging.LogRecord) -> bool:
-        """
-        Modify the log record to include a reference to the source file and
-        line number.
-
-        :param record: The log record to modify.
-        :return: True to indicate the record should be logged.
-        """
-        pathname: str = record.pathname
-        cwd: str = os.getcwd()
-        if pathname.startswith(cwd):
-            record.ref = f"{os.path.relpath(pathname, cwd)}:{record.lineno}"
-        else:
-            record.ref = f".../{os.path.basename(pathname)}:{record.lineno}"
-        return True
-
-
-__log_format__: str = (
-    f"{grey(italic('pid:'))}%(process)-8d "
-    f"{grey(italic('process:'))}%(processName)-12s "
-    f"{grey(italic('thread:'))}%(threadName)-20s "
-    "%(levelname)12s %(message)-60s "
-    f"{grey(italic('%(ref)s'))}"
-)
-
-formatter: logging.Formatter = logging.Formatter(__log_format__)
-
-handler: logging.StreamHandler = logging.StreamHandler()
-handler.setFormatter(formatter)
-handler.addFilter(WoolLogFilter())
-logging.getLogger().addHandler(handler)