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
`pyproject.toml` file (more on that below).
#### `-h`, `--help`
Show available command-line options and exit.
#### `-c`, `--code`
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-
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`
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`
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 1 if some files would be reformatted; or
@ -162,8 +170,8 @@ $ echo $?
#### `--diff`
Passing `--diff` will make _Black_ print out diffs that indicate what changes _Black_
would've made. They are printed to stdout so capturing them is simple.
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.
If you'd like colored diffs, you can enable them with `--color`.
@ -179,6 +187,10 @@ All done! ✨ 🍰 ✨
1 file would be reformatted.
```
#### `--color` / `--no-color`
Show (or do not show) colored diff. Only applies when `--diff` is given.
### `--line-ranges`
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.
```
#### `--color` / `--no-color`
Show (or do not show) colored diff. Only applies when `--diff` is given.
#### `--fast` / `--safe`
By default, _Black_ performs [an AST safety check](labels/ast-changes) after formatting
@ -256,7 +264,7 @@ instead of overriding them.
#### `--force-exclude`
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.
#### `--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.
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`
Passing `-q` / `--quiet` will cause _Black_ to stop emitting all non-critical output.
Error messages will still be emitted (which can silenced by `2>/dev/null`).
Stop emitting all non-critical output. Error messages will still be emitted (which can
silenced by `2>/dev/null`).
```console
$ black src/ -q
@ -289,9 +297,9 @@ error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
#### `-v`, `--verbose`
Passing `-v` / `--verbose` will cause _Black_ to also emit messages about files that
were not changed or were ignored due to exclusion patterns. If _Black_ is using a
configuration file, a blue message detailing which one it is using will be emitted.
Emit messages about files that were not changed or were ignored due to exclusion
patterns. If _Black_ is using a configuration file, a message detailing which one it is
using will be emitted.
```console
$ black src/ -v
@ -321,10 +329,6 @@ black, 23.11.0
Read configuration options from a configuration file. See
[below](#configuration-via-a-file) for more details on the configuration file.
#### `-h`, `--help`
Show available command-line options and exit.
### Environment variable options
_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`
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
@ -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
`--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
used.
If you're running with `--verbose`, you will see a message if a file was found and used.
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,
multiple=True,
help=(
"Python versions that should be supported by Black's output. By default, Black"
" will try to infer this from the project metadata in pyproject.toml. If this"
" does not yield conclusive results, Black will use per-file auto-detection."
"Python versions that should be supported by Black's output. You should"
" include all versions that your code supports. By default, Black will infer"
" 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(
"--pyi",
is_flag=True,
help=(
"Format all input files like typing stubs regardless of file extension (useful"
" when piping source on standard input)."
"Format all input files like typing stubs regardless of file extension. This"
" is useful when piping source on standard input."
),
)
@click.option(
"--ipynb",
is_flag=True,
help=(
"Format all input files like Jupyter Notebooks regardless of file extension "
"(useful when piping source on standard input)."
"Format all input files like Jupyter Notebooks regardless of file extension."
"This is useful when piping source on standard input."
),
)
@click.option(
@ -310,14 +311,22 @@ def validate_regex(
@click.option(
"--diff",
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(
"--line-ranges",
multiple=True,
metavar="START-END",
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"
" formatted. Each range must be specified as two integers connected by a `-`:"
" `<START>-<END>`. The `<START>` and `<END>` integer indices are 1-based and"
@ -325,23 +334,24 @@ def validate_regex(
),
default=(),
)
@click.option(
"--color/--no-color",
is_flag=True,
help="Show colored diff. Only applies when `--diff` is given.",
)
@click.option(
"--fast/--safe",
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(
"--required-version",
type=str,
help=(
"Require a specific version of Black to be running (useful for unifying results"
" across many environments e.g. with a pyproject.toml file). It can be"
" either a major version number or an exact version."
"Require a specific version of Black to be running. This is useful for"
" ensuring that all contributors to your project are using the same"
" 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(
@ -371,8 +381,10 @@ def validate_regex(
type=str,
callback=validate_regex,
help=(
"Like --exclude, but files and directories matching this regex will be "
"excluded even when they are passed explicitly as arguments."
"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 programmatically on changed files, such as in a pre-commit"
" hook or editor plugin."
),
)
@click.option(
@ -380,9 +392,9 @@ def validate_regex(
type=str,
is_eager=True,
help=(
"The name of the file when passing it through stdin. Useful to make "
"sure Black will respect --force-exclude option on some "
"editors that rely on using stdin."
"The name of the file when passing it through stdin. Useful to make sure Black"
" will respect the --force-exclude option on some editors that rely on using"
" stdin."
),
)
@click.option(
@ -405,8 +417,10 @@ def validate_regex(
type=click.IntRange(min=1),
default=None,
help=(
"Number of parallel workers [default: BLACK_NUM_WORKERS environment variable "
"or number of CPUs in the system]"
"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 BLACK_NUM_WORKERS environment variable. Defaults"
" to the number of CPUs in the system."
),
)
@click.option(
@ -414,8 +428,8 @@ def validate_regex(
"--quiet",
is_flag=True,
help=(
"Don't emit non-error messages to stderr. Errors are still emitted; silence"
" those with 2>/dev/null."
"Stop emitting all non-critical output. Error messages will still be emitted"
" (which can silenced by 2>/dev/null)."
),
)
@click.option(
@ -423,8 +437,9 @@ def validate_regex(
"--verbose",
is_flag=True,
help=(
"Also emit messages to stderr about files that were not changed or were ignored"
" due to exclusion patterns."
"Emit messages about files that were not changed or were ignored due to"
" exclusion patterns. If Black is using a configuration file, a message"
" detailing which one it is using will be emitted."
),
)
@click.version_option(
@ -455,7 +470,7 @@ def validate_regex(
),
is_eager=True,
callback=read_pyproject_toml,
help="Read configuration from FILE path.",
help="Read configuration options from a configuration file.",
)
@click.pass_context
def main( # noqa: C901