asgi-tools 1.1.0__cp313-cp313-musllinux_1_2_aarch64.whl → 1.2.0__cp313-cp313-musllinux_1_2_aarch64.whl

asgi_tools/multipart.py

@@ -256,18 +256,18 @@ class MultipartParser(BaseParser):
     """
 
     __slots__ = (
+        "boundary",
+        "boundary_chars",
         "callbacks",
         "cursize",
-        "max_size",
-        "state",
-        "index",
         "flags",
         "header_field_pos",
         "header_value_pos",
-        "part_data_pos",
-        "boundary",
-        "boundary_chars",
+        "index",
         "lookbehind",
+        "max_size",
+        "part_data_pos",
+        "state",
     )
 
     def __init__(self, boundary, callbacks: dict, max_size: int = 0):
@@ -587,6 +587,3 @@ def prune_data(data_len: int, cursize: int, max_size: int) -> int:
         return max_size - cursize
 
     return data_len
-
-
-# ruff: noqa: TRY003

asgi_tools/request.py

@@ -5,7 +5,7 @@ incoming request.
 from __future__ import annotations
 
 from http import cookies
-from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Iterator, Optional, Union
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Iterator, Mapping, Protocol, TypeVar
 
 from yarl import URL
 
@@ -17,11 +17,21 @@ from .types import TJSON, TASGIReceive, TASGIScope, TASGISend
 from .utils import CIMultiDict, parse_headers, parse_options_header
 
 if TYPE_CHECKING:
+    from pathlib import Path
+
     from multidict import MultiDict, MultiDictProxy
 
+T = TypeVar("T")
+
+
+class UploadHandler(Protocol):
+    """Protocol for file upload handlers."""
+
+    async def __call__(self, filename: str, content_type: str, content: bytes) -> str | Path: ...
+
 
 class Request(TASGIScope):
-    """Represent a HTTP Request.
+    """Provides a convenient, high-level interface for incoming HTTP requests.
 
     :param scope: HTTP ASGI Scope
     :param receive: an asynchronous callable which lets the application
@@ -32,16 +42,16 @@ class Request(TASGIScope):
     """
 
     __slots__ = (
-        "scope",
-        "receive",
-        "send",
-        "_is_read",
-        "_url",
         "_body",
+        "_cookies",
         "_form",
         "_headers",
+        "_is_read",
         "_media",
-        "_cookies",
+        "_url",
+        "receive",
+        "scope",
+        "send",
     )
 
     def __init__(self, scope: TASGIScope, receive: TASGIReceive, send: TASGISend):
@@ -51,12 +61,12 @@ class Request(TASGIScope):
         self.send = send
 
         self._is_read: bool = False
-        self._url: Optional[URL] = None
-        self._body: Optional[bytes] = None
-        self._form: Optional[MultiDict] = None
-        self._headers: Optional[CIMultiDict] = None
-        self._media: Optional[dict[str, str]] = None
-        self._cookies: Optional[dict[str, str]] = None
+        self._url: URL | None = None
+        self._body: bytes | None = None
+        self._form: MultiDict | None = None
+        self._headers: CIMultiDict | None = None
+        self._media: dict[str, str] | None = None
+        self._cookies: dict[str, str] | None = None
 
     def __str__(self) -> str:
         """Return the request's params."""
@@ -174,11 +184,11 @@ class Request(TASGIScope):
         return self._cookies
 
     @property
-    def media(self) -> dict[str, str]:
+    def media(self) -> Mapping[str, str]:
         """Prepare a media data for the request."""
         if self._media is None:
-            conten_type_header = self.headers.get("content-type", "")
-            content_type, opts = parse_options_header(conten_type_header)
+            content_type_header = self.headers.get("content-type", "")
+            content_type, opts = parse_options_header(content_type_header)
             self._media = dict(opts, content_type=content_type)
 
         return self._media
@@ -215,16 +225,16 @@ class Request(TASGIScope):
         """
         if self._is_read:
             if self._body is None:
-                raise RuntimeError("Stream has been read")  # noqa: TRY003
+                raise RuntimeError("Stream has been read")
             yield self._body
 
         else:
             self._is_read = True
-            message = await self.receive()
-            yield message.get("body", b"")
-            while message.get("more_body"):
+            while True:
                 message = await self.receive()
                 yield message.get("body", b"")
+                if not message.get("more_body"):
+                    break
 
     async def body(self) -> bytes:
         """Read and return the request's body as bytes.
