madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Document jupyter hook (#2416)
authorMarco Edward Gorelli <marcogorelli@protonmail.com>
Fri, 27 Aug 2021 20:21:08 +0000 (21:21 +0100)
committerGitHub <noreply@github.com>
Fri, 27 Aug 2021 20:21:08 +0000 (16:21 -0400)
This also introduces a script so we can reference the latest version in
the example pre-commit configuration in the docs without forgetting to
update it when doing a release!

Commit history before merge:

* document jupyter hook
* note minimum version
* add check for pre-commit version
* use git tag
* curl api during ci
* parse version from changes file
* fixup script
* rename variables
* Tweak the docs & magical script
* fix couple of typos
* pin additional dependencies in hook
* Add types-PyYAML to lockfile

Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
.pre-commit-config.yaml
Pipfile
Pipfile.lock
docs/faq.md
docs/integrations/source_version_control.md
scripts/__init__.py [new file with mode: 0644]
scripts/check_pre_commit_rev_in_example.py [new file with mode: 0644]
src/black/__init__.py

index 5ae418d9bddc3f768542a4053e5d7e7e61ec0656..b3cbe352e38f715a6621445d09094654e0e9f471 100644 (file)
@@ -12,6 +12,14 @@ repos:
         require_serial: true
         types_or: [python, pyi]
 
+      - id: check-pre-commit-rev-in-example
+        name: Check pre-commit rev in example
+        language: python
+        entry: python -m scripts.check_pre_commit_rev_in_example
+        files: '(CHANGES\.md|source_version_control\.md)$'
+        additional_dependencies:
+          ["commonmark==0.9.1", "pyyaml==5.4.1", "beautifulsoup4==4.9.3"]
+
   - repo: https://gitlab.com/pycqa/flake8
     rev: 3.9.2
     hooks:
@@ -25,6 +33,7 @@ repos:
         exclude: ^docs/conf.py
         additional_dependencies:
           - types-dataclasses >= 0.1.3
+          - types-PyYAML
           - tomli >= 0.2.6, < 2.0.0
           - types-typed-ast >= 1.4.1
           - click >= 8.0.0
diff --git a/Pipfile b/Pipfile
index 7f386c5381f74943c170058d3912a48987ddf04d..824beda16ccedac93c8736cfb46a1e2705506f41 100644 (file)
--- a/Pipfile
+++ b/Pipfile
@@ -21,6 +21,7 @@ flake8-bugbear = "*"
 mypy = ">=0.910"
 types-dataclasses = ">=0.1.3"
 types-typed-ast = ">=1.4.1"
+types-PyYAML = ">=5.4.1"
 
 # Documentation related requirements.
 Sphinx = ">=4.1.2"
index 6d62ec76680e8cea03bab4a0e77f6445fe593b36..30a4defcca35d48f82c91bbe80fd978343f6b65b 100644 (file)
@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "ac07cc9a5cb19ea72381baf4ba0db1689f475538d37e4be3119fc958a722b062"
+            "sha256": "ebf216584cfb2c962a1792d0682f3c08b44c7ae27305a03a54eacd6f42df27db"
         },
         "pipfile-spec": 6,
         "requires": {},
             "markers": "python_version >= '3.6'",
             "version": "==2.0.1"
         },
+        "matplotlib-inline": {
+            "hashes": [
+                "sha256:5cf1176f554abb4fa98cb362aa2b55c500147e4bdbb07e3fda359143e1da0811",
+                "sha256:f41d5ff73c9f5385775d5c0bc13b424535c8402fe70ea8210f93e11f3683993e"
+            ],
+            "markers": "python_version >= '3.5'",
+            "version": "==0.1.2"
+        },
         "mccabe": {
             "hashes": [
                 "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
                 "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
                 "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==2.4.7"
         },
         "pytest": {
                 "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926",
                 "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"
             ],
-            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==1.16.0"
         },
         "snowballstemmer": {
                 "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
                 "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
             ],
-            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2'",
+            "markers": "python_version >= '2.6' and python_version not in '3.0, 3.1, 3.2, 3.3'",
             "version": "==0.10.2"
         },
         "tomli": {
             "index": "pypi",
             "version": "==0.1.7"
         },
+        "types-pyyaml": {
+            "hashes": [
+                "sha256:745dcb4b1522423026bcc83abb9925fba747f1e8602d902f71a4058f9e7fb662",
+                "sha256:96f8d3d96aa1a18a465e8f6a220e02cff2f52632314845a364ecbacb0aea6e30"
+            ],
+            "index": "pypi",
+            "version": "==5.4.6"
+        },
         "types-typed-ast": {
             "hashes": [
                 "sha256:b7f561796b4d002c7522b0020f58b18f715bd28a31429d424a78e2e2dbbd6785",
index d7e6a16351fb2e901de0c28faea3f667d588c589..c361addf7ae2b21b69ef1860824c1e02e12f0887 100644 (file)
@@ -57,7 +57,7 @@ following will not be formatted:
   get_ipython().system('ls')
   ```
 
-- invalid syntax, as it can't be safely distinguished from automagics in the absense of
+- invalid syntax, as it can't be safely distinguished from automagics in the absence of
   a running `IPython` kernel.
 
 ## Why are Flake8's E203 and W503 violated?
index 1ca6161bf0bd128f2763cbb6babd71d3bb979a34..e1482487aa4afa6dd301206634bacb2eb2f610c5 100644 (file)
@@ -7,8 +7,21 @@ Use [pre-commit](https://pre-commit.com/). Once you
 ```yaml
 repos:
   - repo: https://github.com/psf/black
-    rev: stable # Replace by any tag/version: https://github.com/psf/black/tags
+    rev: 21.7b0
     hooks:
       - id: black
         language_version: python3 # Should be a command that runs python3.6+
 ```
+
+Feel free to switch out the `rev` value to something else, like another
+[tag/version][black-tags] or even a specific commit. Although we discourage the use of
+branches or other mutable refs since the hook [won't auto update as you may
+expect][pre-commit-mutable-rev].
+
+If you want support for Jupyter Notebooks as well, then replace `id: black` with
+`id: black-jupyter` (though note that it's only available from version `21.8b0`
+onwards).
+
+[black-tags]: https://github.com/psf/black/tags
+[pre-commit-mutable-rev]:
+  https://pre-commit.com/#using-the-latest-version-for-a-repository
diff --git a/scripts/__init__.py b/scripts/__init__.py
new file mode 100644 (file)
index 0000000..e69de29
diff --git a/scripts/check_pre_commit_rev_in_example.py b/scripts/check_pre_commit_rev_in_example.py
new file mode 100644 (file)
index 0000000..9560b3b
--- /dev/null
@@ -0,0 +1,54 @@
+"""
+Check that the rev value in the example pre-commit configuration matches
+the latest version of Black. This saves us from forgetting to update that
+during the release process.
+
+Why can't we just use `rev: stable` and call it a day? Well pre-commit
+won't auto update the hook as you may expect (and for good reasons, some
+technical and some pragmatic). Encouraging bad practice is also just
+not ideal. xref: https://github.com/psf/black/issues/420
+"""
+
+import os
+import sys
+
+import commonmark
+import yaml
+from bs4 import BeautifulSoup
+
+
+def main(changes: str, source_version_control: str) -> None:
+    changes_html = commonmark.commonmark(changes)
+    changes_soup = BeautifulSoup(changes_html, "html.parser")
+    headers = changes_soup.find_all("h2")
+    latest_tag, *_ = [
+        header.string for header in headers if header.string != "Unreleased"
+    ]
+
+    source_version_control_html = commonmark.commonmark(source_version_control)
+    source_version_control_soup = BeautifulSoup(
+        source_version_control_html, "html.parser"
+    )
+    pre_commit_repos = yaml.safe_load(
+        source_version_control_soup.find(class_="language-yaml").string
+    )["repos"]
+
+    for repo in pre_commit_repos:
+        pre_commit_rev = repo["rev"]
+        if not pre_commit_rev == latest_tag:
+            print(
+                "Please set the rev in ``source_version_control.md`` to be the latest "
+                f"one.\nExpected {latest_tag}, got {pre_commit_rev}.\n"
+            )
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    with open("CHANGES.md", encoding="utf-8") as fd:
+        changes = fd.read()
+    with open(
+        os.path.join("docs", "integrations", "source_version_control.md"),
+        encoding="utf-8",
+    ) as fd:
+        source_version_control = fd.read()
+    main(changes, source_version_control)
index 60f4fa34e9ddf28ad097be35704b2d3e3790f3a1..d033e01141aa9f4f77ba16559c0697e14d81b6a6 100644 (file)
@@ -977,7 +977,7 @@ def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> FileCon
     """Format Jupyter notebook.
 
     Operate cell-by-cell, only on code cells, only for Python notebooks.
-    If the ``.ipynb`` originally had a trailing newline, it'll be preseved.
+    If the ``.ipynb`` originally had a trailing newline, it'll be preserved.
     """
     trailing_newline = src_contents[-1] == "\n"
     modified = False