Replace docformatter with pydocstringformatter

.pre-commit-config.yaml

@@ -10,7 +10,7 @@ ci:
     - check-manifest
     - deptry
     - doc8
-    - docformatter
+    - pydocstringformatter
     - docs
     - interrogate
     - interrogate-docs
@@ -128,9 +128,9 @@ repos:
         additional_dependencies: [uv==0.9.5]
         stages: [pre-commit]
 
-      - id: docformatter
-        name: docformatter
-        entry: uv run --extra=dev -m docformatter --in-place
+      - id: pydocstringformatter
+        name: pydocstringformatter
+        entry: uv run --extra=dev pydocstringformatter
         language: python
         types_or: [python]
         # We exclude this file to avoid https://github.com/PyCQA/docformatter/issues/291.

bin/vuforia-cloud-reco.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 
-"""
-Run VWS Cloud Reco CLI.
-"""
+"""Run VWS Cloud Reco CLI."""
 
 from vws_cli.query import vuforia_cloud_reco
 

bin/vuforia-web-services.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 
-"""
-Run VWS CLI.
-"""
+"""Run VWS CLI."""
 
 from vws_cli import vws_group
 

docs/source/__init__.py

@@ -1,3 +1 @@
-"""
-Documentation.
-"""
+"""Documentation."""

docs/source/conf.py

@@ -1,7 +1,5 @@
 #!/usr/bin/env python3
-"""
-Configuration for Sphinx.
-"""
+"""Configuration for Sphinx."""
 
 # pylint: disable=invalid-name
 

pyproject.toml

