asyncer 0__py3-none-any.whl

asyncer/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.0.4"
+
+from ._main import PendingValueException as PendingValueException
+from ._main import SoonValue as SoonValue
+from ._main import TaskGroup as TaskGroup
+from ._main import asyncify as asyncify
+from ._main import create_task_group as create_task_group
+from ._main import runnify as runnify
+from ._main import syncify as syncify

asyncer/_main.py

@@ -0,0 +1,362 @@
+import functools
+import sys
+from importlib import import_module
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Coroutine,
+    Dict,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+)
+
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
+else:
+    from typing_extensions import ParamSpec
+
+import anyio
+import sniffio
+from anyio._core._eventloop import threadlocals
+from anyio.abc import TaskGroup as _TaskGroup
+
+
+# This was obtained with: from anyio._core._eventloop import get_asynclib
+# Removed in https://github.com/agronholm/anyio/pull/429
+# First release (not released yet): 4.0-dev
+def get_asynclib(asynclib_name: Union[str, None] = None) -> Any:
+    if asynclib_name is None:
+        asynclib_name = sniffio.current_async_library()
+
+    modulename = "anyio._backends._" + asynclib_name
+    try:
+        return sys.modules[modulename]
+    except KeyError:  # pragma: no cover
+        return import_module(modulename)
+
+
+T_Retval = TypeVar("T_Retval")
+T_ParamSpec = ParamSpec("T_ParamSpec")
+T = TypeVar("T")
+
+
+class PendingType:
+    def __repr__(self) -> str:
+        return "AsyncerPending"
+
+
+Pending = PendingType()
+
+
+class PendingValueException(Exception):
+    pass
+
+
+class SoonValue(Generic[T]):
+    def __init__(self) -> None:
+        self._stored_value: Union[T, PendingType] = Pending
+
+    @property
+    def value(self) -> T:
+        if isinstance(self._stored_value, PendingType):
+            raise PendingValueException(
+                "The return value of this task is still pending. Maybe you forgot to "
+                "access it after the async with asyncer.create_task_group() block. "
+                "If you need to access values of async tasks inside the same task "
+                "group, you probably need a different approach, for example with "
+                "AnyIO Streams."
+            )
+        return self._stored_value
+
+    @property
+    def ready(self) -> bool:
+        return not isinstance(self._stored_value, PendingType)
+
+
+class TaskGroup(_TaskGroup):
+    def soonify(
+        self, async_function: Callable[T_ParamSpec, Awaitable[T]], name: object = None
+    ) -> Callable[T_ParamSpec, SoonValue[T]]:
+        """
+        Create and return a function that when called will start a new task in this
+        task group.
+
+        Internally it uses the same `task_group.start_soon()` method. But
+        `task_group.soonify()` supports keyword arguments additional to positional
+        arguments and it adds better support for autocompletion and inline errors
+        for the arguments of the function called.
+
+        Use it like this:
+
+        ```Python
+        async with asyncer.create_task_group() as task_group:
+            async def do_work(arg1, arg2, kwarg1="", kwarg2="") -> str:
+                # Do work
+                return "Some result value"
+
+            result = task_group.soonify(do_work)("spam", "ham", kwarg1="a", kwarg2="b")
+
+        print(result.value)
+        ```
+
+        The return value from that function (`result` in the example) is an object
+        `SoonValue`.
+
+        This `SoonValue` object has an attribute `soon_value.value` that will hold the
+        return value of the original `async_function` *after* the `async with` block.
+
+        If you try to access the `soon_value.value` inside the `async with` block,
+        before it has the actual return value, it will raise a an exception
+        `asyncer.PendingValueException`.
+
+        If you think you need to access the return values inside the `async with` block,
+        there's a high chance that you really need a different approach, for example
+        using an AnyIO Stream.
+
+        But either way, if you have checkpoints inside the `async with` block (you have
+        some `await` there), one or more of the `SoonValue` objects you might have
+        could end up having the result value ready before ending the `async with` block.
+        You can check that with `soon_value.pending`. For example:
+
+        ```Python
+        async def do_work(name: str) -> str:
+            return f"Hello {name}"
+
+        async with asyncer.create_task_group() as task_group:
+            result1 = task_group.soonify(do_work)(name="task 1")
+            result2 = task_group.soonify(do_work)(name="task 2")
+            await anyio.sleep(0)
+            if not result1.pending:
+                print(result1.value)
+            if not result2.pending:
+                print(result2.value)
+        ```
+
+
+        ## Arguments
+
+        `async_function`: an async function to call soon
+        `name`: name of the task, for the purposes of introspection and debugging
+
+        ## Return
+
+        A function that takes positional and keyword arguments and when called
+        uses `task_group.start_soon()` to start the task in this task group.
+
+        That function returns a `SoonValue` object holding the return value of the
+        original function in `soon_value.value`.
+        """
+
+        @functools.wraps(async_function)
+        def wrapper(
+            *args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs
+        ) -> SoonValue[T]:
+            partial_f = functools.partial(async_function, *args, **kwargs)
+            soon_value: SoonValue[T] = SoonValue()
+
+            @functools.wraps(partial_f)
+            async def value_wrapper(*args: Any) -> None:
+                value = await partial_f()
+                soon_value._stored_value = value
+
+            self.start_soon(value_wrapper, name=name)
+            return soon_value
+
+        return wrapper
+
+    # This is only for the return type annotation, but it won't really be called
+    async def __aenter__(self) -> "TaskGroup":  # pragma: nocover
+        """Enter the task group context and allow starting new tasks."""
+        return await super().__aenter__()  # type: ignore
+
+
+def create_task_group() -> "TaskGroup":
+    """
+    Create a task group used to start multiple concurrent tasks with async functions.
+
+    `asyncer.create_task_group()` is different from `anyio.create_task_group()` in that
+    it creates an extended `TaskGroup` object that includes the `task_group.soonify()`
+    method.
+    """
+
+    LibTaskGroup = get_asynclib().TaskGroup
+
+    class ExtendedTaskGroup(LibTaskGroup, TaskGroup):  # type: ignore
+        pass
+
+    return ExtendedTaskGroup()
+
+
+def runnify(
+    async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    backend: str = "asyncio",
+    backend_options: Optional[Dict[str, Any]] = None,
+) -> Callable[T_ParamSpec, T_Retval]:
+    """
+    Take an async function and create a regular (blocking) function that receives the
+    same keyword and positional arguments for the original async function, and that when
+    called will create an event loop and use it to run the original `async_function`
+    with those arguments.
+
+    That function returns the return value from the original `async_function`.
+
+    The current thread must not be already running an event loop.
+
+    This calls `anyio.run()` underneath.
+
+    Use it like this:
+
+    ```Python
+    async def program(name: str) -> str:
+        return f"Hello {name}"
+
+
+    result = asyncer.runnify(program)(name="World")
+    print(result)
+    ```
+
+    ## Arguments
+
+    `async_function`: an async function to call
+    `backend`: name of the asynchronous event loop implementation - currently either
+        `asyncio` or `trio`
+    `backend_options` keyword arguments to call the backend `run()` implementation with
+
+    ## Return
+
+    The return value of the async function
+
+    ## Raises
+
+    `RuntimeError`: if an asynchronous event loop is already running in this thread
+    `LookupError`: if the named backend is not found
+    """
+
+    @functools.wraps(async_function)
+    def wrapper(*args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs) -> T_Retval:
+        partial_f = functools.partial(async_function, *args, **kwargs)
+
+        return anyio.run(partial_f, backend=backend, backend_options=backend_options)
+
+    return wrapper
+
+
+def syncify(
+    async_function: Callable[T_ParamSpec, Coroutine[Any, Any, T_Retval]],
+    raise_sync_error: bool = True,
+) -> Callable[T_ParamSpec, T_Retval]:
+    """
+    Take an async function and create a regular one that receives the same keyword and
+    positional arguments, and that when called, calls the original async function in
+    the main async loop from the worker thread using `anyio.to_thread.run()`.
+
+    By default this is expected to be used from a worker thread. For example inside
+    some function passed to `asyncify()`.
+
+    But if you set `raise_sync_error` to `False`, you can also use this function
+    in a non-async context: without an async event loop. For example, from a
+    blocking/regular function called at the top level of a Python file. In that case,
+    if it is not being called from inside a worker thread started from an async context
+    (e.g. this is not called from a function that was called with `asyncify()`) it will
+    run `async_function` in a new async event loop with `anyio.run()`.
+
+    This functionality with `raise_sync_error` is there only to allow using
+    `syncify()` in codebases that are used by async code in some cases and by blocking
+    code in others. For example, during migrations from blocking code to async code.
+
+    Internally, `asyncer.syncify()` uses the same `anyio.from_thread.run()`, but it
+    supports keyword arguments additional to positional arguments and it adds better
+    support for tooling (e.g. editor autocompletion and inline errors) for the
+    arguments and return value of the function.
+
+    Use it like this:
+
+    ```Python
+    async def do_work(arg1, arg2, kwarg1="", kwarg2=""):
+        # Do work
+
+    result = from_thread.syncify(do_work)("spam", "ham", kwarg1="a", kwarg2="b")
+    ```
+
+    ## Arguments
+
+    `async_function`: an async function to be called in the main thread, in the async
+        event loop
+    `raise_sync_error`: If set to `False`, when used in a non-async context (without
+        an async event loop), it will run `async_function` in a new async event loop,
+        instead of raising an exception.
+
+    ## Return
+
+    A regular blocking function that takes the same positional and keyword arguments
+        as the original async one, that when called runs the same original function in
+        the main async loop when called from a worker thread and returns the result.
+    """
+
+    @functools.wraps(async_function)
+    def wrapper(*args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs) -> T_Retval:
+        current_async_module = getattr(threadlocals, "current_async_module", None)
+        partial_f = functools.partial(async_function, *args, **kwargs)
+        if current_async_module is None and raise_sync_error is False:
+            return anyio.run(partial_f)
+        return anyio.from_thread.run(partial_f)
+
+    return wrapper
+
+
+def asyncify(
+    function: Callable[T_ParamSpec, T_Retval],
+    *,
+    cancellable: bool = False,
+    limiter: Optional[anyio.CapacityLimiter] = None,
+) -> Callable[T_ParamSpec, Awaitable[T_Retval]]:
+    """
+    Take a blocking function and create an async one that receives the same
+    positional and keyword arguments, and that when called, calls the original function
+    in a worker thread using `anyio.to_thread.run_sync()`. Internally,
+    `asyncer.asyncify()` uses the same `anyio.to_thread.run_sync()`, but it supports
+    keyword arguments additional to positional arguments and it adds better support for
+    autocompletion and inline errors for the arguments of the function called and the
+    return value.
+
+    If the `cancellable` option is enabled and the task waiting for its completion is
+    cancelled, the thread will still run its course but its return value (or any raised
+    exception) will be ignored.
+
+    Use it like this:
+
+    ```Python
+    def do_work(arg1, arg2, kwarg1="", kwarg2="") -> str:
+            # Do work
+            return "Some result"
+
+    result = await to_thread.asyncify(do_work)("spam", "ham", kwarg1="a", kwarg2="b")
+    print(result)
+    ```
+
+    ## Arguments
+
+    `function`: a blocking regular callable (e.g. a function)
+    `cancellable`: `True` to allow cancellation of the operation
+    `limiter`: capacity limiter to use to limit the total amount of threads running
+        (if omitted, the default limiter is used)
+
+    ## Return
+
+    An async function that takes the same positional and keyword arguments as the
+    original one, that when called runs the same original function in a thread worker
+    and returns the result.
+    """
+
+    async def wrapper(
+        *args: T_ParamSpec.args, **kwargs: T_ParamSpec.kwargs
+    ) -> T_Retval:
+        partial_f = functools.partial(function, *args, **kwargs)
+        return await anyio.to_thread.run_sync(
+            partial_f, cancellable=cancellable, limiter=limiter
+        )
+
+    return wrapper

