plain 0.69.0__py3-none-any.whl → 0.71.0__py3-none-any.whl

plain/internal/files/locks.py

@@ -17,14 +17,22 @@ Example Usage::
     ...     f.write('Plain')
 """
 
+from __future__ import annotations
+
 import os
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import IO
 
 __all__ = ("LOCK_EX", "LOCK_SH", "LOCK_NB", "lock", "unlock")
 
 
-def _fd(f):
+def _fd(f: IO[bytes] | int) -> int:
     """Get a filedescriptor from something which could be a file or an fd."""
-    return f.fileno() if hasattr(f, "fileno") else f
+    if isinstance(f, int):
+        return f
+    return f.fileno()
 
 
 if os.name == "nt":
@@ -33,7 +41,7 @@ if os.name == "nt":
         POINTER,
         Structure,
         Union,
-        WinDLL,
+        WinDLL,  # type: ignore[attr-defined]
         byref,
         c_int64,
         c_ulong,
@@ -82,14 +90,14 @@ if os.name == "nt":
     UnlockFileEx.restype = BOOL
     UnlockFileEx.argtypes = [HANDLE, DWORD, DWORD, DWORD, LPOVERLAPPED]
 
-    def lock(f, flags):
-        hfile = msvcrt.get_osfhandle(_fd(f))
+    def lock(f: IO[bytes] | int, flags: int) -> bool:
+        hfile = msvcrt.get_osfhandle(_fd(f))  # type: ignore[attr-defined]
         overlapped = OVERLAPPED()
         ret = LockFileEx(hfile, flags, 0, 0, 0xFFFF0000, byref(overlapped))
         return bool(ret)
 
-    def unlock(f):
-        hfile = msvcrt.get_osfhandle(_fd(f))
+    def unlock(f: IO[bytes] | int) -> bool:
+        hfile = msvcrt.get_osfhandle(_fd(f))  # type: ignore[attr-defined]
         overlapped = OVERLAPPED()
         ret = UnlockFileEx(hfile, 0, 0, 0xFFFF0000, byref(overlapped))
         return bool(ret)
@@ -106,23 +114,23 @@ else:
         LOCK_EX = LOCK_SH = LOCK_NB = 0
 
         # Dummy functions that don't do anything.
-        def lock(f, flags):
+        def lock(f: IO[bytes] | int, flags: int) -> bool:
             # File is not locked
             return False
 
-        def unlock(f):
+        def unlock(f: IO[bytes] | int) -> bool:
             # File is unlocked
             return True
 
     else:
 
-        def lock(f, flags):
+        def lock(f: IO[bytes] | int, flags: int) -> bool:
             try:
                 fcntl.flock(_fd(f), flags)
                 return True
             except BlockingIOError:
                 return False
 
-        def unlock(f):
+        def unlock(f: IO[bytes] | int) -> bool:
             fcntl.flock(_fd(f), fcntl.LOCK_UN)
             return True

plain/internal/files/move.py

@@ -5,6 +5,8 @@ Move a file in the safest way possible::
     >>> file_move_safe("/tmp/old_file", "/tmp/new_file")
 """
 
+from __future__ import annotations
+
 import os
 from shutil import copymode, copystat
 
@@ -13,7 +15,7 @@ from plain.internal.files import locks
 __all__ = ["file_move_safe"]
 
 
-def _samefile(src, dst):
+def _samefile(src: str, dst: str) -> bool:
     # Macintosh, Unix.
     if hasattr(os.path, "samefile"):
         try:
@@ -28,8 +30,11 @@ def _samefile(src, dst):
 
 
 def file_move_safe(
-    old_file_name, new_file_name, chunk_size=1024 * 64, allow_overwrite=False
-):
+    old_file_name: str,
+    new_file_name: str,
+    chunk_size: int = 1024 * 64,
+    allow_overwrite: bool = False,
+) -> None:
     """
     Move a file from one location to another in the safest way possible.
 

plain/internal/files/temp.py

@@ -16,11 +16,17 @@ arguments available in tempfile.NamedTemporaryFile.
 2: https://bugs.python.org/issue14243
 """
 
