Fix codeblock dynamic line length calculation for indented examples by MichaReiser · Pull Request #13523 · astral-sh/ruff

MichaReiser · 2024-09-26T13:20:52Z

Summary

This PR fixes the line-length calculation for the mode dynamic for docstring code blocks.

def length(numbers: list[int]) -> int:
    """Get the length of the given list of numbers.

    Example:
        >>> length([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20])
        20
    """
    return len(numbers)

The current implementation only accounted for the docstring's indent and the space taken by the >>> but it didn't account for the indent inside the docstring (for spaces relative to Example). This PR changes the line length calculation to consider the relative indent.

Fixes #13358

Test Plan

I added a few new tests that and they demonstrate that the lines remain collapsed but expand in preview mode (with the fix).

I reviewed all ecosystem changes and they look correct. Many of those docstrings also have E501 suppressions that won't be needed with the fix.

github-actions · 2024-09-26T13:31:24Z

`ruff-ecosystem` results

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

ℹ️ ecosystem check detected format changes. (+20 -6 lines in 4 files in 3 projects; 51 projects unchanged)

apache/airflow (+3 -1 lines across 1 file)

ruff format --preview

airflow/models/baseoperator.py~L1264

             # This is equivalent to
             with DAG(...):
                 generate_content = GenerateContentOperator(task_id="generate_content")
-                send_email = EmailOperator(..., html_content="{{ task_instance.xcom_pull('generate_content') }}")
+                send_email = EmailOperator(
+                    ..., html_content="{{ task_instance.xcom_pull('generate_content') }}"
+                )
                 generate_content >> send_email
 
         """

pandas-dev/pandas (+14 -4 lines across 2 files)

ruff format --preview

pandas/core/arrays/base.py~L1793

                # type for the array, to the physical storage type for
                # the data, before passing to take.
 
-               result = take(data, indices, fill_value=fill_value, allow_fill=allow_fill)
+               result = take(
+                   data, indices, fill_value=fill_value, allow_fill=allow_fill
+               )
                return self._from_sequence(result, dtype=self.dtype)
         """  # noqa: E501
         # Implementer note: The `fill_value` parameter should be a user-facing

pandas/plotting/_core.py~L247

     .. plot::
         :context: close-figs
 
-        >>> data = {"length": [1.5, 0.5, 1.2, 0.9, 3], "width": [0.7, 0.2, 0.15, 0.2, 1.1]}
+        >>> data = {
+        ...     "length": [1.5, 0.5, 1.2, 0.9, 3],
+        ...     "width": [0.7, 0.2, 0.15, 0.2, 1.1],
+        ... }
         >>> index = ["pig", "rabbit", "duck", "chicken", "horse"]
         >>> df = pd.DataFrame(data, index=index)
         >>> hist = df.hist(bins=3)

pandas/plotting/_core.py~L833

         :context: close-figs
 
         >>> df = pd.DataFrame(
-        ...     {"length": [1.5, 0.5, 1.2, 0.9, 3], "width": [0.7, 0.2, 0.15, 0.2, 1.1]},
+        ...     {
+        ...         "length": [1.5, 0.5, 1.2, 0.9, 3],
+        ...         "width": [0.7, 0.2, 0.15, 0.2, 1.1],
+        ...     },
         ...     index=["pig", "rabbit", "duck", "chicken", "horse"],
         ... )
         >>> plot = df.plot(title="DataFrame Plot")

pandas/plotting/_core.py~L1614

             ...         "signups": [5, 5, 6, 12, 14, 13],
             ...         "visits": [20, 42, 28, 62, 81, 50],
             ...     },
-            ...     index=pd.date_range(start="2018/01/01", end="2018/07/01", freq="ME"),
+            ...     index=pd.date_range(
+            ...         start="2018/01/01", end="2018/07/01", freq="ME"
+            ...     ),
             ... )
             >>> ax = df.plot.area()

pytest-dev/pytest (+3 -1 lines across 1 file)

ruff format --preview

