Merge branch 'main' into incorrect_organization_replacement_in_general_README

Author: evvaaaa

docs/user/how-to/existing.rst

@@ -4,14 +4,15 @@ How to adopt the skeleton in an existing repo
 If you have an existing repo and would like to adopt the skeleton structure
 then you can use the commandline tool to merge the skeleton into your repo::
 
-    python3-pip-skeleton existing /path/to/existing/repo --org my_github_user_or_org
+    python3-pip-skeleton existing /path/to/existing/repo --org my_github_user_or_org --skeleton-org some_institution
 
 This will:
 
 - Take the repo name from the last element of the path
 - Take the package name from the repo name unless overridden by ``--package``
 - Clone the existing repo in /tmp
 - Create a new orphan merge branch from the skeleton repo
+- Use the version of the skeleton in ``some_institution``'s organization (default ``DiamondLightSource``)
 - Create a single commit that modifies the skeleton with the repo and package name
 - Push that merge branch back to the existing repo
 - Merge with the currently checked out branch, leaving you to fix the conflicts

docs/user/how-to/maintain-your-own-skeleton.rst

@@ -0,0 +1,12 @@
+Creating a new skeleton fork
+============================
+
+There may be some features in the DiamondLightSource skeleton which aren't required,
+or some you want to add which Diamond doesn't require. The python3-pip-skeleton can be used
+with any ``https://github.com/SomeInstitution/python3-pip-skeleton`` forked from 
+``https://github.com/DiamondLightSource/python3-pip-skeleton`` by using ``--skeleton-org SomeInstitution``
+when implementing the skeleton on a new or existing repo.
+
+The forked skeleton repo has to have the name ``python3-pip-skeleton``. It can be changed however the 
+institution requires, then DiamondLightSource's skeleton can be periodically pulled from upstream 
+to acquire the latest changes. 

docs/user/index.rst

@@ -26,6 +26,7 @@ side-bar.
             :caption: How-to Guides
             :maxdepth: 1
 
+            how-to/maintain-your-own-skeleton
             how-to/run-container
             how-to/existing
             how-to/update

docs/user/tutorials/new.rst

@@ -1,17 +1,18 @@
 Creating a new repo from the skeleton
 =====================================
 
-Once you have followed the `installation` tutorial, you can use the
+Once you have followed the ``installation`` tutorial, you can use the
 commandline tool to make a new repo that inherits the skeleton::
 
-    python3-pip-skeleton new /path/to/be/created --org my_github_user_or_org
+    python3-pip-skeleton new /path/to/be/created --org my_github_user_or_org --skeleton-org some_institution
 
 This will:
 
 - Take the repo name from the last element of the path
 - Take the package name from the repo name unless overridden by ``--package``
 - Create a new repo at the requested path, forked from the skeleton repo
 - Create a single commit that modifies the skeleton with the repo and package name
+- Use the version of the skeleton in ``some_institution``'s organization (default ``DiamondLightSource``)
 
 
 Getting started with your new repo

pyproject.toml

@@ -13,7 +13,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
 ]
 description = "One line description of your module"
-dependencies = [] # Add project dependencies here, e.g. ["click", "numpy"]
+dependencies = ["tomli"] # Add project dependencies here, e.g. ["click", "numpy"]
 dynamic = ["version"]
 license.file = "LICENSE"
 readme = "README.rst"

src/python3_pip_skeleton/__main__.py

@@ -7,12 +7,15 @@
 from tempfile import TemporaryDirectory
 from typing import Dict, List, Optional, Tuple
 
+import tomli
+
 from . import __version__
 
 __all__ = ["main"]
 
-# The source of the skeleton module to pull from
-SKELETON = "https://github.com/DiamondLightSource/python3-pip-skeleton"
+# The url of the default skeleton module to pull from, a different skeleton
+# url can be passed in with --skeleton-git-url
+SKELETON_URL = "https://github.com/%s/python3-pip-skeleton"
 # The name of the merge branch that will be created
 MERGE_BRANCH = "skeleton-merge-branch"
 # Extensions to change
@@ -63,6 +66,7 @@ def merge_skeleton(
     full_name: str,
     email: str,
     from_branch: str,
+    skeleton_org: str,
     package,
 ):
     path = path.resolve()
@@ -77,6 +81,10 @@ def replace_text(text: str) -> str:
         text = text.replace("main", from_branch)
         return text
 
