Skip to content

Commit

Permalink
config: add new docstring-code-format knob (#8854)
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@BurntSushi
BurntSushi committed Dec 13, 2023
1 parent 18452cf commit b6fb972
Show file tree
Hide file tree
Showing 21 changed files with 505 additions and 55 deletions.
93 changes: 93 additions & 0 deletions crates/ruff_cli/tests/format.rs
View file
Expand Up @@ -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()?;
Expand Down
15 changes: 8 additions & 7 deletions crates/ruff_python_formatter/src/options.rs
View file
Expand Up @@ -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;
Expand Down Expand Up @@ -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 {
Expand Down
10 changes: 5 additions & 5 deletions crates/ruff_python_formatter/tests/snapshots/format@docstring.py.snap
View file
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down
43 changes: 30 additions & 13 deletions crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples.py.snap
View file
Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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(
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_crlf.py.snap
View file
Expand Up @@ -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
```

Expand Down
4 changes: 2 additions & 2 deletions crates/ruff_python_formatter/tests/snapshots/format@expression__bytes.py.snap
View file
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down
4 changes: 2 additions & 2 deletions crates/ruff_python_formatter/tests/snapshots/format@expression__string.py.snap
View file
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down
4 changes: 2 additions & 2 deletions crates/ruff_python_formatter/tests/snapshots/format@fmt_on_off__fmt_off_docstring.py.snap
View file
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```

Expand Down

0 comments on commit b6fb972

Please sign in to comment.