Add module docstrings for the tests hierarchy. (0a0ba0a) - derivepassphrase.git

Add module docstrings for the tests hierarchy.

Marco Ricci commited on 2025-11-30 13:54:36
Zeige 20 geänderte Dateien mit 114 Einfügungen und 3 Löschungen.

Consistently add docstrings to all modules in the tests hierarchy that
would appear in the (developer setup) documentation.

docs/reference/tests.test_000_testing_machinery.md 0000000..ad8d5ff
mkdocs_devsetup.yml a9ae262..a7a9a90
tests/datcallables.py 0c2b2d8..e3feffb
tests/machinery/__init__.py bd03cef..bf81fde
tests/test_000_testing_machinery.py ea07ba8..c0b9a07
tests/test_derivepassphrase_cli/__init__.py 5e6a2cf..7f0f5e0
tests/test_derivepassphrase_cli/test_all_cli.py 18d8898..71ff187
tests/test_derivepassphrase_cli/test_heavy_duty.py 3b49004..b93bc65
tests/test_derivepassphrase_cli/test_shell_completion.py bad14d9..28708ed
tests/test_derivepassphrase_cli/test_transition.py b28268a..f807ab0
tests/test_derivepassphrase_cli/test_utils.py e61bc06..d1473f6
tests/test_derivepassphrase_cli/test_vault_cli_notes_handling.py 6c450f9..274ec3e
tests/test_derivepassphrase_cli_export_vault.py 7b4fe72..338b1d2
tests/test_derivepassphrase_exporter.py ba7bc5b..4d22fcd
tests/test_derivepassphrase_ssh_agent/__init__.py 5e6a2cf..25cc15c
tests/test_derivepassphrase_ssh_agent/test_000_basic.py d76aedc..54e1352
tests/test_derivepassphrase_ssh_agent/test_heavy_duty.py 2d6f0f1..c03fa6a
tests/test_derivepassphrase_types/__init__.py 5e6a2cf..6bd24ff
tests/test_derivepassphrase_types/test_000_basic.py 3d44693..55c87b1
tests/test_derivepassphrase_types/test_heavy_duty.py 8c733c0..8f3b8cb

docs/reference/tests.test_000_testing_machinery.md

Zeige Datei @ 0a0ba0a

...	...	@@ -0,0 +1,3 @@
	1	+::: tests.test_000_testing_machinery
	2	+ options:
	3	+ heading_level: 1

mkdocs_devsetup.yml

Zeige Datei @ 0a0ba0a

@@ -40,6 +40,7 @@ nav:
         - pytest configuration: reference/tests.conftest.md
         - Common testing data: reference/tests.data.md
         - Common testing machinery: reference/tests.machinery.md
+        - Miscellaneous test machinery tests: reference/tests.test_000_testing_machinery.md
       - Localization machinery: reference/tests.test_l10n.md
       - derivepassphrase command-line:
         - cli module, helpers and machinery:

tests/datcallables.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,17 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""General machinery for `derivepassphrase` testing data.
+
+This module contains machinery supplementary to the data from the
+`tests.data` module, such as common dummy functions, or simple parsers
+for (the restricted format in use by) the data.  It also contains some
+actual test data that needs to be generated programmatically, or that
+e.g. includes a function from this module as an embedded callback
+parameter.
+
+"""
+
 from __future__ import annotations
 
 import os

tests/machinery/__init__.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,14 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Testing machinery for `derivepassphrase`.
+
+This is all the standalone, non-test-system-specific machinery used to
+test `derivepassphrase`; this includes global settings, external API
+wrappers, stub systems, and the like.
+
+"""
+
 from __future__ import annotations
 
 import contextlib