+    def replace_in_file(file_path: Path, text_from: str, text_to: str):
+        file_contents = file_path.read_text()
+        file_path.write_text(file_contents.replace(text_from, text_to))
+
     branches = list_branches(path)
     assert MERGE_BRANCH not in branches, (
         f"{MERGE_BRANCH} already exists. "
@@ -94,7 +102,7 @@ def replace_text(text: str) -> str:
         # will do the wrong thing
         shutil.rmtree(git_tmp / "src", ignore_errors=True)
         # Merge in the skeleton commits
-        git_tmp("pull", "--rebase=false", SKELETON, from_branch)
+        git_tmp("pull", "--rebase=false", SKELETON_URL % skeleton_org, from_branch)
         # Move things around
         if package != "python3_pip_skeleton":
             git_tmp("mv", "src/python3_pip_skeleton", f"src/{package}")
@@ -135,6 +143,13 @@ def replace_text(text: str) -> str:
                         )
                 child.write_text(replaced_text)
 
+        # Change instructions in the docs to reflect which pip skeleton is in use
+        replace_in_file(
+            Path(git_tmp.name) / "docs/developer/how-to/update-tools.rst",
+            "DiamondLightSource",
+            skeleton_org,
+        )
+
         # Commit what we have and push to the original repo
         git_tmp("commit", "-a", "-m", f"Rename python3-pip-skeleton -> {repo}")
         git_tmp("push", "origin", MERGE_BRANCH)
@@ -157,7 +172,7 @@ def validate_package(args) -> str:
     return package
 
 
-def verify_not_adopted(root: Path):
+def verify_not_adopted(root: Path, skeleton_git_url: str):
     """Verify that module has not already adopted skeleton"""
 
     # This call does not print anything - the return code is 0 if it is an ancestor
@@ -175,40 +190,148 @@ def verify_not_adopted(root: Path):
 
     assert not_adopted, (
         f"Package {root} has already adopted skeleton. You can type:\n"
-        f"    git pull --rebase=false {SKELETON}\n"
+        f"    git pull --rebase=false {skeleton_git_url}\n"
         "to update. If there were significant upstream changes a re-adopt may be "
         "better. use the --force flag to the command you just ran."
     )
 
 
+def obtain_git_author_email(path: Path, force_local=True):
+    # If we force local then we require there to be a local .git we can look for
+    # the username and password on.
+    # If we don't force local then we will try to look for a local .git, if not found
+    # git will use the global user.[name, email].
+    if force_local and not (path / ".git").exists():
+        raise FileNotFoundError(
+            ".git could not be found when searching "
+            f"for a username and password in {path}"
+        )
+    author = str(
+        git("--git-dir", path / ".git", "config", "--get", "user.name").strip()
+    )
+    author_email = str(
+        git("--git-dir", path / ".git", "config", "--get", "user.email").strip()
+    )
+
+    return author, author_email
+
+
 def new(args):
     path: Path = args.path
 
+    package = validate_package(args)
+
     if path.exists():
         assert path.is_dir() and not list(
             path.iterdir()
         ), f"Expected {path} to not exist, or be an empty dir"
     else:
         path.mkdir(parents=True)
 
