Doc: Use proper name capitalization of tooling (Ruff, Black, Flake8) (#10913)

Avasam · web-flow · commit 35873ec3d874 · 2023-10-18T23:46:53.000+01:00
diff --git a/.flake8 b/.flake8
@@ -8,7 +8,7 @@
 #     RST    flake8-rst-docstrings
 #     TYP    flake8-typing-imports
 
-# The following rules are incompatible with or enforced by black:
+# The following rules are incompatible with or enforced by Black:
 #     E203   whitespace before ':' -- scripts only
 #     E301   expected 1 blank line
 #     E302   expected 2 blank lines
@@ -31,15 +31,15 @@ extend-ignore = A, D, N8, SIM, RST, TYP, E301, E302, E305, E501
 per-file-ignores =
   *.py: E203
   *.pyi: B, E701, E741, F401, F403, F405
-  # Since typing.pyi defines "overload" this is not recognized by flake8 as typing.overload.
-  # Unfortunately, flake8 does not allow to "noqa" just a specific error inside the file itself.
+  # Since typing.pyi defines "overload" this is not recognized by Flake8 as typing.overload.
+  # Unfortunately, Flake8 does not allow to "noqa" just a specific error inside the file itself.
   # https://github.com/PyCQA/flake8/issues/1079
   #     F811 redefinition of unused '...'
   stdlib/typing.pyi: B, E701, E741, F401, F403, F405, F811
   # Generated protobuf files include docstrings
   # *_pb2.pyi: B, E701, E741, F401, F403, F405, Y021, Y026, Y053, Y054
 
-# TODO: Re-enable flake8 on generated protobuf files
+# TODO: Re-enable Flake8 on generated protobuf files
 # after https://github.com/nipunn1313/mypy-protobuf/issues/523 is resolved
 exclude = .venv*,.git,*_pb2.pyi
 noqa_require_code = true
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -46,7 +46,7 @@ jobs:
       - run: ./tests/check_new_syntax.py
 
   flake8:
-    name: Lint with flake8
+    name: Lint with Flake8
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -27,7 +27,7 @@
         "bungcip.better-toml",
         // Don't use two mypy extensions simultaneously
         "matangover.mypy",
-        // We use black
+        // We use Black
         "ms-python.autopep8",
         // Not using pylint
         "ms-python.pylint",
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,9 +27,12 @@ it takes a bit longer. For more details, read below.
 ### Code away!
 
 Typeshed runs continuous integration (CI) on all pull requests. This means that
-if you file a pull request (PR), our full test suite -- including our linter,
-`flake8` -- is run on your PR. It also means that bots will automatically apply
-changes to your PR (using `black`, `isort` and `ruff`) to fix any formatting issues.
+if you file a pull request (PR), our full test suite
+-- including our linter, [Flake8](https://github.com/PyCQA/flake8) --
+is run on your PR. It also means that bots will automatically apply
+changes to your PR (using [Black](https://github.com/psf/black),
+[isort](https://github.com/PyCQA/isort) and
+[Ruff](https://github.com/astral-sh/ruff)) to fix any formatting issues.
 This frees you up to ignore all local setup on your side, focus on the
 code and rely on the CI to fix everything, or point you to the places that
 need fixing.
@@ -84,16 +87,18 @@ terminal to install all non-pytype requirements:
 
 ## Code formatting
 
-The code is formatted using `black` and `isort`. Various other autofixes are
-also performed by `ruff`.
+The code is formatted using [`Black`](https://github.com/psf/black)
+and [`isort`](https://github.com/PyCQA/isort).
+Various other autofixes are
+also performed by [`Ruff`](https://github.com/astral-sh/ruff).
 
 The repository is equipped with a [`pre-commit.ci`](https://pre-commit.ci/)
 configuration file. This means that you don't *need* to do anything yourself to
 run the code formatters. When you push a commit, a bot will run those for you
 right away and add a commit to your PR.
 
 That being said, if you *want* to run the checks locally when you commit,
-you're free to do so. Either run `isort`, `black` and `ruff` manually...
+you're free to do so. Either run the following manually...
 
 ```bash
 (.venv)$ isort .
@@ -104,9 +109,12 @@ you're free to do so. Either run `isort`, `black` and `ruff` manually...
 ...Or install the pre-commit hooks: please refer to the
 [pre-commit](https://pre-commit.com/) documentation.
 
-Our code is also linted using `flake8`, with plugins `flake8-pyi`,
-`flake8-bugbear`, and `flake8-noqa`. As with our other checks, running
-flake8 before filing a PR is not required. However, if you wish to run flake8
+Our code is also linted using [`Flake8`](https://github.com/pycqa/flake8),
+with plugins [`flake8-pyi`](https://github.com/pycqa/flake8-pyi),
+[`flake8-bugbear`](https://github.com/PyCQA/flake8-bugbear),
+and [`flake8-noqa`](https://github.com/plinss/flake8-noqa).
+As with our other checks, running
+Flake8 before filing a PR is not required. However, if you wish to run Flake8
 locally, install the test dependencies as outlined above, and then run:
 
 ```bash
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,7 +3,7 @@ line_length = 130
 target_version = ["py310"]
 skip_magic_trailing_comma = true
 # Exclude protobuf files because they have long line lengths
-# Ideally, we could configure black to allow longer line lengths
+# Ideally, we could configure Black to allow longer line lengths
 # for just these files, but doesn't seem possible yet.
 force-exclude = ".*_pb2.pyi"
 
@@ -13,8 +13,8 @@ combine_as_imports = true
 line_length = 130
 skip = [".git", ".github", ".venv"]
 extra_standard_library = [
-    "typing_extensions",
     "_typeshed",
+    "typing_extensions",
     # Extra modules not recognized by isort
     "_ast",
     "_bisect",
@@ -56,7 +56,7 @@ extra_standard_library = [
     "opcode",
     "pyexpat",
 ]
-known_first_party = ["utils", "parse_metadata"]
+known_first_party = ["parse_metadata", "utils"]
 
 [tool.ruff]
 line-length = 130
@@ -68,33 +68,33 @@ exclude = [
     # Ignore generated protobuf stubs
     "*_pb2.pyi",
     # virtual environment, cache directories, etc.:
-    "env",
     ".env",
-    ".venv",
     ".git",
     ".mypy_cache",
     ".pytype",
+    ".venv",
+    "env",
 ]
 
 # Only enable rules that have safe autofixes;
 # only enable rules that are relevant to stubs
 select = [
-    "F401",   # Remove unused imports
-    "UP004",  # Remove explicit `object` inheritance
-    "UP006",  # PEP-585 autofixes
-    "UP007",  # PEP-604 autofixes
-    "UP013",  # Class-based syntax for TypedDicts
-    "UP014",  # Class-based syntax for NamedTuples
-    "UP019",  # Use str over typing.Text
-    "UP035",  # import from typing, not typing_extensions, wherever possible
-    "UP039",  # don't use parens after a class definition with no bases
-    "PYI009",  # use `...`, not `pass`, in empty class bodies
-    "PYI010",  # function bodies must be empty
-    "PYI012",  # class bodies must not contain `pass`
-    "PYI013",  # non-empty class bodies must not contain `...`
-    "PYI020",  # quoted annotations are always unnecessary in stubs
-    "PYI025",  # always alias `collections.abc.Set` as `AbstractSet` when importing it
-    "PYI032",  # use `object`, not `Any`, as the second parameter to `__eq__`
+    "F401", # Remove unused imports
+    "PYI009", # use `...`, not `pass`, in empty class bodies
+    "PYI010", # function bodies must be empty
+    "PYI012", # class bodies must not contain `pass`
+    "PYI013", # non-empty class bodies must not contain `...`
+    "PYI020", # quoted annotations are always unnecessary in stubs
+    "PYI025", # always alias `collections.abc.Set` as `AbstractSet` when importing it
+    "PYI032", # use `object`, not `Any`, as the second parameter to `__eq__`
+    "UP004", # Remove explicit `object` inheritance
+    "UP006", # PEP-585 autofixes
+    "UP007", # PEP-604 autofixes
+    "UP013", # Class-based syntax for TypedDicts
+    "UP014", # Class-based syntax for NamedTuples
+    "UP019", # Use str over typing.Text
+    "UP035", # import from typing, not typing_extensions, wherever possible
+    "UP039", # don't use parens after a class definition with no bases
 ]
 
 [tool.typeshed]
diff --git a/scripts/create_baseline_stubs.py b/scripts/create_baseline_stubs.py
@@ -61,7 +61,7 @@ def run_stubdefaulter(stub_dir: str) -> None:
 
 
 def run_black(stub_dir: str) -> None:
-    print(f"Running black: black {stub_dir}")
+    print(f"Running Black: black {stub_dir}")
     subprocess.run(["black", stub_dir])
 
 
@@ -71,7 +71,7 @@ def run_isort(stub_dir: str) -> None:
 
 
 def run_ruff(stub_dir: str) -> None:
-    print(f"Running ruff: ruff {stub_dir}")
+    print(f"Running Ruff: ruff {stub_dir}")
     subprocess.run([sys.executable, "-m", "ruff", stub_dir])
 
 
@@ -189,7 +189,7 @@ def add_pyright_exclusion(stub_dir: str) -> None:
 def main() -> None:
     parser = argparse.ArgumentParser(
         description="""Generate baseline stubs automatically for an installed pip package
-                       using stubgen. Also run black, isort and ruff. If the name of
+                       using stubgen. Also run Black, isort and Ruff. If the name of
                        the project is different from the runtime Python package name, you may
                        need to use --package (example: --package yaml PyYAML)."""
     )
diff --git a/scripts/generate_proto_stubs.sh b/scripts/generate_proto_stubs.sh
@@ -45,7 +45,7 @@ PYTHON_PROTOBUF_DIR="protobuf-$PYTHON_PROTOBUF_VERSION"
 VENV=venv
 python3 -m venv "$VENV"
 source "$VENV/bin/activate"
-pip install -r "$REPO_ROOT/requirements-tests.txt"  # for black and isort
+pip install -r "$REPO_ROOT/requirements-tests.txt"  # for Black and isort
 
 # Install mypy-protobuf
 pip install "git+https://github.com/dropbox/mypy-protobuf@$MYPY_PROTOBUF_VERSION"
diff --git a/scripts/runtests.py b/scripts/runtests.py
@@ -82,7 +82,7 @@ def main() -> None:
     pytype_result: subprocess.CompletedProcess[bytes] | None = None
 
     # Run formatters first. Order matters.
-    print("\nRunning ruff...")
+    print("\nRunning Ruff...")
     subprocess.run([sys.executable, "-m", "ruff", path])
     print("\nRunning isort...")
     subprocess.run([sys.executable, "-m", "isort", path])
diff --git a/stdlib/_winapi.pyi b/stdlib/_winapi.pyi
@@ -54,7 +54,7 @@ if sys.platform == "win32":
     HIGH_PRIORITY_CLASS: Literal[0x80]
     INFINITE: Literal[0xFFFFFFFF]
     if sys.version_info >= (3, 8):
-        # Ignore the flake8 error -- flake8-pyi assumes
+        # Ignore the Flake8 error -- flake8-pyi assumes
         # most numbers this long will be implementation details,
         # but here we can see that it's a power of 2
         INVALID_HANDLE_VALUE: Literal[0xFFFFFFFFFFFFFFFF]  # noqa: Y054
diff --git a/test_cases/stdlib/builtins/check_exception_group-py311.py b/test_cases/stdlib/builtins/check_exception_group-py311.py
@@ -5,7 +5,7 @@
 from typing_extensions import assert_type
 
 if sys.version_info >= (3, 11):
-    # This can be removed later, but right now `flake8` does not know
+    # This can be removed later, but right now Flake8 does not know
     # about these two classes:
     from builtins import BaseExceptionGroup, ExceptionGroup
 
diff --git a/tests/check_consistent.py b/tests/check_consistent.py
@@ -191,7 +191,7 @@ def check_precommit_requirements() -> None:
     precommit_requirements = get_precommit_requirements()
     no_txt_entry_msg = "All pre-commit requirements must also be listed in `requirements-tests.txt` (missing {requirement!r})"
     for requirement, specifier in precommit_requirements.items():
-        # annoying: the ruff and black repos for pre-commit are different to the names in requirements-tests.txt
+        # annoying: the Ruff and Black repos for pre-commit are different to the names in requirements-tests.txt
         if requirement in {"ruff-pre-commit", "black-pre-commit-mirror"}:
             requirement = requirement.split("-")[0]
         assert requirement in requirements_txt_requirements, no_txt_entry_msg.format(requirement=requirement)
