asgi-tools 1.1.0__tar.gz → 1.3.1__tar.gz

{asgi_tools-1.1.0/asgi_tools.egg-info → asgi_tools-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: asgi-tools
-Version: 1.1.0
+Version: 1.3.1
 Summary: ASGI Toolkit to build web applications
 Author-email: Kirill Klenov <horneds@gmail.com>
 License: MIT License
@@ -13,7 +13,6 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -23,18 +22,18 @@ Classifier: Programming Language :: Cython
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Framework :: AsyncIO
 Classifier: Framework :: Trio
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: http-router>=4.0.0
-Requires-Dist: multidict
+Requires-Dist: multidict>=6.6.3
 Requires-Dist: sniffio
 Requires-Dist: yarl>=1.8.2
 Requires-Dist: async-timeout; python_version < "3.11"
 Provides-Extra: tests
 Requires-Dist: aiofile; extra == "tests"
 Requires-Dist: pytest; extra == "tests"
-Requires-Dist: pytest-aio[curio,trio]>=1.1.0; extra == "tests"
+Requires-Dist: pytest-aio[curio,trio]>=1.3.1; extra == "tests"
 Requires-Dist: pytest-benchmark; extra == "tests"
 Requires-Dist: PyYAML; extra == "tests"
 Requires-Dist: ruff; extra == "tests"
@@ -58,6 +57,7 @@ Requires-Dist: cython; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: sphinx; extra == "dev"
 Requires-Dist: pydata-sphinx-theme; extra == "dev"
+Dynamic: license-file
 
 .. image:: https://raw.githubusercontent.com/klen/asgi-tools/develop/.github/assets/asgi-tools.png
    :height: 100
@@ -124,7 +124,7 @@ For instance these middlewares were built with the library:
 Requirements
 =============
 
-- python >= 3.9
+- python >= 3.10
 
 .. note:: pypy3 is also supported
 
@@ -145,7 +145,7 @@ A Quick Example
 
 You can use any of ASGI-Tools components independently.
 
-Dispite this ASGI-Tools contains App_ helper to quickly build ASGI
+Despite this ASGI-Tools contains App_ helper to quickly build ASGI
 applications. For instance:
 
 Save this to ``app.py``.
@@ -201,7 +201,7 @@ Licensed under a `MIT license`_.
 .. _klen: https://github.com/klen
 .. _uvicorn: http://www.uvicorn.org/
 .. _daphne: https://github.com/django/daphne/
-.. _hypercorn: https://pgjones.gitlab.io/hypercorn/
+.. _hypercorn: https://github.com/pgjones/hypercorn/
 
 .. _Request: https://klen.github.io/asgi-tools/api.html#request
 .. _Response: https://klen.github.io/asgi-tools/api.html#responses

{asgi_tools-1.1.0 → asgi_tools-1.3.1}/README.rst

@@ -63,7 +63,7 @@ For instance these middlewares were built with the library:
 Requirements
 =============
 
-- python >= 3.9
+- python >= 3.10
 
 .. note:: pypy3 is also supported
 
@@ -84,7 +84,7 @@ A Quick Example
 
 You can use any of ASGI-Tools components independently.
 
-Dispite this ASGI-Tools contains App_ helper to quickly build ASGI
+Despite this ASGI-Tools contains App_ helper to quickly build ASGI
 applications. For instance:
 
 Save this to ``app.py``.
@@ -140,7 +140,7 @@ Licensed under a `MIT license`_.
 .. _klen: https://github.com/klen
 .. _uvicorn: http://www.uvicorn.org/
 .. _daphne: https://github.com/django/daphne/
-.. _hypercorn: https://pgjones.gitlab.io/hypercorn/
+.. _hypercorn: https://github.com/pgjones/hypercorn/
 
 .. _Request: https://klen.github.io/asgi-tools/api.html#request
 .. _Response: https://klen.github.io/asgi-tools/api.html#responses

{asgi_tools-1.1.0 → asgi_tools-1.3.1}/asgi_tools/__init__.py

@@ -1,4 +1,5 @@
-""" ASGI-Tools -- Tools to make ASGI Applications """
+"""ASGI-Tools -- Tools to make ASGI Applications"""
+
 from __future__ import annotations
 
 from http_router import InvalidMethodError, NotFoundError
@@ -29,7 +30,7 @@ from .response import (
 )
 from .view import HTTPView
 
-__all__ = (
+__all__ = (  # noqa: RUF022
     # Errors
     "ASGIConnectionClosedError",
     "ASGIError",

{asgi_tools-1.1.0 → asgi_tools-1.3.1}/asgi_tools/_compat.py

@@ -1,4 +1,4 @@
-"""Compatability layer."""
+"""Compatibility layer."""
 
 from __future__ import annotations
 
@@ -34,17 +34,17 @@ __all__ = (
     "aio_spawn",
     "aio_stream_file",
     "aio_wait",
+    "aiofile_installed",
     "create_task",
+    "curio_installed",
     "json_dumps",
     "json_loads",
-    "aiofile_installed",
     "trio_installed",
-    "curio_installed",
 )
 
 try:
     from asyncio import timeout as asyncio_timeout  # type: ignore[attr-defined]
-except ImportError:  # python 39, 310
+except ImportError:  # python 310
     from async_timeout import timeout as asyncio_timeout  # type: ignore[no-redef]
 
 
@@ -103,7 +103,7 @@ async def aio_spawn(fn: Callable[..., Awaitable], *args, **kwargs):
         await task.join()  # type: ignore [union-attr]
 
     else:
-        coro = cast(Coroutine, fn(*args, **kwargs))
+        coro = cast("Coroutine", fn(*args, **kwargs))
         task = create_task(coro)
         yield task
         await task
@@ -138,7 +138,7 @@ async def aio_timeout(timeout: float):  # noqa: ASYNC109
 
 
 async def aio_wait(*aws: Awaitable, strategy: str = ALL_COMPLETED) -> Any:
-    """Run the coros concurently, wait for all completed or cancel others.
+    """Run the coros concurrently, wait for all completed or cancel others.
 
     Only ALL_COMPLETED, FIRST_COMPLETED are supported.
     """
@@ -198,7 +198,7 @@ async def aio_stream_file(
     if trio_installed and current_async_library() == "trio":
         async with await trio_open_file(filepath, "rb") as fp:
             while True:
-                chunk = cast(bytes, await fp.read(chunk_size))
+                chunk = cast("bytes", await fp.read(chunk_size))
                 if not chunk:
                     break
                 yield chunk
@@ -206,14 +206,14 @@ async def aio_stream_file(
     elif curio_installed and current_async_library() == "curio":
         async with curio_open(filepath, "rb") as fp:
             while True:
-                chunk = cast(bytes, await fp.read(chunk_size))
+                chunk = cast("bytes", await fp.read(chunk_size))
                 if not chunk:
                     break
                 yield chunk
 
     else:
         if not aiofile_installed:
-            raise RuntimeError(  # noqa: TRY003
+            raise RuntimeError(
                 "`aiofile` is required to return files with asyncio",
             )
 
@@ -221,7 +221,7 @@ async def aio_stream_file(
             async for chunk in aiofile.Reader(  # type: ignore [assignment]
                 fp, chunk_size=chunk_size
             ):
-                yield cast(bytes, chunk)
+                yield cast("bytes", chunk)
 
 
 async def trio_jockey(coro: Awaitable, channel):
@@ -257,6 +257,3 @@ with suppress(ImportError):
 with suppress(ImportError):
     from orjson import dumps as json_dumps  # type: ignore[assignment,no-redef]
     from orjson import loads as json_loads  # type: ignore[assignment,no-redef]
-
-
-# ruff: noqa: PGH003, F811

{asgi_tools-1.1.0 → asgi_tools-1.3.1}/asgi_tools/app.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from functools import partial
 from inspect import isclass
-from typing import TYPE_CHECKING, Callable, Optional, Union  # py39
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, cast
 
 from http_router import PrefixedRoute
 
@@ -28,38 +28,45 @@ if TYPE_CHECKING:
         TASGIScope,
         TASGISend,
         TExceptionHandler,
-        TVCallable,
         TVExceptionHandler,
     )
 
+T = TypeVar("T")
+TRouteHandler = TypeVar("TRouteHandler", bound=Callable[[Request], Any])
+TCallable = TypeVar("TCallable", bound=Callable[..., Any])
+
 
 class App:
-    """A helper to build ASGI Applications.
+    """A helper class to build ASGI applications quickly and efficiently.
 
     Features:
-
-    * Routing
-    * ASGI-Tools :class:`Request`, :class:`Response`
-    * Exception management
-    * Static files
-    * Lifespan events
-    * Simplest middlewares
+        - Routing with flexible path and method matching
+        - ASGI-Tools :class:`Request`, :class:`Response` integration
+        - Exception management and custom error handlers
+        - Static files serving
+        - Lifespan events (startup/shutdown)
+        - Simple middleware support
 
     :param debug: Enable debug mode (more logging, raise unhandled exceptions)
-    :type debug: bool, False
-
+    :type debug: bool
     :param logger: Custom logger for the application
     :type logger: logging.Logger
-
-    :param static_url_prefix: A prefix for static files
-    :type static_url_prefix: str, "/static"
-
-    :param static_folders: A list of folders to look static files
-    :type static_folders: list[str]
-
-    :param trim_last_slash: Consider "/path" and "/path/" as the same
-    :type trim_last_slash: bool, False
-
+    :param static_url_prefix: URL prefix for static files
+    :type static_url_prefix: str
+    :param static_folders: List of folders to serve static files from
+    :type static_folders: Optional[list[str | Path]]
+    :param trim_last_slash: Treat "/path" and "/path/" as the same route
+    :type trim_last_slash: bool
+    :raises ValueError: If static_url_prefix is set without static_folders
+    :raises TypeError: If static_folders is not a list of strings or Paths
+    :raises RuntimeError: If the app is not an ASGI application
+
+    Example:
+        >>> from asgi_tools import App
+        >>> app = App()
+        >>> @app.route("/")
+        ... async def homepage(request):
+        ...     return "Hello, World!"
     """
 
     exception_handlers: dict[type[BaseException], TExceptionHandler]
@@ -70,10 +77,23 @@ class App:
         debug: bool = False,
         logger: logging.Logger = logger,
         static_url_prefix: str = "/static",
-        static_folders: Optional[list[Union[str, Path]]] = None,
+        static_folders: list[str | Path] | None = None,
         trim_last_slash: bool = False,
     ):
-        """Initialize router and lifespan middleware."""
+        """Initialize the ASGI application with routing, logging, static files,
+           and lifespan support.
+
+        :param debug: Enable debug mode (more logging, raise unhandled exceptions)
+        :type debug: bool
+        :param logger: Custom logger for the application
+        :type logger: logging.Logger
+        :param static_url_prefix: URL prefix for static files
+        :type static_url_prefix: str
+        :param static_folders: List of folders to serve static files from
+        :type static_folders: Optional[list[str|Path]]
+        :param trim_last_slash: Treat "/path" and "/path/" as the same route
+        :type trim_last_slash: bool
+        """
 
         # Register base exception handlers
         self.exception_handlers = {
@@ -116,15 +136,15 @@ class App:
         self.internal_middlewares: list = []
 
     async def __call__(self, scope: TASGIScope, receive: TASGIReceive, send: TASGISend) -> None:
-        """Convert the given scope into a request and process."""
+        """ASGI entrypoint. Converts the given scope into a request and processes it."""
         await self.lifespan(scope, receive, send)
 
     async def __process__(self, scope: TASGIScope, receive: TASGIReceive, send: TASGISend):
-        """Send ASGI messages."""
+        """Internal request processing: builds a Request, calls the app, and handles exceptions."""
         scope["app"] = self
         request = Request(scope, receive, send)
         try:
-            response: Optional[Response] = await self.__app__(request, receive, send)
+            response: Response | None = await self.__app__(request, receive, send)
             if response is not None:
                 await response(scope, receive, send)
 
@@ -144,8 +164,8 @@ class App:
 
     async def __match__(
         self, request: Request, _: TASGIReceive, send: TASGISend
-    ) -> Optional[Response]:
-        """Find and call a callback, parse a response, handle exceptions."""
+    ) -> Response | None:
+        """Finds and calls a route handler, parses the response, and handles routing exceptions."""
         scope = request.scope
         path = f"{ scope.get('root_path', '') }{ scope['path'] }"
         try:
@@ -159,7 +179,8 @@ class App:
 
         scope["endpoint"] = match.target
         scope["path_params"] = {} if match.params is None else match.params
-        response = await match.target(request)  # type: ignore[]
+        handler = cast("Callable[[Request], Any]", match.target)
+        response = await handler(request)
 
         if scope["type"] == "http":
             return parse_response(response)
@@ -170,14 +191,30 @@ class App:
         return None
 
     def __route__(self, router: Router, *prefixes: str, **_) -> "App":
-        """Mount self as a nested application."""
+        """Mount this app as a nested application under given prefixes."""
         for prefix in prefixes:
             route = RouteApp(prefix, set(), target=self)
             router.dynamic.insert(0, route)
         return self
 
-    def middleware(self, md: TVCallable, *, insert_first: bool = False) -> TVCallable:
-        """Register a middleware."""
+    def middleware(self, md: TCallable, *, insert_first: bool = False) -> TCallable:
+        """Register a middleware for the application.
+
+        Middleware can be a coroutine (request/response) or a regular callable (lifespan).
+
+        :param md: The middleware function or class
+        :type md: TCallable
+        :param insert_first: If True, insert as the first middleware
+        :type insert_first: bool
+        :return: The registered middleware
+        :rtype: TCallable
+
+        Example:
+            >>> @app.middleware
+            ... async def log_requests(handler, request):
+            ...     print(f"Request: {request.method} {request.url}")
+            ...     return await handler(request)
+        """
         # Register as a simple middleware
         if iscoroutinefunction(md):
             if md not in self.internal_middlewares:
@@ -197,33 +234,50 @@ class App:
 
         return md
 
-    def route(self, *paths: TPath, methods: Optional[TMethods] = None, **opts):
-        """Register a route."""
+    def route(
+        self, *paths: TPath, methods: TMethods | None = None, **opts: Any
+    ) -> Callable[[TRouteHandler], TRouteHandler]:
+        """Register a route handler.
+
+        :param paths: One or more URL paths to match
+        :type paths: TPath
+        :param methods: HTTP methods to match (GET, POST, etc.)
+        :type methods: Optional[TMethods]
+        :param opts: Additional options for the route
+        :type opts: Any
+        :return: Decorator function
+        :rtype: Callable[[TRouteHandler], TRouteHandler]
+        """
         return self.router.route(*paths, methods=methods, **opts)
 
     def on_startup(self, fn: Callable) -> None:
-        """Register a startup handler."""
+        """Register a startup event handler.
+
+        :param fn: The function to call on startup
+        :type fn: Callable
+        """
         return self.lifespan.on_startup(fn)
 
     def on_shutdown(self, fn: Callable) -> None:
-        """Register a shutdown handler."""
+        """Register a shutdown event handler.
+
+        :param fn: The function to call on shutdown
+        :type fn: Callable
+        """
         return self.lifespan.on_shutdown(fn)
 
     def on_error(self, etype: type[BaseException]):
-        """Register an exception handler.
-
-        .. code-block::
-
-            @app.on_error(TimeoutError)
-            async def timeout(request, error):
-                return 'Something bad happens'
+        """Register a custom exception handler for a given exception type.
 
-            @app.on_error(ResponseError)
-            async def process_http_errors(request, response_error):
-                if response_error.status_code == 404:
-                    return render_template('page_not_found.html'), 404
-                return response_error
+        :param etype: The exception type to handle
+        :type etype: type[BaseException]
+        :return: A decorator to register the handler
+        :rtype: Callable
 
+        Example:
+            >>> @app.on_error(TimeoutError)
+            ... async def timeout_handler(request, error):
+            ...     return 'Timeout occurred'
         """
         assert isclass(etype), f"Invalid exception type: {etype}"
         assert issubclass(etype, BaseException), f"Invalid exception type: {etype}"
@@ -236,10 +290,10 @@ class App:
 
 
 class RouteApp(PrefixedRoute):
-    """Custom route to submount an application."""
+    """Custom route to submount an application under a given path prefix."""
 
     def __init__(self, path: str, methods: set, target: App):
-        """Create app callable."""
+        """Create a submounted app callable for the given prefix."""
         path = path.rstrip("/")
 
         def app(request: Request):

{asgi_tools-1.1.0 → asgi_tools-1.3.1}/asgi_tools/forms.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from io import BytesIO
 from tempfile import SpooledTemporaryFile
-from typing import TYPE_CHECKING, Callable, Optional
+from typing import TYPE_CHECKING, Callable
 from urllib.parse import unquote_to_bytes
 
 from multidict import MultiDict
@@ -19,7 +19,7 @@ if TYPE_CHECKING:
 async def read_formdata(
     request: "Request",
     max_size: int,
-    upload_to: Optional[Callable],
+    upload_to: Callable | None,
     file_memory_limit: int = 1024 * 1024,
 ) -> MultiDict:
     """Read formdata from the given request."""
@@ -43,7 +43,7 @@ async def read_formdata(
 class FormReader:
     """Process querystring form data."""
 
-    __slots__ = "form", "curname", "curvalue", "charset"
+    __slots__ = "charset", "curname", "curvalue", "form"
 
     def __init__(self, charset: str):
         self.charset = charset
@@ -80,18 +80,18 @@ class MultipartReader(FormReader):
     """Process multipart formdata."""
 
     __slots__ = (
-        "form",
+        "charset",
         "curname",
         "curvalue",
-        "charset",
+        "file_memory_limit",
+        "form",
+        "headers",
         "name",
         "partdata",
-        "headers",
         "upload_to",
-        "file_memory_limit",
     )
 
-    def __init__(self, charset: str, upload_to: Optional[Callable], file_memory_limit: int):
+    def __init__(self, charset: str, upload_to: Callable | None, file_memory_limit: int):
         super().__init__(charset)
         self.name = ""
         self.headers: dict[bytes, bytes] = {}
@@ -102,7 +102,7 @@ class MultipartReader(FormReader):
     def init_parser(self, request: "Request", max_size: int) -> BaseParser:
         boundary = request.media.get("boundary", "")
         if not boundary:
-            raise ValueError("Invalid content type boundary")  # noqa: TRY003
+            raise ValueError("Invalid content type boundary")
 
         return MultipartParser(
             boundary,