diff --git a/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.options.json b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.options.json index 75eee27329..9400ae4bea 100644 --- a/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.options.json +++ b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples.options.json @@ -44,5 +44,11 @@ "docstring_code_line_width": 60, "indent_style": "space", "indent_width": 4 + }, + { + "docstring_code": "enabled", + "docstring_code_line_width": "dynamic", + "indent_style": "space", + "indent_width": 4 } ] diff --git a/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.options.json b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.options.json new file mode 100644 index 0000000000..3367effa00 --- /dev/null +++ b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.options.json @@ -0,0 +1,26 @@ +[ + { + "docstring_code": "enabled", + "docstring_code_line_width": "dynamic", + "indent_style": "space", + "indent_width": 4 + }, + { + "docstring_code": "enabled", + "docstring_code_line_width": "dynamic", + "indent_style": "space", + "indent_width": 2 + }, + { + "docstring_code": "enabled", + "docstring_code_line_width": "dynamic", + "indent_style": "tab", + "indent_width": 4 + }, + { + "docstring_code": "enabled", + "docstring_code_line_width": "dynamic", + "indent_style": "tab", + "indent_width": 8 + } +] diff --git a/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.py b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.py new file mode 100644 index 0000000000..04027909ed --- /dev/null +++ b/crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.py @@ -0,0 +1,172 @@ +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + +```py +class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) +``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + +```py +class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + self.x = doit( 5 ) +``` + + Done. + """ + pass diff --git a/crates/ruff_python_formatter/src/context.rs b/crates/ruff_python_formatter/src/context.rs index ac5dea3710..8407e7cdc4 100644 --- a/crates/ruff_python_formatter/src/context.rs +++ b/crates/ruff_python_formatter/src/context.rs @@ -1,7 +1,7 @@ use crate::comments::Comments; use crate::expression::string::QuoteChar; use crate::PyFormatOptions; -use ruff_formatter::{Buffer, FormatContext, GroupId, SourceCode}; +use ruff_formatter::{Buffer, FormatContext, GroupId, IndentWidth, SourceCode}; use ruff_source_file::Locator; use std::fmt::{Debug, Formatter}; use std::ops::{Deref, DerefMut}; @@ -12,6 +12,7 @@ pub struct PyFormatContext<'a> { contents: &'a str, comments: Comments<'a>, node_level: NodeLevel, + indent_level: IndentLevel, /// Set to a non-None value when the formatter is running on a code /// snippet within a docstring. The value should be the quote character of the /// docstring containing the code snippet. @@ -30,6 +31,7 @@ impl<'a> PyFormatContext<'a> { contents, comments, node_level: NodeLevel::TopLevel(TopLevelStatementPosition::Other), + indent_level: IndentLevel::new(0), docstring: None, } } @@ -51,6 +53,14 @@ impl<'a> PyFormatContext<'a> { self.node_level } + pub(crate) fn set_indent_level(&mut self, level: IndentLevel) { + self.indent_level = level; + } + + pub(crate) fn indent_level(&self) -> IndentLevel { + self.indent_level + } + pub(crate) fn comments(&self) -> &Comments<'a> { &self.comments } @@ -210,3 +220,115 @@ where .set_node_level(self.saved_level); } } + +/// The current indent level of the formatter. +/// +/// One can determine the the width of the indent itself (in number of ASCII +/// space characters) by multiplying the indent level by the configured indent +/// width. +/// +/// This is specifically used inside the docstring code formatter for +/// implementing its "dynamic" line width mode. Namely, in the nested call to +/// the formatter, when "dynamic" mode is enabled, the line width is set to +/// `min(1, line_width - indent_level * indent_width)`, where `line_width` in +/// this context is the global line width setting. +#[derive(Copy, Clone, Debug, Eq, PartialEq)] +pub(crate) struct IndentLevel { + /// The numeric level. It is incremented for every whole indent in Python + /// source code. + /// + /// Note that the first indentation level is actually 1, since this starts + /// at 0 and is incremented when the first top-level statement is seen. So + /// even though the first top-level statement in Python source will have no + /// indentation, its indentation level is 1. + level: u16, +} + +impl IndentLevel { + /// Returns a new indent level for the given value. + pub(crate) fn new(level: u16) -> IndentLevel { + IndentLevel { level } + } + + /// Returns the next indent level. + pub(crate) fn increment(self) -> IndentLevel { + IndentLevel { + level: self.level.saturating_add(1), + } + } + + /// Convert this indent level into a specific number of ASCII whitespace + /// characters based on the given indent width. + pub(crate) fn to_ascii_spaces(self, width: IndentWidth) -> u16 { + let width = u16::try_from(width.value()).unwrap_or(u16::MAX); + // Why the subtraction? IndentLevel starts at 0 and asks for the "next" + // indent level before seeing the first top-level statement. So it's + // always 1 more than what we expect it to be. + let level = self.level.saturating_sub(1); + width.saturating_mul(level) + } +} + +/// Change the [`IndentLevel`] of the formatter for the lifetime of this +/// struct. +pub(crate) struct WithIndentLevel<'a, B, D> +where + D: DerefMut, + B: Buffer>, +{ + buffer: D, + saved_level: IndentLevel, +} + +impl<'a, B, D> WithIndentLevel<'a, B, D> +where + D: DerefMut, + B: Buffer>, +{ + pub(crate) fn new(level: IndentLevel, mut buffer: D) -> Self { + let context = buffer.state_mut().context_mut(); + let saved_level = context.indent_level(); + + context.set_indent_level(level); + + Self { + buffer, + saved_level, + } + } +} + +impl<'a, B, D> Deref for WithIndentLevel<'a, B, D> +where + D: DerefMut, + B: Buffer>, +{ + type Target = B; + + fn deref(&self) -> &Self::Target { + &self.buffer + } +} + +impl<'a, B, D> DerefMut for WithIndentLevel<'a, B, D> +where + D: DerefMut, + B: Buffer>, +{ + fn deref_mut(&mut self) -> &mut Self::Target { + &mut self.buffer + } +} + +impl<'a, B, D> Drop for WithIndentLevel<'a, B, D> +where + D: DerefMut, + B: Buffer>, +{ + fn drop(&mut self) { + self.buffer + .state_mut() + .context_mut() + .set_indent_level(self.saved_level); + } +} diff --git a/crates/ruff_python_formatter/src/expression/string/docstring.rs b/crates/ruff_python_formatter/src/expression/string/docstring.rs index 0fb03ce07d..e750a52641 100644 --- a/crates/ruff_python_formatter/src/expression/string/docstring.rs +++ b/crates/ruff_python_formatter/src/expression/string/docstring.rs @@ -7,13 +7,13 @@ use std::{borrow::Cow, collections::VecDeque}; use {once_cell::sync::Lazy, regex::Regex}; use { - ruff_formatter::{write, IndentStyle, Printed}, + ruff_formatter::{write, FormatOptions, IndentStyle, LineWidth, Printed}, ruff_python_trivia::{is_python_whitespace, PythonWhitespace}, ruff_source_file::Locator, ruff_text_size::{Ranged, TextLen, TextRange, TextSize}, }; -use crate::{prelude::*, FormatModuleError}; +use crate::{prelude::*, DocstringCodeLineWidth, FormatModuleError}; use super::{NormalizedString, QuoteChar}; @@ -460,11 +460,22 @@ impl<'ast, 'buf, 'fmt, 'src> DocstringLinePrinter<'ast, 'buf, 'fmt, 'src> { .map(|line| line.code) .collect::>() .join("\n"); + let line_width = match self.f.options().docstring_code_line_width() { + DocstringCodeLineWidth::Fixed(width) => width, + DocstringCodeLineWidth::Dynamic => { + let global_line_width = self.f.options().line_width().value(); + let indent_width = self.f.options().indent_width(); + let indent_level = self.f.context().indent_level(); + let current_indent = indent_level.to_ascii_spaces(indent_width); + let width = std::cmp::max(1, global_line_width.saturating_sub(current_indent)); + LineWidth::try_from(width).expect("width is capped at a minimum of 1") + } + }; let options = self .f .options() .clone() - .with_line_width(self.f.options().docstring_code_line_width()) + .with_line_width(line_width) // It's perhaps a little odd to be hard-coding the indent // style here, but I believe it is necessary as a result // of the whitespace normalization otherwise done in diff --git a/crates/ruff_python_formatter/src/lib.rs b/crates/ruff_python_formatter/src/lib.rs index ce3988dd54..beaa4070c0 100644 --- a/crates/ruff_python_formatter/src/lib.rs +++ b/crates/ruff_python_formatter/src/lib.rs @@ -16,7 +16,8 @@ use crate::comments::{ }; pub use crate::context::PyFormatContext; pub use crate::options::{ - DocstringCode, MagicTrailingComma, PreviewMode, PyFormatOptions, QuoteStyle, + DocstringCode, DocstringCodeLineWidth, MagicTrailingComma, PreviewMode, PyFormatOptions, + QuoteStyle, }; pub use crate::shared_traits::{AsFormat, FormattedIter, FormattedIterExt, IntoFormat}; use crate::verbatim::suppressed_node; diff --git a/crates/ruff_python_formatter/src/options.rs b/crates/ruff_python_formatter/src/options.rs index 003cfea4bf..8f3bc431ec 100644 --- a/crates/ruff_python_formatter/src/options.rs +++ b/crates/ruff_python_formatter/src/options.rs @@ -52,8 +52,7 @@ pub struct PyFormatOptions { /// The preferred line width at which the formatter should wrap lines in /// docstring code examples. This only has an impact when `docstring_code` /// is enabled. - #[cfg_attr(feature = "serde", serde(default = "default_line_width"))] - docstring_code_line_width: LineWidth, + docstring_code_line_width: DocstringCodeLineWidth, /// Whether preview style formatting is enabled or not preview: PreviewMode, @@ -83,7 +82,7 @@ impl Default for PyFormatOptions { magic_trailing_comma: MagicTrailingComma::default(), source_map_generation: SourceMapGeneration::default(), docstring_code: DocstringCode::default(), - docstring_code_line_width: default_line_width(), + docstring_code_line_width: DocstringCodeLineWidth::default(), preview: PreviewMode::default(), } } @@ -126,7 +125,7 @@ impl PyFormatOptions { self.docstring_code } - pub fn docstring_code_line_width(&self) -> LineWidth { + pub fn docstring_code_line_width(&self) -> DocstringCodeLineWidth { self.docstring_code_line_width } @@ -302,3 +301,50 @@ impl DocstringCode { matches!(self, DocstringCode::Enabled) } } + +#[derive(Copy, Clone, 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), + #[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 { + DocstringCodeLineWidth::Fixed(v) => v.value().fmt(f), + DocstringCodeLineWidth::Dynamic => "dynamic".fmt(f), + } + } +} + +/// Responsible for deserializing the `DocstringCodeLineWidth::Dynamic` +/// variant. +fn deserialize_docstring_code_line_width_dynamic<'de, D>(d: D) -> Result<(), D::Error> +where + D: serde::Deserializer<'de>, +{ + use serde::{de::Error, Deserialize}; + + let value = String::deserialize(d)?; + match &*value { + "dynamic" => Ok(()), + s => Err(D::Error::invalid_value( + serde::de::Unexpected::Str(s), + &"dynamic", + )), + } +} diff --git a/crates/ruff_python_formatter/src/statement/suite.rs b/crates/ruff_python_formatter/src/statement/suite.rs index b60474dbd0..1b33dbd41a 100644 --- a/crates/ruff_python_formatter/src/statement/suite.rs +++ b/crates/ruff_python_formatter/src/statement/suite.rs @@ -8,7 +8,7 @@ use ruff_text_size::{Ranged, TextRange}; use crate::comments::{ leading_comments, trailing_comments, Comments, LeadingDanglingTrailingComments, }; -use crate::context::{NodeLevel, TopLevelStatementPosition, WithNodeLevel}; +use crate::context::{NodeLevel, TopLevelStatementPosition, WithIndentLevel, WithNodeLevel}; use crate::expression::string::StringLayout; use crate::prelude::*; use crate::statement::stmt_expr::FormatStmtExpr; @@ -71,7 +71,8 @@ impl FormatRule> for FormatSuite { let source = f.context().source(); let source_type = f.options().source_type(); - let f = &mut WithNodeLevel::new(node_level, f); + let f = WithNodeLevel::new(node_level, f); + let f = &mut WithIndentLevel::new(f.context().indent_level().increment(), f); // Format the first statement in the body, which often has special formatting rules. let first = match self.kind { diff --git a/crates/ruff_python_formatter/tests/fixtures.rs b/crates/ruff_python_formatter/tests/fixtures.rs index a425a1e597..3845385d73 100644 --- a/crates/ruff_python_formatter/tests/fixtures.rs +++ b/crates/ruff_python_formatter/tests/fixtures.rs @@ -363,7 +363,7 @@ preview = {preview:?}"#, line_ending = self.0.line_ending(), magic_trailing_comma = self.0.magic_trailing_comma(), docstring_code = self.0.docstring_code(), - docstring_code_line_width = self.0.docstring_code_line_width().value(), + docstring_code_line_width = self.0.docstring_code_line_width(), preview = self.0.preview() ) } 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 index e0c672c090..b93825ea19 100644 --- 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 @@ -13673,4 +13673,1371 @@ def markdown_skipped_rst_directive(): ``` +### Output 10 +``` +indent-style = space +line-width = 88 +indent-width = 4 +quote-style = Double +line-ending = LineFeed +magic-trailing-comma = Respect +docstring-code = Enabled +docstring-code-line-width = "dynamic" +preview = Disabled +``` + +```python +############################################################################### +# DOCTEST CODE EXAMPLES +# +# This section shows examples of docstrings that contain code snippets in +# Python's "doctest" format. +# +# See: https://docs.python.org/3/library/doctest.html +############################################################################### + +# The simplest doctest to ensure basic formatting works. +def doctest_simple(): + """ + Do cool stuff. + + >>> cool_stuff(1) + 2 + """ + pass + + +# Another simple test, but one where the Python code +# extends over multiple lines. +def doctest_simple_continued(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(f"hi {x}") + hi 2 + """ + pass + + +# Test that we support multiple directly adjacent +# doctests. +def doctest_adjacent(): + """ + Do cool stuff. + + >>> cool_stuff(x) + >>> cool_stuff(y) + 2 + """ + pass + + +# Test that a doctest on the last non-whitespace line of a docstring +# reformats correctly. +def doctest_last_line(): + """ + Do cool stuff. + + >>> cool_stuff(x) + """ + pass + + +# Test that a doctest that continues to the last non-whitespace line of +# a docstring reformats correctly. +def doctest_last_line_continued(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(f"hi {x}") + """ + pass + + +# Test that a doctest on the real last line of a docstring reformats +# correctly. +def doctest_really_last_line(): + """ + Do cool stuff. + + >>> cool_stuff(x)""" + pass + + +# Test that a continued doctest on the real last line of a docstring reformats +# correctly. +def doctest_really_last_line_continued(): + """ + Do cool stuff. + + >>> cool_stuff(x) + ... more(y)""" + pass + + +# Test that a doctest is correctly identified and formatted with a blank +# continuation line. +def doctest_blank_continued(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(x) + ... + ... print(x) + """ + pass + + +# Tests that a blank PS2 line at the end of a doctest can get dropped. +# It is treated as part of the Python snippet which will trim the +# trailing whitespace. +def doctest_blank_end(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(x) + ... print(x) + """ + pass + + +# Tests that a blank PS2 line at the end of a doctest can get dropped +# even when there is text following it. +def doctest_blank_end_then_some_text(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(x) + ... print(x) + + And say something else. + """ + pass + + +# Test that a doctest containing a triple quoted string gets formatted +# correctly and doesn't result in invalid syntax. +def doctest_with_triple_single(): + """ + Do cool stuff. + + >>> x = '''tricksy''' + """ + pass + + +# Test that a doctest containing a triple quoted f-string gets +# formatted correctly and doesn't result in invalid syntax. +def doctest_with_triple_single(): + """ + Do cool stuff. + + >>> x = f'''tricksy''' + """ + pass + + +# Another nested multi-line string case, but with triple escaped double +# quotes inside a triple single quoted string. +def doctest_with_triple_escaped_double(): + """ + Do cool stuff. + + >>> x = '''\"\"\"''' + """ + pass + + +# Tests that inverting the triple quoting works as expected. +def doctest_with_triple_inverted(): + ''' + Do cool stuff. + + >>> x = """tricksy""" + ''' + pass + + +# Tests that inverting the triple quoting with an f-string works as +# expected. +def doctest_with_triple_inverted_fstring(): + ''' + Do cool stuff. + + >>> x = f"""tricksy""" + ''' + pass + + +# Tests nested doctests are ignored. That is, we don't format doctests +# recursively. We only recognize "top level" doctests. +# +# This restriction primarily exists to avoid needing to deal with +# nesting quotes. It also seems like a generally sensible restriction, +# although it could be lifted if necessary I believe. +def doctest_nested_doctest_not_formatted(): + ''' + Do cool stuff. + + >>> def nested(x): + ... """ + ... Do nested cool stuff. + ... >>> func_call( 5 ) + ... """ + ... pass + ''' + pass + + +# Tests that the starting column does not matter. +def doctest_varying_start_column(): + """ + Do cool stuff. + + >>> assert "Easy!" + >>> import math + >>> math.floor(1.9) + 1 + """ + pass + + +# Tests that long lines get wrapped... appropriately. +# +# The docstring code formatter uses the same line width settings as for +# formatting other code. This means that a line in the docstring can +# actually extend past the configured line limit. +# +# It's not quite clear whether this is desirable or not. We could in +# theory compute the intendation length of a code snippet and then +# adjust the line-width setting on a recursive call to the formatter. +# But there are assuredly pathological cases to consider. Another path +# would be to expose another formatter option for controlling the +# line-width of code snippets independently. +def doctest_long_lines(): + """ + Do cool stuff. + + 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 + ... ) + + 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 + ... ) + """ + # This demostrates a normal line that will get wrapped but won't + # get wrapped in the docstring above because of how the line-width + # setting gets reset at the first column in each code snippet. + foo, bar, quux = this_is_a_long_line( + lion, giraffe, hippo, zeba, lemur, penguin, monkey + ) + + +# Checks that a simple but invalid doctest gets skipped. +def doctest_skipped_simple(): + """ + Do cool stuff. + + >>> cool-stuff( x ): + 2 + """ + pass + + +# Checks that a simple doctest that is continued over multiple lines, +# but is invalid, gets skipped. +def doctest_skipped_simple_continued(): + """ + Do cool stuff. + + >>> def cool-stuff( x ): + ... print( f"hi {x}" ); + 2 + """ + pass + + +# Checks that a doctest with improper indentation gets skipped. +def doctest_skipped_inconsistent_indent(): + """ + Do cool stuff. + + >>> def cool_stuff( x ): + ... print( f"hi {x}" ); + hi 2 + """ + pass + + +# Checks that a doctest with some proper indentation and some improper +# indentation is "partially" formatted. That is, the part that appears +# before the inconsistent indentation is formatted. This requires that +# the part before it is valid Python. +def doctest_skipped_partial_inconsistent_indent(): + """ + Do cool stuff. + + >>> def cool_stuff(x): + ... print(x) + ... print( f"hi {x}" ); + hi 2 + """ + pass + + +# Checks that a doctest with improper triple single quoted string gets +# skipped. That is, the code snippet is itself invalid Python, so it is +# left as is. +def doctest_skipped_triple_incorrect(): + """ + Do cool stuff. + + >>> foo( x ) + ... '''tri'''cksy''' + """ + pass + + +# Tests that a doctest on a single line is skipped. +def doctest_skipped_one_line(): + ">>> foo( x )" + pass + + +# f-strings are not considered docstrings[1], so any doctests +# inside of them should not be formatted. +# +# [1]: https://docs.python.org/3/reference/lexical_analysis.html#formatted-string-literals +def doctest_skipped_fstring(): + f""" + Do cool stuff. + + >>> cool_stuff( 1 ) + 2 + """ + pass + + +# Test that a doctest containing a triple quoted string at least +# does not result in invalid Python code. Ideally this would format +# correctly, but at time of writing it does not. +def doctest_invalid_skipped_with_triple_double_in_single_quote_string(): + """ + Do cool stuff. + + >>> x = '\"\"\"' + """ + pass + + +############################################################################### +# reStructuredText CODE EXAMPLES +# +# This section shows examples of docstrings that contain code snippets in +# reStructuredText formatted code blocks. +# +# See: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks +# See: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block +# See: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks +# See: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#toc-entry-30 +# See: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#toc-entry-38 +############################################################################### + + +def rst_literal_simple(): + """ + Do cool stuff:: + + cool_stuff(1) + + Done. + """ + pass + + +def rst_literal_simple_continued(): + """ + Do cool stuff:: + + def cool_stuff(x): + print(f"hi {x}") + + Done. + """ + pass + + +# Tests that we can end the literal block on the second +# to last line of the docstring. +def rst_literal_second_to_last(): + """ + Do cool stuff:: + + cool_stuff(1) + """ + pass + + +# Tests that we can end the literal block on the actual +# last line of the docstring. +def rst_literal_actually_last(): + """ + Do cool stuff:: + + cool_stuff(1)""" + pass + + +def rst_literal_with_blank_lines(): + """ + Do cool stuff:: + + def cool_stuff(x): + print(f"hi {x}") + + + def other_stuff(y): + print(y) + + Done. + """ + pass + + +# Extra blanks should be preserved. +def rst_literal_extra_blanks(): + """ + Do cool stuff:: + + + + cool_stuff(1) + + + + Done. + """ + pass + + +# If a literal block is never properly ended (via a non-empty unindented line), +# then the end of the block should be the last non-empty line. And subsequent +# empty lines should be preserved as-is. +def rst_literal_extra_blanks_at_end(): + """ + Do cool stuff:: + + + cool_stuff(1) + + + + """ + pass + + +# A literal block can contain many empty lines and it should not end the block +# if it continues. +def rst_literal_extra_blanks_in_snippet(): + """ + Do cool stuff:: + + cool_stuff(1) + + + cool_stuff(2) + + Done. + """ + pass + + +# This tests that a unindented line appearing after an indented line (but where +# the indent is still beyond the minimum) gets formatted properly. +def rst_literal_subsequent_line_not_indented(): + """ + Do cool stuff:: + + if True: + cool_stuff( + ''' + hiya''' + ) + + Done. + """ + pass + + +# This checks that if the first line in a code snippet has been indented with +# tabs, then so long as its "indentation length" is considered bigger than the +# line with `::`, it is reformatted as code. +# +# (If your tabwidth is set to 4, then it looks like the code snippet +# isn't indented at all, which is perhaps counter-intuitive. Indeed, reST +# itself also seems to recognize this as a code block, although it appears +# under-specified.) +def rst_literal_first_line_indent_uses_tabs_4spaces(): + """ + Do cool stuff:: + + cool_stuff(1) + + Done. + """ + pass + + +# Like the test above, but with multiple lines. +def rst_literal_first_line_indent_uses_tabs_4spaces_multiple(): + """ + Do cool stuff:: + + cool_stuff(1) + cool_stuff(2) + + Done. + """ + pass + + +# Another test with tabs, except in this case, if your tabwidth is less than +# 8, than the code snippet actually looks like its indent is *less* than the +# opening line with a `::`. One might presume this means that the code snippet +# is not treated as a literal block and thus not reformatted, but since we +# assume all tabs have tabwidth=8 when computing indentation length, the code +# snippet is actually seen as being more indented than the opening `::` line. +# As with the above example, reST seems to behave the same way here. +def rst_literal_first_line_indent_uses_tabs_8spaces(): + """ + Do cool stuff:: + + cool_stuff(1) + + Done. + """ + pass + + +# Like the test above, but with multiple lines. +def rst_literal_first_line_indent_uses_tabs_8spaces_multiple(): + """ + Do cool stuff:: + + cool_stuff(1) + cool_stuff(2) + + Done. + """ + pass + + +# Tests that if two lines in a literal block are indented to the same level +# but by different means (tabs versus spaces), then we correctly recognize the +# block and format it. +def rst_literal_first_line_tab_second_line_spaces(): + """ + Do cool stuff:: + + cool_stuff(1) + cool_stuff(2) + + Done. + """ + pass + + +# Tests that when two lines in a code snippet have weird and inconsistent +# indentation, the code still gets formatted so long as the indent is greater +# than the indent of the `::` line. +# +# In this case, the minimum indent is 5 spaces (from the second line) where as +# the first line has an indent of 8 spaces via a tab (by assuming tabwidth=8). +# The minimum indent is stripped from each code line. Since tabs aren't +# divisible, the entire tab is stripped, which means the first and second lines +# wind up with the same level of indentation. +# +# An alternative behavior here would be that the tab is replaced with 3 spaces +# instead of being stripped entirely. The code snippet itself would then have +# inconsistent indentation to the point of being invalid Python, and thus code +# formatting would be skipped. +# +# I decided on the former behavior because it seems a bit easier to implement, +# but we might want to switch to the alternative if cases like this show up in +# the real world. ---AG +def rst_literal_odd_indentation(): + """ + Do cool stuff:: + + cool_stuff(1) + cool_stuff(2) + + Done. + """ + pass + + +# Tests that having a line with a lone `::` works as an introduction of a +# literal block. +def rst_literal_lone_colon(): + """ + Do cool stuff. + + :: + + cool_stuff(1) + + Done. + """ + pass + + +def rst_directive_simple(): + """ + .. code-block:: python + + cool_stuff(1) + + Done. + """ + pass + + +def rst_directive_case_insensitive(): + """ + .. cOdE-bLoCk:: python + + cool_stuff(1) + + Done. + """ + pass + + +def rst_directive_sourcecode(): + """ + .. sourcecode:: python + + cool_stuff(1) + + Done. + """ + pass + + +def rst_directive_options(): + """ + .. code-block:: python + :linenos: + :emphasize-lines: 2,3 + :name: blah blah + + cool_stuff(1) + cool_stuff(2) + cool_stuff(3) + cool_stuff(4) + + Done. + """ + pass + + +# In this case, since `pycon` isn't recognized as a Python code snippet, the +# docstring reformatter ignores it. But it then picks up the doctest and +# reformats it. +def rst_directive_doctest(): + """ + .. code-block:: pycon + + >>> cool_stuff(1) + + Done. + """ + pass + + +# This checks that if the first non-empty line after the start of a literal +# block is not indented more than the line containing the `::`, then it is not +# treated as a code snippet. +def rst_literal_skipped_first_line_not_indented(): + """ + Do cool stuff:: + + cool_stuff( 1 ) + + Done. + """ + pass + + +# Like the test above, but inserts an indented line after the un-indented one. +# This should not cause the literal block to be resumed. +def rst_literal_skipped_first_line_not_indented_then_indented(): + """ + Do cool stuff:: + + cool_stuff( 1 ) + cool_stuff( 2 ) + + Done. + """ + pass + + +# This also checks that a code snippet is not reformatted when the indentation +# of the first line is not more than the line with `::`, but this uses tabs to +# make it a little more confounding. It relies on the fact that indentation +# length is computed by assuming a tabwidth equal to 8. reST also rejects this +# and doesn't treat it as a literal block. +def rst_literal_skipped_first_line_not_indented_tab(): + """ + Do cool stuff:: + + cool_stuff( 1 ) + + Done. + """ + pass + + +# Like the previous test, but adds a second line. +def rst_literal_skipped_first_line_not_indented_tab_multiple(): + """ + Do cool stuff:: + + cool_stuff( 1 ) + cool_stuff( 2 ) + + Done. + """ + pass + + +# Tests that a code block with a second line that is not properly indented gets +# skipped. A valid code block needs to have an empty line separating these. +# +# One trick here is that we need to make sure the Python code in the snippet is +# valid, otherwise it would be skipped because of invalid Python. +def rst_literal_skipped_subsequent_line_not_indented(): + """ + Do cool stuff:: + + if True: + cool_stuff( ''' + hiya''' ) + + Done. + """ + pass + + +# In this test, we write what looks like a code-block, but it should be treated +# as invalid due to the missing `language` argument. +# +# It does still look like it could be a literal block according to the literal +# rules, but we currently consider the `.. ` prefix to indicate that it is not +# a literal block. +def rst_literal_skipped_not_directive(): + """ + .. code-block:: + + cool_stuff( 1 ) + + Done. + """ + pass + + +# In this test, we start a line with `.. `, which makes it look like it might +# be a directive. But instead continue it as if it was just some periods from +# the previous line, and then try to end it by starting a literal block. +# +# But because of the `.. ` in the beginning, we wind up not treating this as a +# code snippet. The reST render I was using to test things does actually treat +# this as a code block, so we may be out of conformance here. +def rst_literal_skipped_possible_false_negative(): + """ + This is a test. + .. This is a test:: + + cool_stuff( 1 ) + + Done. + """ + pass + + +# This tests that a doctest inside of a reST literal block doesn't get +# reformatted. It's plausible this isn't the right behavior, but it also seems +# like it might be the right behavior since it is a literal block. (The doctest +# makes the Python code invalid.) +def rst_literal_skipped_doctest(): + """ + Do cool stuff:: + + >>> cool_stuff( 1 ) + + Done. + """ + pass + + +def rst_literal_skipped_markdown(): + """ + Do cool stuff:: + + ```py + cool_stuff( 1 ) + ``` + + Done. + """ + pass + + +def rst_directive_skipped_not_indented(): + """ + .. code-block:: python + + cool_stuff( 1 ) + + Done. + """ + pass + + +def rst_directive_skipped_wrong_language(): + """ + .. code-block:: rust + + cool_stuff( 1 ) + + Done. + """ + pass + + +# This gets skipped for the same reason that the doctest in a literal block +# gets skipped. +def rst_directive_skipped_doctest(): + """ + .. code-block:: python + + >>> cool_stuff( 1 ) + + Done. + """ + pass + + +############################################################################### +# Markdown CODE EXAMPLES +# +# This section shows examples of docstrings that contain code snippets in +# Markdown fenced code blocks. +# +# See: https://spec.commonmark.org/0.30/#fenced-code-blocks +############################################################################### + + +def markdown_simple(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ``` + + Done. + """ + pass + + +def markdown_simple_continued(): + """ + Do cool stuff. + + ```python + def cool_stuff(x): + print(f"hi {x}") + ``` + + Done. + """ + pass + + +# Tests that unlabeled Markdown fenced code blocks are assumed to be Python. +def markdown_unlabeled(): + """ + Do cool stuff. + + ``` + cool_stuff(1) + ``` + + Done. + """ + pass + + +# Tests that fenced code blocks using tildes work. +def markdown_tildes(): + """ + Do cool stuff. + + ~~~py + cool_stuff(1) + ~~~ + + Done. + """ + pass + + +# Tests that a longer closing fence is just fine and dandy. +def markdown_longer_closing_fence(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + `````` + + Done. + """ + pass + + +# Tests that an invalid closing fence is treated as invalid. +# +# We embed it into a docstring so that the surrounding Python +# remains valid. +def markdown_longer_closing_fence(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ''' + ```invalid + ''' + cool_stuff(2) + ``` + + Done. + """ + pass + + +# Tests that one can nest fenced code blocks by using different numbers of +# backticks. +def markdown_nested_fences(): + """ + Do cool stuff. + + `````` + do_something( + ''' + ``` + did i trick you? + ``` + ''' + ) + `````` + + Done. + """ + pass + + +# Tests that an unclosed block gobbles up everything remaining in the +# docstring. When it's only empty lines, those are passed into the formatter +# and thus stripped. +def markdown_unclosed_empty_lines(): + """ + Do cool stuff. + + ```py + cool_stuff(1)""" + pass + + +# Tests that we can end the block on the second to last line of the +# docstring. +def markdown_second_to_last(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ``` + """ + pass + + +# Tests that an unclosed block with one extra line at the end is treated +# correctly. As per the CommonMark spec, an unclosed fenced code block contains +# everything following the opening fences. Since formatting the code snippet +# trims lines, the last empty line is removed here. +def markdown_second_to_last(): + """ + Do cool stuff. + + ```py + cool_stuff(1)""" + pass + + +# Tests that we can end the block on the actual last line of the docstring. +def markdown_actually_last(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ```""" + pass + + +# Tests that an unclosed block that ends on the last line of a docstring +# is handled correctly. +def markdown_unclosed_actually_last(): + """ + Do cool stuff. + + ```py + cool_stuff(1)""" + pass + + +def markdown_with_blank_lines(): + """ + Do cool stuff. + + ```py + def cool_stuff(x): + print(f"hi {x}") + + + def other_stuff(y): + print(y) + ``` + + Done. + """ + pass + + +def markdown_first_line_indent_uses_tabs_4spaces(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ``` + + Done. + """ + pass + + +def markdown_first_line_indent_uses_tabs_4spaces_multiple(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + cool_stuff(2) + ``` + + Done. + """ + pass + + +def markdown_first_line_indent_uses_tabs_8spaces(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ``` + + Done. + """ + pass + + +def markdown_first_line_indent_uses_tabs_8spaces_multiple(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + cool_stuff(2) + ``` + + Done. + """ + pass + + +def markdown_first_line_tab_second_line_spaces(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + cool_stuff(2) + ``` + + Done. + """ + pass + + +def markdown_odd_indentation(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + cool_stuff(2) + ``` + + Done. + """ + pass + + +# Extra blanks should be *not* be preserved (unlike reST) because they are part +# of the code snippet (per CommonMark spec), and thus get trimmed as part of +# code formatting. +def markdown_extra_blanks(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + ``` + + Done. + """ + pass + + +# A block can contain many empty lines within it. +def markdown_extra_blanks_in_snippet(): + """ + Do cool stuff. + + ```py + cool_stuff(1) + + + cool_stuff(2) + ``` + + Done. + """ + pass + + +def markdown_weird_closing(): + """ + Code block with weirdly placed closing fences. + + ```python + cool_stuff(1) + ``` + # The above fences look like it shouldn't close the block, but we + # allow it to. The fences below re-open a block (until the end of + # the docstring), but it's invalid Python and thus doesn't get + # reformatted. + a = 10 + ``` + + Now the code block is closed + """ + pass + + +def markdown_over_indented(): + """ + A docstring + over intended + ```python + print(5) + ``` + """ + pass + + +# This tests that we can have additional text after the language specifier. +def markdown_additional_info_string(): + """ + Do cool stuff. + + ```python tab="plugin.py" + cool_stuff(1) + ``` + + Done. + """ + pass + + +# Tests that an unclosed block gobbles up everything remaining in the +# docstring, even if it isn't valid Python. Since it isn't valid Python, +# reformatting fails and the entire thing is skipped. +def markdown_skipped_unclosed_non_python(): + """ + Do cool stuff. + + ```py + cool_stuff( 1 ) + + I forgot to close the code block, and this is definitely not + Python. So nothing here gets formatted. + """ + pass + + +# This has a Python snippet with a docstring that contains a closing fence. +# This splits the embedded docstring and makes the overall snippet invalid. +def markdown_skipped_accidental_closure(): + """ + Do cool stuff. + + ```py + cool_stuff( 1 ) + ''' + ``` + ''' + ``` + + Done. + """ + pass + + +# When a line is unindented all the way out before the standard indent of the +# docstring, the code reformatting ends up interacting poorly with the standard +# docstring whitespace normalization logic. This is probably a bug, and we +# should probably treat the Markdown block as valid, but for now, we detect +# the unindented line and declare the block as invalid and thus do no code +# reformatting. +# +# FIXME: Fixing this (if we think it's a bug) probably requires refactoring the +# docstring whitespace normalization to be aware of code snippets. Or perhaps +# plausibly, to do normalization *after* code snippets have been formatted. +def markdown_skipped_unindented_completely(): + """ + Do cool stuff. + + ```py + cool_stuff( 1 ) + ``` + + Done. + """ + pass + + +# This test is fallout from treating fenced code blocks with unindented lines +# as invalid. We probably should treat this as a valid block. Indeed, if we +# remove the logic that makes the `markdown_skipped_unindented_completely` test +# pass, then this code snippet will get reformatted correctly. +def markdown_skipped_unindented_somewhat(): + """ + Do cool stuff. + + ```py + cool_stuff( 1 ) + ``` + + Done. + """ + pass + + +# This tests that if a Markdown block contains a line that has less of an +# indent than another line. +# +# There is some judgment involved in what the right behavior is here. We +# could "normalize" the indentation so that the minimum is the indent of the +# opening fence line. If we did that here, then the code snippet would become +# valid and format as Python. But at time of writing, we don't, which leads to +# inconsistent indentation and thus invalid Python. +def markdown_skipped_unindented_with_inconsistent_indentation(): + """ + Do cool stuff. + + ```py + cool_stuff( 1 ) + cool_stuff( 2 ) + ``` + + Done. + """ + pass + + +def markdown_skipped_doctest(): + """ + Do cool stuff. + + ```py + >>> cool_stuff( 1 ) + ``` + + Done. + """ + pass + + +def markdown_skipped_rst_literal(): + """ + Do cool stuff. + + ```py + And do this:: + + cool_stuff( 1 ) + + ``` + + Done. + """ + pass + + +def markdown_skipped_rst_directive(): + """ + Do cool stuff. + + ```py + .. code-block:: python + + cool_stuff( 1 ) + + ``` + + Done. + """ + pass +``` + + diff --git a/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_dynamic_line_width.py.snap b/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_dynamic_line_width.py.snap new file mode 100644 index 0000000000..91c1984124 --- /dev/null +++ b/crates/ruff_python_formatter/tests/snapshots/format@docstring_code_examples_dynamic_line_width.py.snap @@ -0,0 +1,1630 @@ +--- +source: crates/ruff_python_formatter/tests/fixtures.rs +input_file: crates/ruff_python_formatter/resources/test/fixtures/ruff/docstring_code_examples_dynamic_line_width.py +--- +## Input +```python +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + self.x = doit( 5 ) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + +```py +class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + self.x = doit( 5 ) +``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + +```py +class Abcdefghijklmopqrstuvwxyz(Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5): + def abcdefghijklmnopqrstuvwxyz(self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + def abcdefghijklmnopqrstuvwxyz(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + self.x = doit( 5 ) +``` + + Done. + """ + pass +``` + +## Outputs +### Output 1 +``` +indent-style = space +line-width = 88 +indent-width = 4 +quote-style = Double +line-ending = LineFeed +magic-trailing-comma = Respect +docstring-code = Enabled +docstring-code-line-width = "dynamic" +preview = Disabled +``` + +```python +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678 + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678 + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass +``` + + +### Output 2 +``` +indent-style = space +line-width = 88 +indent-width = 2 +quote-style = Double +line-ending = LineFeed +magic-trailing-comma = Respect +docstring-code = Enabled +docstring-code-line-width = "dynamic" +preview = Disabled +``` + +```python +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass +``` + + +### Output 3 +``` +indent-style = tab +line-width = 88 +indent-width = 4 +quote-style = Double +line-ending = LineFeed +magic-trailing-comma = Respect +docstring-code = Enabled +docstring-code-line-width = "dynamic" +preview = Disabled +``` + +```python +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678 + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print(abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a567) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + def abcdefghijklmnopqrstuvwxyz( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4 + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, ddef, ghi, jkl, mno, pqr, stu, vwx, yz, a1, a2, a3, a4, a5678 + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass +``` + + +### Output 4 +``` +indent-style = tab +line-width = 88 +indent-width = 8 +quote-style = Double +line-ending = LineFeed +magic-trailing-comma = Respect +docstring-code = Enabled +docstring-code-line-width = "dynamic" +preview = Disabled +``` + +```python +def simple(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we double everything up to ensure the indent level is +# tracked correctly. +def repeated(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like simple, but we make one line exactly one character longer than the limit +# (for 4-space indents) and make sure it gets wrapped. +def barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a5678, + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# This tests that if the code block is unindented, that it gets indented and +# the dynamic line width setting is applied correctly. +def unindented(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is just one character shy of + # tripping the default line width of 88. So it should not be + # wrapped. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a567, + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass + + +# Like unindented, but contains a `print` line where it just barely exceeds the +# globally configured line width *after* its indentation has been corrected. +def unindented_barely_exceeds_limit(): + """ + First line. + + ```py + class Abcdefghijklmopqrstuvwxyz( + Abc, Def, Ghi, Jkl, Mno, Pqr, Stu, Vwx, Yz, A1, A2, A3, A4, A5 + ): + def abcdefghijklmnopqrstuvwxyz( + self, + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + def abcdefghijklmnopqrstuvwxyz( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + ): + # For 4 space indents, this is 89 columns, which is one + # more than the limit. Therefore, it should get wrapped for + # indent_width >= 4. + print( + abc, + ddef, + ghi, + jkl, + mno, + pqr, + stu, + vwx, + yz, + a1, + a2, + a3, + a4, + a5678, + ) + return 5 + + self.x = doit(5) + ``` + + Done. + """ + pass +``` + + +