-    package = validate_package(args)
+    if args.full_name and args.email:
+        author, author_email = args.full_name, args.email
+    else:
+        author, author_email = obtain_git_author_email(Path("."), force_local=False)
+
     git("init", "-b", "main", cwd=path)
     print(f"Created git repo in {path}")
     merge_skeleton(
         path=path,
         org=args.org,
-        full_name=args.full_name or git("config", "--get", "user.name").strip(),
-        email=args.email or git("config", "--get", "user.email").strip(),
+        full_name=author,
+        email=author_email,
         from_branch=args.from_branch or "main",
+        skeleton_org=args.skeleton_org,
         package=package,
     )
 
 
 cfg_issue = """Missing parameter in setup.cfg. Expected format:
-[metadata]
-name = example
-author = Firstname Lastname
-author_email = [email protected]"""
+    [metadata]
+    name = example
+    author = Firstname Lastname
+    author_email = [email protected]
+
+    ------- pyproject.toml
+    [[project.authors]]
+    name = "Firstname Lastname"
+    email = "[email protected]"
+"""
+
+
+def obtain_author_name_email(path: Path) -> tuple:
+    author: str = ""
+    author_email: str = ""
+    file_path_setup_cfg: Path = path / "setup.cfg"
+    file_path_pyproject_toml: Path = path / "pyproject.toml"
+
+    # Parse for an author name, email. The order of preference used is
+    # setup.cfg -> pyproject.toml -> .git -> user input.
+    # Author and Email are recieved together to avoid mismatches from
+    # obtaining in different places.
+
+    if file_path_setup_cfg.exists():
+        try:
+            conf_cfg = ConfigParser()
+            conf_cfg.read(file_path_setup_cfg)
+
+            if "metadata" in conf_cfg:
+                if "author" in conf_cfg["metadata"]:
+                    author = conf_cfg["metadata"]["author"]
+                if "author_email" in conf_cfg["metadata"]:
+                    author_email = conf_cfg["metadata"]["author_email"]
+        except Exception as exception:
+            print(
+                "\033[1mUnable to parse setup.cfg because of the following error, "
+                "will try other sources:\033[0m"
+            )
+            print(exception)
+            print()
+
+    if (not author or not author_email) and file_path_pyproject_toml.exists():
+        file = open(file_path_pyproject_toml, "rb")
+        try:
+            conf_toml = tomli.load(file)
+            if "project" in conf_toml and "authors" in conf_toml["project"]:
+                # pyproject.toml will use "author" or "name" so we look for both
+                for author_variable_name in ["author", "name"]:
+                    if author_variable_name in conf_toml["project"]["authors"][0]:
+                        author = conf_toml["project"]["authors"][0][
+                            author_variable_name
+                        ]
+                if "email" in conf_toml["project"]["authors"][0]:
+                    author_email = conf_toml["project"]["authors"][0]["email"]
+        except Exception as exception:
+            # We want to use something else if the pyproject.toml has some errors.
+            print(
+                "\033[1mUnable to parse project.toml because of the following error, "
+                "will try other sources:\033[0m"
+            )
+            print(exception)
+            print()
+        file.close()
+
+    if not author or not author_email:
+        try:
+            author, author_email = obtain_git_author_email(path)
+        except FileNotFoundError:
+            print(
+                "\033[1mUnable to find a .git in the repo,"
+                "will try other sources\033[0m"
+            )
+
+    # If all else fails, just ask the user.
+    if not author or not author_email:
+        print(cfg_issue)
+        print("Enter author name manually:")
+        author = str(input())
+        print("Enter author email manually:")
+        author_email = str(input())
+
+    assert author, "Inputted no author"
+    assert author_email, "Inputted no author_email"
+
+    return author, author_email
 
 
 def existing(args):
@@ -217,22 +340,22 @@ def existing(args):
 
     assert path.is_dir(), f"Expected {path} to be an existing directory"
     package = validate_package(args)
-    file_path: Path = path / "setup.cfg"
-    assert file_path.is_file(), "Expected a setup.cfg file in the directory."
+
     if not args.force:
-        verify_not_adopted(args.path)
+        verify_not_adopted(args.path, skeleton_git_url=SKELETON_URL % args.skeleton_org)
+
+    if args.full_name and args.email:
+        author, author_email = args.full_name, args.email
+    else:
+        author, author_email = obtain_author_name_email(path)
 
-    conf = ConfigParser()
-    conf.read(path / "setup.cfg")
-    assert "metadata" in conf, cfg_issue
-    assert "author" in conf["metadata"], cfg_issue
-    assert "author_email" in conf["metadata"], cfg_issue
     merge_skeleton(
         path=args.path,
         org=args.org,
-        full_name=conf["metadata"]["author"],
-        email=conf["metadata"]["author_email"],
+        full_name=author,
+        email=author_email,
         from_branch=args.from_branch or "main",
+        skeleton_org=args.skeleton_org,
         package=package,
     )
 
@@ -256,11 +379,17 @@ def main(args=None):
     parser = ArgumentParser()
     subparsers = parser.add_subparsers()
     parser.add_argument("--version", action="version", version=__version__)
+
     # Add a command for making a new repo
     sub = subparsers.add_parser("new", help="Make a new repo forked from this skeleton")
     sub.set_defaults(func=new)
     sub.add_argument("path", type=Path, help="Path to new repo to create")
     sub.add_argument("--org", required=True, help="GitHub organization for the repo")
+    sub.add_argument(
+        "--skeleton-org",
+        default="DiamondLightSource",
+        help="The organisation of the python3-pip-skeleton to use",
+    )
     sub.add_argument(
         "--package", default=None, help="Package name, defaults to directory name"
     )
@@ -281,9 +410,20 @@ def main(args=None):
     sub.add_argument("path", type=Path, help="Path to new repo to existing repo")
     sub.add_argument("--force", action="store_true", help="force readoption")
     sub.add_argument("--org", required=True, help="GitHub organization for the repo")
+    sub.add_argument(
+        "--skeleton-org",
+        default="DiamondLightSource",
+        help="The organisation of the python3-pip-skeleton to use",
+    )
     sub.add_argument(
         "--package", default=None, help="Package name, defaults to directory name"
     )
+    sub.add_argument(
+        "--full-name", default=None, help="Full name, defaults to git config user.name"
+    )
+    sub.add_argument(
+        "--email", default=None, help="Email address, defaults to git config user.email"
+    )
     sub.add_argument(
         "--from-branch",
         default=None,