Pyjoyment 0.1.0__py3-none-any.whl

Pyjo/Asset/File.py

@@ -0,0 +1,377 @@
+"""
+Pyjo.Asset.File - File storage for HTTP content
+===============================================
+::
+
+    from Pyjo.Asset.File import File
+
+    # Temporary file
+    file = File()
+    file.add_chunk(b'foo bar baz')
+    if file.contains(b'bar') >= 0:
+        print('File contains "bar"')
+    print(file.slurp())
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjo.Asset.File
+
+    # Temporary file
+    file = Pyjo.Asset.File.new()
+    file.add_chunk(b'foo bar baz')
+    if file.contains(b'bar') >= 0:
+        print('File contains "bar"')
+    print(file.slurp())
+
+    # Existing file
+    file = Pyjo.Asset.File.new(path='/home/sri/foo.txt')
+    file.move_to('/yada.txt')
+    print(file.slurp())
+
+:mod:`Pyjo.Asset.File` is a file storage backend for HTTP content.
+
+The end of a ``with`` block closes the file, and deletes it with
+:attr:`~Pyjo_Asset_File.cleanup`.
+
+Events
+------
+
+:mod:`Pyjo.Asset.File` inherits all events from :mod:`Pyjo.Asset`.
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojo::Asset::File <https://github.com/mojolicious/mojo/blob/v9.49/lib/Mojo/Asset/File.pm>`_
+of Mojolicious 9.49.
+"""
+
+import Pyjo.Asset
+import Pyjo.Exception
+import Pyjo.File
+
+import atexit
+import builtins
+import os
+import sys
+import tempfile
+import weakref
+
+from types import TracebackType
+from typing import IO, Self
+
+
+type Anything = builtins.object
+
+
+class Pyjo_Asset_File(Pyjo.Asset.object):
+    """
+    :mod:`Pyjo.Asset.File` inherits all methods from :mod:`Pyjo.Asset` and
+    implements the following new ones.
+    """
+
+    def __init__(
+        self,
+        *,
+        cleanup: bool | None = None,
+        end_range: int | None = None,
+        handle: IO[bytes] | None = None,
+        path: str | os.PathLike[str] | None = None,
+        start_range: int = 0,
+        tmpdir: str | os.PathLike[str] | None = None,
+    ) -> None:
+        """::
+
+            file = Pyjo.Asset.File.new()
+            file = Pyjo.Asset.File.new(path='/home/sri/test.txt')
+
+        Construct a new :mod:`Pyjo.Asset.File` object.
+        """
+        super().__init__(end_range=end_range, start_range=start_range)
+
+        self.cleanup = cleanup
+        """::
+
+            boolean = file.cleanup
+            file.cleanup = boolean
+
+        Delete :attr:`path` automatically once the file is not used anymore.
+        """
+
+        self.path = None if path is None else os.fspath(path)
+        """::
+
+            path = file.path
+            file.path = '/home/sri/foo.txt'
+
+        File path used to create :attr:`handle`.
+        """
+
+        self._handle = handle
+        self._pid = os.getpid()
+        self._tmpdir = None if tmpdir is None else os.fspath(tmpdir)
+        _FILES.add(self)
+
+    def __del__(self) -> None:
+        # Module globals may be gone at the end of the interpreter
+        try:
+            if not sys.is_finalizing():
+                self.close()
+        except Exception:
+            pass
+
+    # Not in Mojolicious: a context manager closes the file where it ends, as PyPy frees the object only later
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self, type: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None
+    ) -> None:
+        self.close()
+
+    @property
+    def handle(self) -> IO[bytes]:
+        """::
+
+            handle = file.handle
+            file.handle = open('/home/sri/foo.txt', 'rb')
+
+        Filehandle, created on demand for :attr:`path`, which can be
+        generated automatically and safely based on :attr:`tmpdir`.
+        """
+        if self._handle is not None:
+            return self._handle
+
+        # Open existing file
+        path = self.path
+        if path is not None and os.path.exists(path):
+            self._handle = Pyjo.File.new(path).open('rb', buffering=0)
+            return self._handle
+
+        if self.cleanup is None:
+            self.cleanup = True
+
+        # Create a temporary file
+        if path is None:
+            fd, path = tempfile.mkstemp(prefix='pyjo.tmp.', dir=self.tmpdir)
+            os.close(fd)
+            self.path = path
+
+        # Create a specific file, appended to as Perl's +>> does
+        self._handle = Pyjo.File.new(path).open('a+b', buffering=0)
+        return self._handle
+
+    @handle.setter
+    def handle(self, value: IO[bytes]) -> None:
+        self._handle = value
+
+    @property
+    def tmpdir(self) -> str:
+        """::
+
+            tmpdir = file.tmpdir
+            file.tmpdir = '/tmp'
+
+        Temporary directory used to generate :attr:`path`, defaults to the
+        value of the ``PYJO_TMPDIR`` environment variable or auto-detection.
+        """
+        if self._tmpdir is None:
+            self._tmpdir = os.environ.get('PYJO_TMPDIR') or tempfile.gettempdir()
+        return self._tmpdir
+
+    @tmpdir.setter
+    def tmpdir(self, value: str | os.PathLike[str]) -> None:
+        self._tmpdir = os.fspath(value)
+
+    def add_chunk(self, chunk: bytes) -> Self:
+        """::
+
+            file = file.add_chunk(b'foo bar baz')
+
+        Add chunk of data.
+        """
+        try:
+            written = self.handle.write(chunk)
+        except OSError as e:
+            error = type(e)(f"Can't write to asset: {e.strerror}" if e.strerror else "Can't write to asset")
+            error.errno = e.errno
+            raise error from e
+        if written != len(chunk):
+            raise Pyjo.Exception.new("Can't write to asset: incomplete write")
+        return self
+
+    # Not in Mojolicious: what DESTROY does, which Python does when it frees the file, PyPy only later
+    def close(self) -> None:
+        """::
+
+            file.close()
+
+        Close :attr:`handle` and delete :attr:`path` with :attr:`cleanup`, as
+        it happens when the file is freed.
+        """
+        if (handle := self._handle) is not None:
+            handle.close()
+        if not self.cleanup or (path := self.path) is None:
+            return
+
+        # Only the process that created the file is allowed to remove it
+        if os.access(path, os.W_OK) and self._pid == os.getpid():
+            Pyjo.File.new(path).remove()
+
+    def contains(self, string: bytes) -> int:
+        """::
+
+            position = file.contains(b'bar')
+
+        Check if asset contains a specific string.
+        """
+        handle = self.handle
+        handle.seek(self.start_range, os.SEEK_SET)
+
+        # Calculate window size
+        end = self.end_range if self.end_range is not None else self.size
+        length = len(string)
+        size = length if length > 131072 else 131072
+        if size > end - self.start_range:
+            size = end - self.start_range
+
+        # Sliding window search
+        offset = 0
+        window = handle.read(length) or b''
+        start = len(window)
+        while offset < end:
+            # Read as much as possible
+            diff = end - (start + offset)
+            buffer = handle.read(diff if diff < size else size) or b''
+            read = len(buffer)
+            window += buffer
+
+            # Search window
+            if (pos := window.find(string)) >= 0:
+                return offset + pos
+            offset += read
+            if read == 0 or offset == end:
+                return -1
+
+            # Resize window
+            window = window[read:]
+
+        return -1
+
+    def get_chunk(self, offset: int, max: int | None = None) -> bytes:
+        """::
+
+            chunk = file.get_chunk(offset)
+            chunk = file.get_chunk(offset, max)
+
+        Get chunk of data starting from a specific position, defaults to a
+        maximum chunk size of ``131072`` bytes (128KiB).
+        """
+        if max is None:
+            max = 131072
+
+        offset += self.start_range
+        handle = self.handle
+        handle.seek(offset, os.SEEK_SET)
+
+        if (end := self.end_range) is not None:
+            if (chunk := end + 1 - offset) <= 0:
+                return b''
+            return handle.read(chunk if chunk < max else max) or b''
+        return handle.read(max) or b''
+
+    @property
+    def is_file(self) -> bool:
+        """::
+
+            boolean = file.is_file
+
+        True, this is a :mod:`Pyjo.Asset.File` object.
+        """
+        return True
+
+    def move_to(self, to: Anything) -> Self:
+        """::
+
+            file = file.move_to('/home/sri/bar.txt')
+
+        Move asset data into a specific file and disable :attr:`cleanup`.
+        """
+        # Windows requires that the handle is closed
+        self.handle.close()
+        self._handle = None
+
+        # Move file and prevent clean up
+        Pyjo.File.new(self.path).move_to(to)
+        self.path = str(to)
+        self.cleanup = False
+        return self
+
+    @property
+    def mtime(self) -> float:
+        """::
+
+            mtime = file.mtime
+
+        Modification time of asset.
+        """
+        return os.fstat(self.handle.fileno()).st_mtime
+
+    @property
+    def size(self) -> int:
+        """::
+
+            size = file.size
+
+        Size of asset data in bytes.
+        """
+        return os.fstat(self.handle.fileno()).st_size
+
+    def slurp(self) -> bytes:
+        """::
+
+            content = file.slurp()
+
+        Read all asset data at once.
+        """
+        handle = self.handle
+        handle.seek(0, os.SEEK_SET)
+        content = b''
+        try:
+            while buffer := handle.read(131072):
+                content += buffer
+        except OSError as e:
+            error = type(e)(f"Can't read from asset: {e.strerror}" if e.strerror else "Can't read from asset")
+            error.errno = e.errno
+            raise error from e
+        return content
+
+    def to_file(self) -> Self:
+        """::
+
+            file = file.to_file()
+
+        Does nothing but return the invocant, since we already have a
+        :mod:`Pyjo.Asset.File` object.
+        """
+        return self
+
+
+# Not in Mojolicious: the files that exist, which are closed, and deleted with cleanup, at the end of the interpreter, as
+# Perl does it then, while __del__ does nothing
+_FILES: 'weakref.WeakSet[Pyjo_Asset_File]' = weakref.WeakSet()
+
+
+@atexit.register
+def _close() -> None:
+    for file in list(_FILES):
+        try:
+            file.close()
+        except Exception:
+            pass
+
+
+new = Pyjo_Asset_File.new
+object = Pyjo_Asset_File
+File = Pyjo_Asset_File

