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

Doc: Developer reference update (#3755)

Browse Source
This commit is contained in:
rdrll 2023-06-28 13:45:56 -07:00 committed by GitHub
parent 63481bb926
commit f01aaa63a0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 222 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGES.md
View File

@ -76,6 +76,9 @@
<!-- Major changes to documentation and policies. Small docs changes
don't need a changelog entry. -->
- Updated the _classes_ and _exceptions_ documentation in Developer reference to match
the latest ccode base. (#3755)
## 23.3.0
### Highlights

165
docs/contributing/reference/reference_classes.rst
View File

@ -3,6 +3,9 @@
*Contents are subject to change.*
Black Classes
~~~~~~~~~~~~~~
.. currentmodule:: black
:class:`BracketTracker`
@ -18,6 +21,12 @@
:members:
:special-members: __str__, __bool__
:class:`RHSResult`
-------------------------
.. autoclass:: black.lines.RHSResult
:members:
:class:`LinesBlock`
-------------------------
@ -43,6 +52,12 @@
.. autoclass:: black.comments.ProtoComment
:members:
:class:`Mode`
---------------------
.. autoclass:: black.mode.Mode
:members:
:class:`Report`
---------------
@ -50,6 +65,20 @@
:members:
:special-members: __str__
:class:`Ok`
---------------
.. autoclass:: black.rusty.Ok
:show-inheritance:
:members:
:class:`Err`
---------------
.. autoclass:: black.rusty.Err
:show-inheritance:
:members:
:class:`Visitor`
----------------
@ -57,20 +86,115 @@
:show-inheritance:
:members:
Enums
=====
:class:`StringTransformer`
----------------------------
.. autoclass:: black.trans.StringTransformer
:show-inheritance:
:members:
:class:`CustomSplit`
----------------------------
.. autoclass:: black.trans.CustomSplit
:members:
:class:`CustomSplitMapMixin`
-----------------------------
.. autoclass:: black.trans.CustomSplitMapMixin
:show-inheritance:
:members:
:class:`StringMerger`
----------------------
.. autoclass:: black.trans.StringMerger
:show-inheritance:
:members:
:class:`StringParenStripper`
-----------------------------
.. autoclass:: black.trans.StringParenStripper
:show-inheritance:
:members:
:class:`BaseStringSplitter`
-----------------------------
.. autoclass:: black.trans.BaseStringSplitter
:show-inheritance:
:members:
:class:`StringSplitter`
-----------------------------
.. autoclass:: black.trans.StringSplitter
:show-inheritance:
:members:
:class:`StringParenWrapper`
-----------------------------
.. autoclass:: black.trans.StringParenWrapper
:show-inheritance:
:members:
:class:`StringParser`
-----------------------------
.. autoclass:: black.trans.StringParser
:members:
:class:`DebugVisitor`
------------------------
.. autoclass:: black.debug.DebugVisitor
:show-inheritance:
:members:
:class:`Replacement`
------------------------
.. autoclass:: black.handle_ipynb_magics.Replacement
:members:
:class:`CellMagic`
------------------------
.. autoclass:: black.handle_ipynb_magics.CellMagic
:members:
:class:`CellMagicFinder`
------------------------
.. autoclass:: black.handle_ipynb_magics.CellMagicFinder
:show-inheritance:
:members:
:class:`OffsetAndMagic`
------------------------
.. autoclass:: black.handle_ipynb_magics.OffsetAndMagic
:members:
:class:`MagicFinder`
------------------------
.. autoclass:: black.handle_ipynb_magics.MagicFinder
:show-inheritance:
:members:
Enum Classes
~~~~~~~~~~~~~
Classes inherited from Python `Enum <https://docs.python.org/3/library/enum.html#enum.Enum>`_ class.
:class:`Changed`
----------------
.. autoclass:: black.Changed
:show-inheritance:
:members:
:class:`Mode`
-----------------
.. autoclass:: black.Mode
.. autoclass:: black.report.Changed
:show-inheritance:
:members:
@ -80,3 +204,24 @@ Enums
.. autoclass:: black.WriteBack
:show-inheritance:
:members:
:class:`TargetVersion`
----------------------
.. autoclass:: black.mode.TargetVersion
:show-inheritance:
:members:
:class:`Feature`
------------------
.. autoclass:: black.mode.Feature
:show-inheritance:
:members:
:class:`Preview`
------------------
.. autoclass:: black.mode.Preview
:show-inheritance:
:members:

10
docs/contributing/reference/reference_exceptions.rst
View File

@ -5,8 +5,14 @@
.. currentmodule:: black
.. autoexception:: black.trans.CannotTransform
.. autoexception:: black.linegen.CannotSplit
.. autoexception:: black.NothingChanged
.. autoexception:: black.brackets.BracketMatchError
.. autoexception:: black.InvalidInput
.. autoexception:: black.report.NothingChanged
.. autoexception:: black.parsing.InvalidInput
.. autoexception:: black.mode.Deprecated

7
docs/contributing/reference/reference_summary.rst
View File

@ -3,8 +3,11 @@ Developer reference
.. note::
The documentation here is quite outdated and has been neglected. Many objects worthy
of inclusion aren't documented. Contributions are appreciated!
As of June 2023, the documentation of *Black classes* and *Black exceptions*
has been updated to the latest available version.
The documentation of *Black functions* is quite outdated and has been neglected. Many
functions worthy of inclusion aren't documented. Contributions are appreciated!
*Contents are subject to change.*

3
src/black/handle_ipynb_magics.py
View File

@ -335,7 +335,8 @@ class CellMagicFinder(ast.NodeVisitor):
For example,
%%time\nfoo()
%%time\n
foo()
would have been transformed to

95
src/black/trans.py
View File

@ -205,11 +205,11 @@ def do_match(self, line: Line) -> TMatchResult:
"""
Returns:
* Ok(string_indices) such that for each index, `line.leaves[index]`
is our target string if a match was able to be made. For
transformers that don't result in more lines (e.g. StringMerger,
StringParenStripper), multiple matches and transforms are done at
once to reduce the complexity.
OR
is our target string if a match was able to be made. For
transformers that don't result in more lines (e.g. StringMerger,
StringParenStripper), multiple matches and transforms are done at
once to reduce the complexity.
OR
* Err(CannotTransform), if no match could be made.
"""
@ -220,12 +220,12 @@ def do_transform(
"""
Yields:
* Ok(new_line) where new_line is the new transformed line.
OR
OR
* Err(CannotTransform) if the transformation failed for some reason. The
`do_match(...)` template method should usually be used to reject
the form of the given Line, but in some cases it is difficult to
know whether or not a Line meets the StringTransformer's
requirements until the transformation is already midway.
`do_match(...)` template method should usually be used to reject
the form of the given Line, but in some cases it is difficult to
know whether or not a Line meets the StringTransformer's
requirements until the transformation is already midway.
Side Effects:
This method should NOT mutate @line directly, but it MAY mutate the
@ -335,8 +335,8 @@ def pop_custom_splits(self, string: str) -> List[CustomSplit]:
Returns:
* A list of the custom splits that are mapped to @string, if any
exist.
OR
exist.
OR
* [], otherwise.
Side Effects:
@ -365,14 +365,14 @@ class StringMerger(StringTransformer, CustomSplitMapMixin):
Requirements:
(A) The line contains adjacent strings such that ALL of the validation checks
listed in StringMerger._validate_msg(...)'s docstring pass.
OR
OR
(B) The line contains a string which uses line continuation backslashes.
Transformations:
Depending on which of the two requirements above where met, either:
(A) The string group associated with the target string is merged.
OR
OR
(B) All line-continuation backslashes are removed from the target string.
Collaborations:
@ -965,17 +965,20 @@ class BaseStringSplitter(StringTransformer):
Requirements:
* The target string value is responsible for the line going over the
line length limit. It follows that after all of black's other line
split methods have been exhausted, this line (or one of the resulting
lines after all line splits are performed) would still be over the
line_length limit unless we split this string.
AND
line length limit. It follows that after all of black's other line
split methods have been exhausted, this line (or one of the resulting
lines after all line splits are performed) would still be over the
line_length limit unless we split this string.
AND
* The target string is NOT a "pointless" string (i.e. a string that has
no parent or siblings).
AND
no parent or siblings).
AND
* The target string is not followed by an inline comment that appears
to be a pragma.
AND
to be a pragma.
AND
* The target string is not a multiline (i.e. triple-quote) string.
"""
@ -1027,7 +1030,7 @@ def _validate(self, line: Line, string_idx: int) -> TResult[None]:
Returns:
* Ok(None), if ALL of the requirements are met.
OR
OR
* Err(CannotTransform), if ANY of the requirements are NOT met.
"""
LL = line.leaves
@ -1299,9 +1302,9 @@ class StringSplitter(BaseStringSplitter, CustomSplitMapMixin):
Requirements:
* The line consists ONLY of a single string (possibly prefixed by a
string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
a trailing comma.
AND
string operator [e.g. '+' or '==']), MAYBE a string trailer, and MAYBE
a trailing comma.
AND
* All of the requirements listed in BaseStringSplitter's docstring.
Transformations:
@ -1808,26 +1811,26 @@ class StringParenWrapper(BaseStringSplitter, CustomSplitMapMixin):
addition to the requirements listed below:
* The line is a return/yield statement, which returns/yields a string.
OR
OR
* The line is part of a ternary expression (e.g. `x = y if cond else
z`) such that the line starts with `else <string>`, where <string> is
some string.
OR
z`) such that the line starts with `else <string>`, where <string> is
some string.
OR
* The line is an assert statement, which ends with a string.
OR
OR
* The line is an assignment statement (e.g. `x = <string>` or `x +=
<string>`) such that the variable is being assigned the value of some
string.
OR
<string>`) such that the variable is being assigned the value of some
string.
OR
* The line is a dictionary key assignment where some valid key is being
assigned the value of some string.
OR
assigned the value of some string.
OR
* The line is an lambda expression and the value is a string.
OR
OR
* The line starts with an "atom" string that prefers to be wrapped in
parens. It's preferred to be wrapped when it's is an immediate child of
a list/set/tuple literal, AND the string is surrounded by commas (or is
the first/last child).
parens. It's preferred to be wrapped when it's is an immediate child of
a list/set/tuple literal, AND the string is surrounded by commas (or is
the first/last child).
Transformations:
The chosen string is wrapped in parentheses and then split at the LPAR.
@ -2273,7 +2276,7 @@ def parse(self, leaves: List[Leaf], string_idx: int) -> int:
Returns:
The index directly after the last leaf which is apart of the string
trailer, if a "trailer" exists.
OR
OR
@string_idx + 1, if no string "trailer" exists.
"""
assert leaves[string_idx].type == token.STRING
@ -2287,11 +2290,11 @@ def _next_state(self, leaf: Leaf) -> bool:
"""
Pre-conditions:
* On the first call to this function, @leaf MUST be the leaf that
was directly after the string leaf in question (e.g. if our target
string is `line.leaves[i]` then the first call to this method must
be `line.leaves[i + 1]`).
was directly after the string leaf in question (e.g. if our target
string is `line.leaves[i]` then the first call to this method must
be `line.leaves[i + 1]`).
* On the next call to this function, the leaf parameter passed in
MUST be the leaf directly following @leaf.
MUST be the leaf directly following @leaf.
Returns:
True iff @leaf is apart of the string's trailer.