Docstrings.

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):

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,
         )

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: