wool 0.1rc20__py3-none-any.whl

wool/core/worker/service.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from typing import AsyncIterator
+
+import cloudpickle
+from grpc import StatusCode
+from grpc.aio import ServicerContext
+
+import wool
+from wool._work import WoolTask
+from wool._work import WoolTaskEvent
+from wool.core import protobuf as pb
+
+
+class ReadOnlyEvent:
+    """A read-only wrapper around :class:`asyncio.Event`.
+
+    Provides access to check if an event is set and wait for it to be
+    set, but prevents external code from setting or clearing the event.
+
+    :param event:
+        The underlying :class:`asyncio.Event` to wrap.
+    """
+
+    def __init__(self, event: asyncio.Event):
+        self._event = event
+
+    def is_set(self) -> bool:
+        """Check if the event is set.
+
+        :returns:
+            ``True`` if the event is set, ``False`` otherwise.
+        """
+        return self._event.is_set()
+
+    async def wait(self) -> None:
+        """Wait until the underlying event is set."""
+        await self._event.wait()
+
+
+class WorkerService(pb.worker.WorkerServicer):
+    """gRPC service for task execution.
+
+    Implements the worker gRPC interface for receiving and executing
+    tasks. Runs tasks in the current asyncio event loop and streams
+    results back to the client.
+
+    Handles graceful shutdown by rejecting new tasks while allowing
+    in-flight tasks to complete. Exposes :attr:`stopping` and
+    :attr:`stopped` events for lifecycle monitoring.
+    """
+
+    _tasks: set[asyncio.Task]
+    _stopped: asyncio.Event
+    _stopping: asyncio.Event
+    _task_completed: asyncio.Event
+
+    def __init__(self):
+        self._stopped = asyncio.Event()
+        self._stopping = asyncio.Event()
+        self._task_completed = asyncio.Event()
+        self._tasks = set()
+
+    @property
+    def stopping(self) -> ReadOnlyEvent:
+        """Read-only event signaling that the service is stopping.
+
+        :returns:
+            A :class:`ReadOnlyEvent`.
+        """
+        return ReadOnlyEvent(self._stopping)
+
+    @property
+    def stopped(self) -> ReadOnlyEvent:
+        """Read-only event signaling that the service has stopped.
+
+        :returns:
+            A :class:`ReadOnlyEvent`.
+        """
+        return ReadOnlyEvent(self._stopped)
+
+    async def dispatch(
+        self, request: pb.task.Task, context: ServicerContext
+    ) -> AsyncIterator[pb.worker.Response]:
+        """Execute a task in the current event loop.
+
+        Deserializes the incoming task into a :class:`WoolTask`
+        instance, schedules it for execution in the current asyncio
+        event loop, and yields responses for acknowledgment and result.
+
+        :param request:
+            The protobuf task message containing the serialized task
+            data.
+        :param context:
+            The :class:`grpc.aio.ServicerContext` for this request.
+        :yields:
+            First yields an Ack Response when task processing begins,
+            then yields a Response containing the task result.
+
+        .. note::
+            Emits a :class:`WoolTaskEvent` when the task is
+            scheduled for execution.
+        """
+        if self._stopping.is_set():
+            await context.abort(
+                StatusCode.UNAVAILABLE, "Worker service is shutting down"
+            )
+
+        with self._tracker(WoolTask.from_protobuf(request)) as task:
+            try:
+                yield pb.worker.Response(ack=pb.worker.Ack())
+                try:
+                    result = pb.task.Result(dump=cloudpickle.dumps(await task))
+                    yield pb.worker.Response(result=result)
+                except Exception as e:
+                    exception = pb.task.Exception(dump=cloudpickle.dumps(e))
+                    yield pb.worker.Response(exception=exception)
+            except asyncio.CancelledError as e:
+                exception = pb.task.Exception(dump=cloudpickle.dumps(e))
+                yield pb.worker.Response(exception=exception)
+
+    async def stop(
+        self, request: pb.worker.StopRequest, context: ServicerContext | None
+    ) -> pb.worker.Void:
+        """Stop the worker service and its thread.
+
+        Gracefully shuts down the worker thread and signals the server
+        to stop accepting new requests. This method is idempotent and
+        can be called multiple times safely.
+
+        :param request:
+            The protobuf stop request containing the wait timeout.
+        :param context:
+            The :class:`grpc.aio.ServicerContext` for this request.
+        :returns:
+            An empty protobuf response indicating completion.
+        """
+        if self._stopping.is_set():
+            return pb.worker.Void()
+        await self._stop(timeout=request.timeout)
+        return pb.worker.Void()
+
+    @contextmanager
+    def _tracker(self, wool_task: WoolTask):
+        """Context manager for tracking running tasks.
+
+        Manages the lifecycle of a task execution, adding it to the
+        active tasks set and emitting appropriate events. Ensures
+        proper cleanup when the task completes or fails.
+
+        :param wool_task:
+            The :class:`WoolTask` instance to execute and track.
+        :yields:
+            The :class:`asyncio.Task` created for the wool task.
+
+        .. note::
+            Emits a :class:`WoolTaskEvent` with type "task-scheduled"
+            when the task begins execution.
+        """
+        WoolTaskEvent("task-scheduled", task=wool_task).emit()
+        task = asyncio.create_task(wool_task.run())
+        self._tasks.add(task)
+        try:
+            yield task
+        finally:
+            self._tasks.remove(task)
+
+    async def _stop(self, *, timeout: float | None = 0) -> None:
+        self._stopping.set()
+        await self._await_or_cancel_tasks(timeout=timeout)
+        try:
+            if proxy_pool := wool.__proxy_pool__.get():
+                await proxy_pool.clear()
+        finally:
+            self._stopped.set()
+
+    async def _await_or_cancel_tasks(self, *, timeout: float | None = 0) -> None:
+        """Stop the worker service gracefully.
+
+        Gracefully shuts down the worker service by canceling or waiting
+        for running tasks. This method is idempotent and can be called
+        multiple times safely.
+
+        :param timeout:
+            Maximum time to wait for tasks to complete. If 0 (default),
+            tasks are canceled immediately. If None, waits indefinitely.
+            If a positive number, waits for that many seconds before
+            canceling tasks.
+
+        .. note::
+            If a timeout occurs while waiting for tasks to complete,
+            the method recursively calls itself with a timeout of 0
+            to cancel all remaining tasks immediately.
+        """
+        if self._tasks and timeout == 0:
+            await self._cancel(*self._tasks)
+        elif self._tasks:
+            try:
+                await asyncio.wait_for(
+                    asyncio.gather(*self._tasks, return_exceptions=True),
+                    timeout=timeout,
+                )
+            except asyncio.TimeoutError:
+                return await self._await_or_cancel_tasks(timeout=0)
+
+    async def _cancel(self, *tasks: asyncio.Task):
+        """Cancel multiple tasks safely.
+
+        Cancels the provided tasks while performing safety checks to
+        avoid canceling the current task or already completed tasks.
+        Waits for all cancelled tasks to complete in parallel and handles
+        cancellation exceptions.
+
+        :param tasks:
+            The :class:`asyncio.Task` instances to cancel.
+
+        .. note::
+            This method performs the following safety checks:
+            - Avoids canceling the current task (would cause deadlock)
+            - Only cancels tasks that are not already done
+            - Properly handles :exc:`asyncio.CancelledError`
+              exceptions.
+        """
+        current = asyncio.current_task()
+        to_cancel = [task for task in tasks if not task.done() and task != current]
+        for task in to_cancel:
+            task.cancel()
+        if to_cancel:
+            await asyncio.gather(*to_cancel, return_exceptions=True)

