asgi-tools 1.1.0__cp310-cp310-macosx_10_9_universal2.whl → 1.3.1__cp310-cp310-macosx_10_9_universal2.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 (
@@ -402,8 +399,7 @@ class ResponseRedirect(Response, BaseException):
 class ResponseErrorMeta(type):
     """Generate Response Errors by HTTP names."""
 
-    # TODO: From python 3.9 -> partial['ResponseError]
-    def __getattr__(cls, name: str) -> Callable[..., ResponseError]:
+    def __getattr__(cls, name: str) -> partial[ResponseError]:
         """Generate Response Errors by HTTP names."""
         status = HTTPStatus[name]
         return partial(
@@ -413,7 +409,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
@@ -451,9 +447,8 @@ class ResponseError(Response, BaseException, metaclass=ResponseErrorMeta):
         UNSUPPORTED_MEDIA_TYPE: Callable[..., ResponseError]  # 415
         REQUESTED_RANGE_NOT_SATISFIABLE: Callable[..., ResponseError]  # 416
         EXPECTATION_FAILED: Callable[..., ResponseError]  # 417
-        # TODO: From python 3.9
-        # IM_A_TEAPOT: Callable[..., ResponseError]                       # 418
-        # MISDIRECTED_REQUEST: Callable[..., ResponseError]               # 421
+        IM_A_TEAPOT: Callable[..., ResponseError]  # 418
+        MISDIRECTED_REQUEST: Callable[..., ResponseError]  # 421
         UNPROCESSABLE_ENTITY: Callable[..., ResponseError]  # 422
         LOCKED: Callable[..., ResponseError]  # 423
         FAILED_DEPENDENCY: Callable[..., ResponseError]  # 424
@@ -462,8 +457,7 @@ class ResponseError(Response, BaseException, metaclass=ResponseErrorMeta):
         PRECONDITION_REQUIRED: Callable[..., ResponseError]  # 428
         TOO_MANY_REQUESTS: Callable[..., ResponseError]  # 429
         REQUEST_HEADER_FIELDS_TOO_LARGE: Callable[..., ResponseError]  # 431
-        # TODO: From python 3.9
-        # UNAVAILABLE_FOR_LEGAL_REASONS: Callable[..., ResponseError]     # 451
+        UNAVAILABLE_FOR_LEGAL_REASONS: Callable[..., ResponseError]  # 451
 
         INTERNAL_SERVER_ERROR: Callable[..., ResponseError]  # 500
         NOT_IMPLEMENTED: Callable[..., ResponseError]  # 501
@@ -477,7 +471,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 +489,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 +514,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:
@@ -537,6 +529,3 @@ def parse_websocket_msg(
 
 async def empty():
     yield b""
-
-
-# ruff: noqa: ERA001