mafw.tools.recent_files

Reusable recent-file history and storage abstractions.

Added in version v2.4.

Author:

Bulgheroni Antonio (antonio.bulgheroni@ec.europa.eu)

Description:

Maintain bounded recent-file history independently of any graphical interface.

Classes

InMemoryRecentFileStorage([paths])	Keep recent-file data in memory for applications without persistent storage.
JsonRecentFileStorage(path)	Persist recent-file history as a UTF-8 JSON array at a configured path.
RecentFileService(storage, *, max_entries, ...)	Maintain configurable, normalized, duplicate-free recent-file history.
RecentFileStorage(*args, **kwargs)	Define the replaceable persistence interface used by recent-file histories.

class mafw.tools.recent_files.InMemoryRecentFileStorage(paths: Iterable[str] = ())

Bases: object

Keep recent-file data in memory for applications without persistent storage.

Added in version v2.4.

read() → Sequence[str]

Return the currently stored paths.

write(paths: Sequence[str]) → None

Replace the stored paths.

class mafw.tools.recent_files.JsonRecentFileStorage(path: Path | str)

Bases: object

Persist recent-file history as a UTF-8 JSON array at a configured path.

Added in version v2.4.

read() → Sequence[str]

Read the stored path list, treating unavailable or invalid data as empty.

write(paths: Sequence[str]) → None

Write the path list, creating its parent directory when needed.

class mafw.tools.recent_files.RecentFileService(storage: ~mafw.tools.recent_files.RecentFileStorage, *, max_entries: int = 10, exists: ~collections.abc.Callable[[~pathlib.Path], bool] = <function Path.is_file>)

Bases: object

Maintain configurable, normalized, duplicate-free recent-file history.

Storage and path-existence checks are injectable so the service can be shared by independent MAFw applications and tested without constructing GUI widgets.

Added in version v2.4.

_is_file(path: Path) → bool

Check file availability while treating filesystem errors as stale entries.

_normalize(path: Path | str) → Path

Resolve a path to a stable absolute representation without requiring it to exist.

_persist() → None

Persist history without allowing storage failures to break file operations.

_prune_missing() → None

Remove paths that disappeared after they were added to history.

_restore() → None

Load persisted entries and normalize, de-duplicate, limit, and prune them.

add(path: Path | str) → list[Path]

Promote a file to the top of history and return the updated entries.

files() → list[Path]

Return existing recent files, pruning stale paths from storage.

class mafw.tools.recent_files.RecentFileStorage(*args, **kwargs)

Bases: Protocol

Define the replaceable persistence interface used by recent-file histories.

Added in version v2.4.

read() → Sequence[str]

Return stored paths without interpreting or validating them.

write(paths: Sequence[str]) → None

Persist paths in the order supplied by the history service.