[tor-commits] [chutney/master] TorNet: Add function comments to the path functions

[teor at torproject.org]

commit d5956193b096aec35520cb99602fb91fde078f14
Author: teor <teor at torproject.org>
Date:   Fri Jan 24 10:46:26 2020 +1000

    TorNet: Add function comments to the path functions
    
    Documentation for 32969.
---
 lib/chutney/TorNet.py | 46 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 43 insertions(+), 3 deletions(-)

diff --git a/lib/chutney/TorNet.py b/lib/chutney/TorNet.py
index 66e19d2..395bb4a 100644
--- a/lib/chutney/TorNet.py
+++ b/lib/chutney/TorNet.py
@@ -123,6 +123,10 @@ def make_datadir_subdirectory(datadir, subdir):
     mkdir_p(os.path.join(datadir, subdir))
 
 def get_absolute_chutney_path():
+    """
+       Returns the absolute path of the directory containing the chutney
+       executable script.
+    """
     # use the current directory as the default
     # (./chutney already sets CHUTNEY_PATH using the path to the script)
     # use tools/test-network.sh if you want chutney to try really hard to find
@@ -131,27 +135,63 @@ def get_absolute_chutney_path():
     return os.path.abspath(relative_chutney_path)
 
 def get_absolute_net_path():
+    """
+       Returns the absolute path of the "net" directory that chutney should
+       use to store "node*" directories containing torrcs and tor runtime data.
+
+       If the CHUTNEY_DATA_DIR environmental variable is an absolute path, it
+       is returned unmodified, regardless of whether the path actually exists.
+       (Chutney creates any directories that do not exist.)
+
+       Otherwise, if it is a relative path, and there is an existing directory
+       with that name in the directory containing the chutney executable
+       script, return that path (this check exists for legacy reasons).
+
+       Finally, return the path relative to the current working directory,
+       regardless of whether the path actually exists.
+    """
     data_dir = os.environ.get('CHUTNEY_DATA_DIR', 'net')
     if os.path.isabs(data_dir):
         # if we are given an absolute path, we should use it
+        # regardless of whether the directory exists
         return data_dir
     # use the chutney path as the default
     absolute_chutney_path = get_absolute_chutney_path()
     relative_net_path = data_dir
     # but what is it relative to?
-    # let's check if it's in CHUTNEY_PATH first, to preserve
-    # backwards-compatible behaviour
+    # let's check if there's an existing directory with this name in
+    # CHUTNEY_PATH first, to preserve backwards-compatible behaviour
     chutney_net_path = os.path.join(absolute_chutney_path, relative_net_path)
     if os.path.isdir(chutney_net_path):
         return chutney_net_path
-    # ok, it's relative to the current directory, whatever that is
+    # ok, it's relative to the current directory, whatever that is, and whether
+    # or not the path actually exists
     return os.path.abspath(relative_net_path)
 
 def get_absolute_nodes_path():
+    """
+       Returns the absolute path of the "nodes" symlink that points to the
+       "nodes*" directory that chutney should use to store the current
+       network's torrcs and tor runtime data.
+
+       See get_new_absolute_nodes_path() for more details.
+    """
     # there's no way to customise this: we really don't need more options
     return os.path.join(get_absolute_net_path(), 'nodes')
 
 def get_new_absolute_nodes_path(now=time.time()):
+    """
+       Returns the absolute path of a unique "nodes*" directory that chutney
+       should use to store the current network's torrcs and tor runtime data.
+
+       The nodes directory suffix is based on the current timestamp,
+       incremented if necessary to avoid collisions with existing directories.
+
+       (The existing directory check contains known race conditions: running
+       multiple simultaneous chutney instances on the same "net" directory is
+       not supported. The uniqueness check is only designed to avoid
+       collisions if the clock is set backwards.)
+    """
     # automatically chosen to prevent path collisions, and result in an ordered
     # series of directory path names
     # should only be called by 'chutney configure', all other chutney commands