@@ -232,7 +242,10 @@ class Request(TASGIScope):
         `body = await request.body()`
         """
         if self._body is None:
-            self._body = b"".join([chunk async for chunk in self.stream()])
+            data = bytearray()
+            async for chunk in self.stream():
+                data.extend(chunk)
+            self._body = bytes(data)
 
         return self._body
 
@@ -261,38 +274,38 @@ class Request(TASGIScope):
     async def form(
         self,
         max_size: int = 0,
-        upload_to: Optional[Callable] = None,
+        upload_to: UploadHandler | None = None,
         file_memory_limit: int = 1024 * 1024,
     ) -> MultiDict:
-        """Read and return the request's multipart formdata as a multidict.
-
-        The method reads the request's stream stright into memory formdata.
-        Any subsequent calls to :py:meth:`body`, :py:meth:`json` will raise an error.
+        """Read and return the request's form data.
 
-        :param max_size: The maximum size of the request body in bytes.
-        :param upload_to: A callable to be used to determine the upload path for files.
-        :param file_memory_limit: The maximum size of the file to be stored in memory in bytes.
+        :param max_size: Maximum size of the form data in bytes
+        :type max_size: int
+        :param upload_to: Callable to handle file uploads
+        :type upload_to: Optional[UploadHandler]
+        :param file_memory_limit: Maximum size of file to keep in memory
+        :type file_memory_limit: int
+        :return: Form data as MultiDict
+        :rtype: MultiDict
 
         `formdata = await request.form()`
-
         """
         if self._form is None:
-            try:
-                self._form = await read_formdata(
-                    self,
-                    max_size,
-                    upload_to,
-                    file_memory_limit,
-                )
-            except (LookupError, ValueError) as exc:
-                raise ASGIDecodeError from exc
-
+            self._form = await read_formdata(
+                self,
+                max_size=max_size,
+                upload_to=upload_to,
+                file_memory_limit=file_memory_limit,
+            )
         return self._form
 
-    async def data(self, *, raise_errors: bool = False) -> Union[str, bytes, MultiDict, TJSON]:
-        """The method checks Content-Type Header and parse the request's data automatically.
+    async def data(self, *, raise_errors: bool = False) -> str | bytes | MultiDict | TJSON:
+        """Read and return the request's data based on content type.
 
         :param raise_errors: Raise an error if the given data is invalid.
+        :return: Request data in appropriate format
+        :rtype: Union[str, bytes, MultiDict, TJSON]
+        :raises ASGIDecodeError: If data cannot be decoded and raise_errors is True
 
         `data = await request.data()`
 
@@ -302,14 +315,15 @@ class Request(TASGIScope):
         Returns data from :py:meth:`json` for `application/json`, :py:meth:`form` for
         `application/x-www-form-urlencoded`,  `multipart/form-data` and :py:meth:`text` otherwise.
         """
+        content_type = self.content_type
         try:
-            if self.content_type in {
-                "application/x-www-form-urlencoded",
+            if content_type in {
                 "multipart/form-data",
+                "application/x-www-form-urlencoded",
             }:
                 return await self.form()
 
-            if self.content_type == "application/json":
+            if content_type == "application/json":
                 return await self.json()
 
         except ASGIDecodeError:
@@ -317,5 +331,7 @@ class Request(TASGIScope):
                 raise
             return await self.body()
 
-        else:
+        if content_type.startswith("text/"):
             return await self.text()
+
+        return await self.body()

asgi_tools/response.py

@@ -11,7 +11,7 @@ from http.cookies import SimpleCookie
 from mimetypes import guess_type
 from pathlib import Path
 from stat import S_ISDIR
-from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Mapping, Optional, Union
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Callable, Mapping, TypeVar
 from urllib.parse import quote, quote_plus
 
 from multidict import MultiDict
@@ -24,12 +24,15 @@ from .request import Request
 if TYPE_CHECKING:
     from .types import TASGIMessage, TASGIReceive, TASGIScope, TASGISend
 
+T = TypeVar("T")
+TContent = TypeVar("TContent", str, bytes, dict, list, None)
+
 
 class Response:
-    """A base class to make ASGI_ responses.
+    """Base class for creating HTTP responses.
 
     :param content: A response's body
-    :type content: str | bytes
+    :type content: str | bytes | dict | list | None
     :param status_code: An HTTP status code
     :type status_code: int
     :param headers: A dictionary of HTTP headers
@@ -57,17 +60,17 @@ class Response:
       strategy ('lax'|'strict'|'none')
 
     """
-    content_type: Optional[str] = None
+    content_type: str | None = None
     status_code: int = HTTPStatus.OK.value
 
     def __init__(
         self,
-        content,
+        content: TContent,
         *,
-        status_code: Optional[int] = None,
-        content_type: Optional[str] = None,
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
+        status_code: int | None = None,
+        content_type: str | None = None,
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
     ):
         """Setup the response."""
         self.content = self.process_content(content)
@@ -80,8 +83,7 @@ class Response:
         if content_type:
             self.headers.setdefault(
                 "content-type",
-                content_type.startswith("text/")
-                and f"{content_type}; charset={DEFAULT_CHARSET}"
+                (content_type.startswith("text/") and f"{content_type}; charset={DEFAULT_CHARSET}")
                 or content_type,
             )
 
@@ -101,7 +103,8 @@ class Response:
         await send({"type": "http.response.body", "body": self.content})
 
     @staticmethod
-    def process_content(content) -> bytes:
+    def process_content(content: TContent) -> bytes:
+        """Process content into bytes."""
         if not isinstance(content, bytes):
             return str(content).encode(DEFAULT_CHARSET)
         return content
@@ -127,19 +130,19 @@ class Response:
 
 
 class ResponseText(Response):
-    """A helper to return plain text responses (text/plain)."""
+    """Returns plain text responses (text/plain)."""
 
     content_type = "text/plain"
 
 
 class ResponseHTML(Response):
-    """A helper to return HTML responses (text/html)."""
+    """Returns HTML responses (text/html)."""
 
     content_type = "text/html"
 
 
 class ResponseJSON(Response):
-    """A helper to return JSON responses (application/json).
+    """Returns JSON responses (application/json).
 
     The class optionally supports `ujson <https://pypi.org/project/ujson/>`_ and `orjson
     <https://pypi.org/project/orjson/>`_ JSON libraries. Install one of them to use instead
@@ -156,7 +159,7 @@ class ResponseJSON(Response):
 
 
 class ResponseStream(Response):
-    """A helper to stream a response's body.
+    """Streams response body as chunks.
 
     :param content: An async generator to stream the response's body
     :type content: AsyncGenerator
@@ -197,7 +200,7 @@ class ResponseStream(Response):
 
 
 class ResponseSSE(ResponseStream):
-    """A helper to stream SSE (server side events).
+    """Streams Server-Sent Events (SSE).
 
     :param content: An async generator to stream the events
     :type content: AsyncGenerator
@@ -211,19 +214,19 @@ class ResponseSSE(ResponseStream):
         return super().msg_start()
 
     @staticmethod
-    def process_content(chunk) -> bytes:
+    def process_content(content) -> bytes:
         """Prepare a chunk from stream generator to send."""
-        if isinstance(chunk, dict):
-            chunk = "\n".join(f"{k}: {v}" for k, v in chunk.items())
+        if isinstance(content, dict):
+            content = "\n".join(f"{k}: {v}" for k, v in content.items())
 
-        if not isinstance(chunk, bytes):
-            chunk = chunk.encode(DEFAULT_CHARSET)
+        if not isinstance(content, bytes):
+            content = content.encode(DEFAULT_CHARSET)
 
-        return chunk + b"\n\n"
+        return content + b"\n\n"
 
 
 class ResponseFile(ResponseStream):
-    """A helper to stream files as a response body.
+    """Serves files as HTTP responses.
 
     :param filepath: The filepath to the file
     :type filepath: str | Path