Pyjo/Asset/Memory.py

@@ -0,0 +1,235 @@
+"""
+Pyjo.Asset.Memory - In-memory storage for HTTP content
+======================================================
+::
+
+    from Pyjo.Asset.Memory import Memory
+
+    mem = Memory()
+    mem.add_chunk(b'foo bar baz')
+    print(mem.slurp())
+
+    # Or import the module, as in Google Python Style Guide
+
+    import Pyjo.Asset.Memory
+
+    mem = Pyjo.Asset.Memory.new()
+    mem.add_chunk(b'foo bar baz')
+    print(mem.slurp())
+
+:mod:`Pyjo.Asset.Memory` is an in-memory storage backend for HTTP content.
+
+Events
+------
+
+:mod:`Pyjo.Asset.Memory` inherits all events from :mod:`Pyjo.Asset` and can
+emit the following new ones.
+
+upgrade
+~~~~~~~
+::
+
+    mem.on('upgrade', lambda mem, file: ...)
+
+Emitted when asset gets upgraded to a :mod:`Pyjo.Asset.File` object. ::
+
+    mem.on('upgrade', lambda mem, file: file.set(tmpdir='/tmp'))
+
+See also
+--------
+
+:mod:`Pyjoyment`, https://mojolicious.org.
+
+Ported from `Mojo::Asset::Memory <https://github.com/mojolicious/mojo/blob/v9.51/lib/Mojo/Asset/Memory.pm>`_
+of Mojolicious 9.51.
+"""
+
+import Pyjo.Asset
+import Pyjo.Asset.File
+import Pyjo.Exception
+import Pyjo.File
+
+import builtins
+import os
+import time
+
+from typing import Self
+
+
+type Anything = builtins.object
+
+# The time the program started, as Perl's $^T: the time this module is loaded
+MTIME = time.time()
+
+
+class Pyjo_Asset_Memory(Pyjo.Asset.object):
+    """
+    :mod:`Pyjo.Asset.Memory` inherits all methods from :mod:`Pyjo.Asset`
+    and implements the following new ones.
+    """
+
+    def __init__(
+        self,
+        *,
+        auto_upgrade: bool | None = None,
+        end_range: int | None = None,
+        max_memory_size: int | None = None,
+        mtime: float | None = None,
+        start_range: int = 0,
+    ) -> None:
+        """::
+
+            mem = Pyjo.Asset.Memory.new()
+            mem = Pyjo.Asset.Memory.new(max_memory_size=1024, auto_upgrade=True)
+
+        Construct a new :mod:`Pyjo.Asset.Memory` object.
+        """
+        super().__init__(end_range=end_range, start_range=start_range)
+
+        self.auto_upgrade = auto_upgrade
+        """::
+
+            boolean = mem.auto_upgrade
+            mem.auto_upgrade = boolean
+
+        Try to detect if content size exceeds :attr:`max_memory_size` limit
+        and automatically upgrade to a :mod:`Pyjo.Asset.File` object.
+        """
+
+        self._max_memory_size: int | None = max_memory_size
+
+        self._content = b''
+        self._frozen = False
+        self._mtime = mtime if mtime is not None else MTIME
+
+    @property
+    def max_memory_size(self) -> int:
+        """::
+
+            size = mem.max_memory_size
+            mem.max_memory_size = 1024
+
+        Maximum size in bytes of data to keep in memory before automatically
+        upgrading to a :mod:`Pyjo.Asset.File` object, defaults to the value
+        of the ``PYJO_MAX_MEMORY_SIZE`` environment variable or ``262144``
+        (256KiB).
+        """
+        if self._max_memory_size is None:
+            self._max_memory_size = int(os.environ.get('PYJO_MAX_MEMORY_SIZE') or 262144)
+        return self._max_memory_size
+
+    @max_memory_size.setter
+    def max_memory_size(self, value: int) -> None:
+        self._max_memory_size = value
+
+    @property
+    def mtime(self) -> float:
+        """::
+
+            mtime = mem.mtime
+            mem.mtime = 1408567500
+
+        Modification time of asset, defaults to the time the program started,
+        as Perl's ``$^T``.
+        """
+        return self._mtime
+
+    @mtime.setter
+    def mtime(self, value: float) -> None:
+        self._mtime = value
+
+    def add_chunk(self, chunk: bytes) -> Pyjo.Asset.object:
+        """::
+
+            mem = mem.add_chunk(b'foo bar baz')
+            file = mem.add_chunk(b'abc' * 262144)
+
+        Add chunk of data and upgrade to :mod:`Pyjo.Asset.File` object if
+        necessary.
+        """
+        if self._frozen:
+            raise Pyjo.Exception.new('Asset has been upgraded and is now frozen')
+        if self.auto_upgrade and (self.size + len(chunk)) > self.max_memory_size:
+            file = Pyjo.Asset.File.new()
+            self.emit('upgrade', file)
+            self._frozen = True
+            return file.add_chunk(self.slurp() + chunk)
+
+        self._content += chunk
+        return self
+
+    def contains(self, string: bytes) -> int:
+        """::
+
+            position = mem.contains(b'bar')
+
+        Check if asset contains a specific string.
+        """
+        start = self.start_range
+        pos = self._content.find(string, start)
+        if start and pos >= 0:
+            pos -= start
+        end = self.end_range
+
+        return -1 if end and (pos + len(string)) >= end else pos
+
+    def get_chunk(self, offset: int, max: int | None = None) -> bytes:
+        """::
+
+            chunk = mem.get_chunk(offset)
+            chunk = mem.get_chunk(offset, max)
+
+        Get chunk of data starting from a specific position, defaults to a
+        maximum chunk size of ``131072`` bytes (128KiB).
+        """
+        if max is None:
+            max = 131072
+
+        offset += self.start_range
+        if (end := self.end_range) is not None and (offset + max) > end:
+            max = end + 1 - offset
+
+        return self._content[offset : offset + max] if max > 0 else b''
+
+    def move_to(self, to: Anything) -> Self:
+        """::
+
+            mem = mem.move_to('/home/sri/foo.txt')
+
+        Move asset data into a specific file.
+        """
+        Pyjo.File.new(to).spew(self._content)
+        return self
+
+    @property
+    def size(self) -> int:
+        """::
+
+            size = mem.size
+
+        Size of asset data in bytes.
+        """
+        return len(self._content)
+
+    def slurp(self) -> bytes:
+        """::
+
+            content = mem.slurp()
+
+        Read all asset data at once.
+        """
+        return self._content
+
+    def to_file(self) -> Pyjo.Asset.File.object:
+        """::
+
+            file = mem.to_file()
+
+        Convert asset to :mod:`Pyjo.Asset.File` object.
+        """
+        return Pyjo.Asset.File.new().add_chunk(self.slurp())
+
+
+new = Pyjo_Asset_Memory.new
+object = Pyjo_Asset_Memory
+Memory = Pyjo_Asset_Memory