diff --git a/pyproject.toml b/pyproject.toml index db4c2ce8..f1480963 100644 --- a/pyproject.toml +++ b/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 diff --git a/src/safir/__init__.py b/src/safir/__init__.py index 682c7dc9..486c9a01 100644 --- a/src/safir/__init__.py +++ b/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. """ diff --git a/src/safir/arq.py b/src/safir/arq.py index 0abac796..1134aa24 100644 --- a/src/safir/arq.py +++ b/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 diff --git a/src/safir/dependencies/arq.py b/src/safir/dependencies/arq.py index af7ab6c0..35daab7e 100644 --- a/src/safir/dependencies/arq.py +++ b/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. +""" diff --git a/src/safir/github/_client.py b/src/safir/github/_client.py index 8a7a532a..cf64e286 100644 --- a/src/safir/github/_client.py +++ b/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 ---------- diff --git a/src/safir/github/models.py b/src/safir/github/models.py index fa268075..4c214571 100644 --- a/src/safir/github/models.py +++ b/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.") diff --git a/src/safir/github/webhooks.py b/src/safir/github/webhooks.py index bfae5949..5815679f 100644 --- a/src/safir/github/webhooks.py +++ b/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" diff --git a/src/safir/redis.py b/src/safir/redis.py index 1234bff2..854568a5 100644 --- a/src/safir/redis.py +++ b/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 diff --git a/tests/redis_test.py b/tests/redis_test.py index 7bed2e2b..b973a32f 100644 --- a/tests/redis_test.py +++ b/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:" )