Merge pull request #434 from akaihola/doc-pre-commit-black-version

CHANGES.rst

@@ -8,6 +8,7 @@ Added
 - Declare Python 3.11 as supported in package metadata.
 - Document how to set up a development environment, run tests, run linters and update
  contributors list in ``CONTRIBUTING.rst``.
+- Document how to pin reformatter/linter versions in ``pre-commit``.
 
 Fixed
 -----

README.rst

@@ -571,18 +571,45 @@ do the following:
 
  pre-commit sample-config >.pre-commit-config.yaml
 
-3. Append to the created ``.pre-commit-config.yaml`` the following lines::
+3. Append to the created ``.pre-commit-config.yaml`` the following lines:
 
- - repo: https:/akaihola/darker
- rev: 1.6.0
- hooks:
- - id: darker
+ .. code-block:: yaml
+
+ - repo: https:/akaihola/darker
+ rev: 1.6.0
+ hooks:
+ - id: darker
 
 4. install the Git hook scripts and update to the newest version::
 
  pre-commit install
  pre-commit autoupdate
 
+When auto-updating, care is being taken to protect you from possible incompatibilities
+introduced by Black updates. See `Guarding against Black compatibility breakage`_ for
+more information.
+
+If you'd prefer to not update but keep a stable pre-commit setup, you can pin Black and
+other reformatter/linter tools you use to known compatible versions, for example:
+
+.. code-block:: yaml
+
+ - repo: https:/akaihola/darker
+ rev: 1.6.0
+ hooks:
+ - id: darker
+ args:
+ - --isort
+ - --lint mypy
+ - --lint flake8
+ - --lint pylint
+ additional_dependencies:
+ - black==22.12.0
+ - isort==5.11.4
+ - mypy==0.990
+ - flake8==5.0.4
+ - pylint==2.15.5
+
 .. _pre-commit: https://pre-commit.com/
 .. _pre-commit Installation: https://pre-commit.com/#installation
 
@@ -591,15 +618,17 @@ Using arguments
 ---------------
 
 You can provide arguments, such as enabling isort, by specifying ``args``.
-Note the inclusion of the isort Python package under ``additional_dependencies``::
-
- - repo: https:/akaihola/darker
- rev: 1.6.0
- hooks:
- - id: darker
- args: [--isort]
- additional_dependencies:
- - isort~=5.9
+Note the inclusion of the isort Python package under ``additional_dependencies``:
+
+.. code-block:: yaml
+
+ - repo: https:/akaihola/darker
+ rev: 1.6.0
+ hooks:
+ - id: darker
+ args: [--isort]
+ additional_dependencies:
+ - isort~=5.9
 
 
 GitHub Actions integration

release_tools/bump_version.py

@@ -22,7 +22,7 @@
 import sys
 from datetime import date
 from pathlib import Path
-from typing import Dict, Match, Optional, Tuple
+from typing import Dict, List, Match, Optional, Tuple
 from warnings import warn
 
 import click
@@ -78,8 +78,7 @@
  "README.rst": {
  r"^ pip install --upgrade darker~={old_version->new_version}",
  r"^ conda install -c conda-forge darker~={old_version->new_version} isort",
- r"^ rev: {old_version->new_version}",
- r"^ rev: {old_version->new_version}",
+ r"^ (?: )?rev: {old_version->new_version}",
  r"^ - uses: akaihola/darker@{old_version->new_version}",
  r'^ version: "~={old_version->new_version}"',
  r"label=release%20{any_version->next_version}",
@@ -127,8 +126,8 @@ def bump_version( # pylint: disable=too-many-locals
  template_match, patterns, replacements
  )
  # example: current_pattern == "14", replacement == "15"
- pattern = replace_span(
- template_match.span(), f"({current_pattern})", pattern_template
+ pattern = replace_spans(
+ [template_match.span()], f"({current_pattern})", pattern_template
  )
  # example: pattern = r"darker/(14)"
  content = replace_group_1(pattern, replacement, content, path=path_str)
@@ -369,19 +368,26 @@ def get_next_milestone_version(
  return Version(f"{version.major}.{version.minor}.{version.micro + 1}")
 
 
-def replace_span(span: Tuple[int, int], replacement: str, content: str) -> str:
- """Replace given span in a string with the desired replacement string
+def replace_spans(spans: List[Tuple[int, int]], replacement: str, content: str) -> str:
+ """Replace given spans in a string with the desired replacement string
 
- :param span: The span to replace
+ :param spans: The spans to replace
  :param replacement: The string to use as the replacement
  :param content: The content to replace the span in
  :return: The result after the replacement
 
+ >>> replace_spans([(2, 4), (6, 8)], "BAR", "__FU__FU__")
+ '__BAR__BAR__'
+
  """
- start, end = span
- before = content[:start]
- after = content[end:]
- return f"{before}{replacement}{after}"
+ parts = []
+ for (_, end1), (start2, end2) in zip(
+ [(..., 0)] + spans, spans + [(len(content), ...)]
+ ):
+ parts.append(content[end1:start2])
+ if end2 is not ...:
+ parts.append(replacement)
+ return "".join(parts)
 
 
 def replace_group_1(pattern: str, replacement: str, content: str, path: str) -> str:
@@ -398,10 +404,10 @@ def replace_group_1(pattern: str, replacement: str, content: str, path: str) ->
  :return: The resulting content after the replacement
 
  """
- match = re.search(pattern, content, flags=re.MULTILINE)
- if not match:
+ matches = re.finditer(pattern, content, flags=re.MULTILINE)
+ if not matches:
  raise NoMatch(f"Can't find `{pattern}` in `{path}`")
- return replace_span(match.span(1), replacement, content)
+ return replace_spans([match.span(1) for match in matches], replacement, content)
 
 
 def patch_changelog(next_version: Version, dry_run: bool) -> None: