From 7439d7cb8f4b4feb86ad013f1dfdfdf873ea8f0c Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Sat, 30 May 2026 16:58:29 -0700 Subject: [PATCH] Docstrings. --- borgmatic/actions/browse/archives_list.py | 2 +- borgmatic/actions/browse/file_preview.py | 2 +- borgmatic/actions/browse/workers.py | 66 +++++++++++++++++++++-- 3 files changed, 64 insertions(+), 6 deletions(-) diff --git a/borgmatic/actions/browse/archives_list.py b/borgmatic/actions/browse/archives_list.py index 8d414068..c6c24ebe 100644 --- a/borgmatic/actions/browse/archives_list.py +++ b/borgmatic/actions/browse/archives_list.py @@ -36,7 +36,7 @@ class Archives_list(textual.widgets.OptionList): archives_list=self, config=self.config, repository=self.repository, - timer=timer, + loading_timer=timer, ) def on_option_list_option_highlighted(self, event): diff --git a/borgmatic/actions/browse/file_preview.py b/borgmatic/actions/browse/file_preview.py index 1f34cc48..171daf44 100644 --- a/borgmatic/actions/browse/file_preview.py +++ b/borgmatic/actions/browse/file_preview.py @@ -52,5 +52,5 @@ class File_preview(textual.widgets.RichLog): repository=self.repository, archive_name=self.archive_name, file_path=self.file_path, - timer=timer, + loading_timer=timer, ) diff --git a/borgmatic/actions/browse/workers.py b/borgmatic/actions/browse/workers.py index e7697722..ed8b8579 100644 --- a/borgmatic/actions/browse/workers.py +++ b/borgmatic/actions/browse/workers.py @@ -14,7 +14,16 @@ logger = logging.getLogger('__name__') @textual.work(thread=True) -def add_repository_archives(browse_app, archives_list, config, repository, timer): +def add_repository_archives(browse_app, archives_list, config, repository, loading_timer): + ''' + Given a running Browse_app instance, an Archives_list instance, a configuration dict, a + repository dict, and a loading indicator timer, load a list of the archives from the repository + and add them as options in the archives list. Reverse the order so the most recent archive is + first. + + This function runs in a separate thread from the main UI. When loading is complete, remove the + loading indicator and stop its timer. + ''' archives_data = borgmatic.actions.browse.archive.get_repository_archives(config, repository) loading_option = archives_list.get_option('loading-indicator') @@ -43,10 +52,21 @@ def add_repository_archives(browse_app, archives_list, config, repository, timer ) browse_app.call_from_thread(archives_list.remove_option, 'loading-indicator') - browse_app.call_from_thread(timer.stop) + browse_app.call_from_thread(loading_timer.stop) def record_path(archive_path, hierarchy, path_components): + ''' + Given an Archive_path instance, a dict capturing a filesystem hierarchy of paths, and a tuple of + path components for the archive path, set the archive path into the hierarchy data structure. + + For instance, if given an archive path and path components representing "foo/bar/baz.txt", + produce a hierarchy that looks like: + + {'foo': {'bar': {'baz.txt': Archive_path('-', 'foo/bar/baz.txt', '')}}} + + Note that the hierarchy is modified in place, so any existing paths there are retained. + ''' if len(path_components) == 1: hierarchy[path_components[0]] = {} if archive_path.path_type == 'd' else archive_path return @@ -55,6 +75,23 @@ def record_path(archive_path, hierarchy, path_components): def get_paths(hierarchy, path_components, full_path_components=None): + ''' + Given a dict capturing a filesystem hierarchy of paths (or a subset thereof), a tuple of path + components for an archive path relative to the hierarchy root, and an optional tuple of + *absolute* path components for the same archive path (if different), return the corresponding + Archive_path from the hierarchy. + + For instance, given the following hierarchy: + + {'foo': {'bar': {'baz.txt': Archive_path('-', 'foo/bar/baz.txt', '')}}} + + ... and path components of ('foo', 'bar', 'baz.txt'), return the Archive_path instance above. + + Or in the case of path components of only ('foo', 'bar'), return a directory with the absolute + path: + + Archive_path('d', 'foo/bar', '') + ''' if full_path_components is None: full_path_components = path_components @@ -75,6 +112,13 @@ LOADING_DONE = object() class Archive_path_loaded(textual.signal.Signal): + ''' + A signal that publishes when each subsequent path is loaded from an archive, intended for + consumption in widgets that display paths as they are loaded. This signal also tracks the + complete filesystem hierarchy seen thus far, so new widgets that get created after loading has + started can "catch up" with existing known paths. Lastly, this signal publishes and tracks when + loading is complete. + ''' def __init__(self, owner, name): self.path_hierarchy = {} self.complete = False @@ -92,6 +136,14 @@ class Archive_path_loaded(textual.signal.Signal): @textual.work(thread=True) def load_archive_paths(browse_app, directory_list, config, repository, archive_name): + ''' + Given a running Browse_app instance, a Directory_list instance, a configuration dict, a + repository dict, and an archive name, load the paths in this archive and publish each one via + the Archive_path_loaded signal, so interested widgets can subscribe. Also send a "loading done" + signal when loading completes. + + This function runs in a separate thread from the main UI. + ''' for archive_path in borgmatic.actions.browse.archive.get_archive_paths( config, repository, archive_name ): @@ -101,12 +153,18 @@ def load_archive_paths(browse_app, directory_list, config, repository, archive_n @textual.work(thread=True) -def load_file_preview(browse_app, file_preview, config, repository, archive_name, file_path, timer): +def load_file_preview(browse_app, file_preview, config, repository, archive_name, file_path, + loading_timer): + ''' + Given a running Browse_app instance, a File_preview instance, a configuration dict, a repository + dict, an archive name, the path of a file in that archive, and a loading indicator timer, load + the contents of the file and write it into the given file preview widget. + ''' file_content = borgmatic.actions.browse.archive.get_archive_file_content( config, repository, archive_name, file_path ) - browse_app.call_from_thread(timer.stop) + browse_app.call_from_thread(loading_timer.stop) browse_app.call_from_thread(file_preview.clear) if file_content is None: