From f01aaa63a0ff792b932205cbb539f70aca769d7d Mon Sep 17 00:00:00 2001 From: rdrll <13176405+rdrll@users.noreply.github.com> Date: Wed, 28 Jun 2023 13:45:56 -0700 Subject: [PATCH] Doc: Developer reference update (#3755) --- CHANGES.md | 3 + .../reference/reference_classes.rst | 161 +++++++++++++++++- .../reference/reference_exceptions.rst | 10 +- .../reference/reference_summary.rst | 7 +- src/black/handle_ipynb_magics.py | 3 +- src/black/trans.py | 95 ++++++----- 6 files changed, 220 insertions(+), 59 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 2dfed8a..ba7947a 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -76,6 +76,9 @@ +- Updated the _classes_ and _exceptions_ documentation in Developer reference to match + the latest ccode base. (#3755) + ## 23.3.0 ### Highlights diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst index 3931e0e..29b2500 100644 --- a/docs/contributing/reference/reference_classes.rst +++ b/docs/contributing/reference/reference_classes.rst @@ -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` +---------------------------- -:class:`Changed` ----------------- +.. autoclass:: black.trans.StringTransformer + :show-inheritance: + :members: -.. autoclass:: black.Changed +:class:`CustomSplit` +---------------------------- + +.. autoclass:: black.trans.CustomSplit + :members: + +:class:`CustomSplitMapMixin` +----------------------------- + +.. autoclass:: black.trans.CustomSplitMapMixin :show-inheritance: :members: -:class:`Mode` ------------------ +:class:`StringMerger` +---------------------- -.. autoclass:: black.Mode +.. 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 `_ class. + +:class:`Changed` +---------------- + +.. 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: diff --git a/docs/contributing/reference/reference_exceptions.rst b/docs/contributing/reference/reference_exceptions.rst index aafe61e..ab46ebd 100644 --- a/docs/contributing/reference/reference_exceptions.rst +++ b/docs/contributing/reference/reference_exceptions.rst @@ -5,8 +5,14 @@ .. currentmodule:: black +.. autoexception:: black.trans.CannotTransform + .. autoexception:: black.linegen.CannotSplit -.. autoexception:: black.NothingChanged +.. autoexception:: black.brackets.BracketMatchError + +.. autoexception:: black.report.NothingChanged + +.. autoexception:: black.parsing.InvalidInput -.. autoexception:: black.InvalidInput +.. autoexception:: black.mode.Deprecated diff --git a/docs/contributing/reference/reference_summary.rst b/docs/contributing/reference/reference_summary.rst index f6ff468..c6163d8 100644 --- a/docs/contributing/reference/reference_summary.rst +++ b/docs/contributing/reference/reference_summary.rst @@ -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.* diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py index 2b6b920..4324819 100644 --- a/src/black/handle_ipynb_magics.py +++ b/src/black/handle_ipynb_magics.py @@ -335,7 +335,8 @@ class CellMagicFinder(ast.NodeVisitor): For example, - %%time\nfoo() + %%time\n + foo() would have been transformed to diff --git a/src/black/trans.py b/src/black/trans.py index 1e28ed0..4d40cb4 100644 --- a/src/black/trans.py +++ b/src/black/trans.py @@ -205,11 +205,11 @@ class StringTransformer(ABC): """ 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 @@ class StringTransformer(ABC): """ 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 @@ class CustomSplitMapMixin: 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 @@ class BaseStringSplitter(StringTransformer): 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 `, where is - some string. - OR + z`) such that the line starts with `else `, where 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 = ` or `x += - `) such that the variable is being assigned the value of some - string. - OR + `) 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 @@ class StringParser: 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 @@ class StringParser: """ 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. -- 2.39.2