[stack-pr] Convert stack-pr.py into an installable python package (#6)

Refactor the bare scripts into a proper python package with a
pyproject.toml.

Add support for a build backend so stack-pr can submitted to the
Python Package Index and be easily installed with pipx.

Fix some minor import issues and lint warnings using ruff.

Author: zbowling

.gitattributes

@@ -0,0 +1,2 @@
+# GitHub syntax highlighting
+pixi.lock linguist-language=YAML linguist-generated=true

.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# IPython
+profile_default/
+ipython_config.py
+
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm-project.org/#use-with-ide
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+.pdm-python
+
+# pixi environments
+.pixi
+*.egg-info
+pixi.lock

README.md

@@ -21,12 +21,26 @@ This is a non-comprehensive list of dependencies required by `stack-pr.py`:
 - Install `gh`, e.g., `brew install gh` on MacOS.
 - Run `gh auth login` with SSH
 
+## Installation
+
+To install via [pipx](https://pipx.pypa.io/stable/) run:
+
+```bash
+pipx install stack-pr
+```
+
+Manually, you can clone the repository and run the following command:
+
+```bash
+pipx install .
+```
+
 ## Workflow
 
-`stack-pr.py` is a script allowing you to work with stacked PRs: submit,
+`stack-pr` is a tool allowing you to work with stacked PRs: submit,
 view, and land them.
 
-`stack-pr.py` tool has four commands:
+The `stack-pr` tool has four commands:
 
 - `submit` (or `export`) - create a new stack of PRs from the given set of
   commits. One can think of this as “push my local changes to the corresponding
@@ -104,7 +118,7 @@ We can double-check that by running the script with `view` command - it is
 always a safe command to run:
 
 ```bash
-# stack-pr.py view
+# stack-pr view
 ...
 VIEW
 **Stack:**
@@ -119,7 +133,7 @@ corresponding PRs and cross-link them. To do that, we run the tool with
 `submit` command:
 
 ```bash
-# stack-pr.py submit
+# stack-pr submit
 ...
 SUCCESS!
 ```
@@ -140,7 +154,7 @@ If the command succeeded, we should see “SUCCESS!” in the end, and we can no
 run `view` again to look at the new stack:
 
 ```python
-# stack-pr.py view
+# stack-pr view
 ...
 VIEW
 **Stack:**
@@ -161,7 +175,7 @@ and run `submit` again. If needed, we can rearrange commits or add new ones.
 When we are ready to merge our changes, we use `land` command.
 
 ```python
-# stack-pr.py land
+# stack-pr land
 LAND
 Stack:
    * cc932b71 (#439, 'ZolotukhinM/stack/103' -> 'ZolotukhinM/stack/102'): Optimized navigation algorithms for deep space travel
@@ -181,7 +195,7 @@ This command lands the first PR of the stack and rebases the rest. If we run
 there:
 
 ```python
-# stack-pr.py view
+# stack-pr view
 VIEW
 **Stack:**
    * **8177f347** (#439, 'ZolotukhinM/stack/103' -> 'ZolotukhinM/stack/102'): Optimized navigation algorithms for deep space travel
@@ -198,13 +212,13 @@ the script:
 
 ```bash
 # Submit a stack of last 5 commits
-stack-pr.py submit -B HEAD~5
+stack-pr submit -B HEAD~5
 
 # Use 'origin/main' instead of 'main' as the base for the stack
-stack-pr.py submit -B origin/main
+stack-pr submit -B origin/main
 
 # Do not include last two commits to the stack
-stack-pr.py submit -H HEAD~2
+stack-pr submit -H HEAD~2
 ```
 
 These options work for all script commands (and it’s recommended to first use
@@ -214,12 +228,12 @@ land first three of them:
 
 ```bash
 # Inspect what commits will be included HEAD~5..HEAD
-stack-pr.py view -B HEAD~5
+stack-pr view -B HEAD~5
 # Create a stack from last five commits
-stack-pr.py submit -B HEAD~5
+stack-pr submit -B HEAD~5
 
 # Inspect what commits will be included into the range HEAD~5..HEAD~2
-stack-pr.py view -B HEAD~5 -H HEAD~2
+stack-pr view -B HEAD~5 -H HEAD~2
 # Land first three PRs from the stack
-stack-pr.py land -B HEAD~5 -H HEAD~2
+stack-pr land -B HEAD~5 -H HEAD~2
 ```

pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["pdm-backend"]
+build-backend = "pdm.backend"
+
+[project]
+name = "stack-pr"
+authors = [
+    {name = "Modular Inc", email = "[email protected]"},
+]
+maintainers = [
+    {name = "Modular Inc", email = "[email protected]"}
+]
+description = "Stacked PRs for GitHub"
+version = "1.0"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.8"
+keywords = ["stacked-prs", "github", "pull-requests", "stack-pr", "git", "version-control"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Version Control :: Git",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/modularml/stack-pr"
+Repository = "https://github.com/modularml/stack-pr"
+"Bug Tracker" = "https://github.com/modularml/stack-pr/issues"
+
+[project.scripts]
+stack-pr = "stack_pr.cli:main"
+
+[tool.pdm]
+distribution = true
+
+[tool.pixi.project]
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "osx-64", "linux-64", "linux-aarch64"]
+
+[tool.pixi.pypi-dependencies]
+stack-pr = { path = ".", editable = true }
+
+[tool.pixi.tasks]
+
+[tool.pixi.dependencies]
+python = ">=3.8"

src/stack_pr/__init__.py

@@ -0,0 +1,4 @@
+from .stack_pr import main
+
+if __name__ == "__main__":
+    main()

src/stack_pr/__main__.py

@@ -55,14 +55,14 @@
 import re
 from subprocess import SubprocessError
 
-from git import (
+from .git import (
     branch_exists,
     check_gh_installed,
     get_current_branch_name,
     get_gh_username,
     get_uncommitted_changes,
 )
-from shell_commands import get_command_output, run_shell_command
+from .shell_commands import get_command_output, run_shell_command
 from typing import List, NamedTuple, Optional, Pattern
 
 # A bunch of regexps for parsing commit messages and PR descriptions
@@ -199,9 +199,7 @@ def commit_id(self) -> str:
         return self._search_group(RE_RAW_COMMIT_ID, "commit")
 
     def parents(self) -> List[str]:
-        return [
-            m.group("commit") for m in RE_RAW_PARENT.finditer(self.raw_header)
-        ]
+        return [m.group("commit") for m in RE_RAW_PARENT.finditer(self.raw_header)]
 
     def author(self) -> str:
         return self._search_group(RE_RAW_AUTHOR, "author")
@@ -214,8 +212,7 @@ def author_email(self) -> str:
 
     def commit_msg(self) -> str:
         return "\n".join(
-            m.group("line")
-            for m in RE_RAW_COMMIT_MSG_LINE.finditer(self.raw_header)
+            m.group("line") for m in RE_RAW_COMMIT_MSG_LINE.finditer(self.raw_header)
         )
 
 
@@ -408,9 +405,7 @@ def get_stack(base: str, head: str) -> List[StackEntry]:
     st: List[StackEntry] = []
     stack = (
         split_header(
-            get_command_output(
-                ["git", "rev-list", "--header", "^" + base, head]
-            )
+            get_command_output(["git", "rev-list", "--header", "^" + base, head])
         )
     )[::-1]
 
@@ -561,9 +556,7 @@ def init_local_branches(st: List[StackEntry], remote: str):
     log(h("Initializing local branches"), level=1)
     set_head_branches(st, remote)
     for e in st:
-        run_shell_command(
-            ["git", "checkout", e.commit.commit_id(), "-B", e.head]
-        )
+        run_shell_command(["git", "checkout", e.commit.commit_id(), "-B", e.head])
 
 
 def push_branches(st: List[StackEntry], remote):
@@ -574,12 +567,8 @@ def push_branches(st: List[StackEntry], remote):
 
 
 def print_cmd_failure_details(exc: SubprocessError):
-    cmd_stdout = (
-        exc.stdout.decode("utf-8").replace("\\n", "\n").replace("\\t", "\t")
-    )
-    cmd_stderr = (
-        exc.stderr.decode("utf-8").replace("\\n", "\n").replace("\\t", "\t")
-    )
+    cmd_stdout = exc.stdout.decode("utf-8").replace("\\n", "\n").replace("\\t", "\t")
+    cmd_stderr = exc.stderr.decode("utf-8").replace("\\n", "\n").replace("\\t", "\t")
     print(f"Exitcode: {exc.returncode}")
     print(f"Stdout: {cmd_stdout}")
     print(f"Stderr: {cmd_stderr}")
@@ -656,9 +645,7 @@ def add_cross_links(st: List[StackEntry], keep_body: bool):
         if keep_body:
             # Keep current body of the PR after the cross links component
             current_pr_body = get_current_pr_body(e)
-            pr_body.append(
-                current_pr_body.split(CROSS_LINKS_DELIMETER, 1)[-1].lstrip()
-            )
+            pr_body.append(current_pr_body.split(CROSS_LINKS_DELIMETER, 1)[-1].lstrip())
         else:
             pr_body.extend(
                 [
@@ -827,9 +814,7 @@ def command_submit(
     # Now we have all the branches, so we can create the corresponding PRs
     log(h("Submitting PRs"), level=1)
     for e_idx, e in enumerate(st):
-        is_pr_draft = draft or (
-            (draft_bitmask is not None) and draft_bitmask[e_idx]
-        )
+        is_pr_draft = draft or ((draft_bitmask is not None) and draft_bitmask[e_idx])
         create_pr(e, is_pr_draft, reviewer)
 
     # Verify consistency in everything we have so far
@@ -998,9 +983,7 @@ def command_land(args: CommonArgs):
         for e in prs_to_rebase:
             rebase_pr(e, args.remote, args.target)
         # Change the target of the new bottom-most PR in the stack to 'target'
-        run_shell_command(
-            ["gh", "pr", "edit", prs_to_rebase[0].pr, "-B", args.target]
-        )
+        run_shell_command(["gh", "pr", "edit", prs_to_rebase[0].pr, "-B", args.target])
 
     # Delete local and remote stack branches
     run_shell_command(["git", "checkout", current_branch])
@@ -1013,9 +996,7 @@ def command_land(args: CommonArgs):
         run_shell_command(
             ["git", "rebase", f"{args.remote}/{args.target}", args.target]
         )
-    run_shell_command(
-        ["git", "rebase", f"{args.remote}/{args.target}", current_branch]
-    )
+    run_shell_command(["git", "rebase", f"{args.remote}/{args.target}", current_branch])
 
     log(h(blue("SUCCESS!")), level=1)
 
@@ -1143,13 +1124,9 @@ def create_argparser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(help="sub-command help", dest="command")
 
     common_parser = argparse.ArgumentParser(add_help=False)
-    common_parser.add_argument(
-        "-R", "--remote", default="origin", help="Remote name"
-    )
+    common_parser.add_argument("-R", "--remote", default="origin", help="Remote name")
     common_parser.add_argument("-B", "--base", help="Local base branch")
-    common_parser.add_argument(
-        "-H", "--head", default="HEAD", help="Local head branch"
-    )
+    common_parser.add_argument("-H", "--head", default="HEAD", help="Local head branch")
     common_parser.add_argument(
         "-T", "--target", default="main", help="Remote target branch"
     )