Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Formalise style preference description #2818

Merged
merged 2 commits into from Jan 29, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/the_black_code_style/current_style.md
Expand Up @@ -2,10 +2,14 @@

## Code style

_Black_ reformats entire files in place. Style configuration options are deliberately
limited and rarely added. It doesn't take previous formatting into account, except for
the magic trailing comma and preserving newlines. It doesn't reformat blocks that start
with `# fmt: off` and end with `# fmt: on`, or lines that ends with `# fmt: skip`.
_Black_ aims for consistency, generality, readability and reducing git diffs. Similar
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any other important aspects to add?

language constructs are formatted with similar rules. Style configuration options are
deliberately limited and rarely added. Previous formatting isn't taken into account,
except for the magic trailing comma and preserving newlines. The coding style used by
felix-hilden marked this conversation as resolved.
Show resolved Hide resolved
_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
[YAPF](https://github.com/google/yapf)'s block comments to the same effect, as a
courtesy for straddling code.
Expand All @@ -18,8 +22,7 @@ running `black --preview`.

_Black_ ignores previous formatting and applies uniform horizontal and vertical
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
strict subset of PEP 8.
whatever makes `pycodestyle` happy.

As for vertical whitespace, _Black_ tries to render one full expression or simple
statement per line. If this fits the allotted line length, great.
Expand Down
4 changes: 4 additions & 0 deletions docs/the_black_code_style/index.rst
Expand Up @@ -12,6 +12,10 @@ The Black Code Style
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
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.
felix-hilden marked this conversation as resolved.
Show resolved Hide resolved

Stability Policy
----------------
Expand Down