From 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sat, 14 Nov 2026 18:44:23 +0100 Subject: docs(core): standardize reST docstrings Expand function and method documentation with consistent reST parameter, return, and exception fields while clarifying behavior where additional context is useful. Normalize test and migration docstrings to the same documentation conventions. --- tests/test_cli.py | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) (limited to 'tests/test_cli.py') diff --git a/tests/test_cli.py b/tests/test_cli.py index 8fa61d5..49494d2 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -43,7 +43,10 @@ def database_app(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Fl def _script_directory() -> ScriptDirectory: - """Open the migration scripts configured for this application.""" + """Open the migration scripts configured for this application. + + :returns: Configured Alembic script directory for the application. + """ return ScriptDirectory(str(migrate.directory)) @@ -229,7 +232,10 @@ def test_create_db_preserves_logging( def test_upgrade_backfills_portable_digest_for_existing_received_rows( database_app: Flask, ) -> None: - """Upgrade a pre-fingerprint SQLite database without losing historical rows.""" + """Upgrade a pre-fingerprint SQLite database without losing historical rows. + + :param database_app: Flask application connected to the legacy SQLite schema. + """ from webmentions_ssg.models import received_url_digest with database_app.app_context(): @@ -277,7 +283,10 @@ def test_upgrade_backfills_portable_digest_for_existing_received_rows( def test_upgrade_converts_received_status_without_losing_rows( database_app: Flask, ) -> None: - """An existing text status survives the non-native Enum migration.""" + """Verify that status rows survive conversion to the non-native Enum. + + :param database_app: Flask application connected to the legacy SQLite schema. + """ identifier = "0" * 31 + "1" with database_app.app_context(): migrate_upgrade(revision="e62b1a7c4d90") @@ -389,7 +398,12 @@ def test_mail_cli_reports_smtp_failure(app: Flask) -> None: def _add_user(app: Flask, username: str, password: str = "original") -> None: - """Persist a user using the same model as the CLI.""" + """Persist a user using the same model as the CLI. + + :param app: Flask application in which to create the user. + :param username: Username to persist. + :param password: Plain-text password for the test user. + """ with app.app_context(): db.session.add(User(username=username, password=password)) db.session.commit() -- cgit v1.3.1