+from __future__ import annotations
+
 import os
 import tempfile
+from typing import TYPE_CHECKING
 
 from plain.internal.files.utils import FileProxyMixin
 
+if TYPE_CHECKING:
+    from typing import Any
+
 __all__ = (
     "NamedTemporaryFile",
     "gettempdir",
@@ -39,7 +45,14 @@ if os.name == "nt":
         'newline' keyword arguments.
         """
 
-        def __init__(self, mode="w+b", bufsize=-1, suffix="", prefix="", dir=None):
+        def __init__(
+            self,
+            mode: str = "w+b",
+            bufsize: int = -1,
+            suffix: str = "",
+            prefix: str = "",
+            dir: str | None = None,
+        ) -> None:
             fd, name = tempfile.mkstemp(suffix=suffix, prefix=prefix, dir=dir)
             self.name = name
             self.file = os.fdopen(fd, mode, bufsize)
@@ -50,7 +63,7 @@ if os.name == "nt":
         # as self.unlink only
         unlink = os.unlink
 
-        def close(self):
+        def close(self) -> None:
             if not self.close_called:
                 self.close_called = True
                 try:
@@ -62,14 +75,19 @@ if os.name == "nt":
                 except OSError:
                     pass
 
-        def __del__(self):
+        def __del__(self) -> None:
             self.close()
 
-        def __enter__(self):
+        def __enter__(self) -> TemporaryFile:
             self.file.__enter__()
             return self
 
-        def __exit__(self, exc, value, tb):
+        def __exit__(
+            self,
+            exc: type[BaseException] | None,
+            value: BaseException | None,
+            tb: Any,
+        ) -> None:
             self.file.__exit__(exc, value, tb)
 
     NamedTemporaryFile = TemporaryFile

plain/internal/files/uploadedfile.py

@@ -2,14 +2,21 @@
 Classes representing uploaded files.
 """
 
+from __future__ import annotations
+
 import os
 from io import BytesIO
+from typing import TYPE_CHECKING
 
 from plain.internal.files import temp as tempfile
 from plain.internal.files.base import File
 from plain.internal.files.utils import validate_file_name
 from plain.runtime import settings
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import IO, Any
+
 __all__ = (
     "UploadedFile",
     "TemporaryUploadedFile",
@@ -29,26 +36,26 @@ class UploadedFile(File):
 
     def __init__(
         self,
-        file=None,
-        name=None,
-        content_type=None,
-        size=None,
-        charset=None,
-        content_type_extra=None,
-    ):
+        file: IO[Any] | None = None,
+        name: str | None = None,
+        content_type: str | None = None,
+        size: int | None = None,
+        charset: str | None = None,
+        content_type_extra: dict[str, str] | None = None,
+    ) -> None:
         super().__init__(file, name)
         self.size = size
         self.content_type = content_type
         self.charset = charset
         self.content_type_extra = content_type_extra
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {self.name} ({self.content_type})>"
 
-    def _get_name(self):
+    def _get_name(self) -> str:
         return self._name
 
-    def _set_name(self, name):
+    def _set_name(self, name: str | None) -> None:
         # Sanitize the file name so that it can't be dangerous.
         if name is not None:
             # Just use the basename of the file -- anything else is dangerous.
@@ -72,18 +79,25 @@ class TemporaryUploadedFile(UploadedFile):
     A file uploaded to a temporary location (i.e. stream-to-disk).
     """
 
-    def __init__(self, name, content_type, size, charset, content_type_extra=None):
+    def __init__(
+        self,
+        name: str,
+        content_type: str,
+        size: int,
+        charset: str,
+        content_type_extra: dict[str, str] | None = None,
+    ) -> None:
         _, ext = os.path.splitext(name)
         file = tempfile.NamedTemporaryFile(
             suffix=".upload" + ext, dir=settings.FILE_UPLOAD_TEMP_DIR
         )
         super().__init__(file, name, content_type, size, charset, content_type_extra)
 
-    def temporary_file_path(self):
+    def temporary_file_path(self) -> str:
         """Return the full path of this file."""
         return self.file.name
 
-    def close(self):
+    def close(self) -> None:
         try:
             return self.file.close()
         except FileNotFoundError:
@@ -100,26 +114,26 @@ class InMemoryUploadedFile(UploadedFile):
 
     def __init__(
         self,
-        file,
-        field_name,
-        name,
-        content_type,
-        size,
-        charset,
-        content_type_extra=None,
-    ):
+        file: IO[Any],
+        field_name: str | None,
+        name: str,
+        content_type: str,
+        size: int,
+        charset: str,
+        content_type_extra: dict[str, str] | None = None,
+    ) -> None:
         super().__init__(file, name, content_type, size, charset, content_type_extra)
         self.field_name = field_name
 
-    def open(self, mode=None):
+    def open(self, mode: str | None = None) -> InMemoryUploadedFile:
         self.file.seek(0)
         return self
 
-    def chunks(self, chunk_size=None):
+    def chunks(self, chunk_size: int | None = None) -> Iterator[bytes]:
         self.file.seek(0)
         yield self.read()
 
-    def multiple_chunks(self, chunk_size=None):
+    def multiple_chunks(self, chunk_size: int | None = None) -> bool:
         # Since it's in memory, we'll never have multiple chunks.
         return False
 
@@ -129,14 +143,16 @@ class SimpleUploadedFile(InMemoryUploadedFile):
     A simple representation of a file, which just has content, size, and a name.
     """
 
-    def __init__(self, name, content, content_type="text/plain"):
+    def __init__(
+        self, name: str, content: bytes | None, content_type: str = "text/plain"
+    ) -> None:
         content = content or b""
         super().__init__(
             BytesIO(content), None, name, content_type, len(content), None, None
         )
 
     @classmethod
-    def from_dict(cls, file_dict):
+    def from_dict(cls, file_dict: dict[str, Any]) -> SimpleUploadedFile:
         """
         Create a SimpleUploadedFile object from a dictionary with keys:
            - filename

plain/internal/files/uploadhandler.py

@@ -2,16 +2,25 @@
 Base file upload handler classes, and the built-in concrete subclasses
 """
 
+from __future__ import annotations
+
 import os
 from io import BytesIO
+from typing import TYPE_CHECKING
 
 from plain.internal.files.uploadedfile import (
     InMemoryUploadedFile,
     TemporaryUploadedFile,
+    UploadedFile,
 )
 from plain.runtime import settings
 from plain.utils.module_loading import import_string
 
+if TYPE_CHECKING:
+    from typing import Any
+
+    from plain.http import Request
+
 __all__ = [
     "UploadFileException",
     "StopUpload",
@@ -37,7 +46,7 @@ class StopUpload(UploadFileException):
     This exception is raised when an upload must abort.
     """
 
-    def __init__(self, connection_reset=False):
+    def __init__(self, connection_reset: bool = False) -> None:
         """
         If ``connection_reset`` is ``True``, Plain knows will halt the upload
         without consuming the rest of the upload. This will cause the browser to
@@ -45,7 +54,7 @@ class StopUpload(UploadFileException):
         """
         self.connection_reset = connection_reset
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.connection_reset:
             return "StopUpload: Halt current upload."
         else:
@@ -76,7 +85,7 @@ class FileUploadHandler:
 
     chunk_size = 64 * 2**10  # : The default chunk size is 64 KB.
 
-    def __init__(self, request=None):
+    def __init__(self, request: Request | None = None) -> None:
         self.file_name = None
         self.content_type = None
         self.content_length = None
@@ -85,8 +94,13 @@ class FileUploadHandler:
         self.request = request
 
     def handle_raw_input(
-        self, input_data, meta, content_length, boundary, encoding=None
-    ):
+        self,
+        input_data: Any,
+        meta: dict[str, Any],
+        content_length: int,
+        boundary: bytes,
+        encoding: str | None = None,
+    ) -> None:
         """
         Handle the raw input from the client.
 
@@ -106,13 +120,13 @@ class FileUploadHandler:
 
     def new_file(
         self,
-        field_name,
-        file_name,
-        content_type,
-        content_length,
-        charset=None,
-        content_type_extra=None,
-    ):
+        field_name: str,
+        file_name: str,
+        content_type: str,
+        content_length: int,
+        charset: str | None = None,
+        content_type_extra: dict[str, str] | None = None,
+    ) -> None:
         """
         Signal that a new file has been started.
 
@@ -126,7 +140,7 @@ class FileUploadHandler:
         self.charset = charset
         self.content_type_extra = content_type_extra
 
-    def receive_data_chunk(self, raw_data, start):
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> bytes | None:
         """
         Receive data from the streamed upload parser. ``start`` is the position
         in the file of the chunk.
@@ -135,7 +149,7 @@ class FileUploadHandler:
             "subclasses of FileUploadHandler must provide a receive_data_chunk() method"
         )
 
