Deprecate project id (#644)

* Convert name to an optional parameter.

* Update changelog.

* update init_project call in example code

* Fix assertion.

* Update signac/contrib/project.py

Co-authored-by: Corwin Kerr <[email protected]>

* suggestion: change other init_project

* Address PR comments.

Co-authored-by: Corwin Kerr <[email protected]>

changelog.txt

@@ -31,6 +31,11 @@ Deprecated
  - ``signac.cite`` module is deprecated (#611, #592).
  - ``config.get_config`` method is deprecated (#675).
 
+Changed
++++++++
+
+ - Project names have a default in anticipation of removing names entirely. Project names will be removed in signac 2.0.
+
 Fixed
 +++++
 

signac/__main__.py

@@ -1093,10 +1093,7 @@ def main_shell(args):
     except LookupError:
         print("signac", __version__)
         print("No project within this directory.")
-        print(
-            "If you want to initialize a project, execute `$ signac init <project-name>`, "
-            "where <project-name> can be freely chosen."
-        )
+        print("If you want to initialize a project, execute `$ signac init`.")
     else:
         _jobs = find_with_filter(args)
 
@@ -1201,7 +1198,10 @@ def main():
 
     parser_init = subparsers.add_parser("init")
     parser_init.add_argument(
-        "project_id", type=str, help="Initialize a project with the given project id."
+        "project_id",
+        nargs="?",
+        type=str,
+        help="Initialize a project with the given project id.",
     )
     parser_init.add_argument(
         "-w",

signac/contrib/project.py

@@ -83,6 +83,9 @@ def get_indexes(root):
     "information."
 )
 
+# Temporary default for project names until they are removed entirely in signac 2.0
+_DEFAULT_PROJECT_NAME = None
+
 
 class JobSearchIndex:
     """Search for specific jobs with filters.
@@ -2279,8 +2282,8 @@ def temporary_project(self, name=None, dir=None):
             yield tmp_project
 
     @classmethod
-    def init_project(cls, name, root=None, workspace=None, make_dir=True):
-        """Initialize a project with the given name.
+    def init_project(cls, name=None, root=None, workspace=None, make_dir=True):
+        """Initialize a project.
 
         It is safe to call this function multiple times with the same
         arguments. However, a `RuntimeError` is raised if an existing project
@@ -2291,15 +2294,15 @@ def init_project(cls, name, root=None, workspace=None, make_dir=True):
 
         Parameters
         ----------
-        name : str
-            The name of the project to initialize.
-        root : str
+        name : str, optional
+            The name of the project to initialize (Default value = None).
+        root : str, optional
             The root directory for the project.
             Defaults to the current working directory.
-        workspace : str
+        workspace : str, optional
             The workspace directory for the project.
             Defaults to a subdirectory ``workspace`` in the project root.
-        make_dir : bool
+        make_dir : bool, optional
             Create the project root directory if it does not exist yet
             (Default value = True).
 
@@ -2317,6 +2320,16 @@ def init_project(cls, name, root=None, workspace=None, make_dir=True):
         """
         if root is None:
             root = os.getcwd()
+
+        if name is not None:
+            warnings.warn(
+                "Project names are deprecated and will be removed in signac 2.0 in favor of using "
+                "the project root directory to identify projects. The name argument to "
+                "init_project should be removed.",
+                DeprecationWarning,
+            )
+        else:
+            name = _DEFAULT_PROJECT_NAME
         try:
             project = cls.get_project(root=root, search=False)
         except LookupError:
@@ -3028,24 +3041,24 @@ def _repr_html_(self):
         return repr(self) + self._repr_html_jobs()
 
 
-def init_project(name, root=None, workspace=None, make_dir=True):
-    """Initialize a project with the given name.
+def init_project(name=None, root=None, workspace=None, make_dir=True):
+    """Initialize a project.
 
     It is safe to call this function multiple times with the same arguments.
     However, a `RuntimeError` is raised if an existing project configuration
     would conflict with the provided initialization parameters.
 
     Parameters
     ----------
-    name : str
+    name : str, optional
         The name of the project to initialize.
-    root : str
+    root : str, optional
         The root directory for the project.
         Defaults to the current working directory.
-    workspace : str
+    workspace : str, optional
         The workspace directory for the project.
         Defaults to a subdirectory ``workspace`` in the project root.
-    make_dir : bool
+    make_dir : bool, optional
         Create the project root directory, if it does not exist yet (Default
         value = True).
 

signac/diff.py

@@ -30,7 +30,7 @@ def diff_jobs(*jobs):
     Examples
     --------
     >>> import signac
-    >>> project = signac.init_project('project_name')
+    >>> project = signac.init_project()
     >>> job1 = project.open_job({'constant': 42, 'diff1': 0, 'diff2': 1}).init()
     >>> job2 = project.open_job({'constant': 42, 'diff1': 1, 'diff2': 1}).init()
     >>> job3 = project.open_job({'constant': 42, 'diff1': 2, 'diff2': 2}).init()