Enable Ruff D (pydocstyle) with pep257 convention

lib/ts_utils/metadata.py

@@ -184,7 +184,7 @@ def is_obsolete(self) -> bool:
 
 
 class NoSuchStubError(ValueError):
-    """Raise NoSuchStubError to indicate that a stubs/{distribution} directory doesn't exist"""
+    """Raise NoSuchStubError to indicate that a stubs/{distribution} directory doesn't exist."""
 
 
 @cache
@@ -302,9 +302,10 @@ def read_metadata(distribution: str) -> StubMetadata:
 
 
 def update_metadata(distribution: str, **new_values: object) -> tomlkit.TOMLDocument:
-    """Updates a distribution's METADATA.toml.
+    """Update a distribution's METADATA.toml.
 
-    Return the updated TOML dictionary for use without having to open the file separately."""
+    Return the updated TOML dictionary for use without having to open the file separately.
+    """
     path = metadata_path(distribution)
     try:
         with path.open("rb") as file:

lib/ts_utils/utils.py

@@ -92,7 +92,6 @@ def venv_python(venv_dir: Path) -> Path:
 @cache
 def parse_requirements() -> Mapping[str, Requirement]:
     """Return a dictionary of requirements from the requirements file."""
-
     with REQUIREMENTS_PATH.open(encoding="UTF-8") as requirements_file:
         stripped_lines = map(strip_comments, requirements_file)
         stripped_more = [li for li in stripped_lines if not li.startswith("-")]

pyproject.toml