asyncer-0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Sebastián Ramírez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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.

asyncer-0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.1
+Name: asyncer
+Version: 0
+Summary: Asyncer, async and await, focused on developer experience.
+Home-page: https://github.com/tiangolo/asyncer
+License: MIT
+Author: Sebastián Ramírez
+Author-email: tiangolo@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Trio
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet
+Classifier: Typing :: Typed
+Requires-Dist: anyio (>=3.4.0,<5.0)
+Requires-Dist: typing_extensions (>=4.8.0,<5.0.0) ; python_version < "3.10"
+Project-URL: Documentation, https://asyncer.tiangolo.com
+Project-URL: Repository, https://github.com/tiangolo/asyncer
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://asyncer.tiangolo.com"><img src="https://asyncer.tiangolo.com/img/logo-margin/logo-margin-vector.svg" alt="Asyncer"></a>
+</p>
+<p align="center">
+    <em>Asyncer, async and await, focused on developer experience.</em>
+</p>
+<p align="center">
+<a href="https://github.com/tiangolo/asyncer/actions?query=workflow%3ATest" target="_blank">
+    <img src="https://github.com/tiangolo/asyncer/workflows/Test/badge.svg" alt="Test">
+</a>
+<a href="https://github.com/tiangolo/asyncer/actions?query=workflow%3APublish" target="_blank">
+    <img src="https://github.com/tiangolo/asyncer/workflows/Publish/badge.svg" alt="Publish">
+</a>
+<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/asyncer" target="_blank">
+    <img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/asyncer.svg" alt="Coverage">
+<a href="https://pypi.org/project/asyncer" target="_blank">
+    <img src="https://img.shields.io/pypi/v/asyncer?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+</p>
+
+---
+
+**Documentation**: <a href="https://asyncer.tiangolo.com" target="_blank">https://asyncer.tiangolo.com</a>
+
+**Source Code**: <a href="https://github.com/tiangolo/asyncer" target="_blank">https://github.com/tiangolo/asyncer</a>
+
+---
+
+**Asyncer** is a small library built on top of <a href="https://anyio.readthedocs.io/en/stable/" class="external-link" target="_blank">AnyIO</a>.
+
+**Asyncer** has a small number of utility functions that allow working with `async`, `await`, and concurrent code in a more convenient way under my (<a href="https://twitter.com/tiangolo" class="external-link" target="_blank">@tiangolo - Sebastián Ramírez</a>) very opinionated and subjective point of view.
+
+The main goal of **Asyncer** is to improve **developer experience** by providing better support for **autocompletion** and **inline errors** in the editor, and **more certainty** that the code is **bug-free** by providing better support for type checking tools like **mypy**.
+
+**Asyncer** also tries to improve **convenience** and simplicity when working with **async** code **mixed** with regular <abbr title="synchronous code, code that is not async">**blocking code**</abbr>, allowing to use them together in a simpler way... again, under my very **subjective** point of view.
+
+## 🚨 Warning
+
+This small library only exists to be able to use these **utility functions** until (and if) they are integrated into **AnyIO**.
+
+It will probably take some time for that to happen (or to be decided if it will be included or not).
+
+So I made this to be able to use these ideas right now. 🤓
+
+## Can I Use It?
+
+Yes 🎉 (but continue reading).
+
+You can use this and evaluate the **library API design** I'm proposing. It will probably be useful to know if it works and is useful for you (I hope so).
+
+But still, consider this lab material, expect it to change a bit. 🧪
+
+If you use it, **pin the exact Asyncer version** for your project, to make sure it all works.
+
+Have **tests** for your project (as you should, anyway). And **upgrade the version** once you know that the new version continues to work correctly.
+
+Still, it's **just 4 functions**, so there's not much to change, if you had to refactor your code to update something it would not be much.
+
+And if you don't want to add `asyncer` as a dependency to your project, you can also just copy the main file and try out those functions, it's quite small (but in that case you won't get updates easily).
+
+## Requirements
+
+As **Asyncer** is based on **AnyIO** it will be also installed automatically when you install **Asyncer**.
+
+## Installation
+
+<div class="termy">
+
+```console
+$ pip install asyncer
+---> 100%
+Successfully installed asyncer anyio
+```
+
+</div>
+
+## How to Use
+
+You can read more about each of the use cases and utility functions in **Asyncer** in the <a href="https://asyncer.tiangolo.com/tutorial/" class="external-link" target="_blank">tutorial</a>.
+
+As a sneak preview of one of the utilities, you can **call sync code from async code** using `asyncify()`:
+
+```Python
+import time
+
+import anyio
+from asyncer import asyncify
+
+
+def do_sync_work(name: str):
+    time.sleep(1)
+    return f"Hello, {name}"
+
+
+async def main():
+    message = await asyncify(do_sync_work)(name="World")
+    print(message)
+
+
+anyio.run(main)
+```
+
+**Asyncer**'s `asyncify()` will use AnyIO underneath to do *the smart thing*, avoid blocking the main **async** event loop, and run the **sync**/blocking function in a **worker thread**.
+
+### Editor Support
+
+Everything in **Asyncer** is designed to get the best **developer experience** possible, with the best editor support.
+
+* **Autocompletion** for function arguments:
+
+<img class="shadow" src="https://asyncer.tiangolo.com/img/tutorial/asyncify/image01.png">
+
+* **Autocompletion** for return values:
+
+<img class="shadow" src="https://asyncer.tiangolo.com/img/tutorial/asyncify/image02.png">
+
+* **Inline errors** in editor:
+
+<img class="shadow" src="https://asyncer.tiangolo.com/img/tutorial/soonify/image02.png">
+
+* Support for tools like **mypy**, that can help you verify that your **code is correct**, and prevent many bugs.
+
+## License
+
+This project is licensed under the terms of the [MIT license](https://github.com/tiangolo/asyncer/blob/main/LICENSE).
+

asyncer-0.dist-info/RECORD

@@ -0,0 +1,7 @@
+asyncer/__init__.py,sha256=zwXbjrX3oFTeVasflK20r9_5ilCNF9mlJ8xkvDqpLr8,347
+asyncer/_main.py,sha256=GdSwgl6O8oEA-qVch4DOCKIHUCVbU62czQY9pniWKZI,12826
+asyncer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asyncer-0.dist-info/LICENSE,sha256=S1EnT02PpzNeD8_rIBcSbkGC_9aw6MWKW4myxIlzFIc,1086
+asyncer-0.dist-info/METADATA,sha256=v90P5qxiI0dtjoGUW-f9XmMuC3WM0hGBsVEwbcS5ZfQ,6653
+asyncer-0.dist-info/WHEEL,sha256=FMvqSimYX_P7y0a7UY-_Mc83r5zkBZsCYPm7Lr0Bsq4,88
+asyncer-0.dist-info/RECORD,,

asyncer-0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.8.1
+Root-Is-Purelib: true
+Tag: py3-none-any