{"id":2330,"library":"txaio","title":"txaio","description":"txaio provides a compatibility API between Python's asyncio and Twisted frameworks, allowing developers to write backend-agnostic asynchronous code. It is currently at version 25.12.2 and sees active development with regular releases, often preceded by nightly builds.","status":"active","version":"25.12.2","language":"en","source_language":"en","source_url":"https://github.com/crossbario/txaio","tags":["async","asyncio","twisted","compatibility","utility","concurrency"],"install":[{"cmd":"pip install txaio","lang":"bash","label":"Latest stable version"}],"dependencies":[{"reason":"Required if using the Twisted backend via `txaio.use_twisted()`.","package":"Twisted","optional":true}],"imports":[{"symbol":"txaio","correct":"import txaio"},{"note":"The backend selection (`use_asyncio` or `use_twisted`) should be called once, typically at application startup, using `txaio.<backend_selector>()` after `import txaio`.","wrong":"from txaio import use_asyncio; use_asyncio()","symbol":"use_asyncio","correct":"import txaio\ntxaio.use_asyncio()"},{"symbol":"with_config","correct":"from txaio import with_config"},{"symbol":"make_logger","correct":"from txaio import make_logger"},{"symbol":"start_logging","correct":"from txaio import start_logging"}],"quickstart":{"code":"import txaio\nimport asyncio\n\n# 1. Initialize txaio with the desired backend (must be called once at application startup)\ntxaio.use_asyncio()\n\n# 2. Start txaio's logging system (optional, but good practice)\ntxaio.start_logging(level='info')\nlog = txaio.make_logger()\n\n# 3. Define a backend-agnostic asynchronous function\n@txaio.with_config\nasync def my_async_function(name: str):\n    log.info(f\"Hello from {name} using the {txaio.native_framework_name()} backend!\")\n    await txaio.sleep(0.1)\n    log.info(f\"Goodbye from {name}.\")\n    return f\"Completed {name}\"\n\n# 4. Run the function using the native event loop\nasync def main():\n    result = await my_async_function(\"txaio_example\")\n    print(f\"Function returned: {result}\")\n\nif __name__ == \"__main__\":\n    # This uses asyncio.run() since we configured txaio for asyncio\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to initialize `txaio` with the `asyncio` backend, set up logging, and define a simple asynchronous function using the `@txaio.with_config` decorator to make it backend-agnostic. The function then uses `txaio.sleep` and a `txaio` logger, and is run using `asyncio.run()`."},"warnings":[{"fix":"Ensure `txaio.use_asyncio()` or `txaio.use_twisted()` is the first `txaio` function called in your application's entry point.","message":"The backend must be selected exactly once at application startup using either `txaio.use_asyncio()` or `txaio.use_twisted()`. Calling it multiple times, or calling it late after other txaio operations, can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update calls to `txaio.create_future` to `txaio.create_defer` and `txaio.is_future` to `txaio.is_defer` when working with the Twisted backend.","message":"In `v22.1.1`, the functions `txaio.create_future` and `txaio.is_future` were renamed to `txaio.create_defer` and `txaio.is_defer` respectively, specifically when `txaio.use_twisted()` is in effect. Code written for older versions targeting Twisted will break.","severity":"breaking","affected_versions":">=22.1.1"},{"fix":"Decide on a single backend (asyncio or Twisted) for your `txaio`-managed code and initialize `txaio` accordingly. Avoid attempts to dynamically switch or mix `txaio` backends within the same runtime context.","message":"txaio provides a compatibility layer for *one* selected backend at a time (either asyncio or Twisted). It is not designed to seamlessly interoperate between both backends within the same application scope simultaneously. All `txaio` operations will adapt to the single selected backend.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}