chore: shorten docstrings and single-line comments to 79 (ruff w505: doc-line-too-long) (#2180)

* split comments across multiple lines when necessary

* chore(tooling): check w505 in tox lint env

* fixes

* chore: remove abstract and other admonitions from test module docstrings

* fixes

* chore: fix more malformatted tables

* chore: fix broken unordered-lists/args

* chore: fix broken unordered-lists/args

* chore: improve docstrings, also for D205

* chore: improve docstrings, also for D205

* chore: fix long or poorly formatted comments

* chore: manually revert and fix docstrings/comments

* fix: bad string formatting fix in unit test

* last batch of manual fixes

* fix

* fix

---------

Co-authored-by: danceratopz <[email protected]>

Author: felix314159

.github/scripts/generate_eip_report.py

@@ -1,4 +1,7 @@
-"""Generate a markdown report of outdated EIP references from the EIP version checker output."""
+"""
+Generate a markdown report of outdated EIP references from the EIP version
+checker output.
+"""
 
 import os
 import re

.vscode/settings.json

@@ -14,7 +14,7 @@
         "editor.defaultFormatter": "esbenp.prettier-vscode"
     },
     "[python]": {
-        "editor.rulers": [100],
+        "editor.rulers": [79, 100],
         "editor.formatOnSave": true,
         "editor.defaultFormatter": "charliermarsh.ruff",
         "editor.codeActionsOnSave": {

pyproject.toml

@@ -129,7 +129,7 @@ line-length = 99
 [tool.ruff.lint]
 select = ["E", "F", "B", "W", "I", "A", "N", "D", "C", "ARG001"]
 fixable = ["I", "B", "E", "F", "W", "D", "C"]
-ignore = ["D205", "D203", "D212", "D415", "C420", "C901"]
+ignore = ["D200", "D205", "D203", "D212", "D415", "C420", "C901"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["ARG001"] # TODO: ethereum/execution-spec-tests#2188

src/cli/check_fixtures.py

@@ -27,14 +27,15 @@ def check_json(json_file_path: Path):
     """
     Check all fixtures in the specified json file:
     1. Load the json file into a pydantic model. This checks there are no
-        Validation errors when loading fixtures into EEST models.
+       Validation errors when loading fixtures into EEST models.
     2. Serialize the loaded pydantic model to "json" (actually python data
-        structures, ready to written as json).
+       structures, ready to written as json).
     3. Load the serialized data back into a pydantic model (to get an updated
-        hash) from step 2.
+       hash) from step 2.
     4. Compare hashes:
         a. Compare the newly calculated hashes from step 2. and 3. and
-        b. If present, compare info["hash"] with the calculated hash from step 2.
+        b. If present, compare info["hash"] with the calculated hash from
+           step 2.
     """
     fixtures: Fixtures = Fixtures.model_validate_json(json_file_path.read_text())
     fixtures_json = to_json(fixtures)
@@ -86,7 +87,9 @@ def check_json(json_file_path: Path):
     help="Stop and raise any exceptions encountered while checking fixtures.",
 )
 def check_fixtures(input_str: str, quiet_mode: bool, stop_on_error: bool):
-    """Perform some checks on the fixtures contained in the specified directory."""
+    """
+    Perform some checks on the fixtures contained in the specified directory.
+    """
     input_path = Path(input_str)
     success = True
     file_count = 0

src/cli/compare_fixtures.py

@@ -1,9 +1,9 @@
 """
 Compare two fixture folders and remove duplicates based on fixture hashes.
 
-This tool reads the .meta/index.json files from two fixture directories and identifies
-fixtures with identical hashes on a test case basis, then removes the duplicates from
-both of the folders. Used within the coverage workflow.
+This tool reads the .meta/index.json files from two fixture directories and
+identifies fixtures with identical hashes on a test case basis, then removes
+the duplicates from both of the folders. Used within the coverage workflow.
 """
 
 import json
@@ -95,8 +95,8 @@ def batch_remove_fixtures_from_files(removals_by_file):
 
 def rewrite_index(folder: Path, index: IndexFile, dry_run: bool):
     """
-    Rewrite the index to the correct index file, or if the test count was reduced to zero,
-    the entire directory is deleted.
+    Rewrite the index to the correct index file, or if the test count was
+    reduced to zero, the entire directory is deleted.
     """
     if len(index.test_cases) > 0:
         # Just rewrite the index
@@ -130,7 +130,9 @@ def main(
     dry_run: bool,
     abort_on_empty_patch: bool,
 ):
-    """Compare two fixture folders and remove duplicates based on fixture hashes."""
+    """
+    Compare two fixture folders and remove duplicates based on fixture hashes.
+    """
     try:
         # Load indices
         base_index = load_index(base)

src/cli/eest/commands/clean.py

@@ -19,18 +19,23 @@
 def clean(all_files: bool, dry_run: bool, verbose: bool):
     """
     Remove all generated files and directories from the repository.
-    If `--all` is specified, the virtual environment and .tox directory will also be removed.
+
+    If `--all` is specified, the virtual environment and .tox directory will
+    also be removed.
 
     Args:
-        all_files (bool): Remove the virtual environment and .tox directory as well.
+        all_files (bool): Remove the virtual environment and .tox directory
+                          as well.
 
         dry_run (bool): Simulate the cleanup without removing files.
 
         verbose (bool): Show verbose output.
 
-    Note: The virtual environment and .tox directory are not removed by default.
+    Note: The virtual environment and .tox directory are not removed by
+    default.
 
-    Example: Cleaning all generated files and directories and show the deleted items.
+    Example: Cleaning all generated files and directories and show the deleted
+    items.
 
         uv run eest clean --all -v
 

src/cli/eest/make/cli.py

@@ -1,11 +1,14 @@
 """
-The `make` CLI streamlines the process of scaffolding tasks, such as generating new test files,
-enabling developers to concentrate on the core aspects of specification testing.
+The `make` CLI streamlines the process of scaffolding tasks, such as generating
+new test files, enabling developers to concentrate on the core aspects of
+specification testing.
 
 
-The module calls the appropriate function for the subcommand. If an invalid subcommand
-is chosen, it throws an error and shows a list of valid subcommands. If no subcommand
-is present, it shows a list of valid subcommands to choose from.
+
+The module calls the appropriate function for the subcommand. If an invalid
+subcommand is chosen, it throws an error and shows a list of valid subcommands.
+If no subcommand is present, it shows a list of valid subcommands to choose
+from.
 """
 
 import click

src/cli/eest/make/commands/__init__.py

@@ -1,7 +1,8 @@
 """
-Holds subcommands for the make command. New subcommands must be created as
-modules and exported from this package, then registered under the make command in
-`cli.py`.
+Holds subcommands for the make command.
+
+New subcommands must be created as modules and exported from this package,
+then registered under the make command in `cli.py`.
 """
 
 from .env import create_default_env

src/cli/eest/make/commands/test.py

@@ -1,9 +1,10 @@
 """
 Provides a CLI command to scaffold a test file.
 
-The `test` command guides the user through a series of prompts to generate a test file
-based on the selected test type, fork, EIP number, and EIP name. The generated test file
-is saved in the appropriate directory with a rendered template using Jinja2.
+The `test` command guides the user through a series of prompts to generate a
+test file based on the selected test type, fork, EIP number, and EIP name. The
+generated test file is saved in the appropriate directory with a rendered
+template using Jinja2.
 """
 
 import os
@@ -38,10 +39,11 @@ def test():
     """
     Generate a new test file for an EIP.
 
-    This function guides the user through a series of prompts to generate a test file
-    for Ethereum execution specifications. The user is prompted to select the type of test,
-    the fork to use, and to provide the EIP number and name. Based on the inputs, a test file
-    is created in the appropriate directory with a rendered template.
+    This function guides the user through a series of prompts to generate a
+    test file for Ethereum execution specifications. The user is prompted to
+    select the type of test, the fork to use, and to provide the EIP number and
+    name. Based on the inputs, a test file is created in the appropriate
+    directory with a rendered template.
 
     Example:
         uv run eest make test

src/cli/eest/quotes.py

@@ -51,5 +51,7 @@ def box_quote(quote):
 
 
 def get_quote():
-    """Return random inspirational quote related to system design formatted in a box."""
+    """
+    Return random inspirational quote formatted in a box.
+    """
     return box_quote(random.choice(make_something_great))