config: add new docstring-code-format knob (#8854)

This PR does the plumbing to make a new formatting option, `docstring-code-format`, available in the configuration for end users. It is disabled by default (opt-in). It is opt-in at least initially to reflect a conservative posture. The intent is to make it opt-out at some point in the future. This was split out from #8811 in order to make #8811 easier to merge. Namely, once this is merged, docstring code snippet formatting will become available to end users. (See comments below for how we arrived at the name.) Closes #7146 ## Test Plan Other than the standard test suite, I ran the formatter over the CPython and polars projects to ensure both that the result looked sensible and that tests still passed. At time of writing, one issue that currently appears is that reformatting code snippets trips the long line lint: https://github.com/BurntSushi/polars/actions/runs/7006619426/job/19058868021
astral-sh · Dec 13, 2023 · b6fb972 · b6fb972
1 parent 18452cf
commit b6fb972
Show file tree

Hide file tree

Showing 21 changed files with 505 additions and 55 deletions.
diff --git a/crates/ruff_cli/tests/format.rs b/crates/ruff_cli/tests/format.rs
@@ -139,6 +139,99 @@ if condition:
     Ok(())
 }
 
+#[test]
+fn docstring_options() -> Result<()> {
+    let tempdir = TempDir::new()?;
+    let ruff_toml = tempdir.path().join("ruff.toml");
+    fs::write(
+        &ruff_toml,
+        r#"
+[format]
+docstring-code-format = true
+docstring-code-line-length = 20
+"#,
+    )?;
+
+    assert_cmd_snapshot!(Command::new(get_cargo_bin(BIN_NAME))
+        .args(["format", "--config"])
+        .arg(&ruff_toml)
+        .arg("-")
+        .pass_stdin(r#"
+def f(x):
+    '''
+    Something about `f`. And an example:
+
+    .. code-block:: python
+
+        foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+
+    Another example:
+
+    ```py
+    foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+    ```
+
+    And another:
+
+    >>> foo, bar, quux = this_is_a_long_line(lion, hippo, lemur, bear)
+    '''
+    pass
+"#), @r###"
+success: true
+exit_code: 0
+----- stdout -----
+def f(x):
+    """
+    Something about `f`. And an example:
+
+    .. code-block:: python
+
+        (
+            foo,
+            bar,
+            quux,
+        ) = this_is_a_long_line(
+            lion,
+            hippo,
+            lemur,
+            bear,
+        )
+
+    Another example:
+
+    ```py
+    (
+        foo,
+        bar,
+        quux,
+    ) = this_is_a_long_line(
+        lion,
+        hippo,
+        lemur,
+        bear,
+    )
+    ```
+
+    And another:
+
+    >>> (
+    ...     foo,
+    ...     bar,
+    ...     quux,
+    ... ) = this_is_a_long_line(
+    ...     lion,
+    ...     hippo,
+    ...     lemur,
+    ...     bear,
+    ... )
+    """
+    pass
+
+----- stderr -----
+"###);
+    Ok(())
+}
+
 #[test]
 fn mixed_line_endings() -> Result<()> {
     let tempdir = TempDir::new()?;

diff --git a/crates/ruff_python_formatter/src/options.rs b/crates/ruff_python_formatter/src/options.rs
@@ -175,6 +175,12 @@ impl PyFormatOptions {
         self
     }
 
+    #[must_use]
+    pub fn with_docstring_code_line_width(mut self, line_width: DocstringCodeLineWidth) -> Self {
+        self.docstring_code_line_width = line_width;
+        self
+    }
+
     #[must_use]
     pub fn with_preview(mut self, preview: PreviewMode) -> Self {
         self.preview = preview;
@@ -302,26 +308,21 @@ impl DocstringCode {
     }
 }
 
-#[derive(Copy, Clone, Eq, PartialEq, CacheKey)]
+#[derive(Copy, Clone, Default, Eq, PartialEq, CacheKey)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[cfg_attr(feature = "serde", serde(rename_all = "lowercase"))]
 #[cfg_attr(feature = "serde", serde(untagged))]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum DocstringCodeLineWidth {
     Fixed(LineWidth),
+    #[default]
     #[cfg_attr(
         feature = "serde",
         serde(deserialize_with = "deserialize_docstring_code_line_width_dynamic")
     )]
     Dynamic,
 }
 
