plain 0.1.0__py3-none-any.whl

plain/internal/files/README.md

@@ -0,0 +1,3 @@
+# Files
+
+File upload handling and utilities.

plain/internal/files/__init__.py

@@ -0,0 +1,3 @@
+from plain.internal.files.base import File
+
+__all__ = ["File"]

plain/internal/files/base.py

@@ -0,0 +1,161 @@
+import os
+from io import BytesIO, StringIO, UnsupportedOperation
+
+from plain.internal.files.utils import FileProxyMixin
+from plain.utils.functional import cached_property
+
+
+class File(FileProxyMixin):
+    DEFAULT_CHUNK_SIZE = 64 * 2**10
+
+    def __init__(self, file, name=None):
+        self.file = file
+        if name is None:
+            name = getattr(file, "name", None)
+        self.name = name
+        if hasattr(file, "mode"):
+            self.mode = file.mode
+
+    def __str__(self):
+        return self.name or ""
+
+    def __repr__(self):
+        return "<{}: {}>".format(self.__class__.__name__, self or "None")
+
+    def __bool__(self):
+        return bool(self.name)
+
+    def __len__(self):
+        return self.size
+
+    @cached_property
+    def size(self):
+        if hasattr(self.file, "size"):
+            return self.file.size
+        if hasattr(self.file, "name"):
+            try:
+                return os.path.getsize(self.file.name)
+            except (OSError, TypeError):
+                pass
+        if hasattr(self.file, "tell") and hasattr(self.file, "seek"):
+            pos = self.file.tell()
+            self.file.seek(0, os.SEEK_END)
+            size = self.file.tell()
+            self.file.seek(pos)
+            return size
+        raise AttributeError("Unable to determine the file's size.")
+
+    def chunks(self, chunk_size=None):
+        """
+        Read the file and yield chunks of ``chunk_size`` bytes (defaults to
+        ``File.DEFAULT_CHUNK_SIZE``).
+        """
+        chunk_size = chunk_size or self.DEFAULT_CHUNK_SIZE
+        try:
+            self.seek(0)
+        except (AttributeError, UnsupportedOperation):
+            pass
+
+        while True:
+            data = self.read(chunk_size)
+            if not data:
+                break
+            yield data
+
+    def multiple_chunks(self, chunk_size=None):
+        """
+        Return ``True`` if you can expect multiple chunks.
+
+        NB: If a particular file representation is in memory, subclasses should
+        always return ``False`` -- there's no good reason to read from memory in
+        chunks.
+        """
+        return self.size > (chunk_size or self.DEFAULT_CHUNK_SIZE)
+
+    def __iter__(self):
+        # Iterate over this file-like object by newlines
+        buffer_ = None
+        for chunk in self.chunks():
+            for line in chunk.splitlines(True):
+                if buffer_:
+                    if endswith_cr(buffer_) and not equals_lf(line):
+                        # Line split after a \r newline; yield buffer_.
+                        yield buffer_
+                        # Continue with line.
+                    else:
+                        # Line either split without a newline (line
+                        # continues after buffer_) or with \r\n
+                        # newline (line == b'\n').
+                        line = buffer_ + line
+                    # buffer_ handled, clear it.
+                    buffer_ = None
+
+                # If this is the end of a \n or \r\n line, yield.
+                if endswith_lf(line):
+                    yield line
+                else:
+                    buffer_ = line
+
+        if buffer_ is not None:
+            yield buffer_
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_value, tb):
+        self.close()
+
+    def open(self, mode=None):
+        if not self.closed:
+            self.seek(0)
+        elif self.name and os.path.exists(self.name):
+            self.file = open(self.name, mode or self.mode)
+        else:
+            raise ValueError("The file cannot be reopened.")
+        return self
+
+    def close(self):
+        self.file.close()
+
+
+class ContentFile(File):
+    """
+    A File-like object that takes just raw content, rather than an actual file.
+    """
+
+    def __init__(self, content, name=None):
+        stream_class = StringIO if isinstance(content, str) else BytesIO
+        super().__init__(stream_class(content), name=name)
+        self.size = len(content)
+
+    def __str__(self):
+        return "Raw content"
+
+    def __bool__(self):
+        return True
+
+    def open(self, mode=None):
+        self.seek(0)
+        return self
+
+    def close(self):
+        pass
+
+    def write(self, data):
+        self.__dict__.pop("size", None)  # Clear the computed size.
+        return self.file.write(data)
+
+
+def endswith_cr(line):
+    """Return True if line (a text or bytestring) ends with '\r'."""
+    return line.endswith("\r" if isinstance(line, str) else b"\r")
+
+
+def endswith_lf(line):
+    """Return True if line (a text or bytestring) ends with '\n'."""
+    return line.endswith("\n" if isinstance(line, str) else b"\n")
+
+
+def equals_lf(line):
+    """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

@@ -0,0 +1,127 @@
+"""
+Portable file locking utilities.
+
+Based partially on an example by Jonathan Feignberg in the Python
+Cookbook [1] (licensed under the Python Software License) and a ctypes port by
+Anatoly Techtonik for Roundup [2] (license [3]).
+
+[1] https://code.activestate.com/recipes/65203/
+[2] https://sourceforge.net/p/roundup/code/ci/default/tree/roundup/backends/portalocker.py  # NOQA
+[3] https://sourceforge.net/p/roundup/code/ci/default/tree/COPYING.txt
+
+Example Usage::
+
+    >>> from plain.internal.files import locks
+    >>> with open('./file', 'wb') as f:
+    ...     locks.lock(f, locks.LOCK_EX)
+    ...     f.write('Plain')
+"""
+import os
+
+__all__ = ("LOCK_EX", "LOCK_SH", "LOCK_NB", "lock", "unlock")
+
+
+def _fd(f):
+    """Get a filedescriptor from something which could be a file or an fd."""
+    return f.fileno() if hasattr(f, "fileno") else f
+
+
+if os.name == "nt":
+    import msvcrt
+    from ctypes import (
+        POINTER,
+        Structure,
+        Union,
+        WinDLL,
+        byref,
+        c_int64,
+        c_ulong,
+        c_void_p,
+        sizeof,
+    )
+    from ctypes.wintypes import BOOL, DWORD, HANDLE
+
+    LOCK_SH = 0  # the default
+    LOCK_NB = 0x1  # LOCKFILE_FAIL_IMMEDIATELY
+    LOCK_EX = 0x2  # LOCKFILE_EXCLUSIVE_LOCK
+
+    # --- Adapted from the pyserial project ---
+    # detect size of ULONG_PTR
+    if sizeof(c_ulong) != sizeof(c_void_p):
+        ULONG_PTR = c_int64
+    else:
+        ULONG_PTR = c_ulong
+    PVOID = c_void_p
+
+    # --- Union inside Structure by stackoverflow:3480240 ---
+    class _OFFSET(Structure):
+        _fields_ = [("Offset", DWORD), ("OffsetHigh", DWORD)]
+
+    class _OFFSET_UNION(Union):
+        _anonymous_ = ["_offset"]
+        _fields_ = [("_offset", _OFFSET), ("Pointer", PVOID)]
+
+    class OVERLAPPED(Structure):
+        _anonymous_ = ["_offset_union"]
+        _fields_ = [
+            ("Internal", ULONG_PTR),
+            ("InternalHigh", ULONG_PTR),
+            ("_offset_union", _OFFSET_UNION),
+            ("hEvent", HANDLE),
+        ]
+
+    LPOVERLAPPED = POINTER(OVERLAPPED)
+
+    # --- Define function prototypes for extra safety ---
+    kernel32 = WinDLL("kernel32")
+    LockFileEx = kernel32.LockFileEx
+    LockFileEx.restype = BOOL
+    LockFileEx.argtypes = [HANDLE, DWORD, DWORD, DWORD, DWORD, LPOVERLAPPED]
+    UnlockFileEx = kernel32.UnlockFileEx
+    UnlockFileEx.restype = BOOL
+    UnlockFileEx.argtypes = [HANDLE, DWORD, DWORD, DWORD, LPOVERLAPPED]
+
+    def lock(f, flags):
+        hfile = msvcrt.get_osfhandle(_fd(f))
+        overlapped = OVERLAPPED()
+        ret = LockFileEx(hfile, flags, 0, 0, 0xFFFF0000, byref(overlapped))
+        return bool(ret)
+
+    def unlock(f):
+        hfile = msvcrt.get_osfhandle(_fd(f))
+        overlapped = OVERLAPPED()
+        ret = UnlockFileEx(hfile, 0, 0, 0xFFFF0000, byref(overlapped))
+        return bool(ret)
+
+else:
+    try:
+        import fcntl
+
+        LOCK_SH = fcntl.LOCK_SH  # shared lock
+        LOCK_NB = fcntl.LOCK_NB  # non-blocking
+        LOCK_EX = fcntl.LOCK_EX
+    except (ImportError, AttributeError):
+        # File locking is not supported.
+        LOCK_EX = LOCK_SH = LOCK_NB = 0
+
+        # Dummy functions that don't do anything.
+        def lock(f, flags):
+            # File is not locked
+            return False
+
+        def unlock(f):
+            # File is unlocked
+            return True
+
+    else:
+
+        def lock(f, flags):
+            try:
+                fcntl.flock(_fd(f), flags)
+                return True
+            except BlockingIOError:
+                return False
+
+        def unlock(f):
+            fcntl.flock(_fd(f), fcntl.LOCK_UN)
+            return True

plain/internal/files/move.py

@@ -0,0 +1,102 @@
+"""
+Move a file in the safest way possible::
+
+    >>> from plain.internal.files.move import file_move_safe
+    >>> file_move_safe("/tmp/old_file", "/tmp/new_file")
+"""
+
+import os
+from shutil import copymode, copystat
+
+from plain.internal.files import locks
+
+__all__ = ["file_move_safe"]
+
+
+def _samefile(src, dst):
+    # Macintosh, Unix.
+    if hasattr(os.path, "samefile"):
+        try:
+            return os.path.samefile(src, dst)
+        except OSError:
+            return False
+
+    # All other platforms: check for same pathname.
+    return os.path.normcase(os.path.abspath(src)) == os.path.normcase(
+        os.path.abspath(dst)
+    )
+
+
+def file_move_safe(
+    old_file_name, new_file_name, chunk_size=1024 * 64, allow_overwrite=False
+):
+    """
+    Move a file from one location to another in the safest way possible.
+
+    First, try ``os.rename``, which is simple but will break across filesystems.
+    If that fails, stream manually from one file to another in pure Python.
+
+    If the destination file exists and ``allow_overwrite`` is ``False``, raise
+    ``FileExistsError``.
+    """
+    # There's no reason to move if we don't have to.
+    if _samefile(old_file_name, new_file_name):
+        return
+
+    try:
+        if not allow_overwrite and os.access(new_file_name, os.F_OK):
+            raise FileExistsError(
+                "Destination file %s exists and allow_overwrite is False."
+                % new_file_name
+            )
+
+        os.rename(old_file_name, new_file_name)
+        return
+    except OSError:
+        # OSError happens with os.rename() if moving to another filesystem or
+        # when moving opened files on certain operating systems.
+        pass
+
+    # first open the old file, so that it won't go away
+    with open(old_file_name, "rb") as old_file:
+        # now open the new file, not forgetting allow_overwrite
+        fd = os.open(
+            new_file_name,
+            (
+                os.O_WRONLY
+                | os.O_CREAT
+                | getattr(os, "O_BINARY", 0)
+                | (os.O_EXCL if not allow_overwrite else 0)
+            ),
+        )
+        try:
+            locks.lock(fd, locks.LOCK_EX)
+            current_chunk = None
+            while current_chunk != b"":
+                current_chunk = old_file.read(chunk_size)
+                os.write(fd, current_chunk)
+        finally:
+            locks.unlock(fd)
+            os.close(fd)
+
+    try:
+        copystat(old_file_name, new_file_name)
+    except PermissionError:
+        # Certain filesystems (e.g. CIFS) fail to copy the file's metadata if
+        # the type of the destination filesystem isn't the same as the source
+        # filesystem. This also happens with some SELinux-enabled systems.
+        # Ignore that, but try to set basic permissions.
+        try:
+            copymode(old_file_name, new_file_name)
+        except PermissionError:
+            pass
+
+    try:
+        os.remove(old_file_name)
+    except PermissionError as e:
+        # Certain operating systems (Cygwin and Windows)
+        # fail when deleting opened files, ignore it.  (For the
+        # systems where this happens, temporary files will be auto-deleted
+        # on close anyway.)
+        if getattr(e, "winerror", 0) != 32:
+            raise

plain/internal/files/temp.py

@@ -0,0 +1,79 @@
+"""
+The temp module provides a NamedTemporaryFile that can be reopened in the same
+process on any platform. Most platforms use the standard Python
+tempfile.NamedTemporaryFile class, but Windows users are given a custom class.
+
+This is needed because the Python implementation of NamedTemporaryFile uses the
+O_TEMPORARY flag under Windows, which prevents the file from being reopened
+if the same flag is not provided [1][2]. Note that this does not address the
+more general issue of opening a file for writing and reading in multiple
+processes in a manner that works across platforms.
+
+The custom version of NamedTemporaryFile doesn't support the same keyword
+arguments available in tempfile.NamedTemporaryFile.
+
+1: https://mail.python.org/pipermail/python-list/2005-December/336957.html
+2: https://bugs.python.org/issue14243
+"""
+
+import os
+import tempfile
+
+from plain.internal.files.utils import FileProxyMixin
+
+__all__ = (
+    "NamedTemporaryFile",
+    "gettempdir",
+)
+
+
+if os.name == "nt":
+
+    class TemporaryFile(FileProxyMixin):
+        """
+        Temporary file object constructor that supports reopening of the
+        temporary file in Windows.
+
+        Unlike tempfile.NamedTemporaryFile from the standard library,
+        __init__() doesn't support the 'delete', 'buffering', 'encoding', or
+        'newline' keyword arguments.
+        """
+
+        def __init__(self, mode="w+b", bufsize=-1, suffix="", prefix="", dir=None):
+            fd, name = tempfile.mkstemp(suffix=suffix, prefix=prefix, dir=dir)
+            self.name = name
+            self.file = os.fdopen(fd, mode, bufsize)
+            self.close_called = False
+
+        # Because close can be called during shutdown
+        # we need to cache os.unlink and access it
+        # as self.unlink only
+        unlink = os.unlink
+
+        def close(self):
+            if not self.close_called:
+                self.close_called = True
+                try:
+                    self.file.close()
+                except OSError:
+                    pass
+                try:
+                    self.unlink(self.name)
+                except OSError:
+                    pass
+
+        def __del__(self):
+            self.close()
+
+        def __enter__(self):
+            self.file.__enter__()
+            return self
+
+        def __exit__(self, exc, value, tb):
+            self.file.__exit__(exc, value, tb)
+
+    NamedTemporaryFile = TemporaryFile
+else:
+    NamedTemporaryFile = tempfile.NamedTemporaryFile
+
+gettempdir = tempfile.gettempdir

plain/internal/files/uploadedfile.py

@@ -0,0 +1,150 @@
+"""
+Classes representing uploaded files.
+"""
+
+import os
+from io import BytesIO
+
+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
+
+__all__ = (
+    "UploadedFile",
+    "TemporaryUploadedFile",
+    "InMemoryUploadedFile",
+    "SimpleUploadedFile",
+)
+
+
+class UploadedFile(File):
+    """
+    An abstract uploaded file (``TemporaryUploadedFile`` and
+    ``InMemoryUploadedFile`` are the built-in concrete subclasses).
+
+    An ``UploadedFile`` object behaves somewhat like a file object and
+    represents some file data that the user submitted with a form.
+    """
+
+    def __init__(
+        self,
+        file=None,
+        name=None,
+        content_type=None,
+        size=None,
+        charset=None,
+        content_type_extra=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):
+        return f"<{self.__class__.__name__}: {self.name} ({self.content_type})>"
+
+    def _get_name(self):
+        return self._name
+
+    def _set_name(self, name):
+        # 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.
+            name = os.path.basename(name)
+
+            # File names longer than 255 characters can cause problems on older OSes.
+            if len(name) > 255:
+                name, ext = os.path.splitext(name)
+                ext = ext[:255]
+                name = name[: 255 - len(ext)] + ext
+
+            name = validate_file_name(name)
+
+        self._name = name
+
+    name = property(_get_name, _set_name)
+
+
+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):
+        _, 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):
+        """Return the full path of this file."""
+        return self.file.name
+
+    def close(self):
+        try:
+            return self.file.close()
+        except FileNotFoundError:
+            # The file was moved or deleted before the tempfile could unlink
+            # it. Still sets self.file.close_called and calls
+            # self.file.file.close() before the exception.
+            pass
+
+
+class InMemoryUploadedFile(UploadedFile):
+    """
+    A file uploaded into memory (i.e. stream-to-memory).
+    """
+
+    def __init__(
+        self,
+        file,
+        field_name,
+        name,
+        content_type,
+        size,
+        charset,
+        content_type_extra=None,
+    ):
+        super().__init__(file, name, content_type, size, charset, content_type_extra)
+        self.field_name = field_name
+
+    def open(self, mode=None):
+        self.file.seek(0)
+        return self
+
+    def chunks(self, chunk_size=None):
+        self.file.seek(0)
+        yield self.read()
+
+    def multiple_chunks(self, chunk_size=None):
+        # Since it's in memory, we'll never have multiple chunks.
+        return False
+
+
+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"):
+        content = content or b""
+        super().__init__(
+            BytesIO(content), None, name, content_type, len(content), None, None
+        )
+
+    @classmethod
+    def from_dict(cls, file_dict):
+        """
+        Create a SimpleUploadedFile object from a dictionary with keys:
+           - filename
+           - content-type
+           - content
+        """
+        return cls(
+            file_dict["filename"],
+            file_dict["content"],
+            file_dict.get("content-type", "text/plain"),
+        )