]> git.madduck.net Git - etc/vim.git/commitdiff

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

Doc: Developer reference update (#3755)
authorrdrll <13176405+rdrll@users.noreply.github.com>
Wed, 28 Jun 2023 20:45:56 +0000 (13:45 -0700)
committerGitHub <noreply@github.com>
Wed, 28 Jun 2023 20:45:56 +0000 (13:45 -0700)
CHANGES.md
docs/contributing/reference/reference_classes.rst
docs/contributing/reference/reference_exceptions.rst
docs/contributing/reference/reference_summary.rst
src/black/handle_ipynb_magics.py
src/black/trans.py

index 2dfed8a0dc4bc76d7c664c1250c6aa3e7ed03cad..ba7947a3c7d539e8c83b5f183fd1702aaee3ae62 100644 (file)
@@ -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
index 3931e0e007245682caa2c08875715925ffc40089..29b25003af28ffb801ec616f857ffd61febb6cdd 100644 (file)
@@ -3,6 +3,9 @@
 
 *Contents are subject to change.*
 
 
 *Contents are subject to change.*
 
+Black Classes
+~~~~~~~~~~~~~~
+
 .. currentmodule:: black
 
 :class:`BracketTracker`
 .. currentmodule:: black
 
 :class:`BracketTracker`
     :members:
     :special-members: __str__, __bool__
 
     :members:
     :special-members: __str__, __bool__
 
+:class:`RHSResult`
+-------------------------
+
+.. autoclass:: black.lines.RHSResult
+    :members:
+
 :class:`LinesBlock`
 -------------------------
 
 :class:`LinesBlock`
 -------------------------
 
 .. autoclass:: black.comments.ProtoComment
     :members:
 
 .. autoclass:: black.comments.ProtoComment
     :members:
 
+:class:`Mode`
+---------------------
+
+.. autoclass:: black.mode.Mode
+    :members:
+
 :class:`Report`
 ---------------
 
 :class:`Report`
 ---------------
 
     :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`
 ----------------
 
     :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:
index aafe61e5017c8c15468437b13716b117802ad7fe..ab46ebdb628f1f7c7b69be78deb08223ffd6a5d9 100644 (file)
@@ -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
index f6ff4681557d5341f375982f59c1d98649cea9d3..c6163d897b6bc6c7a4b182a9e6d90930ced5a6b2 100644 (file)
@@ -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.*
 
index 2b6b920921195bbbb7ec18741b14ca8ce621097b..4324819beaf6e584f791950a666b176355f28145 100644 (file)
@@ -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
 
index 1e28ed0656e2c637ecf65ccbdece7c40ef952c75..4d40cb4bdf6ed6ebc270ff30a9728cff2ce79eba 100644 (file)
@@ -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.