arrayfile 0.1.0__tar.gz → 0.1.1__tar.gz

{arrayfile-0.1.0 → arrayfile-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayfile
-Version: 0.1.0
+Version: 0.1.1
 Summary: Arrays backed by disk
 Keywords: logging,terminal,scrollback,indexing
 Author-email: Gareth Davidson <gaz@bitplane.net>
@@ -8,7 +8,6 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -44,7 +43,8 @@ pip install arrayfile
 
 ### 🗑 Temporary Array
 
-This creates an array in your temp dir:
+This creates an array in your temp dir. Its file is deleted when the array is
+closed or garbage-collected. Arrays created with an explicit filename are kept:
 
 ```python
 from arrayfile import Array

{arrayfile-0.1.0 → arrayfile-0.1.1}/README.md

@@ -15,7 +15,8 @@ pip install arrayfile
 
 ### 🗑 Temporary Array
 
-This creates an array in your temp dir:
+This creates an array in your temp dir. Its file is deleted when the array is
+closed or garbage-collected. Arrays created with an explicit filename are kept:
 
 ```python
 from arrayfile import Array

{arrayfile-0.1.0 → arrayfile-0.1.1}/pyproject.toml

@@ -1,18 +1,17 @@
 [project]
 name = "arrayfile"
 description = "Arrays backed by disk"
-version = "0.1.0"
+version = "0.1.1"
 authors = [
     { name = "Gareth Davidson", email = "gaz@bitplane.net" }
 ]
 readme = "README.md"
 requires-python = ">=3.10"
-license = {text = "CC0"} # wtfpl
+license = {file = "LICENSE.md"}
 keywords = ["logging", "terminal", "scrollback", "indexing"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",

{arrayfile-0.1.0 → arrayfile-0.1.1}/src/arrayfile/array.py

@@ -1,6 +1,7 @@
 import io
 import mmap
 import os
+import re
 import struct
 import tempfile
 import threading
@@ -21,6 +22,12 @@ class Array:
 
     def __init__(self, dtype, filename=None, mode="r+b", initial_elements=0):
         self._lock = threading.Lock()
+        if isinstance(mode, str) and "a" in mode:
+            raise ValueError("Append mode is not supported; use r+b and append()")
+        if mode not in ("rb", "r+b", "rb+", "wb", "w+b", "wb+", "xb", "x+b", "xb+"):
+            raise ValueError("mode must be a binary read, write, or exclusive-create mode")
+        if filename is None and mode == "rb":
+            raise ValueError("Read-only mode requires a filename")
 
         try:
             dtype_bytes = dtype.encode("ascii")
@@ -29,7 +36,22 @@ class Array:
         if len(dtype_bytes) > self.MAX_DTYPE_LENGTH:
             raise ValueError(f"dtype must be at most {self.MAX_DTYPE_LENGTH} ASCII bytes")
 
-        if filename is None:
+        try:
+            element_size = struct.calcsize(dtype)
+        except struct.error as error:
+            raise ValueError("dtype must be a valid struct format string") from error
+        value_count = 0
+        for count, code in re.findall(r"(\d*)([A-Za-z?])", dtype):
+            repeat = int(count) if count else 1
+            if code == "p" and repeat == 0:
+                raise ValueError("dtype cannot contain a zero-length Pascal string")
+            if code != "x":
+                value_count += 1 if code in "sp" else repeat
+        if element_size == 0 or value_count != 1:
+            raise ValueError("dtype must have positive size and contain exactly one value")
+
+        temporary = filename is None
+        if temporary:
             fd, filename = tempfile.mkstemp()
             os.close(fd)
             mode = "w+b"  # Always create new temp files
@@ -37,7 +59,7 @@ class Array:
         self._filename = filename
         self._dtype = dtype
         self._dtype_format = dtype
-        self._element_size = struct.calcsize(dtype)
+        self._element_size = element_size
         self._file = None
         self._mmap = None
         self._len = 0
@@ -45,37 +67,51 @@ class Array:
         self._capacity_bytes = 0  # Initialize _capacity_bytes here
         self._data_offset = self.HEADER_SIZE  # All data starts after header
 
-        if "w" in mode or not os.path.exists(filename):
-            # Create or truncate file
-            mode = "w+b"
-            self._file = open(filename, "w+b")  # noqa: SIM115 - kept open for the Array lifetime
-            self._len = 0
-            self._allocate_capacity(initial_elements)
-            self._write_header()
-        else:
-            # Open existing file
-            self._file = open(filename, mode)  # noqa: SIM115 - kept open for the Array lifetime
-            if not self._read_header():
-                raise ValueError("File does not have a valid array header")
-
-            current_file_size = os.fstat(self._file.fileno()).st_size
-            data_size = current_file_size - self.HEADER_SIZE
-            required_data_size = self._len * self._element_size
-            if required_data_size > data_size:
-                raise ValueError(
-                    f"Array header declares {self._len} elements, but file only contains "
-                    f"{data_size // self._element_size}"
-                )
-
-            self._capacity_bytes = data_size
-            self._capacity = data_size // self._element_size
-
-        self._writable = any(flag in mode for flag in "+wa")
-
-        # Only mmap if the file has a non-zero size
-        if self._capacity_bytes > 0:
-            access = mmap.ACCESS_WRITE if self._writable else mmap.ACCESS_READ
-            self._mmap = mmap.mmap(self._file.fileno(), 0, access=access)
+        try:
+            if "w" in mode or "x" in mode:
+                # Mapping and header updates require random-access reads and writes.
+                mode = "x+b" if "x" in mode else "w+b"
+                self._file = open(filename, mode)  # noqa: SIM115 - kept open for the Array lifetime
+                self._len = 0
+                self._allocate_capacity(initial_elements)
+                self._write_header()
+            else:
+                # Open existing file
+                self._file = open(filename, mode)  # noqa: SIM115 - kept open for the Array lifetime
+                if not self._read_header():
+                    raise ValueError("File does not have a valid array header")
+
+                current_file_size = os.fstat(self._file.fileno()).st_size
+                data_size = current_file_size - self.HEADER_SIZE
+                required_data_size = self._len * self._element_size
+                if required_data_size > data_size:
+                    raise ValueError(
+                        f"Array header declares {self._len} elements, but file only contains "
+                        f"{data_size // self._element_size}"
+                    )
+
+                self._capacity_bytes = data_size
+                self._capacity = data_size // self._element_size
+
+            self._writable = any(flag in mode for flag in "+wa")
+
+            # Only mmap if the file has a non-zero size
+            if self._capacity_bytes > 0:
+                access = mmap.ACCESS_WRITE if self._writable else mmap.ACCESS_READ
+                self._mmap = mmap.mmap(self._file.fileno(), 0, access=access)
+
+        except BaseException:
+            try:
+                if self._mmap is not None:
+                    self._mmap.close()
+            finally:
+                try:
+                    if self._file is not None:
+                        self._file.close()
+                finally:
+                    if temporary:
+                        os.unlink(filename)
+            raise
 
         # Set up finalizer to ensure cleanup even if close() isn't called
         self._finalizer_state = {
@@ -85,6 +121,7 @@ class Array:
             "length": self._len,
             "mmap": self._mmap,
             "writable": self._writable,
+            "temporary_path": filename if temporary else None,
         }
         self._finalizer = weakref.finalize(self, self._finalize_resources, self._finalizer_state)
 
@@ -124,31 +161,41 @@ class Array:
     @classmethod
     def _finalize_resources(cls, state):
         mapped_file = state["mmap"]
-        if mapped_file:
-            mapped_file.flush()
-            mapped_file.close()
-
         file = state["file"]
-        if not file:
-            return
-
-        if state["writable"]:
-            dtype_bytes = state["dtype"].encode("ascii").ljust(cls.MAX_DTYPE_LENGTH, b"\x00")
-            header = struct.pack(
-                cls.HEADER_FORMAT,
-                cls.MAGIC,
-                cls.HEADER_VERSION,
-                len(state["dtype"]),
-                dtype_bytes,
-                state["element_size"],
-                state["length"],
-            )
-            file.seek(0)
-            file.write(header)
-            file.truncate(cls.HEADER_SIZE + state["length"] * state["element_size"])
-            file.flush()
-
-        file.close()
+        try:
+            if mapped_file is not None:
+                try:
+                    mapped_file.flush()
+                finally:
+                    mapped_file.close()
+            if file is None:
+                return
+
+            if state["writable"]:
+                dtype_bytes = state["dtype"].encode("ascii").ljust(cls.MAX_DTYPE_LENGTH, b"\x00")
+                header = struct.pack(
+                    cls.HEADER_FORMAT,
+                    cls.MAGIC,
+                    cls.HEADER_VERSION,
+                    len(state["dtype"]),
+                    dtype_bytes,
+                    state["element_size"],
+                    state["length"],
+                )
+                file.seek(0)
+                file.write(header)
+                file.truncate(cls.HEADER_SIZE + state["length"] * state["element_size"])
+                file.flush()
+        finally:
+            try:
+                if file is not None:
+                    file.close()
+            finally:
+                if state["temporary_path"] is not None:
+                    try:
+                        os.unlink(state["temporary_path"])
+                    except FileNotFoundError:
+                        pass
 
     def _write_header(self):
         """Write header to the beginning of the file."""
@@ -240,17 +287,34 @@ class Array:
         bytes_needed = min_elements * self._element_size + self.HEADER_SIZE
         chunks_needed = (bytes_needed + self.CHUNK_SIZE_BYTES - 1) // self.CHUNK_SIZE_BYTES
         total_file_size = chunks_needed * self.CHUNK_SIZE_BYTES
+        self._file.truncate(total_file_size)
         self._capacity_bytes = total_file_size - self.HEADER_SIZE
         self._capacity = self._capacity_bytes // self._element_size
-        self._file.truncate(total_file_size)
 
     def _resize(self, min_new_len):
-        if self._mmap:
+        old_capacity = self._capacity
+        old_capacity_bytes = self._capacity_bytes
+        if self._mmap is not None:
             self._mmap.close()
+        self._mmap = None
+        self._finalizer_state["mmap"] = None
 
-        self._allocate_capacity(min_new_len)
-        self._mmap = mmap.mmap(self._file.fileno(), 0)
-        self._finalizer_state["mmap"] = self._mmap
+        try:
+            self._allocate_capacity(min_new_len)
+            self._mmap = mmap.mmap(self._file.fileno(), 0)
+        except Exception:
+            self._capacity = old_capacity
+            self._capacity_bytes = old_capacity_bytes
+            # Restore access to existing values if possible. Cleanup must remain
+            # usable even when the operating system cannot create any mapping.
+            if old_capacity_bytes:
+                try:
+                    self._mmap = mmap.mmap(self._file.fileno(), 0)
+                except OSError:
+                    pass
+            raise
+        finally:
+            self._finalizer_state["mmap"] = self._mmap
 
     def extend(self, iterable):
         values = list(iterable)
@@ -306,6 +370,8 @@ class Array:
                 self._finalizer_state["length"] = self._len
             elif value > 1:
                 original_len = self._len
+                if original_len == 0:
+                    return self
                 new_total_len = original_len * value
 
                 # Resize if needed
@@ -334,10 +400,13 @@ class Array:
                 self._write_header()
 
     def close(self):
-        if self._finalizer.alive:
-            self._finalizer()
-        self._mmap = None
-        self._file = None
+        with self._lock:
+            try:
+                if self._finalizer.alive:
+                    self._finalizer()
+            finally:
+                self._mmap = None
+                self._file = None
 
     def __enter__(self):
         return self