Implement no_blank_line_before_class_docstring preview style

[dhruvmanila]

Summary

This PR implements the no_blank_line_before_class_docstring preview style.

Test Plan

Update existing snapshots.

Formatter ecosystem

main

project	similarity index	total files	changed files
cpython	0.75804	1799	1648
django	0.99984	2772	34
home-assistant	0.99955	10596	213
poetry	0.99905	321	15
transformers	0.99967	2657	324
twine	1.00000	33	0
typeshed	0.99980	3669	18
warehouse	0.99976	654	14
zulip	0.99958	1459	36

dhruv/no-blank-line-docstring

project	similarity index	total files	changed files
cpython	0.75804	1799	1648
django	0.99984	2772	34
home-assistant	0.99955	10596	213
poetry	0.99905	321	15
transformers	0.99967	2657	324
twine	1.00000	33	0
typeshed	0.99980	3669	18
warehouse	0.99976	654	14
zulip	0.99958	1459	36

fixes: #8888

[github-actions]

ruff-ecosystem results

Formatter (stable)

✅ ecosystem check detected no format changes.

Formatter (preview)

ℹ️ ecosystem check encountered format errors. (no format changes; 0 project errors)

demisto/content (+0 -2 lines across 2 files)

ruff format --preview --exclude Packs/ThreatQ/Integrations/ThreatQ/ThreatQ.py

Packs/Automox/Integrations/Automox/Automox.py~L42

 
 
 class Client(BaseClient):
-
     """Client class to interact with the service API
 
     This Client implements API calls, and does not contain any XSOAR logic.

Packs/MS-ISAC/Integrations/MSISAC/MSISAC.py~L13

 
 
 class Client(BaseClient):
-
     """
     This client class for MS-ISAC definies two API endpoints
     Query events in a set amount of days /albert/{days}

freedomofpress/securedrop (+0 -13 lines across 8 files)

ruff format --preview

securedrop/models.py~L336

 
 
 class InvalidUsernameException(Exception):
-
     """Raised when a user logs in with an invalid username"""
 
 

securedrop/models.py~L355

 
 
 class LoginThrottledException(Exception):
-
     """Raised when a user attempts to log in
     too many times in a given time period"""
 
 
 class WrongPasswordException(Exception):
-
     """Raised when a user logs in with an incorrect password"""
 
 
 class PasswordError(Exception):
-
     """Generic error for passwords that are invalid."""
 
 

securedrop/models.py~L387

 
 
 class NonDicewarePassword(PasswordError):
-
     """Raised when attempting to validate a password that is not diceware-like"""
 
 

securedrop/models.py~L840

 
 
 class JournalistLoginAttempt(db.Model):
-
     """This model keeps track of journalist's login attempts so we can
     rate limit them in order to prevent attackers from brute forcing
     passwords or two-factor tokens."""

securedrop/tests/migrations/migration_15ac9509fc68.py~L18

 
 
 class UpgradeTester:
-
     """This migration has no upgrade because there are no tables in the
     database prior to running, so there is no data to load or test.
     """

securedrop/tests/migrations/migration_3d91d6948753.py~L12

 
 
 class UpgradeTester:
-
     """This migration verifies that the UUID column now exists, and that
     the data migration completed successfully.
     """

securedrop/tests/migrations/migration_60f41bb14d98.py~L21

 
 
 class UpgradeTester:
-
     """This migration verifies that the session_nonce column now exists, and
     that the data migration completed successfully.
     """

securedrop/tests/migrations/migration_6db892e17271.py~L77

 
 
 class UpgradeTester:
-
     """This migration verifies that the deleted_by_source column now exists,
     and that the data migration completed successfully.
     """

securedrop/tests/migrations/migration_e0a525cbab83.py~L77

 
 
 class UpgradeTester:
-
     """This migration verifies that the deleted_by_source column now exists,
     and that the data migration completed successfully.
     """

securedrop/tests/migrations/migration_f2833ac34bb6.py~L20

 
 
 class UpgradeTester:
-
     """This migration verifies that the UUID column now exists, and that
     the data migration completed successfully.
     """

securedrop/tests/migrations/migration_fccf57ceef02.py~L32

 
 
 class UpgradeTester:
-
     """This migration verifies that the UUID column now exists, and that
     the data migration completed successfully.
     """

mlflow/mlflow (+0 -2 lines across 2 files)

ruff format --preview

mlflow/langchain/retriever_chain.py~L17

 
 @experimental
 class _RetrieverChain(Chain):
-
     """
     Chain that wraps a retriever for use with MLflow.
 

tests/sagemaker/mock/init.py~L707

 
 
 class TransformJob(TimestampedResource):
-
     """
     Object representing a SageMaker transform job. The SageMakerBackend will create
     and manage transform jobs.

pypa/pip (+0 -2 lines across 2 files)

ruff format --preview

src/pip/_internal/index/collector.py~L395

 
 
 class LinkCollector:
-
     """
     Responsible for collecting Link objects from all configured locations,
     making network requests as needed.

src/pip/_internal/utils/logging.py~L212

 
 
 class ExcludeLoggerFilter(Filter):
-
     """
     A logging Filter that excludes records from a logger (or its children).
     """

pypa/setuptools (+0 -2 lines across 1 file)

ruff format --preview

setuptools/_distutils/version.py~L111

 
 
 class StrictVersion(Version):
-
     """Version numbering for anal retentives and software idealists.
     Implements the standard interface for version number classes as
     described above.  A version number consists of two or three

setuptools/_distutils/version.py~L286

 
 
 class LooseVersion(Version):
-
     """Version numbering for anarchists and software realists.
     Implements the standard interface for version number classes as
     described above.  A version number consists of a series of numbers,

python/mypy (+0 -2 lines across 1 file)

ruff format --preview

mypy/main.py~L342

 
 
 class CapturableArgumentParser(argparse.ArgumentParser):
-
     """Override ArgumentParser methods that use sys.stdout/sys.stderr directly.
 
     This is needed because hijacking sys.std* is not thread-safe,

mypy/main.py~L396

 
 
 class CapturableVersionAction(argparse.Action):
-
     """Supplement CapturableArgumentParser to handle --version.
 
     This is nearly identical to argparse._VersionAction except,

[T-256]

It seems ecosystem reported numbers are wrong.
Also, links pointed lines aren't exact.

[MichaReiser]

Could you update your pr summary and include the 'old' compatibility numbers. I don't expect them to change but just to be safe

[MichaReiser]

Can we add a few tests where we have comments before the docstring (including new or empty lines)

[dhruvmanila]

I've tested it out locally with different combinations of comments, newline and docstrings. It seems that the Black preview style is a bit inconsistent with the stable style.

Original source code:

class OneBlankLineDocstring:

    """This is a docstring."""


class DocstringWithComment0:
    # This is a comment
    """This is a docstring."""


class DocstringWithComment1:
    # This is a comment

    """This is a docstring."""


class DocstringWithComment2:

    # This is a comment
    """This is a docstring."""


class DocstringWithComment3:

    # This is a comment

    """This is a docstring."""


class DocstringWithComment4:


    # This is a comment


    """This is a docstring."""

Black stable formatting:

class NormalDocstring:

    """This is a docstring."""


class DocstringWithComment0:
    # This is a comment
    """This is a docstring."""


class DocstringWithComment1:
    # This is a comment

    """This is a docstring."""


class DocstringWithComment2:
    # This is a comment
    """This is a docstring."""


class DocstringWithComment3:
    # This is a comment

    """This is a docstring."""


class DocstringWithComment4:
    # This is a comment

    """This is a docstring."""

Black preview formatting:

class OneBlankLineDocstring:
    """This is a docstring."""


class DocstringWithComment0:
    # This is a comment
    """This is a docstring."""


class DocstringWithComment1:
    # This is a comment

    """This is a docstring."""


class DocstringWithComment2:

    # This is a comment
    """This is a docstring."""


class DocstringWithComment3:

    # This is a comment

    """This is a docstring."""


class DocstringWithComment4:

    # This is a comment

    """This is a docstring."""

What I'm noticing is that the rules change if there's a comment in between the class header and docstring in a way that for n1 and n2 number of blank lines before a comment and docstring respectively the following holds true:

1. If n1 / n2 is 0, keep it 0
2. If n1 / n2 is 1, keep it 1
3. If n1 / n2 > 1, then reduce it to 1

It's probably another preview style which is keeping the newline before the comment (allow_empty_first_line_before_block_or_comment).

[charliermarsh]

The ecosystem line numbers are not guaranteed to be exact (hence the tilde). It’s a diff of two changes against HEAD, so mapping that diff back to a line number in HEAD is not trivial. (Not sure about the “number of lines changed” though.)