-impl Default for DocstringCodeLineWidth {
-    fn default() -> DocstringCodeLineWidth {
-        DocstringCodeLineWidth::Fixed(default_line_width())
-    }
-}
-
 impl std::fmt::Debug for DocstringCodeLineWidth {
     fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
         match *self {

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@docstring.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@docstring.py.snap
@@ -173,7 +173,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -347,7 +347,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -521,7 +521,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -695,7 +695,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -869,7 +869,7 @@ quote-style                = Single
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples.py.snap
@@ -1366,7 +1366,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -2736,7 +2736,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -4106,7 +4106,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -5476,7 +5476,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -6846,7 +6846,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Enabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -7090,7 +7090,9 @@ def doctest_long_lines():
     This won't get wrapped even though it exceeds our configured
     line width because it doesn't exceed the line width within this
     docstring. e.g, the `f` in `foo` is treated as the first column.
-    >>> foo, bar, quux = this_is_a_long_line(lion, giraffe, hippo, zeba, lemur, penguin, monkey)
+    >>> foo, bar, quux = this_is_a_long_line(
+    ...     lion, giraffe, hippo, zeba, lemur, penguin, monkey
+    ... )
 
     But this one is long enough to get wrapped.
     >>> foo, bar, quux = this_is_a_long_line(
@@ -8211,7 +8213,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Enabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -8455,7 +8457,9 @@ def doctest_long_lines():
   This won't get wrapped even though it exceeds our configured
   line width because it doesn't exceed the line width within this
   docstring. e.g, the `f` in `foo` is treated as the first column.
-  >>> foo, bar, quux = this_is_a_long_line(lion, giraffe, hippo, zeba, lemur, penguin, monkey)
+  >>> foo, bar, quux = this_is_a_long_line(
+  ...   lion, giraffe, hippo, zeba, lemur, penguin, monkey
+  ... )
 
   But this one is long enough to get wrapped.
   >>> foo, bar, quux = this_is_a_long_line(
@@ -9576,7 +9580,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Enabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -9820,11 +9824,22 @@ def doctest_long_lines():
 	This won't get wrapped even though it exceeds our configured
 	line width because it doesn't exceed the line width within this
 	docstring. e.g, the `f` in `foo` is treated as the first column.
-	>>> foo, bar, quux = this_is_a_long_line(lion, giraffe, hippo, zeba, lemur, penguin, monkey)
+	>>> foo, bar, quux = this_is_a_long_line(
+	...         lion, giraffe, hippo, zeba, lemur, penguin, monkey
+	... )
 
 	But this one is long enough to get wrapped.
 	>>> foo, bar, quux = this_is_a_long_line(
-	...         lion, giraffe, hippo, zeba, lemur, penguin, monkey, spider, bear, leopard
+	...         lion,
+	...         giraffe,
+	...         hippo,
+	...         zeba,
+	...         lemur,
+	...         penguin,
+	...         monkey,
+	...         spider,
+	...         bear,
+	...         leopard,
 	... )
 	"""
 	# This demostrates a normal line that will get wrapped but won't
@@ -10941,7 +10956,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Enabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -11185,7 +11200,9 @@ def doctest_long_lines():
 	This won't get wrapped even though it exceeds our configured
 	line width because it doesn't exceed the line width within this
 	docstring. e.g, the `f` in `foo` is treated as the first column.
-	>>> foo, bar, quux = this_is_a_long_line(lion, giraffe, hippo, zeba, lemur, penguin, monkey)
+	>>> foo, bar, quux = this_is_a_long_line(
+	...     lion, giraffe, hippo, zeba, lemur, penguin, monkey
+	... )
 
 	But this one is long enough to get wrapped.
 	>>> foo, bar, quux = this_is_a_long_line(

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_crlf.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_crlf.py.snap
@@ -25,7 +25,7 @@ quote-style                = Double
 line-ending                = CarriageReturnLineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Enabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@expression__bytes.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@expression__bytes.py.snap
@@ -136,7 +136,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -288,7 +288,7 @@ quote-style                = Single
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@expression__string.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@expression__string.py.snap
@@ -151,7 +151,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -327,7 +327,7 @@ quote-style                = Single
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 

diff --git a/crates/ruff_python_formatter/tests/snapshots/format@fmt_on_off__fmt_off_docstring.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@fmt_on_off__fmt_off_docstring.py.snap
@@ -35,7 +35,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```
 
@@ -71,7 +71,7 @@ quote-style                = Double
 line-ending                = LineFeed
 magic-trailing-comma       = Respect
 docstring-code             = Disabled
-docstring-code-line-width  = 88
+docstring-code-line-width  = "dynamic"
 preview                    = Disabled
 ```