@@ -38,6 +38,7 @@ exclude = ["**/test_cases/**/*.py"]
 external = ["F821", "NQA", "Y"]
 select = [
     "B", # flake8-bugbear
+    "D", # pydocstyle
     "FA", # flake8-future-annotations
     "I", # isort
     "PGH", # pygrep-hooks
@@ -74,6 +75,7 @@ select = [
     "PYI064", # `Final[Literal[{literal}]]` can be replaced with a bare Final
 ]
 extend-safe-fixes = [
+    "D200", # One-line docstring should fit on one line
     "UP036", # Remove unnecessary `sys.version_info` blocks
 ]
 ignore = [
@@ -88,11 +90,15 @@ ignore = [
     ###
     # Rules we don't want or don't agree with
     ###
-    # Slower and more verbose https://github.com/astral-sh/ruff/issues/7871
-    "UP038", # Use `X | Y` in `isinstance` call instead of `(X, Y)`
+    # We're not a library, no need to document everything
+    "D1", # Missing docstring in ...
+    # Doesn't support split "summary line"
+    "D205", # 1 blank line required between summary line and description
     # Used for direct, non-subclass type comparison, for example: `type(val) is str`
     # see https://github.com/astral-sh/ruff/issues/6465
     "E721", # Do not compare types, use `isinstance()`
+    # Slower and more verbose https://github.com/astral-sh/ruff/issues/7871
+    "UP038", # Use `X | Y` in `isinstance` call instead of `(X, Y)`
     ###
     # False-positives, but already checked by type-checkers
     ###
@@ -116,11 +122,19 @@ ignore = [
     # Issues with using a star-imported name will be caught by type-checkers.
     "F405", # may be undefined, or defined from star imports
 ]
-# See comment on black's force-exclude config above
 "*_pb2.pyi" = [
+    # Non-autofixable docstring lints on autogenerated modules
+    "D210", # No whitespaces allowed surrounding docstring text
+    # These modify the docstring content other than spaces
+    "D301", # Use r""" if any backslashes in a docstring
+    "D40",
+    # See comment on black's force-exclude config above
     "E501", # Line too long
 ]
 
+[tool.ruff.lint.pydocstyle]
+convention = "pep257" # https://docs.astral.sh/ruff/settings/#lint_pydocstyle_convention
+
 [tool.ruff.lint.isort]
 split-on-trailing-comma = false
 combine-as-imports = true

scripts/sync_protobuf/_utils.py

@@ -33,7 +33,7 @@ def extract_archive(archive_path: StrPath, destination: StrPath) -> None:
 def run_protoc(
     proto_paths: Iterable[StrPath], mypy_out: StrPath, proto_globs: Iterable[str], cwd: StrOrBytesPath | None = None
 ) -> str:
-    """TODO: Describe parameters and return"""
+    """TODO: Describe parameters and return."""
     protoc_version = (
         subprocess.run([sys.executable, "-m", "grpc_tools.protoc", "--version"], capture_output=True).stdout.decode().strip()
     )

scripts/sync_protobuf/google_protobuf.py

@@ -31,7 +31,7 @@
 
 
 def extract_python_version(file_path: Path) -> str:
-    """Extract the Python version from https://github.com/protocolbuffers/protobuf/blob/main/version.json"""
+    """Extract the Python version from https://github.com/protocolbuffers/protobuf/blob/main/version.json ."""
     with open(file_path) as file:
         data: dict[str, Any] = json.load(file)
     # The root key will be the protobuf source code version
@@ -44,7 +44,7 @@ def extract_proto_file_paths(temp_dir: Path) -> list[str]:
     """
     Roughly reproduce the subset of .proto files on the public interface
     as described in py_proto_library calls in
-    https://github.com/protocolbuffers/protobuf/blob/main/python/dist/BUILD.bazel
+    https://github.com/protocolbuffers/protobuf/blob/main/python/dist/BUILD.bazel .
     """
     with open(temp_dir / EXTRACTED_PACKAGE_DIR / "python" / "dist" / "BUILD.bazel") as file:
         matched_lines = filter(None, (re.search(PROTO_FILE_PATTERN, line) for line in file))

scripts/sync_protobuf/s2clientprotocol.py

@@ -29,7 +29,7 @@
 
 
 def extract_python_version(file_path: Path) -> str:
-    """Extract Python version from s2clientprotocol's build file"""
+    """Extract Python version from s2clientprotocol's build file."""
     match = re.search(VERSION_PATTERN, file_path.read_text())
     assert match
     return match.group(1)

scripts/sync_protobuf/tensorflow.py

@@ -56,14 +56,15 @@
 def move_tree(source: Path, destination: Path) -> None:
     """Move directory and merge if destination already exists.
 
-    Can't use shutil.move because it can't merge existing directories."""
+    Can't use shutil.move because it can't merge existing directories.
+    """
     print(f"Moving '{source}' to '{destination}'")
     shutil.copytree(source, destination, dirs_exist_ok=True)
     shutil.rmtree(source)
 
 
 def post_creation() -> None:
-    """Move third-party and fix imports"""
+    """Move third-party and fix imports."""
     print()
     move_tree(STUBS_FOLDER / "tsl", STUBS_FOLDER / "tensorflow" / "tsl")
     move_tree(STUBS_FOLDER / "xla", STUBS_FOLDER / "tensorflow" / "compiler" / "xla")

stubs/s2clientprotocol/s2clientprotocol/raw_pb2.pyi

@@ -92,9 +92,7 @@ global___CloakState = CloakState
 
 @typing.final
 class StartRaw(google.protobuf.message.Message):
-    """
-    Start
-    """
+    """Start"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -145,9 +143,7 @@ global___StartRaw = StartRaw
 
 @typing.final
 class ObservationRaw(google.protobuf.message.Message):
-    """
-    Observation
-    """
+    """Observation"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -580,9 +576,7 @@ global___Effect = Effect
 
 @typing.final
 class ActionRaw(google.protobuf.message.Message):
-    """
-    Action
-    """
+    """Action"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 

stubs/s2clientprotocol/s2clientprotocol/sc2api_pb2.pyi

@@ -86,9 +86,7 @@ class _DifficultyEnumTypeWrapper(google.protobuf.internal.enum_type_wrapper._Enu
     CheatInsane: _Difficulty.ValueType  # 10
 
 class Difficulty(_Difficulty, metaclass=_DifficultyEnumTypeWrapper):
-    """
-    Game Setup
-    """
+    """Game Setup"""
 
 VeryEasy: Difficulty.ValueType  # 1
 Easy: Difficulty.ValueType  # 2
@@ -218,9 +216,7 @@ global___Result = Result
 
 @typing.final
 class Request(google.protobuf.message.Message):
-    """
-    Request/Response
-    """
+    """Request/Response"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -1784,9 +1780,7 @@ global___PlayerInfo = PlayerInfo
 
 @typing.final
 class PlayerCommon(google.protobuf.message.Message):
-    """
-    During Game
-    """
+    """During Game"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 

stubs/s2clientprotocol/s2clientprotocol/spatial_pb2.pyi

@@ -23,9 +23,7 @@ DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
 
 @typing.final
 class ObservationFeatureLayer(google.protobuf.message.Message):
-    """
-    Observation - Feature Layer
-    """
+    """Observation - Feature Layer"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -304,9 +302,7 @@ global___FeatureLayersMinimap = FeatureLayersMinimap
 
 @typing.final
 class ObservationRender(google.protobuf.message.Message):
-    """
-    Observation - Rendered
-    """
+    """Observation - Rendered"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -329,9 +325,7 @@ global___ObservationRender = ObservationRender
 
 @typing.final
 class ActionSpatial(google.protobuf.message.Message):
-    """
-    Action
-    """
+    """Action"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 

stubs/s2clientprotocol/s2clientprotocol/ui_pb2.pyi

@@ -22,9 +22,7 @@ DESCRIPTOR: google.protobuf.descriptor.FileDescriptor
 
 @typing.final
 class ObservationUI(google.protobuf.message.Message):
-    """
-    Observation
-    """
+    """Observation"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 
@@ -250,9 +248,7 @@ global___ProductionPanel = ProductionPanel
 
 @typing.final
 class ActionUI(google.protobuf.message.Message):
-    """
-    Action
-    """
+    """Action"""
 
     DESCRIPTOR: google.protobuf.descriptor.Descriptor
 

stubs/tensorflow/tensorflow/compiler/xla/tsl/protobuf/test_log_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protocol messages for describing the results of benchmarks and unit tests."""
+Protocol messages for describing the results of benchmarks and unit tests.
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/core/example/example_parser_configuration_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protocol messages for describing the configuration of the ExampleParserOp."""
+Protocol messages for describing the configuration of the ExampleParserOp.
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/core/framework/tensor_shape_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protocol buffer representing the shape of tensors."""
+Protocol buffer representing the shape of tensors.
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/core/framework/tensor_slice_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protocol buffer representing slices of a tensor"""
+Protocol buffer representing slices of a tensor
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/core/protobuf/cluster_pb2.pyi

@@ -34,7 +34,6 @@ class JobDef(google.protobuf.message.Message):
 
     EXAMPLES
     --------
-
     1. A single-process cluster, containing "/job:local/task:0".
 
        Cluster:

stubs/tensorflow/tensorflow/core/protobuf/device_filters_pb2.pyi

@@ -40,7 +40,6 @@ class TaskDeviceFilters(google.protobuf.message.Message):
 
     EXAMPLES
     --------
-
     A two-job cluster with the following ClusterDef:
 
      Cluster:

stubs/tensorflow/tensorflow/core/util/test_log_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protocol messages for describing the results of benchmarks and unit tests."""
+Protocol messages for describing the results of benchmarks and unit tests.
+"""
 
 import google.protobuf.descriptor
 from tensorflow.compiler.xla.tsl.protobuf.test_log_pb2 import (

stubs/tensorflow/tensorflow/python/keras/protobuf/saved_metadata_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-Protobuf containing the metadata for each Keras object saved in a SavedModel."""
+Protobuf containing the metadata for each Keras object saved in a SavedModel.
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/tsl/protobuf/dnn_pb2.pyi

@@ -1,7 +1,8 @@
 """
 @generated by mypy-protobuf.  Do not edit manually!
 isort:skip_file
-LINT: LEGACY_NAMES"""
+LINT: LEGACY_NAMES
+"""
 
 import builtins
 import collections.abc

stubs/tensorflow/tensorflow/tsl/protobuf/error_codes_pb2.pyi

@@ -152,7 +152,6 @@ class Code(_Code, metaclass=_CodeEnumTypeWrapper):
     """The canonical error codes for TensorFlow APIs.
 
     Warnings:
-
     -   Do not change any numeric assignments.
     -   Changes to this list should only be made if there is a compelling
         need that can't be satisfied in another way.  Such changes

tests/mypy_test.py

@@ -62,7 +62,7 @@ class CommandLineArgs:
 
 
 def valid_path(cmd_arg: str) -> Path:
-    """Helper function for argument-parsing"""
+    """Helper function for argument-parsing."""  # noqa: D401
     path = Path(cmd_arg)
     if not path.exists():
         raise argparse.ArgumentTypeError(f'"{path}" does not exist in typeshed!')
@@ -72,7 +72,7 @@ def valid_path(cmd_arg: str) -> Path:
 
 
 def remove_dev_suffix(version: str) -> str:
-    """Helper function for argument-parsing"""
+    """Helper function for argument-parsing."""  # noqa: D401
     if version.endswith("-dev"):
         return version[: -len("-dev")]
     return version
@@ -303,7 +303,6 @@ def test_third_party_distribution(
     Return a tuple, where the first element indicates mypy's return code
     and the second element is the number of checked files.
     """
-
     files: list[Path] = []
     configurations: list[MypyDistConf] = []
     seen_dists: set[str] = set()

tests/pytype_test.py

@@ -74,7 +74,7 @@ def create_parser() -> argparse.ArgumentParser:
 
 
 def run_pytype(*, filename: str, python_version: str, missing_modules: Iterable[str]) -> str | None:
-    """Runs pytype, returning the stderr if any."""
+    """Run pytype, returning the stderr if any."""
     if python_version not in _LOADERS:
         options = pytype_config.Options.create("", parse_pyi=True, python_version=python_version)
         # For simplicity, pretends missing modules are part of the stdlib.
@@ -107,7 +107,7 @@ def _get_relative(filename: str) -> str:
 
 
 def _get_module_name(filename: str) -> str:
-    """Converts a filename {subdir}/m.n/module/foo to module.foo."""
+    """Convert a filename {subdir}/m.n/module/foo to module.foo."""
     parts = _get_relative(filename).split(os.path.sep)
     if parts[0] == "stdlib":
         module_parts = parts[1:]