Add docformatter pre-commit

adamtheturtle · adamtheturtle · commit 464b398a1290 · 2024-10-08T13:03:05.000+01:00
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -59,7 +59,7 @@ repos:
         files: spelling_private_dict\.txt$
       - id: trailing-whitespace
   - repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.10.0 # Use the ref you want to point at
+    rev: v1.10.0
     hooks:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
@@ -84,6 +84,13 @@ repos:
         types_or: [yaml]
         additional_dependencies: ["uv"]
 
+      - id: docformatter
+        name: docformatter
+        entry: uv run --extra=dev -m docformatter
+        language: python
+        types_or: [python]
+        additional_dependencies: ["uv"]
+
       - id: shellcheck
         name: shellcheck
         entry: uv run --extra=dev shellcheck --shell=bash --exclude=SC1017
diff --git a/conftest.py b/conftest.py
@@ -1,4 +1,6 @@
-"""Setup for Sybil."""
+"""
+Setup for Sybil.
+"""
 
 import io
 import uuid
@@ -31,8 +33,8 @@ def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
 def fixture_make_image_file(
     high_quality_image: io.BytesIO,
 ) -> Generator[None]:
-    """
-    Make an image file available in the test directory.
+    """Make an image file available in the test directory.
+
     The path of this file matches the path in the documentation.
     """
     new_image = Path("high_quality_image.jpg")
@@ -46,8 +48,7 @@ def fixture_make_image_file(
 def fixture_mock_vws(
     monkeypatch: pytest.MonkeyPatch,
 ) -> Generator[None]:
-    """
-    Yield a mock VWS.
+    """Yield a mock VWS.
 
     The keys used here match the keys in the documentation.
     """