-    def file_complete(self, file_size):
+    def file_complete(self, file_size: int) -> UploadedFile | None:
         """
         Signal that a file has completed. File size corresponds to the actual
         size accumulated by all the chunks.
@@ -146,14 +160,14 @@ class FileUploadHandler:
             "subclasses of FileUploadHandler must provide a file_complete() method"
         )
 
-    def upload_complete(self):
+    def upload_complete(self) -> None:
         """
         Signal that the upload is complete. Subclasses should perform cleanup
         that is necessary for this handler.
         """
         pass
 
-    def upload_interrupted(self):
+    def upload_interrupted(self) -> None:
         """
         Signal that the upload was interrupted. Subclasses should perform
         cleanup that is necessary for this handler.
@@ -166,7 +180,7 @@ class TemporaryFileUploadHandler(FileUploadHandler):
     Upload handler that streams data into a temporary file.
     """
 
-    def new_file(self, *args, **kwargs):
+    def new_file(self, *args: Any, **kwargs: Any) -> None:
         """
         Create the file object to append to as data is coming in.
         """
@@ -175,15 +189,16 @@ class TemporaryFileUploadHandler(FileUploadHandler):
             self.file_name, self.content_type, 0, self.charset, self.content_type_extra
         )
 
-    def receive_data_chunk(self, raw_data, start):
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> None:
         self.file.write(raw_data)
+        return None
 
-    def file_complete(self, file_size):
+    def file_complete(self, file_size: int) -> TemporaryUploadedFile:
         self.file.seek(0)
         self.file.size = file_size
         return self.file
 
-    def upload_interrupted(self):
+    def upload_interrupted(self) -> None:
         if hasattr(self, "file"):
             temp_location = self.file.temporary_file_path()
             try:
@@ -199,8 +214,13 @@ class MemoryFileUploadHandler(FileUploadHandler):
     """
 
     def handle_raw_input(
-        self, input_data, meta, content_length, boundary, encoding=None
-    ):
+        self,
+        input_data: Any,
+        meta: dict[str, Any],
+        content_length: int,
+        boundary: bytes,
+        encoding: str | None = None,
+    ) -> None:
         """
         Use the content_length to signal whether or not this handler should be
         used.
@@ -209,23 +229,24 @@ class MemoryFileUploadHandler(FileUploadHandler):
         # If the post is too large, we cannot use the Memory handler.
         self.activated = content_length <= settings.FILE_UPLOAD_MAX_MEMORY_SIZE
 
-    def new_file(self, *args, **kwargs):
+    def new_file(self, *args: Any, **kwargs: Any) -> None:
         super().new_file(*args, **kwargs)
         if self.activated:
             self.file = BytesIO()
             raise StopFutureHandlers()
 
-    def receive_data_chunk(self, raw_data, start):
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> bytes | None:
         """Add the data to the BytesIO file."""
         if self.activated:
             self.file.write(raw_data)
+            return None
         else:
             return raw_data
 
-    def file_complete(self, file_size):
+    def file_complete(self, file_size: int) -> InMemoryUploadedFile | None:
         """Return a file object if this handler is activated."""
         if not self.activated:
-            return
+            return None
 
         self.file.seek(0)
         return InMemoryUploadedFile(
@@ -239,13 +260,13 @@ class MemoryFileUploadHandler(FileUploadHandler):
         )
 
 
-def load_handler(path, *args, **kwargs):
+def load_handler(path: str, *args: Any, **kwargs: Any) -> FileUploadHandler:
     """
     Given a path to a handler, return an instance of that handler.
 
     E.g.::
-        >>> from plain.http import HttpRequest
-        >>> request = HttpRequest()
+        >>> from plain.http import Request
+        >>> request = Request()
         >>> load_handler(
         ...     'plain.internal.files.uploadhandler.TemporaryFileUploadHandler',
         ...     request,

plain/internal/files/utils.py

@@ -1,10 +1,17 @@
+from __future__ import annotations
+
 import os
 import pathlib
+from typing import TYPE_CHECKING
 
 from plain.exceptions import SuspiciousFileOperation
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import Any
+
 
-def validate_file_name(name, allow_relative_path=False):
+def validate_file_name(name: str, allow_relative_path: bool = False) -> str:
     # Remove potentially dangerous names
     if os.path.basename(name) in {"", ".", ".."}:
         raise SuspiciousFileOperation(f"Could not derive file name from '{name}'")
@@ -50,29 +57,29 @@ class FileProxyMixin:
     writelines = property(lambda self: self.file.writelines)
 
     @property
-    def closed(self):
+    def closed(self) -> bool:
         return not self.file or self.file.closed
 
-    def readable(self):
+    def readable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "readable"):
             return self.file.readable()
         return True
 
-    def writable(self):
+    def writable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "writable"):
             return self.file.writable()
         return "w" in getattr(self.file, "mode", "")
 
-    def seekable(self):
+    def seekable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "seekable"):
             return self.file.seekable()
         return True
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Any]:
         return iter(self.file)

plain/internal/handlers/base.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import logging
 import types
+from typing import TYPE_CHECKING
 
 from opentelemetry import baggage, trace
 from opentelemetry.semconv.attributes import http_attributes, url_attributes
@@ -12,6 +15,12 @@ from plain.utils.module_loading import import_string
 
 from .exception import convert_exception_to_response
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import Request, Response
+    from plain.urls import ResolverMatch
+
 logger = logging.getLogger("plain.request")
 
 
@@ -34,9 +43,9 @@ tracer = trace.get_tracer("plain")
 
 
 class BaseHandler:
-    _middleware_chain = None
+    _middleware_chain: Callable[[Request], Response] | None = None
 
-    def load_middleware(self):
+    def load_middleware(self) -> None:
         """
         Populate middleware lists from settings.MIDDLEWARE.
 
@@ -63,8 +72,8 @@ class BaseHandler:
         # as a flag for initialization being complete.
         self._middleware_chain = handler
 
-    def get_response(self, request):
-        """Return a Response object for the given HttpRequest."""
+    def get_response(self, request: Request) -> Response:
+        """Return a Response object for the given Request."""
 
         span_attributes = {
             "plain.request.id": request.unique_id,
@@ -115,7 +124,7 @@ class BaseHandler:
                 )
             return response
 
-    def _get_response(self, request):
+    def _get_response(self, request: Request) -> Response:
         """
         Resolve and call the view, then apply view, exception, and
         template_response middleware. This method is everything that happens
@@ -132,7 +141,7 @@ class BaseHandler:
 
         return response
 
-    def resolve_request(self, request):
+    def resolve_request(self, request: Request) -> ResolverMatch:
         """
         Retrieve/set the urlrouter for the request. Return the view resolved,
         with its args and kwargs.
@@ -154,7 +163,12 @@ class BaseHandler:
         request.resolver_match = resolver_match
         return resolver_match
 
-    def check_response(self, response, callback, name=None):
+    def check_response(
+        self,
+        response: Response | None,
+        callback: Callable[..., Response],
+        name: str | None = None,
+    ) -> None:
         """
         Raise an error if the view returned None or an uncalled coroutine.
         """