Greenback

Warnings

• gotcha Greenback works by manipulating the C stack via `greenlet`. Poorly-behaved C extension modules that violate Python's assumption that objects are fully heap-allocated might crash when used with `greenback`.
  Fix: Thoroughly test C extension modules when used in a `greenback`-enabled context. Such issues often indicate a bug in the extension module itself, which `greenback` merely exposes.
• gotcha Calling `greenback.await_()` inside Python finalizers (`__del__` methods), signal handlers, or weakref callbacks is explicitly unsupported and can lead to unexpected behavior or crashes.
  Fix: Avoid using `greenback.await_()` in these specific contexts. Refactor your code to perform async operations outside of finalizers, signal handlers, or weakref callbacks.
• gotcha Setting up a `greenback` portal (e.g., via `await greenback.ensure_portal()`) incurs a minor performance overhead for the task it's enabled on, as each task step passes through `greenback`.
  Fix: Use `greenback.with_portal_run()` or `greenback.with_portal_run_sync()` to explicitly scope the portal's lifetime to only the necessary portion of a task, minimizing performance impact.
• gotcha The `greenback.with_portal_run_tree()` and other portal propagation functions designed for child tasks only work with the `Trio` event loop, not with `asyncio`, due to `asyncio`'s different task model and lack of necessary instrumentation features.
  Fix: When using `asyncio`, you must explicitly call `await greenback.ensure_portal()` in each task that intends to use `greenback.await_()`. Do not rely on automatic portal propagation for `asyncio`.

Install

• pip install greenback Install stable version

Imports

• greenback

  import greenback

  Primary import for all functionalities.
• ensure_portal

  await greenback.ensure_portal()

  Must be awaited as it sets up the greenlet context within an async task.
• await_

  greenback.await_(async_function())

  Used to 'await' an async function from a synchronous context where `await` keyword is not allowed.
• with_portal_run_sync

  greenback.with_portal_run_sync(sync_function)

  Runs a synchronous function with a portal, useful for scoping performance impact.

Quickstart

This quickstart demonstrates how to use `greenback` to call an `async` function (`fetch_data`) from a regular `sync` function (`process_item`, `another_sync_task`) within an `asyncio` event loop. First, `await greenback.ensure_portal()` is called in the main async task to set up the necessary `greenlet` context. Then, `greenback.await_()` is used in the synchronous functions to execute the async calls. The `with_portal_run_sync` helper is also shown for explicit portal scoping.

import asyncio
import greenback

# An async function we want to call from sync code
async def fetch_data(item_id):
    print(f"[Async] Fetching data for {item_id}...")
    await asyncio.sleep(0.1) # Simulate I/O
    return f"Data for {item_id}"

# A synchronous function that needs to call an async function
def process_item(item_id):
    print(f"[Sync] Processing item {item_id}")
    # Call the async function from sync context using greenback.await_
    data = greenback.await_(fetch_data(item_id))
    print(f"[Sync] Received: {data}")
    return data

# The main async entry point
async def main():
    # Ensure a greenback portal is set up for this task
    await greenback.ensure_portal()
    print("Portal ensured.")

    # Call the synchronous function that will use greenback
    result = process_item("A123")
    print(f"Main task received: {result}")

    # Example using with_portal_run_sync
    def another_sync_task():
        print("[Sync 2] Starting another sync task.")
        result2 = greenback.await_(fetch_data("B456"))
        print(f"[Sync 2] Got: {result2}")
        return result2

    final_result = greenback.with_portal_run_sync(another_sync_task)
    print(f"Main task got final result: {final_result}")

if __name__ == "__main__":
    asyncio.run(main())