Document the "test key uploading" helper functions (02be2f8) - derivepassphrase.git

tests/conftest.py

@@ -843,6 +843,24 @@ def _prepare_payload(
     isolated: bool = True,
     time_to_live: int = 30,
 ) -> tuple[_types.SSH_AGENTC, bytes]:
+    """Return a full payload for an "add key" request to the agent.
+
+    For isolated agents, return a standard
+    [`_types.SSH_AGENTC.ADD_IDENTITY`][] request payload.  For
+    non-isolated agents, return a
+    [`_types.SSH_AGENTC.ADD_ID_CONSTRAINED`][] request payload with the
+    specified time-to-live value.
+
+    Args:
+        payload:
+            The private key to upload, already formatted suitably.
+        isolated:
+            `True` if the agent is isolated, `False` otherwise.
+        time_to_live:
+            The amount of seconds to hold the key in the agent, if not
+            isolated.
+
+    """
     return_code = (
         _types.SSH_AGENTC.ADD_IDENTITY
         if isolated
@@ -858,10 +876,25 @@ def _prepare_payload(
 
 def _load_key_optimistically(
     spawned_agent_info: data.SpawnedSSHAgentInfo,
-    key_type: str,
+    key_struct: data.SSHTestKey,
 ) -> bool:
+    """Load a test key optimistically into the spawned agent.
+
+    Load the key with a time-to-live constraint (if isolated) or not, as
+    appropriate.  If that fails because this agent does not support key
+    constraints, retry it without constraints.
+
+    Args:
+        spawned_agent_info: Info on the spawned agent.
+        key_struct: The struct for the SSH test key to upload.
+
+    Returns:
+        `True` if the key was successfully uploaded, `False` otherwise.
+        Retrying an upload because key constraints are not supported
+        still counts as successfully uploaded.
+
+    """
     agent_type, client, isolated = spawned_agent_info
-    key_struct = data.ALL_KEYS[key_type]
     private_key_data = key_struct.private_key_blob
     request_code, payload = _prepare_payload(
         private_key_data, isolated=isolated, time_to_live=30
@@ -874,11 +907,10 @@ def _load_key_optimistically(
                 response_code=_types.SSH_AGENT.SUCCESS,
             )
         except ssh_agent.SSHAgentFailedError:  # pragma: no cover [external]
-            # Pageant can fail to accept a key for two separate
-            # reasons:
+            # Pageant can fail to accept a key for two separate reasons:
             #
-            # - Pageant refuses to accept a key it already holds
-            #   in memory.  Verify this by listing keys.
+            # - Pageant refuses to accept a key it already holds in
+            #   memory.  Verify this by listing keys.
             # - Pageant does not support key constraints (see
             #   references below).
             #
@@ -943,7 +975,7 @@ def ssh_agent_client_with_test_keys_loaded(
             skip this test.
 
     Warning:
-        It is the fixture's responsibility to clean up the SSH agent
+        It is this fixture's responsibility to clean up the SSH agent
         client after the test.  Closing the client's socket connection
         beforehand (e.g. by using the client as a context manager) may
         lead to exceptions being thrown upon fixture teardown.
@@ -965,7 +997,7 @@ def ssh_agent_client_with_test_keys_loaded(
         successfully_loaded_keys = {
             key_type
             for key_type, key_struct in data.ALL_KEYS.items()
-            if _load_key_optimistically(spawn_ssh_agent, key_type)
+            if _load_key_optimistically(spawn_ssh_agent, key_struct)
         }
         if (
             agent_type != data.KnownSSHAgent.StubbedSSHAgent


...	...	@@ -843,6 +843,24 @@ def _prepare_payload(
843	843	isolated: bool = True,
844	844	time_to_live: int = 30,
845	845	) -> tuple[_types.SSH_AGENTC, bytes]:
	846	+ """Return a full payload for an "add key" request to the agent.
	847	+
	848	+ For isolated agents, return a standard
	849	+ [`_types.SSH_AGENTC.ADD_IDENTITY`][] request payload. For
	850	+ non-isolated agents, return a
	851	+ [`_types.SSH_AGENTC.ADD_ID_CONSTRAINED`][] request payload with the
	852	+ specified time-to-live value.
	853	+
	854	+ Args:
	855	+ payload:
	856	+ The private key to upload, already formatted suitably.
	857	+ isolated:
	858	+ `True` if the agent is isolated, `False` otherwise.
	859	+ time_to_live:
	860	+ The amount of seconds to hold the key in the agent, if not
	861	+ isolated.
	862	+
	863	+ """
846	864	return_code = (
847	865	_types.SSH_AGENTC.ADD_IDENTITY
848	866	if isolated
...	...	@@ -858,10 +876,25 @@ def _prepare_payload(
858	876
859	877	def _load_key_optimistically(
860	878	spawned_agent_info: data.SpawnedSSHAgentInfo,
861		- key_type: str,
	879	+ key_struct: data.SSHTestKey,
862	880	) -> bool:
	881	+ """Load a test key optimistically into the spawned agent.
	882	+
	883	+ Load the key with a time-to-live constraint (if isolated) or not, as
	884	+ appropriate. If that fails because this agent does not support key
	885	+ constraints, retry it without constraints.
	886	+
	887	+ Args:
	888	+ spawned_agent_info: Info on the spawned agent.
	889	+ key_struct: The struct for the SSH test key to upload.
	890	+
	891	+ Returns:
	892	+ `True` if the key was successfully uploaded, `False` otherwise.
	893	+ Retrying an upload because key constraints are not supported
	894	+ still counts as successfully uploaded.
	895	+
	896	+ """
863	897	agent_type, client, isolated = spawned_agent_info
864		- key_struct = data.ALL_KEYS[key_type]
865	898	private_key_data = key_struct.private_key_blob
866	899	request_code, payload = _prepare_payload(
867	900	private_key_data, isolated=isolated, time_to_live=30
...	...	@@ -874,11 +907,10 @@ def _load_key_optimistically(
874	907	response_code=_types.SSH_AGENT.SUCCESS,
875	908	)
876	909	except ssh_agent.SSHAgentFailedError: # pragma: no cover [external]
877		- # Pageant can fail to accept a key for two separate
878		- # reasons:
	910	+ # Pageant can fail to accept a key for two separate reasons:
879	911	#
880		- # - Pageant refuses to accept a key it already holds
881		- # in memory. Verify this by listing keys.
	912	+ # - Pageant refuses to accept a key it already holds in
	913	+ # memory. Verify this by listing keys.
882	914	# - Pageant does not support key constraints (see
883	915	# references below).
884	916	#
...	...	@@ -943,7 +975,7 @@ def ssh_agent_client_with_test_keys_loaded(
943	975	skip this test.
944	976
945	977	Warning:
946		- It is the fixture's responsibility to clean up the SSH agent
	978	+ It is this fixture's responsibility to clean up the SSH agent
947	979	client after the test. Closing the client's socket connection
948	980	beforehand (e.g. by using the client as a context manager) may
949	981	lead to exceptions being thrown upon fixture teardown.
...	...	@@ -965,7 +997,7 @@ def ssh_agent_client_with_test_keys_loaded(
965	997	successfully_loaded_keys = {
966	998	key_type
967	999	for key_type, key_struct in data.ALL_KEYS.items()
968		- if _load_key_optimistically(spawn_ssh_agent, key_type)
	1000	+ if _load_key_optimistically(spawn_ssh_agent, key_struct)
969	1001	}
970	1002	if (
971	1003	agent_type != data.KnownSSHAgent.StubbedSSHAgent
972	1004