tests/test_000_testing_machinery.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,16 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Miscellaneous tests for the test suite's data and machinery.
+
+At the moment, this only entails testing [the SSH test
+keys][data.ALL_KEYS] for internal consistency.  Tests for the [stubbed
+SSH agent][tests.machinery.StubbedSSHAgentSocket] (in all variations)
+are included in the [basic tests for the `derivepassphrase.ssh_agent`
+module][tests.test_derivepassphrase_ssh_agent.test_000_basic].
+
+"""
+
 from __future__ import annotations
 
 import base64

tests/test_derivepassphrase_cli/__init__.py

Zeige Datei @ 0a0ba0a

...	...	@@ -1,3 +1,36 @@
1	1	# SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>
2	2	#
3	3	# SPDX-License-Identifier: Zlib
	4	+
	5	+"""Tests for the `derivepassphrase` command-line interface.
	6	+
	7	+There are separate submodules for
	8	+
	9	+ * [testing basic
	10	+ things][tests.test_derivepassphrase_cli.test_000_basic]
	11	+
	12	+ * [common testing across all
	13	+ CLIs][tests.test_derivepassphrase_cli.test_all_cli]
	14	+
	15	+ * [heavy-duty
	16	+ testing][tests.test_derivepassphrase_cli.test_heavy_duty]
	17	+
	18	+ * [testing shell
	19	+ completion][tests.test_derivepassphrase_cli.test_shell_completion]
	20	+
	21	+ * [testing transition functions and
	22	+ messages][tests.test_derivepassphrase_cli.test_transition]
	23	+
	24	+ * [testing internal utility
	25	+ functions][tests.test_derivepassphrase_cli.test_utils]
	26	+
	27	+ * [testing basic functionality of the `vault`
	28	+ CLI][tests.test_derivepassphrase_cli.test_vault_cli_basic_functionality]
	29	+
	30	+ * [testing configuration management via the `vault`
	31	+ CLI][tests.test_derivepassphrase_cli.test_vault_cli_config_management]
	32	+
	33	+ * [testing notes handling in the `vault`
	34	+ CLI][tests.test_derivepassphrase_cli.test_vault_cli_notes_handling]
	35	+
	36	+"""

tests/test_derivepassphrase_cli/test_all_cli.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,13 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for the `derivepassphrase` command-line interface: all subcommands.
+
+This includes tests for functionality or options common to all
+subcommands.
+
+"""
+
 from __future__ import annotations
 
 import contextlib

tests/test_derivepassphrase_cli/test_heavy_duty.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for the `derivepassphrase` command-line interface: heavy-duty tests."""
+
 from __future__ import annotations
 
 import contextlib

tests/test_derivepassphrase_cli/test_shell_completion.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for the `derivepassphrase` command-line interface: shell completion."""
+
 from __future__ import annotations
 
 import contextlib

tests/test_derivepassphrase_cli/test_transition.py

Zeige Datei @ 0a0ba0a

@@ -5,6 +5,13 @@
 # TODO(the-13th-letter): Remove this module in v1.0.
 # https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#upgrading-to-v1.0
 
+"""Tests for the `derivepassphrase` command-line interface: transitional functionality.
+
+This includes deprecation warnings for deprecated commands or options,
+and functionality provided for ease of transition.
+
+"""
+
 from __future__ import annotations
 
 import contextlib

tests/test_derivepassphrase_cli/test_utils.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for the `derivepassphrase` command-line interface: internal utility functions."""
+
 from __future__ import annotations
 
 import base64

tests/test_derivepassphrase_cli/test_vault_cli_notes_handling.py

Zeige Datei @ 0a0ba0a

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Zlib
 
-"""Tests for the `derivepassphrase vault` command-line interface."""
+"""Tests for the `derivepassphrase vault` command-line interface: notes handling."""
 
 from __future__ import annotations
 

tests/test_derivepassphrase_cli_export_vault.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Test the `derivepassphrase export vault` CLI."""
+
 from __future__ import annotations
 
 import base64

tests/test_derivepassphrase_exporter.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Test `derivepassphrase.exporter` and the `derivepassphrase export` CLI."""
+
 from __future__ import annotations
 
 import contextlib

tests/test_derivepassphrase_ssh_agent/__init__.py

Zeige Datei @ 0a0ba0a

...	...	@@ -1,3 +1,12 @@
1	1	# SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>
2	2	#
3	3	# SPDX-License-Identifier: Zlib
	4	+
	5	+"""Tests for `derivepassphrase.ssh_agent`.
	6	+
	7	+There are separate submodules for [basic
	8	+tests][tests.test_derivepassphrase_ssh_agent.test_000_basic] and
	9	+[heavy-duty
	10	+tests][tests.test_derivepassphrase_ssh_agent.test_heavy_duty].
	11	+
	12	+"""

tests/test_derivepassphrase_ssh_agent/test_000_basic.py

Zeige Datei @ 0a0ba0a

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Zlib
 
-"""Test OpenSSH key loading and signing."""
+"""Tests for `derivepassphrase.ssh_agent`: basic tests."""
 
 from __future__ import annotations
 

tests/test_derivepassphrase_ssh_agent/test_heavy_duty.py

Zeige Datei @ 0a0ba0a

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Zlib
 
-"""Test OpenSSH key loading and signing."""
+"""Tests for `derivepassphrase.ssh_agent`: heavy-duty tests."""
 
 from __future__ import annotations
 

tests/test_derivepassphrase_types/__init__.py

Zeige Datei @ 0a0ba0a

...	...	@@ -1,3 +1,11 @@
1	1	# SPDX-FileCopyrightText: 2025 Marco Ricci <software@the13thletter.info>
2	2	#
3	3	# SPDX-License-Identifier: Zlib
	4	+
	5	+"""Tests for `derivepassphrase._types`.
	6	+
	7	+There are separate submodules for [basic
	8	+tests][tests.test_derivepassphrase_types.test_000_basic] and [heavy-duty
	9	+tests][tests.test_derivepassphrase_types.test_heavy_duty].
	10	+
	11	+"""

tests/test_derivepassphrase_types/test_000_basic.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for `derivepassphrase._types`: basic tests."""
+
 from __future__ import annotations
 
 import copy