@@ -42,14 +42,14 @@ optional-dependencies.dev = [
     "deptry==0.24.0",
     "doc8==2.0.0",
     "doccmd==2026.1.23.4",
-    "docformatter==1.7.7",
     "freezegun==1.5.5",
     "furo==2025.12.19",
     "hadolint-bin==2.14.0; sys_platform!='win32'",
     "interrogate==1.7.0",
     "mypy[faster-cache]==1.19.1",
     "mypy-strict-kwargs==2026.1.12",
     "prek==0.3.0",
+    "pydocstringformatter==0.7.3",
     "pylint[spelling]==4.0.4",
     "pyproject-fmt==2.11.1",
     "pyrefly==0.49.0",
@@ -118,8 +118,8 @@ lint.select = [
 lint.ignore = [
     # Ruff warns that this conflicts with the formatter.
     "COM812",
-    # Allow our chosen docstring line-style - no one-line summary.
-    "D200",
+    # Allow our chosen docstring line-style - pydocstringformatter handles formatting
+    # but doesn't enforce D205 (blank line after summary) or D212 (summary on first line).
     "D205",
     "D212",
     # Allow backslashes in a docstring.
@@ -136,6 +136,14 @@ lint.ignore = [
     "S101",
 ]
 
+lint.per-file-ignores."doccmd_*.py" = [
+    # Allow our chosen docstring line-style - pydocstringformatter handles
+    # formatting but docstrings in docs may not match this style.
+    "D200",
+    # Allow asserts in docs.
+    "S101",
+]
+
 lint.per-file-ignores."tests/test_*.py" = [
     # Do not require tests to have a one-line summary.
     "D205",
@@ -260,9 +268,6 @@ spelling-private-dict-file = 'spelling_private_dict.txt'
 # --spelling-private-dict-file option instead of raising a message.
 spelling-store-unknown-words = 'no'
 
-[tool.docformatter]
-make-summary-multi-line = true
-
 [tool.check-manifest]
 
 ignore = [
@@ -340,6 +345,12 @@ enableTypeIgnoreComments = false
 reportUnnecessaryTypeIgnoreComment = true
 typeCheckingMode = "strict"
 
+[tool.pydocstringformatter]
+write = true
+split-summary-body = false
+max-line-length = 75
+linewrap-full-docstring = true
+
 [tool.interrogate]
 fail-under = 100
 omit-covered-files = true

src/vws_cli/__init__.py

@@ -1,6 +1,4 @@
-"""
-A CLI for Vuforia Web Services.
-"""
+"""A CLI for Vuforia Web Services."""
 
 from importlib.metadata import PackageNotFoundError, version
 
@@ -38,9 +36,7 @@
 @click.version_option(version=__version__)
 @beartype
 def vws_group() -> None:
-    """
-    Manage a Vuforia Web Services cloud database.
-    """
+    """Manage a Vuforia Web Services cloud database."""
 
 
 vws_group.add_command(cmd=add_target)

src/vws_cli/commands.py

@@ -456,7 +456,9 @@ def wait_for_target_processed(
     base_vws_url: str,
     timeout_seconds: float,
 ) -> None:
-    """Wait for a target to be "processed". This is done by polling the VWS API."""
+    """Wait for a target to be "processed". This is done by polling the VWS
+    API.
+    """
     vws_client = VWS(
         server_access_key=server_access_key,
         server_secret_key=server_secret_key,

src/vws_cli/options/__init__.py

@@ -1,3 +1 @@
-"""
-Options for the VWS CLI commands.
-"""
+"""Options for the VWS CLI commands."""

src/vws_cli/options/credentials.py

@@ -1,6 +1,4 @@
-"""
-``click`` options regarding credentials.
-"""
+"""``click`` options regarding credentials."""
 
 from collections.abc import Callable
 from typing import Any
@@ -13,9 +11,7 @@
 def server_access_key_option(
     command: Callable[..., Any],
 ) -> Callable[..., Any]:
-    """
-    An option decorator for the Vuforia server access key.
-    """
+    """An option decorator for the Vuforia server access key."""
     return click.option(
         "--server-access-key",
         type=str,
@@ -33,9 +29,7 @@ def server_access_key_option(
 def server_secret_key_option(
     command: Callable[..., Any],
 ) -> Callable[..., Any]:
-    """
-    An option decorator for the Vuforia server secret key.
-    """
+    """An option decorator for the Vuforia server secret key."""
     return click.option(
         "--server-secret-key",
         type=str,
@@ -53,9 +47,7 @@ def server_secret_key_option(
 def client_access_key_option(
     command: Callable[..., Any],
 ) -> Callable[..., Any]:
-    """
-    An option decorator for the Vuforia client access key.
-    """
+    """An option decorator for the Vuforia client access key."""
     return click.option(
         "--client-access-key",
         type=str,
@@ -73,9 +65,7 @@ def client_access_key_option(
 def client_secret_key_option(
     command: Callable[..., Any],
 ) -> Callable[..., Any]:
-    """
-    An option decorator for the Vuforia client secret key.
-    """
+    """An option decorator for the Vuforia client secret key."""
     return click.option(
         "--client-secret-key",
         type=str,

src/vws_cli/options/targets.py

@@ -1,6 +1,4 @@
-"""
-``click`` options regarding targets.
-"""
+"""``click`` options regarding targets."""
 
 from collections.abc import Callable
 from enum import Enum, unique
@@ -20,9 +18,7 @@
 
 @beartype
 def target_name_option(*, required: bool) -> Callable[..., Any]:
-    """
-    An option decorator for choosing a target name.
-    """
+    """An option decorator for choosing a target name."""
     return click.option(
         "--name",
         type=str,
@@ -33,9 +29,7 @@ def target_name_option(*, required: bool) -> Callable[..., Any]:
 
 @beartype
 def target_width_option(*, required: bool) -> Callable[..., Any]:
-    """
-    An option decorator for choosing a target width.
-    """
+    """An option decorator for choosing a target width."""
     option: Callable[..., Any] = click.option(
         "--width",
         type=float,
@@ -47,9 +41,7 @@ def target_width_option(*, required: bool) -> Callable[..., Any]:
 
 @beartype
 def target_image_option(*, required: bool) -> Callable[..., Any]:
-    """
-    An option decorator for choosing a target image.
-    """
+    """An option decorator for choosing a target image."""
     return click.option(
         "--image",
         "image_file_path",
@@ -66,9 +58,7 @@ def target_image_option(*, required: bool) -> Callable[..., Any]:
 
 @unique
 class ActiveFlagChoice(Enum):
-    """
-    Choices for active flag.
-    """
+    """Choices for active flag."""
 
     TRUE = "true"
     FALSE = "false"
@@ -78,9 +68,7 @@ def active_flag_option(
     *,
     allow_none: bool,
 ) -> Callable[..., Any]:
-    """
-    An option decorator for setting a target's active flag.
-    """
+    """An option decorator for setting a target's active flag."""
     if allow_none:
         default = None
         show_default = False

src/vws_cli/query.py

@@ -1,6 +1,4 @@
-"""
-A CLI for the Vuforia Cloud Recognition Service API.
-"""
+"""A CLI for the Vuforia Cloud Recognition Service API."""
 
 import contextlib
 import dataclasses
@@ -34,9 +32,7 @@
 @beartype
 @contextlib.contextmanager
 def _handle_vwq_exceptions() -> Iterator[None]:
-    """
-    Show error messages and catch exceptions from ``VWS-Python``.
-    """
+    """Show error messages and catch exceptions from ``VWS-Python``."""
     try:
         yield
     except BadImageError:
@@ -136,9 +132,7 @@ def vuforia_cloud_reco(
     include_target_data: CloudRecoIncludeTargetData,
     base_vwq_url: str,
 ) -> None:
-    """
-    Make a request to the Vuforia Cloud Recognition Service API.
-    """
+    """Make a request to the Vuforia Cloud Recognition Service API."""
     client = CloudRecoService(
         client_access_key=client_access_key,
         client_secret_key=client_secret_key,

tests/__init__.py

@@ -1,3 +1 @@
-"""
-Tests for the VWS CLI.
-"""
+"""Tests for the VWS CLI."""

tests/conftest.py

@@ -1,6 +1,4 @@
-"""
-``pytest`` fixtures.
-"""
+"""``pytest`` fixtures."""
 
 from collections.abc import Iterator
 
@@ -13,19 +11,15 @@
 
 @beartype
 def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
-    """
-    Apply the beartype decorator to all collected test functions.
-    """
+    """Apply the beartype decorator to all collected test functions."""
     for item in items:
         assert isinstance(item, pytest.Function)
         item.obj = beartype(obj=item.obj)
 
 
 @pytest.fixture(name="mock_database")
 def fixture_mock_database() -> Iterator[VuforiaDatabase]:
-    """
-    Yield a mock ``VuforiaDatabase``.
-    """
+    """Yield a mock ``VuforiaDatabase``."""
     with MockVWS() as mock:
         database = VuforiaDatabase()
         mock.add_database(database=database)
@@ -34,9 +28,7 @@ def fixture_mock_database() -> Iterator[VuforiaDatabase]:
 
 @pytest.fixture
 def vws_client(mock_database: VuforiaDatabase) -> VWS:
-    """
-    Return a VWS client which connects to a mock database.
-    """
+    """Return a VWS client which connects to a mock database."""
     return VWS(
         server_access_key=mock_database.server_access_key,
         server_secret_key=mock_database.server_secret_key,
@@ -48,7 +40,8 @@ def cloud_reco_client(
     mock_database: VuforiaDatabase,
 ) -> CloudRecoService:
     """
-    Return a ``CloudRecoService`` client which connects to a mock database.
+    Return a ``CloudRecoService`` client which connects to a mock
+    database.
     """
     return CloudRecoService(
         client_access_key=mock_database.client_access_key,

tests/test_cli.py

@@ -1,16 +1,12 @@
-"""
-Tests for the VWS CLI.
-"""
+"""Tests for the VWS CLI."""
 
 from click.testing import CliRunner
 
 from vws_cli import vws_group
 
 
 def test_version() -> None:
-    """
-    The CLI version is shown with ``vws --version``.
-    """
+    """The CLI version is shown with ``vws --version``."""
     runner = CliRunner()
     result = runner.invoke(
         cli=vws_group,

tests/test_help.py

@@ -1,6 +1,4 @@
-"""
-Tests for the VWS CLI help.
-"""
+"""Tests for the VWS CLI help."""
 
 import pytest
 from click.testing import CliRunner