a2wsgi

library1.10.10pypypi✓ verified 24d ago

a2wsgi is a Python library that enables seamless conversion between WSGI (Web Server Gateway Interface) and ASGI (Asynchronous Server Gateway Interface) applications. It acts as a middleware, allowing you to run WSGI apps on ASGI servers or ASGI apps on WSGI servers. The current version is 1.10.10, and it maintains an active release schedule with frequent minor updates, primarily focusing on bug fixes and performance improvements.

web-framework http-networking

pip install a2wsgi

github ↗package ↗

INSTALL

IMPORT

SIG · A2WSGI

a2wsgi

web-frameworkpythonv1.10.10

Install

1.6s avg

Import

214ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.10.10 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.226s · 18.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.202s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ASGIMiddleware

✓ from a2wsgi import ASGIMiddleware

WSGIMiddleware

✓ from a2wsgi import WSGIMiddleware

This example demonstrates how to convert a standard synchronous WSGI application into an ASGI application using `ASGIMiddleware`. The resulting `asgi_app` can then be served by any ASGI-compatible web server like Uvicorn.

from a2wsgi import ASGIMiddleware # A simple synchronous WSGI application def wsgi_app(environ, start_response): status = '200 OK' headers = [('Content-type', 'text/plain; charset=utf-8')] start_response(status, headers) return [b"Hello from WSGI!\nRequest Path: " + environ.get('PATH_INFO', '/').encode()] # Convert the WSGI app to an ASGI app asgi_app = ASGIMiddleware(wsgi_app) # To run this converted ASGI app using an ASGI server like Uvicorn: # 1. Save this code as 'app.py' # 2. Install uvicorn: pip install uvicorn # 3. Run from your terminal: uvicorn app:asgi_app --reload # Then open http://127.0.0.1:8000/ in your browser. print("WSGI application 'wsgi_app' successfully wrapped as an ASGI application 'asgi_app'.") print("To serve it, use an ASGI server like Uvicorn (e.g., 'uvicorn app:asgi_app').")

Debug

Known issues

gotchaWSGI applications converted to ASGI via `ASGIMiddleware` still execute synchronously. If your wrapped WSGI app performs blocking I/O operations (e.g., database calls, network requests) directly, it will block the entire ASGI event loop, negating the performance benefits of an async server.

fix

Ensure the WSGI application minimizes blocking I/O or offload such operations to a separate thread pool if absolute necessary. The `a2wsgi` library does not magically make a synchronous app asynchronous.

affects: All versions

gotchaWhen `ASGIMiddleware` converts an ASGI request with a large body to WSGI, it must buffer the entire request body into memory before passing it via `wsgi.input` to the WSGI application. This can lead to significant memory consumption for large file uploads or extensive POST data.

fix

Be mindful of request body sizes when running WSGI apps on ASGI servers. If handling very large bodies is critical, consider refactoring the application to be purely ASGI or use alternative streaming mechanisms where possible.

affects: All versions

gotchaWhen chaining multiple middleware, the order of `a2wsgi` conversion is crucial. You should convert the innermost application to the type expected by the next middleware in the chain. Incorrect ordering can lead to interface mismatches.

fix

Always convert the 'inner' application to the interface required by the 'outer' middleware. For example, to run an ASGI middleware around a WSGI app, first convert the WSGI app to ASGI, then wrap it with the ASGI middleware: `ASGI_Middleware(YOUR_ASGI_MIDDLEWARE(a2wsgi.ASGIMiddleware(your_wsgi_app)))`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'a2wsgi'

The 'a2wsgi' package is not installed in the Python environment.

fix

Install the package using 'pip install a2wsgi'.

ImportError: cannot import name 'WSGIMiddleware' from 'a2wsgi'

The 'a2wsgi' package is installed, but the import statement is incorrect or the package version does not include 'WSGIMiddleware'.

fix

Ensure the import statement is correct: 'from a2wsgi import WSGIMiddleware'. If the error persists, update the package using 'pip install --upgrade a2wsgi'.

TypeError: 'WSGIMiddleware' object is not callable

An instance of 'WSGIMiddleware' is being called as a function, but it is not designed to be called directly.

fix

Ensure that 'WSGIMiddleware' is used to wrap a WSGI application correctly: 'asgi_app = WSGIMiddleware(wsgi_app)'.

AttributeError: module 'a2wsgi' has no attribute 'ASGIMiddleware'

The 'ASGIMiddleware' attribute is not present in the 'a2wsgi' module, possibly due to an outdated package version.

fix

Update the 'a2wsgi' package to the latest version using 'pip install --upgrade a2wsgi'.

ValueError: WSGI application must be a callable object

The object passed to 'WSGIMiddleware' is not a valid WSGI application.

fix

Ensure that the WSGI application passed to 'WSGIMiddleware' is a callable object, typically a function or a class with a '__call__' method.

Upgrade

Version history

1.10.10latest on PyPI · released Jun 18, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

61 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/abersheeran/a2wsgi ↗

packagehttps://pypi.org/project/a2wsgi/ ↗