Github action now reports state of execution #3531

CHANGES.md

@@ -42,6 +42,9 @@
 
 <!-- For example, Docker, GitHub Actions, pre-commit, editors -->
 
+- GitHub Action: adds 2 action outputs to report changes that can be used in other
+  steps. Outputs: `is-formatted` and `changed-files` (#3531)
+
 ### Documentation
 
 <!-- Major changes to documentation and policies. Small docs changes

action.yml

@@ -27,6 +27,13 @@ inputs:
     description: 'Python Version specifier (PEP440) - e.g. "21.5b1"'
     required: false
     default: ""
+outputs:
+  is-formatted:
+    description: "Files checked are formatted to the current black formatter style."
+    value: steps
+  changed-files:
+    description: "Number of files black changed"
+    value: steps
 branding:
   color: "black"
   icon: "check-circle"

action/main.py

@@ -2,9 +2,11 @@
 import shlex
 import sys
 from pathlib import Path
+from re import MULTILINE, search
 from subprocess import PIPE, STDOUT, run
 
 ACTION_PATH = Path(os.environ["GITHUB_ACTION_PATH"])
+GITHUB_OUTPUT = Path(os.environ["GITHUB_OUTPUT"])
 ENV_PATH = ACTION_PATH / ".black-env"
 ENV_BIN = ENV_PATH / ("Scripts" if sys.platform == "win32" else "bin")
 OPTIONS = os.getenv("INPUT_OPTIONS", default="")
@@ -13,6 +15,10 @@
 BLACK_ARGS = os.getenv("INPUT_BLACK_ARGS", default="")
 VERSION = os.getenv("INPUT_VERSION", default="")
 
+_is_formatted_re = r"\s?(?P<changed-files>[0-9]+)\sfiles?\sreformatted(\.|,)\s?"
+
+_outputs = {"is-formatted": "false", "changed-files": "0"}
+
 run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
 
 version_specifier = VERSION
@@ -38,8 +44,25 @@
 base_cmd = [str(ENV_BIN / "black")]
 if BLACK_ARGS:
     # TODO: remove after a while since this is deprecated in favour of SRC + OPTIONS.
-    proc = run([*base_cmd, *shlex.split(BLACK_ARGS)])
+    proc = run([*base_cmd, *shlex.split(BLACK_ARGS)], stderr=PIPE)
 else:
-    proc = run([*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)])
+    proc = run(
+        [*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)],
+        stderr=PIPE
+    )
+# Re-emit stderr back to console so that action output is visible to pipeline
+# Do note, click will strip terminal control codes if the output is not TTY
+# and thus, this will not show colors anymore.
+print(proc.stderr, file=sys.stderr, flush=True)
+
+_output = proc.stderr.decode("utf-8")
+matches = search(_is_formatted_re, _output, MULTILINE)
+if matches:
+    _outputs["is-formatted"] = "true"
+    _outputs["changed-files"] = str(matches.group("changed-files"))
+
+with GITHUB_OUTPUT.open("a+", encoding="utf-8") as f:
+    for k, v in _outputs.items():
+        f.write(f"{k}={v}\n")
 
 sys.exit(proc.returncode)

docs/integrations/github_actions.md

@@ -70,3 +70,43 @@ If you want to match versions covered by Black's
     src: "./src"
     version: "~= 22.0"
 ```
+
+## Outputs
+
+This action will output two variables for further processing of changes black has made
+against `src` set.
+
+### `is-formatted`
+
+Defaults to `"false"`, set to `"true"` if black changed any files.
+
+### `changed-files`
+
+Defaults to `"0"`, set to string representation of integer value of how many files black
+modified.
+
+### Usage
+
+One could use either of these output variables to further have conditional steps within
+the same pipeline, like creating a pull request after black has done changes to the code
+base.
+
+```yaml
+- uses: psf/black@stable
+  with:
+    options: "--verbose"
+    src: "./src"
+    id: "action_black"
+
+- name: Create Pull Request
+  if: steps.action_black.outputs.is-formatted == 'true'
+  uses: peter-evans/create-pull-request@v3
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    title: "Format Python code with psf/black push"
+    commit-message: ":art: Format Python code with psf/black"
+    body: |
+      There appear to be some python formatting errors in ${{ github.sha }}. This pull request
+      uses the [psf/black](https://github.com/psf/black) formatter to fix these issues.
+    base: ${{ github.head_ref }} # Creates pull request onto pull request or commit branch
+```