Merge pull request #2793 from VWS-Python/switch-to-pydocstringformatter

Switch from docformatter to pydocstringformatter

Author: adamtheturtle

.pre-commit-config.yaml

@@ -13,7 +13,7 @@ ci:
     - check-manifest
     - deptry
     - doc8
-    - docformatter
+    - pydocstringformatter
     - docs
     - interrogate
     - interrogate-docs
@@ -104,9 +104,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]
         additional_dependencies: [uv==0.9.5]

conftest.py

@@ -1,6 +1,4 @@
-"""
-Setup for Sybil.
-"""
+"""Setup for Sybil."""
 
 import io
 import uuid
@@ -21,9 +19,7 @@
 
 
 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:
         if isinstance(item, pytest.Function):
             item.obj = beartype(obj=item.obj)

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."""
 
 import importlib.metadata
 from pathlib import Path

pyproject.toml

@@ -42,13 +42,13 @@ optional-dependencies.dev = [
     "deptry==0.24.0",
     "doc8==2.0.0",
     "doccmd==2026.1.22.1",
-    "docformatter==1.7.7",
     "freezegun==1.5.5",
     "furo==2025.12.19",
     "interrogate==1.7.0",
     "mypy[faster-cache]==1.19.1",
     "mypy-strict-kwargs==2026.1.12",
     "prek==0.3.0",
+    "pydocstringformatter==0.7.3",
     "pydocstyle==6.3",
     "pygments==2.19.2",
     "pylint[spelling]==4.0.4",
@@ -119,8 +119,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",
     # Ruff warns that this conflicts with the formatter.
@@ -274,9 +274,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 = [
@@ -346,6 +343,15 @@ enableTypeIgnoreComments = false
 reportUnnecessaryTypeIgnoreComment = true
 typeCheckingMode = "strict"
 
+[tool.pydocstringformatter]
+write = true
+split-summary-body = false
+# Use a lower line length than ruff (79) to avoid conflicts with D200 -
+# pydocstringformatter would otherwise split docstrings at exactly 79 chars
+# which ruff considers should stay on one line.
+max-line-length = 75
+linewrap-full-docstring = true
+
 [tool.interrogate]
 fail-under = 100
 omit-covered-files = true

src/vws/__init__.py

@@ -1,6 +1,4 @@
-"""
-A library for Vuforia Web Services.
-"""
+"""A library for Vuforia Web Services."""
 
 from .query import CloudRecoService
 from .vws import VWS

src/vws/exceptions/__init__.py

@@ -1,3 +1 @@
-"""
-Custom exceptions raised by this package.
-"""
+"""Custom exceptions raised by this package."""

src/vws/exceptions/base_exceptions.py

@@ -1,5 +1,6 @@
 """
-Base exceptions for errors returned by Vuforia Web Services or the Vuforia
+Base exceptions for errors returned by Vuforia Web Services or the
+Vuforia
 Cloud Recognition Web API.
 """
 
@@ -10,9 +11,7 @@
 
 @beartype
 class CloudRecoError(Exception):
-    """
-    Base class for Vuforia Cloud Recognition Web API exceptions.
-    """
+    """Base class for Vuforia Cloud Recognition Web API exceptions."""
 
     def __init__(self, response: Response) -> None:
         """
@@ -24,9 +23,7 @@ def __init__(self, response: Response) -> None:
 
     @property
     def response(self) -> Response:
-        """
-        The response returned by Vuforia which included this error.
-        """
+        """The response returned by Vuforia which included this error."""
         return self._response
 
 
@@ -48,7 +45,5 @@ def __init__(self, response: Response) -> None:
 
     @property
     def response(self) -> Response:
-        """
-        The response returned by Vuforia which included this error.
-        """
+        """The response returned by Vuforia which included this error."""
         return self._response

src/vws/exceptions/cloud_reco_exceptions.py

@@ -1,5 +1,6 @@
-"""
-Exceptions which match errors raised by the Vuforia Cloud Recognition Web APIs.
+"""Exceptions which match errors raised by the Vuforia Cloud Recognition
+Web
+APIs.
 """
 
 from beartype import beartype
@@ -17,31 +18,27 @@ class MaxNumResultsOutOfRangeError(CloudRecoError):
 
 @beartype
 class InactiveProjectError(CloudRecoError):
-    """
-    Exception raised when Vuforia returns a response with a result code
+    """Exception raised when Vuforia returns a response with a result code
     'InactiveProject'.
     """
 
 
 @beartype
 class BadImageError(CloudRecoError):
-    """
-    Exception raised when Vuforia returns a response with a result code
+    """Exception raised when Vuforia returns a response with a result code
     'BadImage'.
     """
 
 
 @beartype
 class AuthenticationFailureError(CloudRecoError):
-    """
-    Exception raised when Vuforia returns a response with a result code
+    """Exception raised when Vuforia returns a response with a result code
     'AuthenticationFailure'.
     """
 
 
 @beartype
 class RequestTimeTooSkewedError(CloudRecoError):
-    """
-    Exception raised when Vuforia returns a response with a result code
+    """Exception raised when Vuforia returns a response with a result code
     'RequestTimeTooSkewed'.
     """

src/vws/exceptions/custom_exceptions.py

@@ -1,7 +1,7 @@
-"""
-Exceptions which do not map to errors at
+"""Exceptions which do not map to errors at the following URL, or simple
+errors given by the cloud recognition service.
+
 https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#result-codes
-or simple errors given by the cloud recognition service.
 """
 
 from beartype import beartype
@@ -11,9 +11,7 @@
 
 @beartype
 class RequestEntityTooLargeError(Exception):
-    """
-    Exception raised when the given image is too large.
-    """
+    """Exception raised when the given image is too large."""
 
     def __init__(self, response: Response) -> None:
         """
@@ -25,24 +23,20 @@ def __init__(self, response: Response) -> None:
 
     @property
     def response(self) -> Response:
-        """
-        The response returned by Vuforia which included this error.
-        """
+        """The response returned by Vuforia which included this error."""
         return self._response
 
 
 @beartype
 class TargetProcessingTimeoutError(Exception):
-    """
-    Exception raised when waiting for a target to be processed times out.
+    """Exception raised when waiting for a target to be processed times
+    out.
     """
 
 
 @beartype
 class ServerError(Exception):  # pragma: no cover
-    """
-    Exception raised when VWS returns a server error.
-    """
+    """Exception raised when VWS returns a server error."""
 
     def __init__(self, response: Response) -> None:
         """
@@ -54,7 +48,5 @@ def __init__(self, response: Response) -> None:
 
     @property
     def response(self) -> Response:
-        """
-        The response returned by Vuforia which included this error.
-        """
+        """The response returned by Vuforia which included this error."""
         return self._response