Genro ASGI

A minimal, stable ASGI foundation - framework-agnostic toolkit for building high-performance web services.

Overview

Genro ASGI provides a minimal, production-ready ASGI foundation built on Python's standard library. It offers essential components for building web services without the overhead of a full framework.

Key Features

• Zero Dependencies: Built entirely on Python stdlib (optional orjson for fast JSON)
• Framework-Agnostic: Use as a foundation or integrate with existing frameworks
• Production-Ready: Minimal, tested, and stable
• Type-Safe: Full type hints for better IDE support
• Essential Components:
  • Core ASGI application
  • Request/Response utilities
  • Lifespan management
  • Essential middleware (CORS, errors, compression, static files)

Installation

# Basic installation (stdlib only)
pip install genro-asgi

# With fast JSON support
pip install genro-asgi[json]

# Development installation
pip install genro-asgi[dev]

Quick Start

Basic Application

from genro_asgi import Application

app = Application()

# Run with uvicorn
# uvicorn app:app

With Request/Response

from genro_asgi import Application, Request, JSONResponse

app = Application()

async def handler(scope, receive, send):
    request = Request(scope)

    # Process request
    data = {"message": "Hello from Genro ASGI", "path": request.path}

    # Send response
    response = JSONResponse(data)
    await response.send(send)

With Middleware

from genro_asgi import Application
from genro_asgi.middleware import CORSMiddleware, ErrorMiddleware

app = Application()

# Wrap with middleware
app = ErrorMiddleware(app, debug=True)
app = CORSMiddleware(app, allow_origins=["*"])

Lifespan Events

from genro_asgi import Application, Lifespan

lifespan = Lifespan()

@lifespan.on_startup
async def startup():
    print("Application starting...")

@lifespan.on_shutdown
async def shutdown():
    print("Application shutting down...")

Architecture

Genro ASGI is designed around these principles:

1. Minimalism: Only essential features, nothing more
2. Composability: Mix and match components as needed
3. Stdlib-First: Avoid external dependencies when possible
4. Type Safety: Full type hints throughout

Core Components

• Application: ASGI application core with routing
• Request: Convenient access to ASGI scope
• Response: Response classes (JSON, HTML, PlainText)
• Lifespan: Startup/shutdown event management
• Middleware: Essential middleware collection

Documentation

Full documentation available at: https://genro-asgi.readthedocs.io

Development

Setup

# Clone repository
git clone https://github.com/genropy/genro-asgi.git
cd genro-asgi

# Install in development mode
pip install -e .[dev]

Testing

# Run tests
pytest

# With coverage
pytest --cov=genro_asgi --cov-report=html

Code Quality

# Format code
black src tests

# Lint code
ruff check .

# Type check
mypy src

License

This project is licensed under the Apache License 2.0.

Copyright © 2025 Softwell S.r.l.

You may obtain a copy of the license at:

https://www.apache.org/licenses/LICENSE-2.0

This project may include third-party components distributed under separate open-source licenses. See the NOTICE file for additional attribution.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Links

• GitHub: https://github.com/genropy/genro-asgi
• PyPI: https://pypi.org/project/genro-asgi/
• Documentation: https://genro-asgi.readthedocs.io
• Issue Tracker: https://github.com/genropy/genro-asgi/issues

Credits

Developed by Softwell S.r.l.