Skip to content

blacken_docs ¤

Callable for blacken-docs.

Functions:

  • run

    Run blacken-docs.

run ¤

run(
    *paths: str | Path,
    exts: Sequence[str] | None = None,
    exclude: Sequence[str | Pattern] | None = None,
    skip_errors: bool = False,
    rst_literal_blocks: bool = False,
    line_length: int | None = None,
    string_normalization: bool = True,
    is_pyi: bool = False,
    is_ipynb: bool = False,
    skip_source_first_line: bool = False,
    magic_trailing_comma: bool = True,
    python_cell_magics: set[str] | None = None,
    preview: bool = False,
    check_only: bool = False
) -> int

Run blacken-docs.

Parameters:

  • *paths (str | Path, default: () ) –

    Directories and files to format.

  • exts (Sequence[str] | None, default: None ) –

    List of extensions to select files with.

  • exclude (Sequence[str | Pattern] | None, default: None ) –

    List of regular expressions to exclude files.

  • skip_errors (bool, default: False ) –

    Don't exit non-zero for errors from Black (normally syntax errors).

  • rst_literal_blocks (bool, default: False ) –

    Also format literal blocks in reStructuredText files (more below).

  • line_length (int | None, default: None ) –

    How many characters per line to allow.

  • string_normalization (bool, default: True ) –

    Normalize string quotes or prefixes.

  • is_pyi (bool, default: False ) –

    Format all input files like typing stubs regardless of file extension.

  • is_ipynb (bool, default: False ) –

    Format all input files like Jupyter Notebooks regardless of file extension.

  • skip_source_first_line (bool, default: False ) –

    Skip the first line of the source code.

  • magic_trailing_comma (bool, default: True ) –

    Use trailing commas as a reason to split lines.

  • python_cell_magics (set[str] | None, default: None ) –

    When processing Jupyter Notebooks, add the given magic to the list of known python-magics (capture, prun, pypy, python, python3, time, timeit). Useful for formatting cells with custom python magics.

  • preview (bool, default: False ) –

    Enable potentially disruptive style changes that may be added to Black's main functionality in the next major release.

  • check_only (bool, default: False ) –

    Don't modify files but indicate when changes are necessary with a message and non-zero return code.

Returns:

  • int

    Success/failure.

Source code in src/duty/callables/blacken_docs.py
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@lazy(name="blacken_docs")
def run(
    *paths: str | Path,
    exts: Sequence[str] | None = None,
    exclude: Sequence[str | Pattern] | None = None,
    skip_errors: bool = False,
    rst_literal_blocks: bool = False,
    line_length: int | None = None,
    string_normalization: bool = True,
    is_pyi: bool = False,
    is_ipynb: bool = False,
    skip_source_first_line: bool = False,
    magic_trailing_comma: bool = True,
    python_cell_magics: set[str] | None = None,
    preview: bool = False,
    check_only: bool = False,
) -> int:
    """Run `blacken-docs`.

    Parameters:
        *paths: Directories and files to format.
        exts: List of extensions to select files with.
        exclude: List of regular expressions to exclude files.
        skip_errors: Don't exit non-zero for errors from Black (normally syntax errors).
        rst_literal_blocks: Also format literal blocks in reStructuredText files (more below).
        line_length: How many characters per line to allow.
        string_normalization: Normalize string quotes or prefixes.
        is_pyi: Format all input files like typing stubs regardless of file extension.
        is_ipynb: Format all input files like Jupyter Notebooks regardless of file extension.
        skip_source_first_line: Skip the first line of the source code.
        magic_trailing_comma: Use trailing commas as a reason to split lines.
        python_cell_magics: When processing Jupyter Notebooks, add the given magic to the list
            of known python-magics (capture, prun, pypy, python, python3, time, timeit).
            Useful for formatting cells with custom python magics.
        preview: Enable potentially disruptive style changes that may be added
            to Black's main functionality in the next major release.
        check_only: Don't modify files but indicate when changes are necessary
            with a message and non-zero return code.

    Returns:
        Success/failure.
    """
    import black
    from blacken_docs import format_file

    exts = ("md", "py") if exts is None else tuple(ext.lstrip(".") for ext in exts)
    if exclude:
        exclude = tuple(re.compile(regex, re.I) if isinstance(regex, str) else regex for regex in exclude)
    filepaths = set()
    for path in paths:
        path = Path(path)  # noqa: PLW2901
        if path.is_file():
            filepaths.add(path.as_posix())
        else:
            for ext in exts:
                filepaths |= {filepath.as_posix() for filepath in path.rglob(f"*.{ext}")}

    black_mode = black.Mode(
        line_length=line_length or black.DEFAULT_LINE_LENGTH,
        string_normalization=string_normalization,
        is_pyi=is_pyi,
        is_ipynb=is_ipynb,
        skip_source_first_line=skip_source_first_line,
        magic_trailing_comma=magic_trailing_comma,
        python_cell_magics=python_cell_magics or set(),
        preview=preview,
    )
    retv = 0
    for filepath in sorted(filepaths):
        retv |= format_file(
            filepath,
            black_mode,
            skip_errors=skip_errors,
            rst_literal_blocks=rst_literal_blocks,
            check_only=check_only,
        )
    return retv