Response

HTTP response classes.

HTTP Response class with auto content-type detection and TYTX support.

Classes:
Response — created by Request, configured via set_result(). Auto-detects

content type (JSON, file, bytes, text). TYTX serialization when request.tytx_mode is active.

Functions:

make_cookie(key, value, **options) — creates Set-Cookie header tuple.

class genro_asgi.response.Response(content=None, status_code=200, headers=None, media_type=None, request=None)[source]

Bases: object

Base HTTP response class.

Sends bytes or string content with headers through the ASGI interface. Implements __call__ to be usable as an ASGI application.

Can be created empty and configured via set_header/set_result before sending.

body

Encoded response body as bytes.

status_code

HTTP status code.

media_type

Content-Type media type (may include charset).

Example

>>> response = Response(content="Hello", media_type="text/plain")
>>> await response(scope, receive, send)

# Or create empty and configure: >>> response = Response() >>> response.set_header(“X-Custom”, “value”) >>> response.set_result({“data”: 123}) # auto-detects JSON >>> await response(scope, receive, send)

ERROR_MAP: dict[str, int] = {'FileNotFoundError': 404, 'NotAuthorized': 403, 'NotFound': 404, 'PermissionError': 403, 'TypeError': 400, 'ValueError': 400}
__init__(content=None, status_code=200, headers=None, media_type=None, request=None)[source]

Initialize response.

Parameters:

  • content (bytes | str | None) – Response body (bytes, string, or None).

  • status_code (int) – HTTP status code (default 200).

  • headers (Mapping[str, str] | list[tuple[str, str]] | None) – Response headers as dict or list of tuples.

  • media_type (str | None) – Content-Type media type (overrides class default).

Note

HTTP status codes 204 (No Content) and 304 (Not Modified) must not have body content per RFC 7230. If you provide content with these status codes, the ASGI server may reject or truncate the response.

body
charset: str = 'utf-8'
media_type: str | None = None
request
set_error(error)[source]

Set response as error from exception.

Maps exception type to HTTP status code using ERROR_MAP. Unknown exceptions default to 500 and are logged.

Parameters:

error (Exception) – The exception to convert to error response.

Return type:

None

set_header(name, value)[source]

Set a response header. Can be called before set_result.

Return type:

None

set_result(result, metadata=None)[source]

Set response body from result.

Uses _guess_mime_type() to determine content type. Falls back to type-based defaults: - dict/list: application/json (or TYTX if request.tytx_mode) - Path: from extension - bytes: application/octet-stream - str: text/plain - None: text/plain (empty body) - other: text/plain (str conversion)

Parameters:

  • result (Any) – The handler result to set as response body.

  • metadata (dict[str, Any] | None) – Route metadata dict. Uses mime_type if present.

Return type:

None

status_code

Create a Set-Cookie header tuple.

This is a helper function for creating cookie headers without modifying the immutable Response object. The returned tuple can be passed directly to Response headers.

Note

Design Decision - Module-level function vs method

This is a module-level function (not a Response method) to preserve Response immutability. Response objects are “frozen” after construction - all headers must be provided at creation time. A response.set_cookie() method would violate this principle by modifying headers after construction.

Using make_cookie() the user creates cookie tuples BEFORE constructing the Response, keeping the Response immutable and predictable.

Parameters:

  • key (str) – Cookie name.

  • value (str) – Cookie value (will be URL-encoded).

  • max_age (int | None) – Max age in seconds. None means session cookie.

  • path (str) – Cookie path (default “/”).

  • domain (str | None) – Cookie domain. None means current domain only.

  • secure (bool) – If True, cookie only sent over HTTPS.

  • httponly (bool) – If True, cookie not accessible via JavaScript.

  • samesite (str | None) – SameSite policy (“strict”, “lax”, “none”, or None to omit).

Return type:

tuple[str, str]

Returns:

Tuple of (“set-cookie”, cookie_string) for use in Response headers.

Example

>>> from genro_asgi import Response, make_cookie
>>> response = Response(
...     content="OK",
...     headers=[
...         make_cookie("session", "abc123", httponly=True, secure=True),
...         make_cookie("prefs", "dark", max_age=31536000),
...     ]
... )