Skip to main content

​
class FileStore

Bases: ABC Abstract base class for file storage operations. This class defines the interface for file storage backends that can handle basic file operations like reading, writing, listing, and deleting files. Implementations should provide a locking mechanism via the lock() context manager for thread/process-safe operations.

​
Methods

​
abstractmethod delete()

Delete the file or directory at the specified path.
  • Parameters: path – The file or directory path to delete.

​
abstractmethod exists()

Check if a file or directory exists at the specified path.
  • Parameters: path – The file or directory path to check.
  • Returns: True if the path exists, False otherwise.

​
abstractmethod get_absolute_path()

Get the absolute filesystem path for a given relative path.
  • Parameters: path – The relative path within the file store.
  • Returns: The absolute path on the filesystem.

​
abstractmethod list()

List all files and directories at the specified path.
  • Parameters: path – The directory path to list contents from.
  • Returns: A list of file and directory names in the specified path.

​
abstractmethod lock()

Acquire an exclusive lock for the given path. This context manager provides thread and process-safe locking. Implementations may use file-based locking, threading locks, or other mechanisms as appropriate.
  • Parameters:
    • path – The path to lock (used to identify the lock).
    • timeout – Maximum seconds to wait for lock acquisition.
  • Yields: None when lock is acquired.
  • Raises: TimeoutError – If lock cannot be acquired within timeout.

​
NOTE

File-based locking (flock) does NOT work reliably on NFS mounts or network filesystems.

​
abstractmethod read()

Read and return the contents of a file as a string.
  • Parameters: path – The file path to read from.
  • Returns: The file contents as a string.

​
abstractmethod write()

Write contents to a file at the specified path.
  • Parameters:
    • path – The file path where contents should be written.
    • contents – The data to write, either as string or bytes.

​
class InMemoryFileStore

Bases: FileStore

​
Properties

  • files: dict[str, str]

​
Methods

​
init()

​
delete()

Delete the file or directory at the specified path.
  • Parameters: path – The file or directory path to delete.

​
exists()

Check if a file exists.

​
get_absolute_path()

Get absolute path (uses temp dir with unique instance ID).

​
list()

List all files and directories at the specified path.
  • Parameters: path – The directory path to list contents from.
  • Returns: A list of file and directory names in the specified path.

​
lock()

Acquire thread lock for in-memory store.

​
read()

Read and return the contents of a file as a string.
  • Parameters: path – The file path to read from.
  • Returns: The file contents as a string.

​
write()

Write contents to a file at the specified path.
  • Parameters:
    • path – The file path where contents should be written.
    • contents – The data to write, either as string or bytes.

​
class LocalFileStore

Bases: FileStore

​
Properties

  • cache: MemoryLRUCache
  • root: str

​
Methods

​
init()

Initialize a LocalFileStore with caching.
  • Parameters:
    • root – Root directory for file storage.
    • cache_limit_size – Maximum number of cached entries (default: 500).
    • cache_memory_size – Maximum cache memory in bytes (default: 20MB).

​
NOTE

The cache assumes exclusive access to files. External modifications to files will not be detected and may result in stale cache reads.

​
delete()

Delete the file or directory at the specified path.
  • Parameters: path – The file or directory path to delete.

​
exists()

Check if a file or directory exists.

​
get_absolute_path()

Get absolute filesystem path.

​
get_full_path()

​
list()

List all files and directories at the specified path.
  • Parameters: path – The directory path to list contents from.
  • Returns: A list of file and directory names in the specified path.

​
lock()

Acquire file-based lock using flock.

​
read()

Read and return the contents of a file as a string.
  • Parameters: path – The file path to read from.
  • Returns: The file contents as a string.

​
write()

Write contents to a file at the specified path.
  • Parameters:
    • path – The file path where contents should be written.
    • contents – The data to write, either as string or bytes.