wool-0.1rc20.dist-info/METADATA

@@ -0,0 +1,463 @@
+Metadata-Version: 2.4
+Name: wool
+Version: 0.1rc20
+Summary: A Python framework for distributed multiprocessing.
+Author-email: Conrad Bzura <conrad@wool.io>
+Maintainer-email: maintainers@wool.io
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright 2025 Wool Labs LLC
+        
+           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.
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.11
+Requires-Dist: cloudpickle
+Requires-Dist: grpcio>=1.76.0
+Requires-Dist: portalocker
+Requires-Dist: protobuf
+Requires-Dist: shortuuid
+Requires-Dist: tblib
+Requires-Dist: typing-extensions
+Requires-Dist: watchdog
+Requires-Dist: zeroconf
+Provides-Extra: dev
+Requires-Dist: debugpy; extra == 'dev'
+Requires-Dist: hypothesis; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-grpc-aio~=0.3.0; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+![](https://raw.githubusercontent.com/wool-labs/wool/refs/heads/main/assets/woolly-transparent-bg-2048.png)
+
+**Wool** is a native Python package for transparently executing tasks in a horizontally scalable, distributed network of agnostic worker processes. Any picklable async function or method can be converted into a task with a simple decorator and a client connection.
+
+## Installation
+
+### Using pip
+
+To install the package using pip, run the following command:
+
+```sh
+pip install --pre wool
+```
+
+### Cloning from GitHub
+
+To install the package by cloning from GitHub, run the following commands:
+
+```sh
+git clone https://github.com/wool-labs/wool.git
+cd wool
+pip install ./wool
+```
+
+## Features
+
+### Declaring tasks
+
+Wool tasks are coroutine functions that are executed in a remote `asyncio` event loop within a worker process. To declare a task, use the `@wool.task` decorator:
+
+```python
+import wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+```
+
+Tasks must be picklable, stateless, and idempotent. Avoid passing unpicklable objects as arguments or return values.
+
+### Worker pools
+
+Worker pools are responsible for executing tasks. Wool provides two types of pools:
+
+#### Ephemeral pools
+
+Ephemeral pools are created and destroyed within the scope of a context manager. Use `wool.pool` to declare an ephemeral pool:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.pool():
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+#### Durable pools
+
+Durable pools are started independently and persist beyond the scope of a single application. Use the `wool` CLI to manage durable pools:
+
+```bash
+wool pool up --port 5050 --authkey deadbeef --module tasks
+```
+
+Connect to a durable pool using `wool.session`:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.session(port=5050, authkey=b"deadbeef"):
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+### CLI commands
+
+Wool provides a command-line interface (CLI) for managing worker pools.
+
+#### Start the worker pool
+
+```sh
+wool pool up --host <host> --port <port> --authkey <authkey> --breadth <breadth> --module <module>
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (default: `0`).
+- `--authkey`: The authentication key (default: `b""`).
+- `--breadth`: The number of worker processes (default: number of CPU cores).
+- `--module`: Python module containing Wool task definitions (optional, can be specified multiple times).
+
+#### Stop the worker pool
+
+```sh
+wool pool down --host <host> --port <port> --authkey <authkey> --wait
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (required).
+- `--authkey`: The authentication key (default: `b""`).
+- `--wait`: Wait for in-flight tasks to complete before shutting down.
+
+#### Ping the worker pool
+
+```sh
+wool ping --host <host> --port <port> --authkey <authkey>
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (required).
+- `--authkey`: The authentication key (default: `b""`).
+
+### Advanced usage
+
+#### Nested pools and sessions
+
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts:
+
+```python
+import wool
+
+@wool.task
+async def task_a():
+    await asyncio.sleep(1)
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
+async def main():
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
+
+asyncio.run(main())
+```
+
+In this example, `task_a` is executed by two different pools, while `task_b` is executed by the pool on port 5050.
+
+### Best practices
+
+#### Sizing worker pools
+
+When configuring worker pools, it is important to balance the number of processes with the available system resources:
+
+- **CPU-bound tasks**: Size the worker pool to match the number of CPU cores. This is the default behavior when spawning a pool.
+- **I/O-bound tasks**: For workloads involving significant I/O, consider oversizing the pool slightly to maximize the system's I/O capacity utilization.
+- **Mixed workloads**: Monitor memory usage and system load to avoid oversubscription, especially for memory-intensive tasks. Use profiling tools to determine the optimal pool size.
+
+#### Defining tasks
+
+Wool tasks are coroutine functions that execute asynchronously in a remote `asyncio` event loop. To ensure smooth execution and scalability, prioritize:
+
+- **Picklability**: Ensure all task arguments and return values are picklable. Avoid passing unpicklable objects such as open file handles, database connections, or lambda functions.
+- **Statelessness and idempotency**: Design tasks to be stateless and idempotent. Avoid relying on global variables or shared mutable state. This ensures predictable behavior and safe retries.
+- **Non-blocking operations**: To achieve higher concurrency, avoid blocking calls within tasks. Use `asyncio`-compatible libraries for I/O operations.
+- **Inter-process synchronization**: Use Wool's synchronization primitives (e.g., `wool.locking`) for inter-worker and inter-pool coordination. Standard `asyncio` primitives will not behave as expected in a multi-process environment.
+
+#### Debugging and logging
+
+- Enable detailed logging during development to trace task execution and worker pool behavior:
+  ```python
+  import logging
+  logging.basicConfig(level=logging.DEBUG)
+  ```
+- Use Wool's built-in logging configuration to capture worker-specific logs.
+
+#### Nested pools and sessions
+
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts. This is useful for workflows requiring task segregation or resource isolation.
+
+Example:
+```python
+import asyncio, wool
+
+@wool.task
+async def task_a():
+    await asyncio.sleep(1)
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
+async def main():
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
+
+asyncio.run(main())
+```
+
+#### Performance optimization
+
+- Minimize the size of arguments and return values to reduce serialization overhead.
+- For large datasets, consider using shared memory or passing references (e.g., file paths) instead of transferring the entire data.
+- Profile tasks to identify and optimize performance bottlenecks.
+
+#### Task cancellation
+
+- Handle task cancellations gracefully by cleaning up resources and rolling back partial changes.
+- Use `asyncio.CancelledError` to detect and respond to cancellations.
+
+#### Error propagation
+
+- Wool propagates exceptions raised within tasks to the caller. Use this feature to handle errors centrally in your application.
+
+Example:
+```python
+try:
+    result = await some_task()
+except Exception as e:
+    print(f"Task failed with error: {e}")
+```
+
+## License
+
+This project is licensed under the Apache License Version 2.0.