From 6362238ea7f1b231f4b509422acffaa591a2e243 Mon Sep 17 00:00:00 2001
From: Florian Spreckelsen <f.spreckelsen@indiscale.com>
Date: Tue, 6 Aug 2024 16:52:16 +0200
Subject: [PATCH] WIP: Add docstrings to more of loadfile's methods
---
src/caosadvancedtools/loadFiles.py | 86 ++++++++++++++++++++++++++----
1 file changed, 77 insertions(+), 9 deletions(-)
diff --git a/src/caosadvancedtools/loadFiles.py b/src/caosadvancedtools/loadFiles.py
index 77872d1d..24b7ddc3 100755
--- a/src/caosadvancedtools/loadFiles.py
+++ b/src/caosadvancedtools/loadFiles.py
@@ -40,6 +40,10 @@ timeout_fallback = 20
def convert_size(size):
+ """Convert `size` from B to a human-readable file size in KB,
+ MB, ...
+
+ """
if (size == 0):
return '0B'
size_name = ("B", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB")
@@ -51,8 +55,24 @@ def convert_size(size):
def combine_ignore_files(caosdbignore, localignore, dirname=None):
- """appends the contents of localignore to caosdbignore and saves the result
- and returns the name
+ """Append the contents of localignore to caosdbignore, save the result,
+ and return the name.
+
+ Parameters
+ ----------
+ caosdbignore : str
+ Path to parent level caosdbignore file
+ localignore : str
+ Path to current working directory's local caosdbignore.
+ dirname : str, optional
+ The path of the directory to which the temporary combined file
+ is written. If None is given, `NamedTemporaryFile`'s default
+ is used. Default is None.
+
+ Returns
+ -------
+ name : str
+ Name of the temporary combined caosdbignore file.
"""
@@ -67,8 +87,21 @@ def combine_ignore_files(caosdbignore, localignore, dirname=None):
def compile_file_list(caosdbignore, localpath):
- """creates a list of files that contain all files under localpath except
- those excluded by caosdbignore
+ """Create a list of files that contain all files under localpath except
+ those excluded by caosdbignore.
+
+ Parameters
+ ----------
+ caosdbignore : str
+ Path of caosdbignore file
+ localpath : str
+ Path of the directory from which the file list will be compiled.
+
+ Returns
+ -------
+ file_list : list[str]
+ List of files in `localpath` after appling the ignore rules
+ from `caosdbignore`.
"""
@@ -111,9 +144,27 @@ def compile_file_list(caosdbignore, localpath):
def create_re_for_file_list(files, localroot, remoteroot):
- """creates a regular expression that matches file paths contained in the
- files argument and all parent directories. The prefix localroot is replaced
- by the prefix remoteroot.
+ """Create a regular expression that matches file paths contained
+ in the files argument and all parent directories. The prefix
+ localroot is replaced by the prefix remoteroot.
+
+ Parameters
+ ----------
+ files : list[str]
+ List of file paths to be converted to a regular expression.
+ localroot : str
+ Prefix (of the local directory root) to be removed from the
+ paths in `files`.
+ remoteroot : str
+ Prefix (of the LinkAhead filesystem's directory root) to be
+ prepended to the file paths after the removal of the
+ `localroot` prefix.
+
+ Returns
+ -------
+ regexp : str
+ Regular expression that matches all file paths from `files`
+ adapted for the remote directory root.
"""
regexp = ""
@@ -130,6 +181,19 @@ def create_re_for_file_list(files, localroot, remoteroot):
def loadpath(path, include, exclude, prefix, dryrun, forceAllowSymlinks, caosdbignore=None,
localpath=None):
+ """Make all files in `path` available to the LinkAhead server as FILE entities.
+
+ Parameters
+ ----------
+ path : str
+ Path to the directory the files of which are to be made
+ available as seen by the linkahead server (i.e., the path from
+ within the Docker container in a typical LinkAhead Control
+ setup.)
+ include : str
+
+
+ """
if caosdbignore:
# create list of files and create regular expression for small chunks
@@ -182,7 +246,11 @@ def loadpath(path, include, exclude, prefix, dryrun, forceAllowSymlinks, caosdbi
def main(argv=None):
- '''Command line options.'''
+ """Run `loadpath` with the arguments specified on the command
+ line, extended by the optional `argv` parameter. See ``--help``
+ for more information.
+
+ """
if argv is None:
argv = sys.argv
@@ -191,7 +259,7 @@ def main(argv=None):
# Setup argument parser
parser = ArgumentParser(description="""
-Make files that the LinkAhead server can see available als FILE entities.
+Make files that the LinkAhead server can see available as FILE entities.
In a typical scenario where LinkAhead runs in a Docker container and a host directory `mydir` is
mounted as an extroot with name `myext`, loadfiles could be called like this:
--
GitLab