plain 0.66.0__py3-none-any.whl → 0.101.2__py3-none-any.whl

plain/internal/files/base.py

@@ -1,14 +1,21 @@
+from __future__ import annotations
+
 import os
 from functools import cached_property
 from io import UnsupportedOperation
+from typing import TYPE_CHECKING
 
 from plain.internal.files.utils import FileProxyMixin
 
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import IO, Any
+
 
 class File(FileProxyMixin):
     DEFAULT_CHUNK_SIZE = 64 * 2**10
 
-    def __init__(self, file, name=None):
+    def __init__(self, file: IO[Any], name: str | None = None) -> None:
         self.file = file
         if name is None:
             name = getattr(file, "name", None)
@@ -16,22 +23,22 @@ class File(FileProxyMixin):
         if hasattr(file, "mode"):
             self.mode = file.mode
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.name or ""
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<{}: {}>".format(self.__class__.__name__, self or "None")
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return bool(self.name)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return self.size
 
     @cached_property
-    def size(self):
+    def size(self) -> int:
         if hasattr(self.file, "size"):
-            return self.file.size
+            return self.file.size  # type: ignore[return-value]
         if hasattr(self.file, "name"):
             try:
                 return os.path.getsize(self.file.name)
@@ -45,7 +52,7 @@ class File(FileProxyMixin):
             return size
         raise AttributeError("Unable to determine the file's size.")
 
-    def chunks(self, chunk_size=None):
+    def chunks(self, chunk_size: int | None = None) -> Iterator[bytes]:
         """
         Read the file and yield chunks of ``chunk_size`` bytes (defaults to
         ``File.DEFAULT_CHUNK_SIZE``).
@@ -62,7 +69,7 @@ class File(FileProxyMixin):
                 break
             yield data
 
-    def multiple_chunks(self, chunk_size=None):
+    def multiple_chunks(self, chunk_size: int | None = None) -> bool:
         """
         Return ``True`` if you can expect multiple chunks.
 
@@ -72,7 +79,7 @@ class File(FileProxyMixin):
         """
         return self.size > (chunk_size or self.DEFAULT_CHUNK_SIZE)
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[bytes | str]:
         # Iterate over this file-like object by newlines
         buffer_ = None
         for chunk in self.chunks():
@@ -99,13 +106,18 @@ class File(FileProxyMixin):
         if buffer_ is not None:
             yield buffer_
 
-    def __enter__(self):
+    def __enter__(self) -> File:
         return self
 
-    def __exit__(self, exc_type, exc_value, tb):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        tb: Any,
+    ) -> None:
         self.close()
 
-    def open(self, mode=None):
+    def open(self, mode: str | None = None) -> File:
         if not self.closed:
             self.seek(0)
         elif self.name and os.path.exists(self.name):
@@ -114,20 +126,24 @@ class File(FileProxyMixin):
             raise ValueError("The file cannot be reopened.")
         return self
 
-    def close(self):
+    def close(self) -> None:
         self.file.close()
 
 
-def endswith_cr(line):
+def endswith_cr(line: str | bytes) -> bool:
     """Return True if line (a text or bytestring) ends with '\r'."""
-    return line.endswith("\r" if isinstance(line, str) else b"\r")
+    if isinstance(line, str):
+        return line.endswith("\r")
+    return line.endswith(b"\r")
 
 
-def endswith_lf(line):
+def endswith_lf(line: str | bytes) -> bool:
     """Return True if line (a text or bytestring) ends with '\n'."""
-    return line.endswith("\n" if isinstance(line, str) else b"\n")
+    if isinstance(line, str):
+        return line.endswith("\n")
+    return line.endswith(b"\n")
 
 
-def equals_lf(line):
+def equals_lf(line: str | bytes) -> bool:
     """Return True if line (a text or bytestring) equals '\n'."""
     return line == ("\n" if isinstance(line, str) else b"\n")

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,18 @@ arguments available in tempfile.NamedTemporaryFile.
 2: https://bugs.python.org/issue14243
 """
 
+from __future__ import annotations
+
 import os
 import tempfile
+from collections.abc import Callable
+from typing import TYPE_CHECKING
 
 from plain.internal.files.utils import FileProxyMixin
 
+if TYPE_CHECKING:
+    from typing import Any
+
 __all__ = (
     "NamedTemporaryFile",
     "gettempdir",
@@ -39,7 +46,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)
@@ -48,9 +62,9 @@ if os.name == "nt":
         # Because close can be called during shutdown
         # we need to cache os.unlink and access it
         # as self.unlink only
-        unlink = os.unlink
+        unlink: Callable[[str], None] = os.unlink
 
-        def close(self):
+        def close(self) -> None:
             if not self.close_called:
                 self.close_called = True
                 try:
@@ -62,14 +76,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, cast
 
 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],
+        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 | None:
         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,28 @@ 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 | None,
+        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
+        file = cast(
+            IO[Any],
+            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 +117,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 | None,
+        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 +146,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