diff --git a/docs/source/__init__.py b/docs/source/__init__.py
@@ -1 +1,3 @@
-"""Documentation."""
+"""
+Documentation.
+"""
diff --git a/pyproject.toml b/pyproject.toml
@@ -44,6 +44,7 @@ optional-dependencies.dev = [
     "deptry==0.20.0",
     "doc8==1.1.2",
     "doccmd==2024.10.8.12",
+    "docformatter==1.7.5",
     "freezegun==1.5.1",
     "furo==2024.8.6",
     "interrogate==1.7.0",
@@ -258,6 +259,9 @@ 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 = [
diff --git a/src/vws/exceptions/base_exceptions.py b/src/vws/exceptions/base_exceptions.py
@@ -32,8 +32,7 @@ def response(self) -> Response:
 
 @beartype
 class VWSError(Exception):
-    """
-    Base class for Vuforia Web Services errors.
+    """Base class for Vuforia Web Services errors.
 
     These errors are defined at
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#result-codes.
diff --git a/src/vws/exceptions/custom_exceptions.py b/src/vws/exceptions/custom_exceptions.py
@@ -11,11 +11,11 @@
 
 @beartype
 class OopsAnErrorOccurredPossiblyBadNameError(Exception):
-    """
-    Exception raised when VWS returns an HTML page which says "Oops, an error
-    occurred".
+    """Exception raised when VWS returns an HTML page which says "Oops, an
+    error occurred".
 
-    This has been seen to happen when the given name includes a bad character.
+    This has been seen to happen when the given name includes a bad
+    character.
     """
 
     def __init__(self, response: Response) -> None:
diff --git a/src/vws/exceptions/vws_exceptions.py b/src/vws/exceptions/vws_exceptions.py
@@ -33,8 +33,7 @@ def target_id(self) -> str:
 @beartype
 class FailError(VWSError):
     """
-    Exception raised when Vuforia returns a response with a result code
-    'Fail'.
+    Exception raised when Vuforia returns a response with a result code 'Fail'.
     """
 
 
diff --git a/src/vws/query.py b/src/vws/query.py
@@ -34,7 +34,9 @@
 
 @beartype
 def _get_image_data(image: _ImageType) -> bytes:
-    """Get the data of an image file."""
+    """
+    Get the data of an image file.
+    """
     original_tell = image.tell()
     image.seek(0)
     image_data = image.read()
@@ -72,8 +74,7 @@ def query(
             CloudRecoIncludeTargetData.TOP
         ),
     ) -> list[QueryResult]:
-        """
-        Use the Vuforia Web Query API to make an Image Recognition Query.
+        """Use the Vuforia Web Query API to make an Image Recognition Query.
 
         See
         https://developer.vuforia.com/library/web-api/vuforia-query-web-api
diff --git a/src/vws/reports.py b/src/vws/reports.py
@@ -12,8 +12,7 @@
 @beartype
 @dataclass(frozen=True)
 class DatabaseSummaryReport:
-    """
-    A database summary report.
+    """A database summary report.
 
     See
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
@@ -49,8 +48,7 @@ class TargetStatuses(Enum):
 @beartype
 @dataclass(frozen=True)
 class TargetSummaryReport:
-    """
-    A target summary report.
+    """A target summary report.
 
     See
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
@@ -70,8 +68,7 @@ class TargetSummaryReport:
 @beartype(conf=BeartypeConf(is_pep484_tower=True))
 @dataclass(frozen=True)
 class TargetRecord:
-    """
-    A target record.
+    """A target record.
 
     See
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.
@@ -100,8 +97,7 @@ class TargetData:
 @beartype
 @dataclass(frozen=True)
 class QueryResult:
-    """
-    One query match result.
+    """One query match result.
 
     See
     https://developer.vuforia.com/library/web-api/vuforia-query-web-api.
@@ -114,8 +110,7 @@ class QueryResult:
 @beartype
 @dataclass(frozen=True)
 class TargetStatusAndRecord:
-    """
-    The target status and a target record.
+    """The target status and a target record.
 
     See
     https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.
diff --git a/src/vws/types.py b/src/vws/types.py
@@ -1,4 +1,6 @@
-"""Responses for requests to VWS and VWQ."""
+"""
+Responses for requests to VWS and VWQ.
+"""
 
 from dataclasses import dataclass
 
diff --git a/src/vws/vws.py b/src/vws/vws.py
@@ -53,7 +53,9 @@
 
 @beartype
 def _get_image_data(image: _ImageType) -> bytes:
-    """Get the data of an image file."""
+    """
+    Get the data of an image file.
+    """
     original_tell = image.tell()
     image.seek(0)
     image_data = image.read()
@@ -72,8 +74,7 @@ def _target_api_request(
     request_path: str,
     base_vws_url: str,
 ) -> Response:
-    """
-    Make a request to the Vuforia Target API.
+    """Make a request to the Vuforia Target API.
 
     This uses `requests` to make a request against https://vws.vuforia.com.
 
@@ -160,8 +161,7 @@ def make_request(
         expected_result_code: str,
         content_type: str,
     ) -> Response:
-        """
-        Make a request to the Vuforia Target API.
+        """Make a request to the Vuforia Target API.
 
         This uses `requests` to make a request against Vuforia.
 
@@ -251,8 +251,7 @@ def add_target(
         *,
         active_flag: bool,
     ) -> str:
-        """
-        Add a target to a Vuforia Web Services database.
+        """Add a target to a Vuforia Web Services database.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#add
@@ -326,8 +325,8 @@ def add_target(
         return str(json.loads(s=response.text)["target_id"])
 
     def get_target_record(self, target_id: str) -> TargetStatusAndRecord:
-        """
-        Get a given target's target record from the Target Management System.
+        """Get a given target's target record from the Target Management
+        System.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#target-record.
@@ -383,8 +382,7 @@ def wait_for_target_processed(
         seconds_between_requests: float = 0.2,
         timeout_seconds: float = 60 * 5,
     ) -> None:
-        """
-        Wait up to five minutes (arbitrary) for a target to get past the
+        """Wait up to five minutes (arbitrary) for a target to get past the
         processing stage.
 
         Args:
@@ -428,8 +426,7 @@ def wait_for_target_processed(
             time.sleep(seconds_between_requests)
 
     def list_targets(self) -> list[str]:
-        """
-        List target IDs.
+        """List target IDs.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#details-list.
@@ -461,8 +458,7 @@ def list_targets(self) -> list[str]:
         return list(json.loads(s=response.text)["results"])
 
     def get_target_summary_report(self, target_id: str) -> TargetSummaryReport:
-        """
-        Get a summary report for a target.
+        """Get a summary report for a target.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
@@ -510,8 +506,7 @@ def get_target_summary_report(self, target_id: str) -> TargetSummaryReport:
         )
 
     def get_database_summary_report(self) -> DatabaseSummaryReport:
-        """
-        Get a summary report for the database.
+        """Get a summary report for the database.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#summary-report.
@@ -557,8 +552,7 @@ def get_database_summary_report(self) -> DatabaseSummaryReport:
         )
 
     def delete_target(self, target_id: str) -> None:
-        """
-        Delete a given target.
+        """Delete a given target.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#delete.
@@ -592,8 +586,7 @@ def delete_target(self, target_id: str) -> None:
         )
 
     def get_duplicate_targets(self, target_id: str) -> list[str]:
-        """
-        Get targets which may be considered duplicates of a given target.
+        """Get targets which may be considered duplicates of a given target.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#check.
@@ -641,8 +634,7 @@ def update_target(
         active_flag: bool | None = None,
         application_metadata: str | None = None,
     ) -> None:
-        """
-        Update a target in a Vuforia Web Services database.
+        """Update a target in a Vuforia Web Services database.
 
         See
         https://developer.vuforia.com/library/web-api/cloud-targets-web-services-api#update
diff --git a/tests/__init__.py b/tests/__init__.py
@@ -1 +1,3 @@
-"""Tests for ``vws``."""
+"""
+Tests for ``vws``.
+"""
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -54,7 +54,9 @@ def fixture_image_file(
     tmp_path: Path,
     request: pytest.FixtureRequest,
 ) -> Generator[BinaryIO]:
-    """An image file object."""
+    """
+    An image file object.
+    """
     file = tmp_path / "image.jpg"
     buffer = high_quality_image.getvalue()
     file.write_bytes(data=buffer)
@@ -69,7 +71,9 @@ def image(
     high_quality_image: io.BytesIO,
     image_file: BinaryIO,
 ) -> io.BytesIO | BinaryIO:
-    """An image in any of the types that the API accepts."""
+    """
+    An image in any of the types that the API accepts.
+    """
     if request.param == "high_quality_image":
         return high_quality_image
     return image_file
diff --git a/tests/test_vws.py b/tests/test_vws.py
@@ -80,8 +80,7 @@ def test_add_two_targets(
         vws_client: VWS,
         image: io.BytesIO | BinaryIO,
     ) -> None:
-        """
-        No exception is raised when adding two targets with different names.
+        """No exception is raised when adding two targets with different names.
 
         This demonstrates that the image seek position is not changed.
         """
diff --git a/tests/test_vws_exceptions.py b/tests/test_vws_exceptions.py
@@ -139,8 +139,8 @@ def test_target_name_exist(
     high_quality_image: io.BytesIO,
 ) -> None:
     """
-    A ``TargetNameExist`` exception is raised after adding two targets with
-    the same name.
+    A ``TargetNameExist`` exception is raised after adding two targets with the
+    same name.
     """
     vws_client.add_target(
         name="x",
@@ -166,8 +166,8 @@ def test_project_inactive(
     high_quality_image: io.BytesIO,
 ) -> None:
     """
-    A ``ProjectInactive`` exception is raised if adding a target to an
-    inactive database.
+    A ``ProjectInactive`` exception is raised if adding a target to an inactive
+    database.
     """
     database = VuforiaDatabase(state=States.PROJECT_INACTIVE)
     with MockVWS() as mock:

-Original file line number
+Diff line change
@@ @@ -1 +1,3 @@ @@
 -"""Documentation."""
 +"""
 +Documentation.
 +"""