src/_pytest/python_api.py~L858

 
        Given that ``pytest.raises`` matches subclasses, be wary of using it to match :class:`Exception` like this::
 
-           with pytest.raises(Exception):  # Careful, this will catch ANY exception raised.
+           with pytest.raises(
+               Exception
+           ):  # Careful, this will catch ANY exception raised.
                some_function()
 
        Because :class:`Exception` is the base class of almost all exceptions, it is easy for this to hide

BurntSushi · 2024-09-26T17:34:51Z

crates/ruff_python_formatter/src/preview.rs

+    context: &PyFormatContext,
+) -> bool {
+    context.is_preview()
+}


How come this is treated as a new style instead of a bug fix? (Sorry, I'm probably out of step with what our policy is here.)

The formatter versioning policy is rather strict:

The stable style changed to prevent invalid syntax, changes to the program's semantics, or removal of comments

It only allows hard correctness errors. The only other permitted changes are bug fixes that don't change any already formatted code. For example, we can fix a bug where the formatter incorrectly collapses two blank lines to one instead of preserving one or two.

The motivation for this strict rule is that a ruff format --check command shouldn't start failing between patch versions for already formatted code.

##### [`v0.6.9](https://github.com/astral-sh/ruff/blob/HEAD/CHANGELOG.md#069) ##### Preview features - Fix codeblock dynamic line length calculation for indented docstring examples ([#13523](astral-sh/ruff#13523)) - \[`refurb`] Mark `FURB118` fix as unsafe ([#13613](astral-sh/ruff#13613)) ##### Rule changes - \[`pydocstyle`] Don't raise `D208` when last line is non-empty ([#13372](astral-sh/ruff#13372)) - \[`pylint`] Preserve trivia (i.e. comments) in `PLR5501` autofix ([#13573](astral-sh/ruff#13573)) ##### Configuration - \[`pyflakes`] Add `allow-unused-imports` setting for `unused-import` rule (`F401`) ([#13601](astral-sh/ruff#13601)) ##### Bug fixes - Support ruff discovery in pip build environments ([#13591](astral-sh/ruff#13591)) - \[`flake8-bugbear`] Avoid short circuiting `B017` for multiple context managers ([#13609](astral-sh/ruff#13609)) - \[`pylint`] Do not offer an invalid fix for `PLR1716` when the comparisons contain parenthesis ([#13527](astral-sh/ruff#13527)) - \[`pyupgrade`] Fix `UP043` to apply to `collections.abc.Generator` and `collections.abc.AsyncGenerator` ([#13611](astral-sh/ruff#13611)) - \[`refurb`] Fix handling of slices in tuples for `FURB118`, e.g., `x[:, 1]` ([#13518](astral-sh/ruff#13518)) ##### Documentation - Update GitHub Action link to `astral-sh/ruff-action` ([#13551](astral-sh/ruff#13551))

##### v0.6.9 (`https://github.com/astral-sh/ruff/blob/HEAD/CHANGELOG.md#069`) ##### Preview features - Fix codeblock dynamic line length calculation for indented docstring examples ([#13523](astral-sh/ruff#13523)) - \[`refurb`] Mark `FURB118` fix as unsafe ([#13613](astral-sh/ruff#13613)) ##### Rule changes - \[`pydocstyle`] Don't raise `D208` when last line is non-empty ([#13372](astral-sh/ruff#13372)) - \[`pylint`] Preserve trivia (i.e. comments) in `PLR5501` autofix ([#13573](astral-sh/ruff#13573)) ##### Configuration - \[`pyflakes`] Add `allow-unused-imports` setting for `unused-import` rule (`F401`) ([#13601](astral-sh/ruff#13601)) ##### Bug fixes - Support ruff discovery in pip build environments ([#13591](astral-sh/ruff#13591)) - \[`flake8-bugbear`] Avoid short circuiting `B017` for multiple context managers ([#13609](astral-sh/ruff#13609)) - \[`pylint`] Do not offer an invalid fix for `PLR1716` when the comparisons contain parenthesis ([#13527](astral-sh/ruff#13527)) - \[`pyupgrade`] Fix `UP043` to apply to `collections.abc.Generator` and `collections.abc.AsyncGenerator` ([#13611](astral-sh/ruff#13611)) - \[`refurb`] Fix handling of slices in tuples for `FURB118`, e.g., `x[:, 1]` ([#13518](astral-sh/ruff#13518)) ##### Documentation - Update GitHub Action link to `astral-sh/ruff-action` ([#13551](astral-sh/ruff#13551))

##### v0.6.9 ##### Preview features - Fix codeblock dynamic line length calculation for indented docstring examples ([#13523](astral-sh/ruff#13523)) - \[`refurb`] Mark `FURB118` fix as unsafe ([#13613](astral-sh/ruff#13613)) ##### Rule changes - \[`pydocstyle`] Don't raise `D208` when last line is non-empty ([#13372](astral-sh/ruff#13372)) - \[`pylint`] Preserve trivia (i.e. comments) in `PLR5501` autofix ([#13573](astral-sh/ruff#13573)) ##### Configuration - \[`pyflakes`] Add `allow-unused-imports` setting for `unused-import` rule (`F401`) ([#13601](astral-sh/ruff#13601)) ##### Bug fixes - Support ruff discovery in pip build environments ([#13591](astral-sh/ruff#13591)) - \[`flake8-bugbear`] Avoid short circuiting `B017` for multiple context managers ([#13609](astral-sh/ruff#13609)) - \[`pylint`] Do not offer an invalid fix for `PLR1716` when the comparisons contain parenthesis ([#13527](astral-sh/ruff#13527)) - \[`pyupgrade`] Fix `UP043` to apply to `collections.abc.Generator` and `collections.abc.AsyncGenerator` ([#13611](astral-sh/ruff#13611)) - \[`refurb`] Fix handling of slices in tuples for `FURB118`, e.g., `x[:, 1]` ([#13518](astral-sh/ruff#13518)) ##### Documentation - Update GitHub Action link to `astral-sh/ruff-action` ([#13551](astral-sh/ruff#13551))

Fix codeblock dynamic line length calculation for indented examples

2d889ad

MichaReiser added formatter Related to the formatter preview Related to preview mode features labels Sep 26, 2024

Discard changes to crates/ruff_python_formatter/src/lib.rs

8189518

MichaReiser marked this pull request as ready for review September 26, 2024 14:52

MichaReiser requested a review from BurntSushi September 26, 2024 14:52

BurntSushi approved these changes Sep 26, 2024

View reviewed changes

MichaReiser merged commit c046101 into main Sep 27, 2024

MichaReiser deleted the micha/fix-docstring-codeblock-dynamic branch September 27, 2024 07:09

BrewTestBot mentioned this pull request Oct 4, 2024

ruff 0.6.9 Homebrew/homebrew-core#192823

Merged

BrewTestBot mentioned this pull request Jan 9, 2025

ruff 0.9.0 Homebrew/homebrew-core#203745

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Fix codeblock dynamic line length calculation for indented examples#13523

Fix codeblock dynamic line length calculation for indented examples#13523
MichaReiser merged 2 commits intomainfrom
micha/fix-docstring-codeblock-dynamic

MichaReiser commented Sep 26, 2024 •

edited

Loading

Uh oh!

github-actions bot commented Sep 26, 2024 •

edited

Loading

Uh oh!

BurntSushi Sep 26, 2024

Uh oh!

MichaReiser Sep 26, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

MichaReiser commented Sep 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

github-actions bot commented Sep 26, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ruff-ecosystem results

Formatter (stable)

Formatter (preview)

Uh oh!

BurntSushi Sep 26, 2024

Choose a reason for hiding this comment

Uh oh!

MichaReiser Sep 26, 2024

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MichaReiser commented Sep 26, 2024 •

edited

Loading

github-actions bot commented Sep 26, 2024 •

edited

Loading

`ruff-ecosystem` results