Revert docstring changes for D205

Our documentation style allows wrapped summary lines longer than a
single line. Disable the corresponding Ruff diagnostic and revert
changes to satisfy that diagnostic.

pyproject.toml

@@ -191,6 +191,7 @@ ignore = [
     "D104",    # don't see the point of documenting every package
     "D105",    # our style doesn't require docstrings for magic methods
     "D106",    # Pydantic uses a nested Config class that doesn't warrant docs
+    "D205",    # our documentation style allows a folded first line
     "EM101",   # justification (duplicate string in traceback) is silly
     "EM102",   # justification (duplicate string in traceback) is silly
     "FBT003",  # positional booleans are normal for Pydantic field defaults

src/safir/__init__.py

@@ -1,6 +1,4 @@
-"""Support library for the Rubin Science Platform.
-
-Safir is the Rubin Observatory's library for building FastAPI services
+"""Safir is the Rubin Observatory's library for building FastAPI services
 for the Rubin Science Platform.
 """
 

src/safir/arq.py

@@ -269,9 +269,7 @@ async def from_job(cls, job: Job) -> Self:
 
 
 class ArqQueue(metaclass=abc.ABCMeta):
-    """arq queue interface supporting either Redis or an in-memory repository.
-
-    Provides a common interface for working with an arq queue that can be
+    """A common interface for working with an arq queue that can be
     implemented either with a real Redis backend, or an in-memory repository
     for testing.
 
@@ -290,9 +288,8 @@ def __init__(
 
     @property
     def default_queue_name(self) -> str:
-        """Name of the default queue.
-
-        Used if the ``_queue_name`` parameter is not set in method calls.
+        """Name of the default queue, if the ``_queue_name`` parameter is not
+        set in method calls.
         """
         return self._default_queue_name
 

src/safir/dependencies/arq.py

@@ -10,11 +10,8 @@
 
 
 class ArqDependency:
-    """FastAPI dependency providing a client for enqueuing tasks.
-
-    This class maintains a singleton Redis client for enqueuing tasks to an
-    arq_ worker pool and provides it to handler methods via the FastAPI
-    dependency interface.
+    """A FastAPI dependency that maintains a Redis client for enqueuing tasks
+    to the worker pool.
     """
 
     def __init__(self) -> None:
@@ -86,4 +83,6 @@ async def __call__(self) -> ArqQueue:
 
 
 arq_dependency = ArqDependency()
-"""Singleton instance of `ArqDependency` as a FastAPI dependency."""
+"""Singleton instance of `ArqDependency` that serves as a FastAPI
+dependency.
+"""

src/safir/github/_client.py

@@ -6,10 +6,8 @@
 
 
 class GitHubAppClientFactory:
-    """Create GitHub App clients.
-
-    Provides a factory for creating GitHub App clients authenticated either as
-    an app or as an installation of that app.
+    """Factory for creating GitHub App clients authenticated either as an app
+    or as an installation of that app.
 
     Parameters
     ----------
@@ -76,10 +74,8 @@ def create_app_client(self) -> GitHubAPI:
     async def create_installation_client(
         self, installation_id: str
     ) -> GitHubAPI:
-        """Create a client for an installation of the GitHub App.
-
-        The resulting client is authenticated as an installation of the GitHub
-        App for a specific repository or organization.
+        """Create a client authenticated as an installation of the GitHub App
+        for a specific repository or organization.
 
         Parameters
         ----------
@@ -106,10 +102,8 @@ async def create_installation_client(
     async def create_installation_client_for_repo(
         self, owner: str, repo: str
     ) -> GitHubAPI:
-        """Create a client for a repository installation of the GitHub App.
-
-        The resulting client is authenticated as an installation of the GitHub
-        App for a specific repository.
+        """Create a client authenticated as an installation of the GitHub App
+        for a specific repository or organization.
 
         Parameters
         ----------

src/safir/github/models.py

@@ -67,9 +67,8 @@ class GitHubUserModel(BaseModel):
 
 
 class GitHubRepositoryModel(BaseModel):
-    """A Pydantic model for the ``repository`` field.
-
-    This field is often found in webhook payloads.
+    """A Pydantic model for the ``repository`` field, often found in webhook
+    payloads.
 
     https://docs.github.com/en/rest/repos/repos#get-a-repository
     """
@@ -271,10 +270,8 @@ class GitHubCheckSuiteConclusion(str, Enum):
 
 
 class GitHubCheckSuiteModel(BaseModel):
-    """A Pydantic model for the ``check_suite`` field.
-
-    This field is found in a ``check_suite`` webhook
-    (`~safir.github.webhooks.GitHubCheckSuiteEventModel`).
+    """A Pydantic model for the ``check_suite`` field in a ``check_suite``
+    webhook (`~safir.github.webhooks.GitHubCheckSuiteEventModel`).
     """
 
     id: str = Field(description="Identifier for this check run.")
@@ -323,7 +320,9 @@ class GitHubCheckRunConclusion(str, Enum):
     """The check run has failed."""
 
     neutral = "neutral"
-    """The check run has a neutral outcome, perhaps because it was skipped."""
+    """The check run has a neutral outcome, perhaps because the check was
+    skipped.
+    """
 
     cancelled = "cancelled"
     """The check run was cancelled."""
@@ -370,9 +369,8 @@ class GitHubCheckRunOutput(BaseModel):
 
 
 class GitHubCheckRunPrInfoModel(BaseModel):
-    """A Pydantic model of the ``pull_requests[]`` items.
-
-    These are found in a check run GitHub API model (`GitHubCheckRunModel`).
+    """A Pydantic model of the ``pull_requests[]`` items in a check run
+    GitHub API model (`GitHubCheckRunModel`).
 
     https://docs.github.com/en/rest/checks/runs#get-a-check-run
     """
@@ -381,10 +379,8 @@ class GitHubCheckRunPrInfoModel(BaseModel):
 
 
 class GitHubCheckRunModel(BaseModel):
-    """A Pydantic model for the ``check_run`` field.
-
-    This is found in a check_run webhook payload
-    (`~safir.github.webhooks.GitHubCheckRunEventModel`).
+    """A Pydantic model for the "check_run" field in a check_run webhook
+    payload (`~safir.github.webhooks.GitHubCheckRunEventModel`).
     """
 
     id: str = Field(description="Identifier for this check run.")

src/safir/github/webhooks.py

@@ -31,18 +31,16 @@
 
 
 class GitHubAppInstallationModel(BaseModel):
-    """A Pydantic model for the ``installation`` field found.
-
-    This field is found in webhook payloads for GitHub Apps.
+    """A Pydantic model for the ``installation`` field found in webhook
+    payloads for GitHub Apps.
     """
 
     id: str = Field(description="The installation ID.")
 
 
 class GitHubPushEventModel(BaseModel):
-    """A Pydantic model for the ``push`` event webhook.
-
-    This webhook is triggered when a commit or tag is pushed.
+    """A Pydantic model for the ``push`` event webhook when a commit or
+    tag is pushed.
 
     https://docs.github.com/en/webhooks/webhook-events-and-payloads#push
     """
@@ -73,10 +71,8 @@ class GitHubPushEventModel(BaseModel):
 
 
 class GitHubAppInstallationEventRepoModel(BaseModel):
-    """A Pydantic model for repository objects used by installation events.
-
-    See `GitHubAppInstallationRepositoriesEventModel` for where this model is
-    used.
+    """A pydantic model for repository objects used by
+    `GitHubAppInstallationRepositoriesEventModel`.
 
     https://docs.github.com/en/webhooks/webhook-events-and-payloads#installation
     """
@@ -98,10 +94,8 @@ def owner_name(self) -> str:
 
 
 class GitHubAppInstallationEventAction(str, Enum):
-    """The action performed on an GitHub App ``installation`` webhook.
-
-    See `GitHubAppInstallationEventModel` for the model of the event where
-    this model is used.
+    """The action performed on an GitHub App ``installation`` webhook
+    (`GitHubAppInstallationEventModel`).
     """
 
     created = "created"
@@ -142,10 +136,8 @@ class GitHubAppInstallationEventModel(BaseModel):
 
 
 class GitHubAppInstallationRepositoriesEventAction(str, Enum):
-    """A Pydantic model for a ``installation_repositories`` action.
-
-    This model is for the action performed on a ``installation_repositories``
-    GitHub App webhook (`GitHubAppInstallationRepositoriesEventModel`).
+    """The action performed on a GitHub App ``installation_repositories``
+    webhook (`GitHubAppInstallationRepositoriesEventModel`).
     """
 
     #: Someone added a repository to an installation.
@@ -179,9 +171,8 @@ class GitHubAppInstallationRepositoriesEventModel(BaseModel):
 
 
 class GitHubPullRequestEventAction(str, Enum):
-    """The action performed on a GitHub ``pull_request`` webhook.
-
-    See `GitHubPullRequestEventModel` for where this model is used.
+    """The action performed on a GitHub ``pull_request`` webhook
+    (`GitHubPullRequestEventModel`).
     """
 
     assigned = "assigned"
@@ -276,9 +267,8 @@ class GitHubPullRequestEventModel(BaseModel):
 
 
 class GitHubCheckSuiteEventAction(str, Enum):
-    """The action performed in a GitHub ``check_suite`` webhook.
-
-    See `GitHubCheckSuiteEventModel` for where this model is used.
+    """The action performed in a GitHub ``check_suite`` webhook
+    (`GitHubCheckSuiteEventModel`).
     """
 
     completed = "completed"
@@ -317,9 +307,8 @@ class GitHubCheckSuiteEventModel(BaseModel):
 
 
 class GitHubCheckRunEventAction(str, Enum):
-    """The action performed in a GitHub ``check_run`` webhook.
-
-    See `GitHubCheckRunEventModel` for where this model is used.
+    """The action performed in a GitHub ``check_run`` webhook
+    (`GitHubCheckRunEventModel`).
     """
 
     completed = "completed"

src/safir/redis.py

@@ -31,9 +31,7 @@
 
 
 class DeserializeError(SlackException):
-    """Error decoding or deserializing a Pydantic object from Redis.
-
-    Raised when a stored Pydantic object in Redis cannot be decoded (and
+    """Raised when a stored Pydantic object in Redis cannot be decoded (and
     possibly decrypted) or deserialized.
 
     Parameters

tests/redis_test.py

@@ -23,7 +23,9 @@ class DemoModel(BaseModel):
 
 
 async def basic_testing(storage: PydanticRedisStorage[DemoModel]) -> None:
-    """Test basic storage operations for encrypted and unencrypted storage."""
+    """Test basic storage operations for either encrypted or unencrypted
+    storage.
+    """
     await storage.store("mark42", DemoModel(name="Mark", value=42))
     await storage.store("mark13", DemoModel(name="Mark", value=13))
     await storage.store("jon7", DemoModel(name="Jon", value=7))
@@ -141,7 +143,9 @@ async def test_deserialization_error(redis_client: redis.Redis) -> None:
 async def test_deserialization_error_with_key_prefix(
     redis_client: redis.Redis,
 ) -> None:
-    """Test deserialization error formatting when a key prefix is used."""
+    """Test that deserialization errors are presented correctly when a key
+    prefix is used.
+    """
     storage = PydanticRedisStorage(
         datatype=DemoModel, redis=redis_client, key_prefix="test:"
     )