arrayfile 0.0.1__tar.gz → 0.1.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayfile
-Version: 0.0.1
+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
@@ -27,14 +26,14 @@ Requires-Dist: ruff ; extra == "dev"
 Requires-Dist: pydoc-markdown ; extra == "dev"
 Provides-Extra: dev
 
-# arrayfile
+# 📃 arrayfile
 
 A file-backed numeric array using struct.pack. Does not support inserts or
 slicing.
 
 Smaller than relying on numpy though.
 
-## Installation
+## ▶️ Installation
 
 ```bash
 pip install arrayfile
@@ -42,9 +41,10 @@ pip install arrayfile
 
 ## Usage
 
-### Temporary Array
+### 🗑 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
@@ -60,7 +60,7 @@ print(f"Values: {[arr[i] for i in range(len(arr))]}")
 arr.close()  # Clean up resources
 ```
 
-### Persistent Array
+### 💽 Persistent Array
 
 You can use the same file, if you want to persist your data across sessions:
 
@@ -84,7 +84,7 @@ arr.append(2000)
 arr.close()
 ```
 
-## Context manager
+## 🔧 Context manager
 
 It has a finalizer in case you forget to call `close()`, but if you like to keep
 your code tidy, you can use a context manager, like so:
@@ -101,4 +101,19 @@ with Array('d', 'measurements.array', 'w+b') as arr:
         print(f"  {i}: {value:.15f}")
 ```
 
