Rename root parameter to path. (#758)

* Change root to path. * Update tests to use path instead of root. * Update benchmarks to use path instead of root. * Update changelog. * Update changelog.txt Co-authored-by: Corwin Kerr <[email protected]> * Update signac/contrib/project.py Co-authored-by: Corwin Kerr <[email protected]> * Update tests/test_project.py Co-authored-by: Corwin Kerr <[email protected]> * Remove use of root. * Refactor docs for fn/isfile methods. * Bradley check these rewordings * Replace outdated job workspace directory * One more outdated job workspace directory * Apply minor changes * Describe path argument searching Co-authored-by: Corwin Kerr <[email protected]>
glotzerlab · May 14, 2022 · ea3b4df · ea3b4df
1 parent cfa1e2c
commit ea3b4df
Show file tree

Hide file tree

Showing 12 changed files with 227 additions and 231 deletions.
diff --git a/benchmarks/benchmarks.py b/benchmarks/benchmarks.py
@@ -70,14 +70,14 @@ def generate_random_data(
 
 
 def setup_random_project(
-    N, num_keys=1, num_doc_keys=0, data_size_mean=0, data_size_std=0, seed=0, root=None
+    N, num_keys=1, num_doc_keys=0, data_size_mean=0, data_size_std=0, seed=0, path=None
 ):
     random.seed(seed)
     if not isinstance(N, int):
         raise TypeError("N must be an integer!")
 
     temp_dir = TemporaryDirectory()
-    project = signac.init_project(f"benchmark-N={N}", root=temp_dir.name)
+    project = signac.init_project(path=temp_dir.name)
     generate_random_data(
         project, N, num_keys, num_doc_keys, data_size_mean, data_size_std
     )

diff --git a/changelog.txt b/changelog.txt
@@ -22,6 +22,7 @@ Changed
    - Projects no longer have names and are identified solely by their root directories. This change also affects a number of public APIs where names are including, most prominently ``signac.init_project`` and ``Project.init_project``. Projects can now be constructed with just a root directory rather than a preloaded config (#677, #684, #706).
    - Project workspaces are no longer configurable, but are instead always defined as a subdirectory of the Project's root directory called ``workspace`` (#714).
  - Rather than searching upwards until the root, ``load_config`` will only load configuration files in the specified directory, which is assumed to be a project directory, as well as the user's home directory (#711).
+ - Changed the ``root`` parameter to ``path`` in the ``signac.get_project`` and ``signac.init_project`` functions and corresponding ``Project`` methods (#757, #758).
 
 Removed
 +++++++

diff --git a/signac/__main__.py b/signac/__main__.py
@@ -73,7 +73,7 @@
 SHELL_BANNER = """Python {python_version}
 signac {signac_version} 🎨
 
-Project:\t{root_path}{job_banner}
+Project:\t{path}{job_banner}
 Size:\t\t{size}
 
 Interact with the project interface using the "project" or "pr" variable.
@@ -230,7 +230,7 @@ def main_remove(args):
 def main_move(args):
     """Handle move subcommand."""
     project = get_project()
-    dst_project = get_project(root=args.project)
+    dst_project = get_project(path=args.project)
     for job_id in args.job_id:
         try:
             job = _open_job_by_id(project, job_id)
@@ -244,7 +244,7 @@ def main_move(args):
 def main_clone(args):
     """Handle clone subcommand."""
     project = get_project()
-    dst_project = get_project(root=args.project)
+    dst_project = get_project(path=args.project)
     for job_id in args.job_id:
         try:
             job = _open_job_by_id(project, job_id)
@@ -333,7 +333,7 @@ def main_view(args):
 
 def main_init(args):
     """Handle init subcommand."""
-    init_project(root=os.getcwd())
+    init_project(path=os.getcwd())
     _print_err("Initialized project.")
 
 
@@ -397,9 +397,9 @@ def _sig(st):
     # Setup synchronization process
     #
 
-    source = get_project(root=args.source)
+    source = get_project(path=args.source)
     try:
-        destination = get_project(root=args.destination)
+        destination = get_project(path=args.destination)
     except LookupError:
         _print_err("WARNING: The destination does not appear to be a project path.")
         raise
@@ -529,7 +529,7 @@ def _main_import_interactive(project, origin, args):
                     python_version=sys.version,
                     signac_version=__version__,
                     job_banner="",
-                    root_path=project.path,
+                    path=project.path,
                     size=len(project),
                     origin=args.origin,
                 ),
@@ -870,7 +870,7 @@ def write_history_file():
                     python_version=sys.version,
                     signac_version=__version__,
                     job_banner=f"\nJob:\t\t{job.id}" if job is not None else "",
-                    root_path=project.path,
+                    path=project.path,
                     size=len(project),
                 ),
             )
@@ -1085,7 +1085,7 @@ def main():
     parser_move.add_argument(
         "project",
         type=str,
-        help="The root directory of the project to move one or more jobs to.",
+        help="The destination project directory.",
     )
     parser_move.add_argument(
         "job_id",
@@ -1099,7 +1099,7 @@ def main():
     parser_clone.add_argument(
         "project",
         type=str,
-        help="The root directory of the project to clone one or more jobs in.",
+        help="The directory of the project to clone one or more jobs in.",
     )
     parser_clone.add_argument(
         "job_id",
@@ -1322,12 +1322,12 @@ def main():
     )
     parser_sync.add_argument(
         "source",
-        help="The root directory of the project that this project should be synchronized with.",
+        help="The directory of the project that this project should be synchronized with.",
     )
     parser_sync.add_argument(
         "destination",
         nargs="?",
-        help="Optional: The root directory of the project that should be modified for "
+        help="Optional: The directory of the project that should be modified for "
         "synchronization, defaults to the local project.",
     )
     _add_verbosity_argument(parser_sync, default=2)

diff --git a/signac/common/config.py b/signac/common/config.py
@@ -19,35 +19,32 @@
 # functions from the public API.
 
 
-def _get_project_config_fn(root):
-    return os.path.abspath(os.path.join(root, PROJECT_CONFIG_FN))
+def _get_project_config_fn(path):
+    return os.path.abspath(os.path.join(path, PROJECT_CONFIG_FN))
 
 
 def _locate_config_dir(search_path):
-    """Locates root directory containing a signac configuration file in a directory hierarchy.
+    """Locates directory containing a signac configuration file in a directory hierarchy.
 
     Parameters
     ----------
-    root : str
+    search_path : str
         Starting path to search.
 
     Returns
     --------
     str or None
-        The root directory containing the configuration file if one is found, otherwise None.
+        The directory containing the configuration file if one is found, otherwise None.
     """
-    root = os.path.abspath(search_path)
+    search_path = os.path.abspath(search_path)
     while True:
-        if os.path.isfile(_get_project_config_fn(root)):
-            return root
-        # TODO: Could use the walrus operator here when we completely drop
-        # Python 3.7 support if we like the operator.
-        up = os.path.dirname(root)
-        if up == root:
+        if os.path.isfile(_get_project_config_fn(search_path)):
+            return search_path
+        if (up := os.path.dirname(search_path)) == search_path:
             logger.debug("Reached filesystem root, no config found.")
             return None
         else:
-            root = up
+            search_path = up
 
 
 def read_config_file(filename):
@@ -81,12 +78,12 @@ def read_config_file(filename):
     return config
 
 
-def load_config(root=None):
+def load_config(path=None):
     """Load configuration from a project directory.
 
     Parameters
     ----------
-    root : str
+    path : str
         The project path to pull project-local configuration data from.
 
     Returns
@@ -96,8 +93,8 @@ def load_config(root=None):
         config data if requested. Note that because this config is a composite,
         modifications to the returned value will not be reflected in the files.
     """
-    if root is None:
-        root = os.getcwd()
+    if path is None:
+        path = os.getcwd()
     config = Config(configspec=cfg.split("\n"))
 
     # Add in any global or user config files. For now this only finds user-specific
@@ -106,8 +103,8 @@ def load_config(root=None):
         if os.path.isfile(fn):
             config.merge(read_config_file(fn))
 
-    if os.path.isfile(_get_project_config_fn(root)):
-        config.merge(read_config_file(_get_project_config_fn(root)))
+    if os.path.isfile(_get_project_config_fn(path)):
+        config.merge(read_config_file(_get_project_config_fn(path)))
     return config
 
 

diff --git a/signac/contrib/job.py b/signac/contrib/job.py
@@ -818,7 +818,7 @@ def sync(self, other, strategy=None, exclude=None, doc_sync=None, **kwargs):
         )
 
     def fn(self, filename):
-        """Prepend a filename with the job's workspace directory path.
+        """Prepend a filename with the job path.
 
         Parameters
         ----------
@@ -828,13 +828,13 @@ def fn(self, filename):
         Returns
         -------
         str
-            The full workspace path of the file.
+            The absolute path to the file.
 
         """
         return os.path.join(self.path, filename)
 
     def isfile(self, filename):
-        """Return True if file exists in the job's workspace.
+        """Check if a filename exists in the job directory.
 
         Parameters
         ----------
@@ -844,7 +844,7 @@ def isfile(self, filename):
         Returns
         -------
         bool
-            True if file with filename exists in workspace.
+            True if filename exists in the job directory.
 
         """
         return os.path.isfile(self.fn(filename))