From 8b0680533420c2ea367860fcbb08df99317a6b44 Mon Sep 17 00:00:00 2001 From: Marco Edward Gorelli Date: Fri, 27 Aug 2021 21:21:08 +0100 Subject: [PATCH] Document jupyter hook (#2416) 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 | 9 ++++ Pipfile | 1 + Pipfile.lock | 24 +++++++-- docs/faq.md | 2 +- docs/integrations/source_version_control.md | 15 +++++- scripts/__init__.py | 0 scripts/check_pre_commit_rev_in_example.py | 54 +++++++++++++++++++++ src/black/__init__.py | 2 +- 8 files changed, 100 insertions(+), 7 deletions(-) create mode 100644 scripts/__init__.py create mode 100644 scripts/check_pre_commit_rev_in_example.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5ae418d..b3cbe35 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -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 7f386c5..824beda 100644 --- 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" diff --git a/Pipfile.lock b/Pipfile.lock index 6d62ec7..30a4def 100644 --- a/Pipfile.lock +++ b/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "ac07cc9a5cb19ea72381baf4ba0db1689f475538d37e4be3119fc958a722b062" + "sha256": "ebf216584cfb2c962a1792d0682f3c08b44c7ae27305a03a54eacd6f42df27db" }, "pipfile-spec": 6, "requires": {}, @@ -901,6 +901,14 @@ "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", @@ -1149,7 +1157,7 @@ "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": { @@ -1340,7 +1348,7 @@ "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": { @@ -1435,7 +1443,7 @@ "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": { @@ -1521,6 +1529,14 @@ "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", diff --git a/docs/faq.md b/docs/faq.md index d7e6a16..c361add 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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? diff --git a/docs/integrations/source_version_control.md b/docs/integrations/source_version_control.md index 1ca6161..e148248 100644 --- a/docs/integrations/source_version_control.md +++ b/docs/integrations/source_version_control.md @@ -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 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 index 0000000..9560b3b --- /dev/null +++ b/scripts/check_pre_commit_rev_in_example.py @@ -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) diff --git a/src/black/__init__.py b/src/black/__init__.py index 60f4fa3..d033e01 100644 --- a/src/black/__init__.py +++ b/src/black/__init__.py @@ -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 -- 2.39.2