tests/test_derivepassphrase_types/test_heavy_duty.py

Zeige Datei @ 0a0ba0a

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Zlib
 
+"""Tests for `derivepassphrase._types`: heavy-duty tests."""
+
 from __future__ import annotations
 
 import math


...	...	@@ -40,6 +40,7 @@ nav:
40	40	- pytest configuration: reference/tests.conftest.md
41	41	- Common testing data: reference/tests.data.md
42	42	- Common testing machinery: reference/tests.machinery.md
	43	+ - Miscellaneous test machinery tests: reference/tests.test_000_testing_machinery.md
43	44	- Localization machinery: reference/tests.test_l10n.md
44	45	- derivepassphrase command-line:
45	46	- cli module, helpers and machinery:

...	...	@@ -2,6 +2,17 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""General machinery for `derivepassphrase` testing data.
	6	+
	7	+This module contains machinery supplementary to the data from the
	8	+`tests.data` module, such as common dummy functions, or simple parsers
	9	+for (the restricted format in use by) the data. It also contains some
	10	+actual test data that needs to be generated programmatically, or that
	11	+e.g. includes a function from this module as an embedded callback
	12	+parameter.
	13	+
	14	+"""
	15	+
5	16	from __future__ import annotations
6	17
7	18	import os

...	...	@@ -2,6 +2,14 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Testing machinery for `derivepassphrase`.
	6	+
	7	+This is all the standalone, non-test-system-specific machinery used to
	8	+test `derivepassphrase`; this includes global settings, external API
	9	+wrappers, stub systems, and the like.
	10	+
	11	+"""
	12	+
5	13	from __future__ import annotations
6	14
7	15	import contextlib

...	...	@@ -2,6 +2,16 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Miscellaneous tests for the test suite's data and machinery.
	6	+
	7	+At the moment, this only entails testing [the SSH test
	8	+keys][data.ALL_KEYS] for internal consistency. Tests for the [stubbed
	9	+SSH agent][tests.machinery.StubbedSSHAgentSocket] (in all variations)
	10	+are included in the [basic tests for the `derivepassphrase.ssh_agent`
	11	+module][tests.test_derivepassphrase_ssh_agent.test_000_basic].
	12	+
	13	+"""
	14	+
5	15	from __future__ import annotations
6	16
7	17	import base64

...	...	@@ -2,6 +2,13 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Tests for the `derivepassphrase` command-line interface: all subcommands.
	6	+
	7	+This includes tests for functionality or options common to all
	8	+subcommands.
	9	+
	10	+"""
	11	+
5	12	from __future__ import annotations
6	13
7	14	import contextlib

...	...	@@ -2,6 +2,8 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Tests for the `derivepassphrase` command-line interface: heavy-duty tests."""
	6	+
5	7	from __future__ import annotations
6	8
7	9	import contextlib

...	...	@@ -5,6 +5,13 @@
5	5	# TODO(the-13th-letter): Remove this module in v1.0.
6	6	# https://the13thletter.info/derivepassphrase/latest/upgrade-notes/#upgrading-to-v1.0
7	7
	8	+"""Tests for the `derivepassphrase` command-line interface: transitional functionality.
	9	+
	10	+This includes deprecation warnings for deprecated commands or options,
	11	+and functionality provided for ease of transition.
	12	+
	13	+"""
	14	+
8	15	from __future__ import annotations
9	16
10	17	import contextlib

...	...	@@ -2,7 +2,7 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
5		-"""Tests for the `derivepassphrase vault` command-line interface."""
	5	+"""Tests for the `derivepassphrase vault` command-line interface: notes handling."""
6	6
7	7	from __future__ import annotations
8	8

...	...	@@ -2,6 +2,8 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Test the `derivepassphrase export vault` CLI."""
	6	+
5	7	from __future__ import annotations
6	8
7	9	import base64

...	...	@@ -2,6 +2,8 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Test `derivepassphrase.exporter` and the `derivepassphrase export` CLI."""
	6	+
5	7	from __future__ import annotations
6	8
7	9	import contextlib

...	...	@@ -2,7 +2,7 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
5		-"""Test OpenSSH key loading and signing."""
	5	+"""Tests for `derivepassphrase.ssh_agent`: basic tests."""
6	6
7	7	from __future__ import annotations
8	8

...	...	@@ -2,6 +2,8 @@
2	2	#
3	3	# SPDX-License-Identifier: Zlib
4	4
	5	+"""Tests for `derivepassphrase._types`: basic tests."""
	6	+
5	7	from __future__ import annotations
6	8
7	9	import copy