@@ -238,10 +241,10 @@ class ResponseFile(ResponseStream):
 
     def __init__(
         self,
-        filepath: Union[str, Path],
+        filepath: str | Path,
         *,
         chunk_size: int = 64 * 1024,
-        filename: Optional[str] = None,
+        filename: str | None = None,
         headers_only: bool = False,
         **kwargs,
     ) -> None:
@@ -252,7 +255,7 @@ class ResponseFile(ResponseStream):
             raise ASGIError(*exc.args) from exc
 
         if S_ISDIR(stat.st_mode):
-            raise ASGIError(f"It's a directory: {filepath}")  # noqa: TRY003
+            raise ASGIError(f"It's a directory: {filepath}")
 
         super().__init__(
             empty() if headers_only else aio_stream_file(filepath, chunk_size),
@@ -261,7 +264,7 @@ class ResponseFile(ResponseStream):
 
         headers = self.headers
         if filename and "content-disposition" not in headers:
-            headers["content-disposition"] = f'attachment; filename="{quote(filename)}"'
+            headers["content-disposition"] = f"attachment; filename*=UTF-8''{quote(filename)}"
 
         if "content-type" not in headers:
             headers["content-type"] = guess_type(filename or str(filepath))[0] or "text/plain"
@@ -273,13 +276,7 @@ class ResponseFile(ResponseStream):
 
 
 class ResponseWebSocket(Response):
-    """A helper to work with websockets.
-
-    :param scope: Request info (ASGI Scope | ASGI-Tools Request)
-    :type scope: dict
-    :param receive: ASGI receive function
-    :param send: ASGI send function
-    """
+    """Provides a WebSocket handler interface."""
 
     class STATES(Enum):
         """Represent websocket states."""
@@ -291,15 +288,15 @@ class ResponseWebSocket(Response):
     def __init__(
         self,
         scope: TASGIScope,
-        receive: Optional[TASGIReceive] = None,
-        send: Optional[TASGISend] = None,
+        receive: TASGIReceive | None = None,
+        send: TASGISend | None = None,
     ) -> None:
         """Initialize the websocket response."""
         if isinstance(scope, Request):
             receive, send = scope.receive, scope.send
 
         if not receive or not send:
-            raise ASGIError("Invalid initialization")  # noqa: TRY003
+            raise ASGIError("Invalid initialization")
 
         super().__init__(b"")
         self._receive: TASGIReceive = receive
@@ -317,7 +314,7 @@ class ResponseWebSocket(Response):
         return self
 
     async def __aexit__(self, *_):
-        """Use it as async context manager."""
+        """Exit async context."""
         await self.close()
 
     @property
@@ -348,13 +345,13 @@ class ResponseWebSocket(Response):
             await self.send({"type": "websocket.close", "code": code})
         self.state = self.STATES.DISCONNECTED
 
-    async def send(self, msg: Union[dict, str, bytes], msg_type="websocket.send") -> None:
+    async def send(self, msg: dict | str | bytes, msg_type="websocket.send") -> None:
         """Send the given message to a client."""
         if self.state == self.STATES.DISCONNECTED:
             raise ASGIConnectionClosedError
 
         if not isinstance(msg, dict):
-            msg = {"type": msg_type, (isinstance(msg, str) and "text" or "bytes"): msg}
+            msg = {"type": msg_type, ((isinstance(msg, str) and "text") or "bytes"): msg}
 
         return await self._send(msg)
 
@@ -362,7 +359,7 @@ class ResponseWebSocket(Response):
         """Serialize the given data to JSON and send to a client."""
         return await self._send({"type": "websocket.send", "bytes": json_dumps(data)})
 
-    async def receive(self, *, raw: bool = False) -> Union[TASGIMessage, str]:
+    async def receive(self, *, raw: bool = False) -> TASGIMessage | str:
         """Receive messages from a client.
 
         :param raw: Receive messages as is.
@@ -382,7 +379,7 @@ class ResponseWebSocket(Response):
 
 
 class ResponseRedirect(Response, BaseException):
-    """A helper to return HTTP redirects. Uses a 307 status code by default.
+    """Creates HTTP redirects. Uses a 307 status code by default.
 
     :param url: A string with the new location
     :type url: str
@@ -390,7 +387,7 @@ class ResponseRedirect(Response, BaseException):
 
     status_code: int = HTTPStatus.TEMPORARY_REDIRECT.value
 
-    def __init__(self, url: str, status_code: Optional[int] = None, **kwargs) -> None:
+    def __init__(self, url: str, status_code: int | None = None, **kwargs) -> None:
         """Set status code and prepare location."""
         super().__init__(b"", status_code=status_code, **kwargs)
         assert (
@@ -413,7 +410,7 @@ class ResponseErrorMeta(type):
 
 
 class ResponseError(Response, BaseException, metaclass=ResponseErrorMeta):
-    """A helper to return HTTP errors. Uses a 500 status code by default.
+    """Helper for returning HTTP errors. Uses a 500 status code by default.
 
     :param message: A string with the error's message (HTTPStatus messages will be used by default)
     :type message: str
@@ -477,7 +474,7 @@ class ResponseError(Response, BaseException, metaclass=ResponseErrorMeta):
         NOT_EXTENDED: Callable[..., ResponseError]  # 510
         NETWORK_AUTHENTICATION_REQUIRED: Callable[..., ResponseError]  # 511
 
-    def __init__(self, message=None, status_code: Optional[int] = None, **kwargs):
+    def __init__(self, message=None, status_code: int | None = None, **kwargs):
         """Check error status."""
         content = message or HTTPStatus(status_code or self.status_code).description
         super().__init__(content=content, status_code=status_code, **kwargs)
@@ -495,7 +492,7 @@ CAST_RESPONSE: Mapping[type, type[Response]] = {
 }
 
 
-def parse_response(response, headers: Optional[dict] = None) -> Response:
+def parse_response(response, headers: dict | None = None) -> Response:
     """Parse the given object and convert it into a asgi_tools.Response."""
     if isinstance(response, Response):
         return response
@@ -520,9 +517,7 @@ def parse_response(response, headers: Optional[dict] = None) -> Response:
     return ResponseText(str(response), headers=headers)
 
 
-def parse_websocket_msg(
-    msg: TASGIMessage, charset: Optional[str] = None
-) -> Union[TASGIMessage, str]:
+def parse_websocket_msg(msg: TASGIMessage, charset: str | None = None) -> TASGIMessage | str:
     """Prepare websocket message."""
     data = msg.get("text")
     if data:

asgi_tools/tests.py

@@ -22,13 +22,10 @@ from typing import (
     Callable,
     Coroutine,
     Deque,
-    Optional,
-    Union,
     cast,
 )
 from urllib.parse import urlencode
 
-from multidict import MultiDict
 from yarl import URL
 
 from ._compat import aio_cancel, aio_sleep, aio_spawn, aio_timeout, aio_wait
@@ -38,6 +35,8 @@ from .response import Response, ResponseJSON, ResponseWebSocket, parse_websocket
 from .utils import CIMultiDict, parse_headers
 
 if TYPE_CHECKING:
+    from multidict import MultiDict
+
     from .types import TJSON, TASGIApp, TASGIMessage, TASGIReceive, TASGIScope, TASGISend
 
 
@@ -53,7 +52,7 @@ class TestResponse(Response):
         msg = await self._receive()
         assert msg.get("type") == "http.response.start", "Invalid Response"
         self.status_code = int(msg.get("status", 502))
-        self.headers = cast(MultiDict, parse_headers(msg.get("headers", [])))
+        self.headers = cast("MultiDict", parse_headers(msg.get("headers", [])))
         self.content_type = self.headers.get("content-type")
         for cookie in self.headers.getall("set-cookie", []):
             self.cookies.load(cookie)
@@ -123,7 +122,7 @@ class TestWebSocketResponse(ResponseWebSocket):
 
 
 class ASGITestClient:
-    """The test client allows you to make requests against an ASGI application.
+    """Built-in test client for ASGI applications.
 
     Features:
 
@@ -151,10 +150,10 @@ class ASGITestClient:
         path: str,
         method: str = "GET",
         *,
-        query: Union[str, dict] = "",
-        headers: Optional[dict[str, str]] = None,
-        cookies: Optional[dict[str, str]] = None,
-        data: Union[bytes, str, dict, AsyncGenerator[Any, bytes]] = b"",
+        query: str | dict = "",
+        headers: dict[str, str] | None = None,
+        cookies: dict[str, str] | None = None,
+        data: bytes | str | dict | AsyncGenerator[Any, bytes] = b"",
         json: TJSON = None,
         follow_redirect: bool = True,
         timeout: float = 10.0,
@@ -214,9 +213,9 @@ class ASGITestClient:
     async def websocket(
         self,
         path: str,
-        query: Union[str, dict, None] = None,
-        headers: Optional[dict] = None,
-        cookies: Optional[dict] = None,
+        query: str | dict | None = None,
+        headers: dict | None = None,
+        cookies: dict | None = None,
     ):
         """Connect to a websocket."""
         pipe = Pipe()
@@ -250,9 +249,9 @@ class ASGITestClient:
     def build_scope(
         self,
         path: str,
-        headers: Union[dict, CIMultiDict, None] = None,
-        query: Union[str, dict, None] = None,
-        cookies: Optional[dict] = None,
+        headers: dict | CIMultiDict | None = None,
+        query: str | dict | None = None,
+        cookies: dict | None = None,
         **scope,
     ) -> TASGIScope:
         """Prepare a request scope."""
@@ -282,7 +281,7 @@ class ASGITestClient:
                 "query_string": url.raw_query_string.encode(),
                 "raw_path": url.raw_path.encode(),
                 "root_path": "",
-                "scheme": scope.get("type") == "http" and self.base_url.scheme or "ws",
+                "scheme": (scope.get("type") == "http" and self.base_url.scheme) or "ws",
                 "headers": [
                     (key.lower().encode(BASE_ENCODING), str(val).encode(BASE_ENCODING))
                     for key, val in (headers or {}).items()
@@ -321,11 +320,11 @@ def encode_multipart(data: dict) -> tuple[bytes, str]:
 
 class Pipe:
     __slots__ = (
-        "delay",
         "app_is_closed",
-        "client_is_closed",
         "app_queue",
+        "client_is_closed",
         "client_queue",
+        "delay",
     )
 
     def __init__(self, delay: float = 1e-3):
@@ -366,7 +365,7 @@ class Pipe:
             await aio_sleep(self.delay)
         return self.app_queue.popleft()
 
-    async def stream(self, data: Union[bytes, AsyncGenerator[Any, bytes]]):
+    async def stream(self, data: bytes | AsyncGenerator[Any, bytes]):
         if isinstance(data, bytes):
             return await self.send_to_app(
                 {"type": "http.request", "body": data, "more_body": False},
@@ -392,7 +391,7 @@ async def manage_lifespan(app, timeout: float = 3e-2):
     async with aio_spawn(safe_spawn) as task:
         await pipe.send_to_app({"type": "lifespan.startup"})
 
-        with suppress(TimeoutError, asyncio.TimeoutError):  # python 39, 310
+        with suppress(TimeoutError, asyncio.TimeoutError):  # python 310
             async with aio_timeout(timeout):
                 msg = await pipe.receive_from_client()
                 if msg["type"] == "lifespan.startup.failed":
@@ -401,6 +400,6 @@ async def manage_lifespan(app, timeout: float = 3e-2):
         yield
 
         await pipe.send_to_app({"type": "lifespan.shutdown"})
-        with suppress(TimeoutError, asyncio.TimeoutError):  # python 39, 310
+        with suppress(TimeoutError, asyncio.TimeoutError):  # python 310
             async with aio_timeout(timeout):
                 await pipe.receive_from_client()

asgi_tools/view.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import inspect
-from typing import TYPE_CHECKING, Final, Optional
+from typing import TYPE_CHECKING, Final
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable
@@ -57,7 +57,7 @@ class HTTPView:
         return self(request, **opts)
 
     @classmethod
-    def __route__(cls, router: Router, *paths: str, methods: Optional[TMethods] = None, **params):
+    def __route__(cls, router: Router, *paths: str, methods: TMethods | None = None, **params):
         """Bind the class view to the given router."""
         view_methods = dict(inspect.getmembers(cls, inspect.isfunction))
         methods = methods or [m for m in HTTP_METHODS if m.lower() in view_methods]