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

Formalise style preference description (#2818)

Browse Source 
Closes #1256: I reworded our style docs to be more explicit about the style we're aiming for and how it is changed (or isn't).
This commit is contained in:
Felix Hildén 2022-01-29 02:49:43 +02:00 committed by GitHub
parent 4ce049dbfa
commit df0aeeeee0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 13 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
docs/the_black_code_style/current_style.md
View File

@ -2,10 +2,14 @@
## Code style ## Code style
_Black_ reformats entire files in place. Style configuration options are deliberately _Black_ aims for consistency, generality, readability and reducing git diffs. Similar
limited and rarely added. It doesn't take previous formatting into account, except for language constructs are formatted with similar rules. Style configuration options are
the magic trailing comma and preserving newlines. It doesn't reformat blocks that start deliberately limited and rarely added. Previous formatting is taken into account as
with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`. little as possible, with rare exceptions like the magic trailing comma. The coding style
used by _Black_ can be viewed as a strict subset of PEP 8.
_Black_ reformats entire files in place. It doesn't reformat blocks that start with
`# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
`# fmt: on/off` have to be on the same level of indentation. It also recognizes `# fmt: on/off` have to be on the same level of indentation. It also recognizes
[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a [YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
courtesy for straddling code. courtesy for straddling code.
@ -18,8 +22,7 @@ running `black --preview`.
_Black_ ignores previous formatting and applies uniform horizontal and vertical _Black_ ignores previous formatting and applies uniform horizontal and vertical
whitespace to your code. The rules for horizontal whitespace can be summarized as: do whitespace to your code. The rules for horizontal whitespace can be summarized as: do
whatever makes `pycodestyle` happy. The coding style used by _Black_ can be viewed as a whatever makes `pycodestyle` happy.
strict subset of PEP 8.
As for vertical whitespace, _Black_ tries to render one full expression or simple As for vertical whitespace, _Black_ tries to render one full expression or simple
statement per line. If this fits the allotted line length, great. statement per line. If this fits the allotted line length, great.

4
docs/the_black_code_style/index.rst
View File

@ -12,6 +12,10 @@ The Black Code Style
While keeping the style unchanged throughout releases has always been a goal, While keeping the style unchanged throughout releases has always been a goal,
the *Black* code style isn't set in stone. It evolves to accommodate for new features the *Black* code style isn't set in stone. It evolves to accommodate for new features
in the Python language and, occasionally, in response to user feedback. in the Python language and, occasionally, in response to user feedback.
Large-scale style preferences presented in :doc:`current_style` are very unlikely to
change, but minor style aspects and details might change according to the stability
policy presented below. Ongoing style considerations are tracked on GitHub with the
`design <https://github.com/psf/black/labels/T%3A%20design>`_ issue label.
Stability Policy Stability Policy
---------------- ----------------