actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Unify option descriptions between --help and the_basics.md (#4076)

Browse Source
This commit is contained in:
cobalt 2023-12-07 11:32:06 -06:00 committed by GitHub
parent 50e287cece
commit 432d9050c3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 69 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/usage_and_configuration/the_basics.md
View File

@ -35,6 +35,10 @@ are deliberately limited and rarely added.
Note that all command-line options listed above can also be configured using a Note that all command-line options listed above can also be configured using a
`pyproject.toml` file (more on that below). `pyproject.toml` file (more on that below).
#### `-h`, `--help`
Show available command-line options and exit.
#### `-c`, `--code` #### `-c`, `--code`
Format the code passed in as a string. Format the code passed in as a string.
@ -109,6 +113,10 @@ useful when piping source on standard input.
When processing Jupyter Notebooks, add the given magic to the list of known python- When processing Jupyter Notebooks, add the given magic to the list of known python-
magics. Useful for formatting cells with custom python magics. magics. Useful for formatting cells with custom python magics.
#### `-x, --skip-source-first-line`
Skip the first line of the source code.
#### `-S, --skip-string-normalization` #### `-S, --skip-string-normalization`
By default, _Black_ uses double quotes for all strings and normalizes string prefixes, By default, _Black_ uses double quotes for all strings and normalizes string prefixes,
@ -132,7 +140,7 @@ functionality in the next major release. Read more about
#### `--check` #### `--check`
Passing `--check` will make _Black_ exit with: Don't write the files back, just return the status. _Black_ will exit with:
- code 0 if nothing would change; - code 0 if nothing would change;
- code 1 if some files would be reformatted; or - code 1 if some files would be reformatted; or
@ -162,8 +170,8 @@ $ echo $?
#### `--diff` #### `--diff`
Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_ Don't write the files back, just output a diff to indicate what changes _Black_ would've
would've made. They are printed to stdout so capturing them is simple. made. They are printed to stdout so capturing them is simple.
If you'd like colored diffs, you can enable them with `--color`. If you'd like colored diffs, you can enable them with `--color`.
@ -179,6 +187,10 @@ All done! ✨ 🍰 ✨
1 file would be reformatted. 1 file would be reformatted.
``` ```
#### `--color` / `--no-color`
Show (or do not show) colored diff. Only applies when `--diff` is given.
### `--line-ranges` ### `--line-ranges`
When specified, _Black_ will try its best to only format these lines. When specified, _Black_ will try its best to only format these lines.
@ -202,10 +214,6 @@ extra lines outside of the ranges when ther are unformatted lines with the exact
content. It also disables _Black_'s formatting stability check in `--safe` mode. content. It also disables _Black_'s formatting stability check in `--safe` mode.
``` ```
#### `--color` / `--no-color`
Show (or do not show) colored diff. Only applies when `--diff` is given.
#### `--fast` / `--safe` #### `--fast` / `--safe`
By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
@ -256,7 +264,7 @@ instead of overriding them.
#### `--force-exclude` #### `--force-exclude`
Like `--exclude`, but files and directories matching this regex will be excluded even Like `--exclude`, but files and directories matching this regex will be excluded even
when they are passed explicitly as arguments. This is useful when invoking _Black_ when they are passed explicitly as arguments. This is useful when invoking Black
programmatically on changed files, such as in a pre-commit hook or editor plugin. programmatically on changed files, such as in a pre-commit hook or editor plugin.
#### `--stdin-filename` #### `--stdin-filename`
@ -275,12 +283,12 @@ exclusions, including from `.gitignore` and command line options.
When _Black_ formats multiple files, it may use a process pool to speed up formatting. When _Black_ formats multiple files, it may use a process pool to speed up formatting.
This option controls the number of parallel workers. This can also be specified via the This option controls the number of parallel workers. This can also be specified via the
`BLACK_NUM_WORKERS` environment variable. `BLACK_NUM_WORKERS` environment variable. Defaults to the number of CPUs in the system.
#### `-q`, `--quiet` #### `-q`, `--quiet`
Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output. Stop emitting all non-critical output. Error messages will still be emitted (which can
Error messages will still be emitted (which can silenced by `2>/dev/null`). silenced by `2>/dev/null`).
```console ```console
$ black src/ -q $ black src/ -q
@ -289,9 +297,9 @@ error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
#### `-v`, `--verbose` #### `-v`, `--verbose`
Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that Emit messages about files that were not changed or were ignored due to exclusion
were not changed or were ignored due to exclusion patterns. If _Black_ is using a patterns. If _Black_ is using a configuration file, a message detailing which one it is
configuration file, a blue message detailing which one it is using will be emitted. using will be emitted.
```console ```console
$ black src/ -v $ black src/ -v
@ -321,10 +329,6 @@ black, 23.11.0
Read configuration options from a configuration file. See Read configuration options from a configuration file. See
[below](#configuration-via-a-file) for more details on the configuration file. [below](#configuration-via-a-file) for more details on the configuration file.
#### `-h`, `--help`
Show available command-line options and exit.
### Environment variable options ### Environment variable options
_Black_ supports the following configuration via environment variables. _Black_ supports the following configuration via environment variables.
@ -355,7 +359,7 @@ All done! ✨ 🍰 ✨
use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude` use `--stdin-filename`. Useful to make sure _Black_ will respect the `--force-exclude`
option on some editors that rely on using stdin. option on some editors that rely on using stdin.
You can also pass code as a string using the `-c` / `--code` option. You can also pass code as a string using the `--code` option.
### Writeback and reporting ### Writeback and reporting
@ -435,8 +439,7 @@ refers to the path to your home directory. On Windows, this will be something li
You can also explicitly specify the path to a particular file that you want with You can also explicitly specify the path to a particular file that you want with
`--config`. In this situation _Black_ will not look for any other file. `--config`. In this situation _Black_ will not look for any other file.
If you're running with `--verbose`, you will see a blue message if a file was found and If you're running with `--verbose`, you will see a message if a file was found and used.
used.
Please note `blackd` will not use `pyproject.toml` configuration. Please note `blackd` will not use `pyproject.toml` configuration.

75
src/black/__init__.py
View File

@ -235,25 +235,26 @@ def validate_regex(
callback=target_version_option_callback, callback=target_version_option_callback,
multiple=True, multiple=True,
help=( help=(
"Python versions that should be supported by Black's output. By default, Black" "Python versions that should be supported by Black's output. You should"
" will try to infer this from the project metadata in pyproject.toml. If this" " include all versions that your code supports. By default, Black will infer"
" does not yield conclusive results, Black will use per-file auto-detection." " target versions from the project metadata in pyproject.toml. If this does"
" not yield conclusive results, Black will use per-file auto-detection."
), ),
) )
@click.option( @click.option(
"--pyi", "--pyi",
is_flag=True, is_flag=True,
help=( help=(
"Format all input files like typing stubs regardless of file extension (useful" "Format all input files like typing stubs regardless of file extension. This"
" when piping source on standard input)." " is useful when piping source on standard input."
), ),
) )
@click.option( @click.option(
"--ipynb", "--ipynb",
is_flag=True, is_flag=True,
help=( help=(
"Format all input files like Jupyter Notebooks regardless of file extension " "Format all input files like Jupyter Notebooks regardless of file extension."
"(useful when piping source on standard input)." "This is useful when piping source on standard input."
), ),
) )
@click.option( @click.option(
@ -310,14 +311,22 @@ def validate_regex(
@click.option( @click.option(
"--diff", "--diff",
is_flag=True, is_flag=True,
help="Don't write the files back, just output a diff for each file on stdout.", help=(
"Don't write the files back, just output a diff to indicate what changes"
" Black would've made. They are printed to stdout so capturing them is simple."
),
)
@click.option(
"--color/--no-color",
is_flag=True,
help="Show (or do not show) colored diff. Only applies when --diff is given.",
) )
@click.option( @click.option(
"--line-ranges", "--line-ranges",
multiple=True, multiple=True,
metavar="START-END", metavar="START-END",
help=( help=(
"When specified, _Black_ will try its best to only format these lines. This" "When specified, Black will try its best to only format these lines. This"
" option can be specified multiple times, and a union of the lines will be" " option can be specified multiple times, and a union of the lines will be"
" formatted. Each range must be specified as two integers connected by a `-`:" " formatted. Each range must be specified as two integers connected by a `-`:"
" `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and" " `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and"
@ -325,23 +334,24 @@ def validate_regex(
), ),
default=(), default=(),
) )
@click.option(
"--color/--no-color",
is_flag=True,
help="Show colored diff. Only applies when `--diff` is given.",
)
@click.option( @click.option(
"--fast/--safe", "--fast/--safe",
is_flag=True, is_flag=True,
help="If --fast given, skip temporary sanity checks. [default: --safe]", help=(
"By default, Black performs an AST safety check after formatting your code."
" The --fast flag turns off this check and the --safe flag explicitly enables"
" it. [default: --safe]"
),
) )
@click.option( @click.option(
"--required-version", "--required-version",
type=str, type=str,
help=( help=(
"Require a specific version of Black to be running (useful for unifying results" "Require a specific version of Black to be running. This is useful for"
" across many environments e.g. with a pyproject.toml file). It can be" " ensuring that all contributors to your project are using the same"
" either a major version number or an exact version." " version, because different versions of Black may format code a little"
" differently. This option can be set in a configuration file for consistent"
" results across environments."
), ),
) )
@click.option( @click.option(
@ -371,8 +381,10 @@ def validate_regex(
type=str, type=str,
callback=validate_regex, callback=validate_regex,
help=( help=(
"Like --exclude, but files and directories matching this regex will be " "Like --exclude, but files and directories matching this regex will be excluded"
"excluded even when they are passed explicitly as arguments." " even when they are passed explicitly as arguments. This is useful when"
" invoking Black programmatically on changed files, such as in a pre-commit"
" hook or editor plugin."
), ),
) )
@click.option( @click.option(
@ -380,9 +392,9 @@ def validate_regex(
type=str, type=str,
is_eager=True, is_eager=True,
help=( help=(
"The name of the file when passing it through stdin. Useful to make " "The name of the file when passing it through stdin. Useful to make sure Black"
"sure Black will respect --force-exclude option on some " " will respect the --force-exclude option on some editors that rely on using"
"editors that rely on using stdin." " stdin."
), ),
) )
@click.option( @click.option(
@ -405,8 +417,10 @@ def validate_regex(
type=click.IntRange(min=1), type=click.IntRange(min=1),
default=None, default=None,
help=( help=(
"Number of parallel workers [default: BLACK_NUM_WORKERS environment variable " "When Black formats multiple files, it may use a process pool to speed up"
"or number of CPUs in the system]" " formatting. This option controls the number of parallel workers. This can"
" also be specified via the BLACK_NUM_WORKERS environment variable. Defaults"
" to the number of CPUs in the system."
), ),
) )
@click.option( @click.option(
@ -414,8 +428,8 @@ def validate_regex(
"--quiet", "--quiet",
is_flag=True, is_flag=True,
help=( help=(
"Don't emit non-error messages to stderr. Errors are still emitted; silence" "Stop emitting all non-critical output. Error messages will still be emitted"
" those with 2>/dev/null." " (which can silenced by 2>/dev/null)."
), ),
) )
@click.option( @click.option(
@ -423,8 +437,9 @@ def validate_regex(
"--verbose", "--verbose",
is_flag=True, is_flag=True,
help=( help=(
"Also emit messages to stderr about files that were not changed or were ignored" "Emit messages about files that were not changed or were ignored due to"
" due to exclusion patterns." " exclusion patterns. If Black is using a configuration file, a message"
" detailing which one it is using will be emitted."
), ),
) )
@click.version_option( @click.version_option(
@ -455,7 +470,7 @@ def validate_regex(
), ),
is_eager=True, is_eager=True,
callback=read_pyproject_toml, callback=read_pyproject_toml,
help="Read configuration from FILE path.", help="Read configuration options from a configuration file.",
) )
@click.pass_context @click.pass_context
def main( # noqa: C901 def main( # noqa: C901