Doc: Developer reference update (#3755)

diff --git a/CHANGES.md b/CHANGES.md
index 2dfed8a0dc4bc76d7c664c1250c6aa3e7ed03cad..ba7947a3c7d539e8c83b5f183fd1702aaee3ae62 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -76,6 +76,9 @@
 <!-- Major changes to documentation and policies. Small docs changes
      don't need a changelog entry. -->
 
 <!-- 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
 ## 23.3.0
 
 ### Highlights

diff --git a/docs/contributing/reference/reference_classes.rst b/docs/contributing/reference/reference_classes.rst
index 3931e0e007245682caa2c08875715925ffc40089..29b25003af28ffb801ec616f857ffd61febb6cdd 100644 (file)
--- a/docs/contributing/reference/reference_classes.rst
+++ b/docs/contributing/reference/reference_classes.rst
@@ -3,6 +3,9 @@
 
 *Contents are subject to change.*
 
 
 *Contents are subject to change.*
 

+Black Classes
+~~~~~~~~~~~~~~
+

 .. currentmodule:: black
 
 :class:`BracketTracker`
 .. currentmodule:: black
 
 :class:`BracketTracker`


@@ -18,6 +21,12 @@
     :members:
     :special-members: __str__, __bool__
 
     :members:
     :special-members: __str__, __bool__
 

+:class:`RHSResult`
+-------------------------
+
+.. autoclass:: black.lines.RHSResult
+    :members:
+

 :class:`LinesBlock`
 -------------------------
 
 :class:`LinesBlock`
 -------------------------
 


@@ -43,6 +52,12 @@
 .. autoclass:: black.comments.ProtoComment
     :members:
 
 .. autoclass:: black.comments.ProtoComment
     :members:
 

+:class:`Mode`
+---------------------
+
+.. autoclass:: black.mode.Mode
+    :members:
+

 :class:`Report`
 ---------------
 
 :class:`Report`
 ---------------
 


@@ -50,6 +65,20 @@
     :members:
     :special-members: __str__
 
     :members:
     :special-members: __str__
 

+:class:`Ok`
+---------------
+
+.. autoclass:: black.rusty.Ok
+    :show-inheritance:
+    :members:
+
+:class:`Err`
+---------------
+
+.. autoclass:: black.rusty.Err
+    :show-inheritance:
+    :members:
+

 :class:`Visitor`
 ----------------
 
 :class:`Visitor`
 ----------------
 


@@ -57,20 +86,115 @@
     :show-inheritance:
     :members:
 
     :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:
 
     :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 <https://docs.python.org/3/library/enum.html#enum.Enum>`_ class.
+
+:class:`Changed`
+----------------
+
+.. autoclass:: black.report.Changed

     :show-inheritance:
     :members:
 
     :show-inheritance:
     :members:
 


@@ -80,3 +204,24 @@ Enums
 .. autoclass:: black.WriteBack
     :show-inheritance:
     :members:
 .. 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 aafe61e5017c8c15468437b13716b117802ad7fe..ab46ebdb628f1f7c7b69be78deb08223ffd6a5d9 100644 (file)
--- a/docs/contributing/reference/reference_exceptions.rst
+++ b/docs/contributing/reference/reference_exceptions.rst
@@ -5,8 +5,14 @@
 
 .. currentmodule:: black
 
 
 .. currentmodule:: black
 

+.. autoexception:: black.trans.CannotTransform
+

 .. autoexception:: black.linegen.CannotSplit
 
 .. 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 f6ff4681557d5341f375982f59c1d98649cea9d3..c6163d897b6bc6c7a4b182a9e6d90930ced5a6b2 100644 (file)
--- a/docs/contributing/reference/reference_summary.rst
+++ b/docs/contributing/reference/reference_summary.rst
@@ -3,8 +3,11 @@ Developer reference
 
 .. note::
 
 
 .. 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.*
 
 
 *Contents are subject to change.*
 

diff --git a/src/black/handle_ipynb_magics.py b/src/black/handle_ipynb_magics.py
index 2b6b920921195bbbb7ec18741b14ca8ce621097b..4324819beaf6e584f791950a666b176355f28145 100644 (file)
--- a/src/black/handle_ipynb_magics.py
+++ b/src/black/handle_ipynb_magics.py
@@ -335,7 +335,8 @@ class CellMagicFinder(ast.NodeVisitor):
 
     For example,
 
 
     For example,
 

-        %%time\nfoo()
+        %%time\n
+        foo()

 
     would have been transformed to
 
 
     would have been transformed to
 

diff --git a/src/black/trans.py b/src/black/trans.py
index 1e28ed0656e2c637ecf65ccbdece7c40ef952c75..4d40cb4bdf6ed6ebc270ff30a9728cff2ce79eba 100644 (file)
--- 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]`
         """
         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.
         """
 
             * 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.
         """
         Yields:
             * Ok(new_line) where new_line is the new transformed line.

-                OR
+              OR

             * Err(CannotTransform) if the transformation failed for some reason. The
             * 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
 
         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
 
         Returns:
             * A list of the custom splits that are mapped to @string, if any

-            exist.
-                OR
+              exist.
+              OR

             * [], otherwise.
 
         Side Effects:
             * [], 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.
     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.
         (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:
         (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
 
     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
         * 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
         * 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.
     """
 
         * 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.
 
         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
             * 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
 
     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:
         * 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.
         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
         * 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.
         * 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 +=
         * 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
         * 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.
         * 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
         * 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.
 
     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.
         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
             @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
         """
         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
             * 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.
 
         Returns:
             True iff @leaf is apart of the string's trailer.