+## ⚖️ License
+
+WTFPL with one extra clause:
+
+1. Don't blame me.
+
+Do what you like, but you're on your own.
+
+## 🔗 Links
+
+* [🏠 home](https://bitplane.net/dev/python/arrayfile)
+* [📖 pydoc](https://bitplane.net/dev/python/arrayfile/pydoc)
+* [🐍 pypi](https://pypi.org/project/arrayfile)
+* [🐱 github](https://github.com/bitplane/arrayfile)
+
 

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

@@ -1,11 +1,11 @@
-# arrayfile
+# 📃 arrayfile
 
 A file-backed numeric array using struct.pack. Does not support inserts or
 slicing.
 
 Smaller than relying on numpy though.
 
-## Installation
+## ▶️ Installation
 
 ```bash
 pip install arrayfile
@@ -13,9 +13,10 @@ pip install arrayfile
 
 ## Usage
 
-### Temporary Array
+### 🗑 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
@@ -31,7 +32,7 @@ print(f"Values: {[arr[i] for i in range(len(arr))]}")
 arr.close()  # Clean up resources
 ```
 
-### Persistent Array
+### 💽 Persistent Array
 
 You can use the same file, if you want to persist your data across sessions:
 
@@ -55,7 +56,7 @@ arr.append(2000)
 arr.close()
 ```
 
-## Context manager
+## 🔧 Context manager
 
 It has a finalizer in case you forget to call `close()`, but if you like to keep
 your code tidy, you can use a context manager, like so:
@@ -72,3 +73,18 @@ with Array('d', 'measurements.array', 'w+b') as arr:
         print(f"  {i}: {value:.15f}")
 ```
 
+## ⚖️ License
+
+WTFPL with one extra clause:
+
+1. Don't blame me.
+
+Do what you like, but you're on your own.
+
+## 🔗 Links
+
+* [🏠 home](https://bitplane.net/dev/python/arrayfile)
+* [📖 pydoc](https://bitplane.net/dev/python/arrayfile/pydoc)
+* [🐍 pypi](https://pypi.org/project/arrayfile)
+* [🐱 github](https://github.com/bitplane/arrayfile)
+

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

@@ -1,18 +1,17 @@
 [project]
 name = "arrayfile"
 description = "Arrays backed by disk"
-version = "0.0.1"
+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.0.1 → arrayfile-0.1.1}/src/arrayfile/array.py

@@ -1,5 +1,7 @@
+import io
 import mmap
 import os
+import re
 import struct
 import tempfile
 import threading
@@ -8,6 +10,7 @@ import weakref
 
 class Array:
     CHUNK_SIZE_BYTES = 4096
+    MAX_DTYPE_LENGTH = 8
 
     # Header constants
     MAGIC = b"ARYF"
@@ -19,8 +22,36 @@ 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")
 
-        if filename is None:
+        try:
+            dtype_bytes = dtype.encode("ascii")
+        except (AttributeError, UnicodeEncodeError) as error:
+            raise ValueError("dtype must be an ASCII struct format string") from error
+        if len(dtype_bytes) > self.MAX_DTYPE_LENGTH:
+            raise ValueError(f"dtype must be at most {self.MAX_DTYPE_LENGTH} ASCII bytes")
+
+        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
@@ -28,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
@@ -36,31 +67,63 @@ 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
-            self._file = open(filename, "w+b")
-            self._len = 0
-            self._allocate_capacity(initial_elements)
-            self._write_header()
-        else:
-            # Open existing file
-            self._file = open(filename, mode)
-            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
-
-            # Calculate capacity based on current data size and ensure chunk alignment
-            min_elements = (data_size + self._element_size - 1) // self._element_size
-            self._allocate_capacity(min_elements)
-
-        # Only mmap if the file has a non-zero size
-        if self._capacity_bytes > 0:
-            self._mmap = mmap.mmap(self._file.fileno(), 0)
+        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 = weakref.finalize(self, self.close)
+        self._finalizer_state = {
+            "dtype": self._dtype,
+            "element_size": self._element_size,
+            "file": self._file,
+            "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)
 
     def __len__(self):
         return self._len
@@ -91,10 +154,52 @@ class Array:
         except struct.error as e:
             raise TypeError(f"Value {value} cannot be packed as {self._dtype_format}: {e}")
 
+    def _ensure_writable(self):
+        if not self._writable:
+            raise io.UnsupportedOperation("Array is not writable")
+
+    @classmethod
+    def _finalize_resources(cls, state):
+        mapped_file = state["mmap"]
+        file = state["file"]
+        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."""
-        dtype_bytes = self._dtype.encode("ascii")[:8]  # Limit to 8 bytes
-        dtype_bytes = dtype_bytes.ljust(8, b"\x00")  # Pad with nulls
+        dtype_bytes = self._dtype.encode("ascii").ljust(self.MAX_DTYPE_LENGTH, b"\x00")
 
         header = struct.pack(
             self.HEADER_FORMAT,
@@ -126,6 +231,9 @@ class Array:
         if version != self.HEADER_VERSION:
             raise ValueError(f"Unsupported header version: {version}")
 
+        if dtype_len > self.MAX_DTYPE_LENGTH:
+            raise ValueError(f"File dtype length {dtype_len} exceeds header capacity")
+
         # Extract dtype string
         dtype = dtype_bytes[:dtype_len].decode("ascii")
 
@@ -153,6 +261,7 @@ class Array:
         index = self._validate_index(index)
 
         with self._lock:
+            self._ensure_writable()
             if not self._mmap:
                 raise RuntimeError("Array is not memory-mapped. This should not happen if len > 0.")
 
@@ -162,6 +271,7 @@ class Array:
 
     def append(self, value):
         with self._lock:
+            self._ensure_writable()
             if self._len == self._capacity:
                 self._resize(self._len + 1)
 
@@ -170,22 +280,41 @@ class Array:
 
             self._mmap[offset : offset + self._element_size] = packed_value
             self._len += 1
+            self._finalizer_state["length"] = self._len
 
     def _allocate_capacity(self, min_elements):
         """Allocate capacity for at least min_elements, rounded up to chunk boundary."""
         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)
+        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)
@@ -195,6 +324,7 @@ class Array:
             return
 
         with self._lock:
+            self._ensure_writable()
             new_len = self._len + num_new_elements
             if new_len > self._capacity:
                 self._resize(new_len)
@@ -207,6 +337,7 @@ class Array:
                 offset += self._element_size
 
             self._len = new_len
+            self._finalizer_state["length"] = self._len
 
     def __contains__(self, value):
         for i in range(self._len):
@@ -225,17 +356,22 @@ class Array:
             return NotImplemented
 
         with self._lock:
+            self._ensure_writable()
             if value == 0:
                 self._len = 0
                 if self._mmap:
                     self._mmap.close()
                     self._mmap = None
+                    self._finalizer_state["mmap"] = None
                 if self._file:
                     self._file.truncate(0)
                 self._capacity = 0
                 self._capacity_bytes = 0
+                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
@@ -253,31 +389,24 @@ class Array:
                     dst_offset += chunk_size
 
                 self._len = new_total_len
+                self._finalizer_state["length"] = self._len
         return self
 
     def flush(self):
-        if self._mmap:
-            self._mmap.flush()
+        with self._lock:
+            if self._mmap:
+                self._mmap.flush()
+            if self._file and self._writable:
+                self._write_header()
 
     def close(self):
-        if self._mmap:
-            # Ensure all writes are on disk before truncating
-            self._mmap.flush()
-            self._mmap.close()
-            self._mmap = None
-
-        if self._file:
-            # Update header with final length
-            self._write_header()
-
-            # Only truncate if the file was opened in a writable mode
-            # and if the current size is greater than the actual data length
-            current_file_size = os.fstat(self._file.fileno()).st_size
-            actual_total_size = self.HEADER_SIZE + self._len * self._element_size
-            if current_file_size > actual_total_size:
-                self._file.truncate(actual_total_size)
-            self._file.close()
-            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