diff options
| author | Dennis Fink | 2026-11-14 18:44:23 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-14 18:44:23 +0100 |
| commit | 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 (patch) | |
| tree | 0096a0125c4d94a047e5bd24288e1f3f4a58ada5 /tests | |
| parent | 2366d455c7d1ae16c84e0bcbffb94ed762c16832 (diff) | |
| download | webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.tar.gz webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.zip | |
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.
Diffstat (limited to 'tests')
| -rw-r--r-- | tests/tasks/test_extension.py | 5 | ||||
| -rw-r--r-- | tests/tasks/test_notifications.py | 6 | ||||
| -rw-r--r-- | tests/test_cli.py | 22 | ||||
| -rw-r--r-- | tests/test_init.py | 2 | ||||
| -rw-r--r-- | tests/test_models.py | 2 | ||||
| -rw-r--r-- | tests/test_net.py | 5 |
6 files changed, 33 insertions, 9 deletions
diff --git a/tests/tasks/test_extension.py b/tests/tasks/test_extension.py index 312696d..323353e 100644 --- a/tests/tasks/test_extension.py +++ b/tests/tasks/test_extension.py @@ -96,7 +96,10 @@ def test_task_raises_without_app(app: Flask, periodic: bool) -> None: @pytest.mark.parametrize("periodic", [False, True], ids=["task", "periodic-task"]) def test_task_declaration_before_init_and_rebind_after_init(periodic: bool) -> None: - """Imported task handles do not capture the first application backend.""" + """Verify that imported tasks switch to the latest application backend. + + :param periodic: Pytest fixture providing the periodic-task test function. + """ queue = Huey() observed_apps: list[str] = [] diff --git a/tests/tasks/test_notifications.py b/tests/tasks/test_notifications.py index f87fd47..876c2b3 100644 --- a/tests/tasks/test_notifications.py +++ b/tests/tasks/test_notifications.py @@ -135,7 +135,11 @@ def test_digest_skips_when_no_new_mentions( def test_digest_lock_uses_current_backend( notifications: ModuleType, app: Flask ) -> None: - """A digest imported before reinitialization uses the new backend's lock.""" + """Verify that a previously imported digest uses the new backend lock. + + :param notifications: Digest notification module under test. + :param app: Configured Flask application fixture. + """ with app.app_context(): previous_backend = huey.huey huey.init_app(app) 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() diff --git a/tests/test_init.py b/tests/test_init.py index ccfdfd8..2b5ea00 100644 --- a/tests/test_init.py +++ b/tests/test_init.py @@ -28,7 +28,7 @@ def test_create_app_exposes_version_in_templates(app: Flask) -> None: def test_importing_views_and_tasks_before_creating_app() -> None: - """Module imports alone must never need an initialized Huey backend.""" + """Verify that imports do not need an initialized Huey backend.""" script = """ from webmentions_ssg import huey from webmentions_ssg.tasks.scanner import manual_scan_sources diff --git a/tests/test_models.py b/tests/test_models.py index 85c216e..01e2cec 100644 --- a/tests/test_models.py +++ b/tests/test_models.py @@ -27,7 +27,7 @@ from webmentions_ssg.models import ( def test_uuid_annotations_and_relationships_resolve() -> None: - """Keep UUID columns and forward relationships mapped without future annotations.""" + """Verify that UUID columns and forward relationships map correctly.""" for model in (ReceivedWebmention, Source, SentWebmention): assert get_type_hints(model)["uuid"] == Mapped[uuid.UUID] assert sa.inspect(model).columns["uuid"].primary_key diff --git a/tests/test_net.py b/tests/test_net.py index 4ac138d..b778310 100644 --- a/tests/test_net.py +++ b/tests/test_net.py @@ -42,7 +42,10 @@ def test_backend_rejects_private_ip_without_socket( def test_rebinding_cannot_change_socket_peer(monkeypatch: pytest.MonkeyPatch) -> None: - """The address is resolved exactly once and the socket sees only that IP.""" + """Verify that DNS rebinding cannot change the connected socket peer. + + :param monkeypatch: Pytest fixture for replacing the DNS resolver and socket calls. + """ dns = Mock(return_value=("93.184.216.34",)) monkeypatch.setattr("webmentions_ssg.net.public_addresses", dns) socket_instance = Mock() |
