Add version to github action (and rewrite the whole thing while at …

…it) (#1940)

Commit history before merge:

* Add black_version to github action
* Merge upstream/main into this branch
* Add version support for the Black action pt.2

  Since we're moving to a composite based action, quite a few changes
  were made. 1) Support was added for all OSes (Windows was painful). 
  2) Isolation from the rest of the workflow had to be done manually
  with a virtual environment.

  Other noteworthy changes:

  - Rewrote basically all of the logic and put it in a Python script
    for easy testing (not doing it here tho cause I'm lazy and I can't
    think of a reasonable way of testing it).
  - Renamed `black_version` to `version` to better fit the existing
    input naming scheme.
  - Added support for log groups, this makes our action's output a
    bit more fancy (I may or may have not added some debug output too).

* Add more to and sorta rewrite the Action's docs

  Reflect compatability and gotchas.

* Add CHANGELOG entry
* Merge main into this branch
* Remove debug; address typos; clean up action.yml

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>

CHANGES.md

@@ -25,7 +25,12 @@
 - Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
   supported. (#2231)
 
-### _Packaging_
+### Integrations
+
+- The official Black action now supports choosing what version to use, and supports the
+  major 3 OSes. (#1940)
+
+### Packaging
 
 - Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline
   (#2198)

action.yml

@@ -4,21 +4,56 @@ author: "Łukasz Langa and contributors to Black"
 inputs:
   options:
     description:
-      "Options passed to black. Use `black --help` to see available options. Default:
+      "Options passed to Black. Use `black --help` to see available options. Default:
       '--check'"
     required: false
     default: "--check --diff"
   src:
-    description: "Source to run black. Default: '.'"
+    description: "Source to run Black. Default: '.'"
     required: false
     default: "."
   black_args:
     description: "[DEPRECATED] Black input arguments."
     required: false
     default: ""
+    deprecationMessage:
+      "Input `with.black_args` is deprecated. Use `with.options` and `with.src` instead."
+  version:
+    description: 'Python Version specifier (PEP440) - e.g. "21.5b1"'
+    required: false
+    default: ""
 branding:
   color: "black"
   icon: "check-circle"
 runs:
-  using: "docker"
-  image: "action/Dockerfile"
+  using: composite
+  steps:
+    - run: |
+        # Exists since using github.action_path + path to main script doesn't work because bash
+        # interprets the backslashes in github.action_path (which are used when the runner OS
+        # is Windows) destroying the path to the target file.
+        #
+        # Also semicolons are necessary because I can't get the newlines to work
+        entrypoint="import sys;
+        import subprocess;
+        from pathlib import Path;
+
+        MAIN_SCRIPT = Path(r'${{ github.action_path }}') / 'action' / 'main.py';
+
+        proc = subprocess.run([sys.executable, str(MAIN_SCRIPT)]);
+        sys.exit(proc.returncode)
+        "
+
+        if [ "$RUNNER_OS" == "Windows" ]; then
+          echo $entrypoint | python
+        else
+          echo $entrypoint | python3
+        fi
+      env:
+        # TODO: Remove once https://github.com/actions/runner/issues/665 is fixed.
+        INPUT_OPTIONS: ${{ inputs.options }}
+        INPUT_SRC: ${{ inputs.src }}
+        INPUT_BLACK_ARGS: ${{ inputs.black_args }}
+        INPUT_VERSION: ${{ inputs.version }}
+        pythonioencoding: utf-8
+      shell: bash

action/main.py

@@ -0,0 +1,39 @@
+import os
+import shlex
+import sys
+from pathlib import Path
+from subprocess import run, PIPE, STDOUT
+
+ACTION_PATH = Path(os.environ["GITHUB_ACTION_PATH"])
+ENV_PATH = ACTION_PATH / ".black-env"
+ENV_BIN = ENV_PATH / ("Scripts" if sys.platform == "win32" else "bin")
+OPTIONS = os.getenv("INPUT_OPTIONS", default="")
+SRC = os.getenv("INPUT_SRC", default="")
+BLACK_ARGS = os.getenv("INPUT_BLACK_ARGS", default="")
+VERSION = os.getenv("INPUT_VERSION", default="")
+
+run([sys.executable, "-m", "venv", str(ENV_PATH)], check=True)
+
+req = "black[colorama,python2]"
+if VERSION:
+    req += f"=={VERSION}"
+pip_proc = run(
+    [str(ENV_BIN / "python"), "-m", "pip", "install", req],
+    stdout=PIPE,
+    stderr=STDOUT,
+    encoding="utf-8",
+)
+if pip_proc.returncode:
+    print(pip_proc.stdout)
+    print("::error::Failed to install Black.", flush=True)
+    sys.exit(pip_proc.returncode)
+
+
+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)])
+else:
+    proc = run([*base_cmd, *shlex.split(OPTIONS), *shlex.split(SRC)])
+
+sys.exit(proc.returncode)

docs/integrations/github_actions.md

@@ -3,6 +3,14 @@
 You can use _Black_ within a GitHub Actions workflow without setting your own Python
 environment. Great for enforcing that your code matches the _Black_ code style.
 
+## Compatiblity
+
+This action is known to support all GitHub-hosted runner OSes. In addition, only
+published versions of _Black_ are supported (i.e. whatever is available on PyPI).
+
+Finally, this action installs _Black_ with both the `colorama` and `python2` extras so
+the `--color` flag and formatting Python 2 code are supported.
+
 ## Usage
 
 Create a file named `.github/workflows/black.yml` inside your repository with:
@@ -17,19 +25,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
       - uses: psf/black@stable
 ```
 
 We recommend the use of the `@stable` tag, but per version tags also exist if you prefer
-that.
+that. Note that the action's version you select is independent of the version of _Black_
+the action will use.
+
+The version of _Black_ the action will use can be configured via `version`. The action
+defaults to the latest release available on PyPI. Only versions available from PyPI are
+supported, so no commit SHAs or branch names.
+
+You can also configure the arguments passed to _Black_ via `options` (defaults to
+`'--check --diff'`) and `src` (default is `'.'`)
 
-You may use `options` (Default is `'--check --diff'`) and `src` (Default is `'.'`) as
-follows:
+Here's an example configuration:
 
 ```yaml
 - uses: psf/black@stable
   with:
     options: "--check --verbose"
     src: "./src"
+    version: "21.5b1"
 ```