derivepassphrase.git

@@ -248,8 +248,40 @@ exclude_also = [

     'class .*\(Protocol\):',

     'pytest\.fail\(',

     '@(?:(?:pytest\.)?mark\.)?xfail\(',

+    'class _Omitted:',

+    'class _DummyModule:',

 ]

+# We use a bunch of "codes", similar to the "type: ignore" comments, as

+# shorthand notation for why we are excluding a certain piece of code

+# manually from coverage, instead of writing a verbose explanation at each

+# call site:

+#

+# "external-api" and "unused": The code is defined by an external API not

+# under our control, or it implements an external interface, and some of the

+# branches of that code we do not yet use ("unused") or don't ever intend to

+# use ("external-api").  In particular, in production and in testing use, we

+# do not expect to hit these code branches unless there are errors in our

+# code.

+#

+# "external": Whether or not we hit this code branch is non-deterministic,

+# and dependent on external factors that are difficult or impossible for us

+# to control, predict, or simulate.  We therefore categorically exclude all

+# branches from coverage.  (Typically though, one particular branch *will*

+# actually run.  We just don't know ahead of time which one.)  (While this

+# applies to "choice of operating system" and "installed Python/library

+# version" as well, these cases are usually tagged with more specific codes,

+# or explained in long-form commentary.)

+#

+# "failsafe": Akin to assertions, these are used to catch "impossible"

+# situations and to still fail in a controlled manner.  We do not expect to

+# hit these code branches during production or testing.

+#

+# "debug", "internal" and "interactive": These code branches are not

+# intended to be called by the general public ("debug", "internal"), or they

+# are only intended to be called interactively ("interactive").  We do not

+# expect to hit these code branches during production or testing.

+

 [tool.coverage.run]

 source_pkgs = ["derivepassphrase", "tests"]

 branch = true

@@ -241,7 +241,7 @@ class ConfigurationMutex:

     def __init__(self) -> None:

         """Initialize self."""

-        if sys.platform == 'win32':  # pragma: no cover

+        if sys.platform == 'win32':  # pragma: unless the-annoying-os no cover

             import msvcrt  # noqa: PLC0415

             locking = msvcrt.locking

@@ -254,7 +254,7 @@ class ConfigurationMutex:

             def unlock_fd(fd: int, /) -> None:

                 locking(fd, LK_UNLCK, LOCK_SIZE)

-        else:

+        else:  # pragma: unless posix no cover

             import fcntl  # noqa: PLC0415

             flock = fcntl.flock

@@ -440,7 +440,7 @@ def config_filename(

         return temp_path / filename_

     try:

         filename = config_filename_table[subsystem]

-    except (KeyError, TypeError):  # pragma: no cover

+    except (KeyError, TypeError):  # pragma: no cover [failsafe]

         msg = f'Unknown configuration subsystem: {subsystem!r}'

         raise AssertionError(msg) from None

     return path / filename

@@ -596,14 +596,14 @@ def get_suitable_ssh_keys(

     with ssh_agent.SSHAgentClient.ensure_agent_subcontext(conn) as client:

         try:

             all_key_comment_pairs = list(client.list_keys())

-        except EOFError as exc:  # pragma: no cover

+        except EOFError as exc:  # pragma: no cover [failsafe]

             raise RuntimeError(AGENT_COMMUNICATION_ERROR) from exc

         suitable_keys = copy.copy(all_key_comment_pairs)

         for pair in all_key_comment_pairs:

             key, _comment = pair

             if vault.Vault.is_suitable_ssh_key(key, client=client):

                 yield pair

-    if not suitable_keys:  # pragma: no cover

+    if not suitable_keys:

         raise LookupError(NO_SUITABLE_KEYS)

@@ -666,7 +666,7 @@ def prompt_for_selection(

                 show_default=False,

                 default='',

             )

-        except click.Abort:  # pragma: no cover

+        except click.Abort:  # pragma: no cover [external]

             # This branch will not be triggered during testing on

             # `click` versions < 8.2.1, due to (non-monkeypatch-able)

             # deficiencies in `click.testing.CliRunner`. Therefore, as

@@ -784,7 +784,7 @@ def prompt_for_passphrase() -> str:

                 err=True,

             ),

         )

-    except click.Abort:  # pragma: no cover

+    except click.Abort:  # pragma: no cover [external]

         # This branch will not be triggered during testing on `click`

         # versions < 8.2.1, due to (non-monkeypatch-able) deficiencies

         # in `click.testing.CliRunner`. Therefore, as an external source

@@ -144,7 +144,7 @@ class CLIofPackageFormatter(logging.Formatter):

         """

         preliminary_result = record.getMessage()

         prefix = f'{self.prog_name}: '

-        if record.levelname == 'DEBUG':  # pragma: no cover

+        if record.levelname == 'DEBUG':  # pragma: no cover [unused]

             level_indicator = 'Debug: '

         elif record.levelname == 'INFO':

             level_indicator = ''

@@ -156,7 +156,7 @@ class CLIofPackageFormatter(logging.Formatter):

             )

         elif record.levelname in {'ERROR', 'CRITICAL'}:

             level_indicator = ''

-        else:  # pragma: no cover

+        else:  # pragma: no cover [failsafe]

             msg = f'Unsupported logging level: {record.levelname}'

             raise AssertionError(msg)

         parts = [

@@ -299,7 +299,7 @@ class StandardWarningsLoggingContextManager(StandardLoggingContextManager):

             file: TextIO | None = None,

             line: str | None = None,

         ) -> None:

-            if file is not None:  # pragma: no cover

+            if file is not None:  # pragma: no cover [external-api]

                 self.stack[0][1](

                     message, category, filename, lineno, file, line

                 )

@@ -492,7 +492,9 @@ class CommandWithHelpGroups(click.Command):

         """

         help_options = self.get_help_option_names(ctx)

-        if not help_options or not self.add_help_option:  # pragma: no cover

+        if (

+            not help_options or not self.add_help_option

+        ):  # pragma: no cover [external-api]

             return None

         def show_help(

@@ -534,15 +536,15 @@ class CommandWithHelpGroups(click.Command):

         # to allow help texts to be general objects, not just strings.

         # Used to implement translatable strings, as objects that

         # stringify to the translation.

-        if self.short_help:  # pragma: no cover

+        if self.short_help:  # pragma: no cover [external-api]

             text = inspect.cleandoc(self._text(self.short_help))

         elif self.help:

             text = click.utils.make_default_short_help(

                 self._text(self.help), limit

             )

-        else:  # pragma: no cover

+        else:  # pragma: no cover [external-api]

             text = ''

-        if self.deprecated:  # pragma: no cover

+        if self.deprecated:  # pragma: no cover [external-api]

             # Modification against click 8.1: The translated string is

             # looked up in the derivepassphrase message domain, not the

             # gettext default domain.

@@ -577,7 +579,7 @@ class CommandWithHelpGroups(click.Command):

             if self.help is not None

             else ''

         )

-        if self.deprecated:  # pragma: no cover

+        if self.deprecated:  # pragma: no cover [external-api]

             # Modification against click 8.1: The translated string is

             # looked up in the derivepassphrase message domain, not the

             # gettext default domain.

@@ -638,7 +640,7 @@ class CommandWithHelpGroups(click.Command):

                 if isinstance(param, OptionGroupOption):

                     group_name = self._text(param.option_group_name)

                     epilogs.setdefault(group_name, self._text(param.epilog))

-                else:  # pragma: no cover

+                else:  # pragma: no cover [external-api]

                     group_name = default_group_name

                 help_records.setdefault(group_name, []).append(rec)

         if default_group_name in help_records:  # pragma: no branch

@@ -688,7 +690,7 @@ class CommandWithHelpGroups(click.Command):

         commands: list[tuple[str, click.Command]] = []

         for subcommand in self.list_commands(ctx):

             cmd = self.get_command(ctx, subcommand)

-            if cmd is None or cmd.hidden:  # pragma: no cover

+            if cmd is None or cmd.hidden:  # pragma: no cover [external-api]

                 continue

             commands.append((subcommand, cmd))

         if commands:  # pragma: no branch

@@ -795,7 +797,7 @@ class DefaultToVaultGroup(CommandWithHelpGroups, click.Group):

         # If we can't find the command but there is a normalization

         # function available, we try with that one.

-        if (  # pragma: no cover

+        if (  # pragma: no cover [external-api]

             cmd is None and ctx.token_normalize_func is not None

         ):

             cmd_name = ctx.token_normalize_func(cmd_name)

@@ -860,7 +862,7 @@ class TopLevelCLIEntryPoint(DefaultToVaultGroup):

     """

-    def __call__(  # pragma: no cover

+    def __call__(  # pragma: no cover [external-api]

         self,

         *args: Any,  # noqa: ANN401

         **kwargs: Any,  # noqa: ANN401

@@ -1108,7 +1110,6 @@ def export_vault_version_option_callback(

         known_extras = {

             _types.PEP508Extra.EXPORT: False,

         }

-        try:

         from derivepassphrase.exporter import storeroom, vault_native  # noqa: I001,PLC0415

         foreign_configuration_formats[

@@ -1123,8 +1124,6 @@ def export_vault_version_option_callback(

         known_extras[_types.PEP508Extra.EXPORT] = (

             not storeroom.STUBBED and not vault_native.STUBBED

         )

-        except ModuleNotFoundError:  # pragma: no cover

-            pass

         click.echo()

         version_info_types: dict[_msg.Label, list[str]] = {

             _msg.Label.SUPPORTED_FOREIGN_CONFIGURATION_FORMATS: [

@@ -1391,5 +1390,5 @@ fi

 """

 if (

     click.shell_completion.ZshComplete.source_template == _ORIG_SOURCE_TEMPLATE

-):  # pragma: no cover

+):  # pragma: no cover [external]

     click.shell_completion.add_completion_class(ZshComplete)

@@ -51,7 +51,7 @@ def load_translations(

     localedirs: list[str | bytes | os.PathLike] | None = None,

     languages: Sequence[str] | None = None,

     class_: type[gettext.NullTranslations] | None = None,

-) -> gettext.NullTranslations:  # pragma: no cover

+) -> gettext.NullTranslations:  # pragma: no cover [external]

     """Load a translation catalog for derivepassphrase.

     Runs [`gettext.translation`][] under the hood for multiple locale

@@ -149,8 +149,7 @@ class DebugTranslations(gettext.NullTranslations):

                     plural = v.plural

                     context = v.l10n_context

                     cache.setdefault((context, singular), (member, trimmed))

-                    # Currently no translatable messages use plural forms

-                    if plural:  # pragma: no cover

+                    if plural:  # pragma: no cover [unused]

                         cache.setdefault((context, plural), (member, trimmed))

     @classmethod

@@ -206,7 +205,8 @@ class DebugTranslations(gettext.NullTranslations):

         msgid2: str,

         n: int,

         /,

-    ) -> str:  # pragma: no cover

+    ) -> str:  # pragma: no cover [unused]

+        """"""  # noqa: D419

         return self._locate_message(msgid1, message_plural=msgid2, n=n)

     @override

@@ -226,7 +226,8 @@ class DebugTranslations(gettext.NullTranslations):

         msgid2: str,

         n: int,

         /,

-    ) -> str:  # pragma: no cover

+    ) -> str:  # pragma: no cover [unused]

+        """"""  # noqa: D419

         return self._locate_message(

             msgid1,

             context=context,

@@ -276,7 +277,7 @@ class TranslatableString(NamedTuple):

                 implemented.

         """

-        if 'python-format' in self.flags:  # pragma: no cover

+        if 'python-format' in self.flags:  # pragma: no cover [unused]

             err_msg = (

                 'Replacement field discovery for %-formatting '

                 'is not implemented'

@@ -334,8 +335,7 @@ class TranslatableString(NamedTuple):

         c, sep2, d = self.plural.partition(filename_str)

         if sep1:

             ret = ret._replace(singular=(a + b))

-        # Currently no translatable messages use plural forms

-        if sep2:  # pragma: no cover

+        if sep2:  # pragma: no cover [unused]

             ret = ret._replace(plural=(c + d))

         return ret

@@ -370,7 +370,7 @@ class TranslatableString(NamedTuple):

         """

         if comments.strip() and not comments.lstrip().startswith(

             'TRANSLATORS:'

-        ):  # pragma: no cover

+        ):  # pragma: no cover [unused]

             comments = 'TRANSLATORS: ' + comments.lstrip()

         comments = self._maybe_rewrap(comments, fix_sentence_endings=False)

         return self._replace(translator_comments=comments)

@@ -511,15 +511,16 @@ class TranslatedString:

         """Return true if the rendered string is truthy."""

         return bool(str(self))

-    def __eq__(self, other: object) -> bool:  # pragma: no cover

+    def __eq__(self, other: object) -> bool:  # pragma: no cover [debug]

         """Return true if the rendered string is equal to `other`."""

         return str(self) == other

-    def __hash__(self) -> int:  # pragma: no cover

+    def __hash__(self) -> int:  # pragma: no cover [debug]

         """Return the hash of the rendered string."""

         return hash(str(self))

-    def __repr__(self) -> str:  # pragma: no cover

+    def __repr__(self) -> str:  # pragma: no cover [debug]

+        """"""  # noqa: D419

         return (

             f'{self.__class__.__name__}({self.template!r}, '

             f'{dict(self.kwargs)!r})'

@@ -2348,7 +2349,7 @@ def _write_po_file(  # noqa: C901,PLR0912

     is_template: bool = True,

     version: str = VERSION,

     build_time: datetime.datetime | None = None,

-) -> None:  # pragma: no cover

+) -> None:  # pragma: no cover [interactive]

     r"""Write a .po file to the given file object.

     Assumes the file object is opened for writing and accepts string

@@ -2483,7 +2484,8 @@ def _write_po_file(  # noqa: C901,PLR0912

 def _format_po_info(

     data: Mapping[str, Any],

     /,

-) -> Iterator[str]:  # pragma: no cover

+) -> Iterator[str]:  # pragma: no cover [internal]

+    """"""  # noqa: D419

     sortorder = [

         'project-id-version',

         'report-msgid-bugs-to',

@@ -2517,7 +2519,8 @@ def _format_po_entry(

     *,

     is_debug_translation: bool = False,

     transformed_string: TranslatableString | None = None,

-) -> tuple[str, ...]:  # pragma: no cover

+) -> tuple[str, ...]:  # pragma: no cover [internal]

+    """"""  # noqa: D419

     ret: list[str] = ['\n']

     ts = transformed_string or cast('TranslatableString', enum_value.value)

     if ts.translator_comments:

@@ -2542,7 +2545,9 @@ def _format_po_entry(

     return tuple(ret)

-def _cstr(s: str) -> str:  # pragma: no cover

+def _cstr(s: str) -> str:  # pragma: no cover [internal]

+    """"""  # noqa: D419

+

     def escape(string: str) -> str:

         return string.translate({

             0: r'\000',

@@ -42,7 +42,7 @@ __all__ = (

 )

-class _Omitted:  # pragma: no cover

+class _Omitted:

     def __bool__(self) -> bool:

         return False

@@ -331,14 +331,20 @@ class _VaultConfigValidator:

             or 'services' not in obj

             or not isinstance(obj['services'], dict)

         ):

-            raise ValueError(self.INVALID_CONFIG_ERROR)  # pragma: no cover

+            raise ValueError(

+                self.INVALID_CONFIG_ERROR

+            )  # pragma: no cover [failsafe]

         if 'global' in obj and not isinstance(obj['global'], dict):

-            raise ValueError(self.INVALID_CONFIG_ERROR)  # pragma: no cover

+            raise ValueError(

+                self.INVALID_CONFIG_ERROR

+            )  # pragma: no cover [failsafe]

         if not all(

             isinstance(service_obj, dict)

             for service_obj in obj['services'].values()

         ):

-            raise ValueError(self.INVALID_CONFIG_ERROR)  # pragma: no cover

+            raise ValueError(

+                self.INVALID_CONFIG_ERROR

+            )  # pragma: no cover [failsafe]

         def falsy(value: Any) -> bool:  # noqa: ANN401

             return not js_truthiness(value)

@@ -460,7 +466,7 @@ def validate_vault_config(

     # then include this in coverage.

     if not isinstance(

         allow_derivepassphrase_extensions, _Omitted

-    ):  # pragma: no cover

+    ):  # pragma: no cover [unused]

         warnings.warn(

             get_overloads(validate_vault_config)[0].__deprecated__,  # type: ignore[attr-defined]

             DeprecationWarning,

@@ -488,7 +494,7 @@ def is_vault_config(obj: Any) -> TypeIs[VaultConfig]:  # noqa: ANN401

             allow_unknown_settings=True,

         )

     except (TypeError, ValueError) as exc:

-        if 'vault config ' not in str(exc):  # pragma: no cover

+        if 'vault config ' not in str(exc):  # pragma: no cover [failsafe]

             raise

         return False

     return True

@@ -150,7 +150,7 @@ def derivepassphrase_export(ctx: click.Context, /) -> None:

             # Constructing the subcontext above will usually already

             # lead to a click.UsageError, so this block typically won't

             # actually be called.

-            with sub_ctx:  # pragma: no cover

+            with sub_ctx:  # pragma: no cover [unused]

                 return derivepassphrase_export_vault.invoke(sub_ctx)

     return None

@@ -407,7 +407,7 @@ class _VaultContext:  # noqa: PLR0904

                         if isinstance(param, class_):

                             group = class_

                             break

-                    else:  # pragma: no cover

+                    else:  # pragma: no cover [failsafe]

                         assert False, f'Unknown option group for {param!r}'  # noqa: B011,PT015

                 else:

                     group = click.Option

@@ -36,7 +36,8 @@ class NotAVaultConfigError(ValueError):

         self.path = os.fspath(path)

         self.format = format

-    def __str__(self) -> str:  # pragma: no cover

+    def __str__(self) -> str:  # pragma: no cover [failsafe]

+        """"""  # noqa: D419

         formatted_format = (

             f'vault {self.format} configuration'

             if self.format

@@ -64,10 +65,10 @@ def get_vault_key() -> bytes:

     """

-    def getenv_environb(env_var: str) -> bytes:  # pragma: no cover

+    def getenv_environb(env_var: str) -> bytes:  # pragma: no cover [external]

         return os.environb.get(env_var.encode('UTF-8'), b'')  # type: ignore[attr-defined]

-    def getenv_environ(env_var: str) -> bytes:  # pragma: no cover

+    def getenv_environ(env_var: str) -> bytes:  # pragma: no cover [external]

         return os.environ.get(env_var, '').encode('UTF-8')

     getenv: Callable[[str], bytes] = (

@@ -107,7 +108,7 @@ def get_vault_path() -> pathlib.Path:

     ).expanduser()

-class ExportVaultConfigDataFunction(Protocol):  # pragma: no cover

+class ExportVaultConfigDataFunction(Protocol):

     """Typing protocol for vault config data export handlers."""

     def __call__(

@@ -53,7 +53,7 @@ else:

         importlib.import_module('cryptography')

     except ModuleNotFoundError as exc:

-        class _DummyModule:  # pragma: no cover

+        class _DummyModule:

             def __init__(self, exc: type[Exception]) -> None:

                 self.exc = exc

@@ -115,7 +115,7 @@ def export_storeroom_data(  # noqa: C901,D417,PLR0912,PLR0914,PLR0915

         path = pathlib.Path(os.fsdecode(path))

     if key is None:

         key = exporter.get_vault_key()

-    if format != 'storeroom':  # pragma: no cover

+    if format != 'storeroom':  # pragma: no cover [failsafe]

         msg = exporter.INVALID_VAULT_NATIVE_CONFIGURATION_FORMAT.format(

             fmt=format

         )

@@ -57,7 +57,7 @@ else:

         importlib.import_module('cryptography')

     except ModuleNotFoundError as exc:

-        class _DummyModule:  # pragma: no cover

+        class _DummyModule:

             def __init__(self, exc: type[Exception]) -> None:

                 self.exc = exc

@@ -121,7 +121,7 @@ def export_vault_native_data(  # noqa: D417

         'v0.2': VaultNativeV02ConfigParser,

         'v0.3': VaultNativeV03ConfigParser,

     }.get(format)

-    if parser_class is None:  # pragma: no cover

+    if parser_class is None:  # pragma: no cover [failsafe]

         msg = exporter.INVALID_VAULT_NATIVE_CONFIGURATION_FORMAT.format(

             fmt=format

         )

@@ -50,14 +50,15 @@ class SSHAgentFailedError(RuntimeError):

             b'',

         ):

             return 'The SSH agent failed to complete the request'

-        elif self.args[1]:  # noqa: RET505  # pragma: no cover

+        elif self.args[1]:  # noqa: RET505  # pragma: no cover [failsafe]

             code = self.args[0]

             msg = self.args[1].decode('utf-8', 'surrogateescape')

             return f'[Code {code:d}] {msg:s}'

-        else:  # pragma: no cover

+        else:  # pragma: no cover [failsafe]

             return repr(self)

-    def __repr__(self) -> str:  # pragma: no cover

+    def __repr__(self) -> str:  # pragma: no cover [debug]

+        """"""  # noqa: D419

         return f'{self.__class__.__name__}{self.args!r}'

@@ -335,7 +336,7 @@ class SSHAgentClient:

         elif isinstance(conn, socket.socket) or conn is None:

             with SSHAgentClient(socket=conn) as client:

                 yield client

-        else:  # pragma: no cover

+        else:  # pragma: no cover [failsafe]

             assert_type(conn, Never)

             msg = f'invalid connection hint: {conn!r}'

             raise TypeError(msg)

@@ -479,7 +480,7 @@ class SSHAgentClient:

         if len(response) < response_length:

             msg = 'truncated response from SSH agent'

             raise EOFError(msg)

-        if not response_code:  # pragma: no cover

+        if not response_code:  # pragma: no cover [failsafe]

             return response[0], response[1:]

         if response[0] not in response_code:

             raise SSHAgentFailedError(response[0], response[1:])

@@ -50,7 +50,7 @@ def _hypothesis_settings_setup() -> None:

         importlib.util.find_spec('coverage') is not None

         and settings.deadline is not None

         and settings.deadline.total_seconds() < 1.0

-    ):  # pragma: no cover

+    ):  # pragma: no cover [external]

         ctracer_class = (

             importlib.import_module('coverage.tracer').CTracer

             if importlib.util.find_spec('coverage.tracer') is not None

@@ -112,7 +112,7 @@ _hypothesis_settings_setup()

 # https://docs.pytest.org/en/stable/explanation/fixtures.html#a-note-about-fixture-cleanup

 # https://github.com/pytest-dev/pytest/issues/5243#issuecomment-491522595

 @pytest.fixture(scope='session', autouse=False)

-def term_handler() -> Iterator[None]:  # pragma: no cover

+def term_handler() -> Iterator[None]:  # pragma: no cover [external]

     try:

         import signal  # noqa: PLC0415

@@ -126,7 +126,7 @@ def term_handler() -> Iterator[None]:  # pragma: no cover

 @pytest.fixture(scope='session')

-def skip_if_no_af_unix_support() -> None:  # pragma: no cover

+def skip_if_no_af_unix_support() -> None:  # pragma: no cover [external]

     """Skip the test if Python does not support AF_UNIX.

     Implemented as a fixture instead of a mark because it has

@@ -170,7 +170,7 @@ class SpawnFunc(Protocol):

         """

-def spawn_pageant(  # pragma: no cover

+def spawn_pageant(  # pragma: no cover [external]

     executable: str | None, env: dict[str, str]

 ) -> subprocess.Popen[str] | None:

     """Spawn an isolated Pageant, if possible.

@@ -195,7 +195,7 @@ def spawn_pageant(  # pragma: no cover

         subprocess.

     """

-    if executable is None:  # pragma: no cover

+    if executable is None:  # pragma: no cover [external]

         return None

     # Apparently, Pageant 0.81 and lower running in debug mode does

@@ -227,7 +227,7 @@ def spawn_pageant(  # pragma: no cover

     v0_82 = packaging.version.Version('0.82')

     pageant_version = packaging.version.Version(pageant_version_string)

-    if pageant_version < v0_82:  # pragma: no cover

+    if pageant_version < v0_82:  # pragma: no cover [external]

         return None

     return subprocess.Popen(

@@ -242,7 +242,7 @@ def spawn_pageant(  # pragma: no cover

     )

-def spawn_openssh_agent(  # pragma: no cover

+def spawn_openssh_agent(  # pragma: no cover [external]

     executable: str | None, env: dict[str, str]

 ) -> subprocess.Popen[str] | None:

     """Spawn an isolated OpenSSH agent, if possible.

@@ -276,7 +276,7 @@ def spawn_openssh_agent(  # pragma: no cover

     )

-def spawn_noop(  # pragma: no cover

+def spawn_noop(  # pragma: no cover [unused]

     executable: str | None, env: dict[str, str]

 ) -> None:

     """Placeholder function. Does nothing."""

@@ -323,7 +323,7 @@ def spawn_named_agent(

     exec_name: str,

     spawn_func: SpawnFunc,

     agent_type: tests.KnownSSHAgent,

-) -> Iterator[tests.SpawnedSSHAgentInfo]:  # pragma: no cover

+) -> Iterator[tests.SpawnedSSHAgentInfo]:  # pragma: no cover [external]

     """Spawn the named SSH agent and check that it is operational.

     Using the correct agent-specific spawn function from the

@@ -379,7 +379,7 @@ def spawn_named_agent(

     with exit_stack:

         if spawn_func is spawn_noop:

             ssh_auth_sock = os.environ['SSH_AUTH_SOCK']

-        elif proc is None:  # pragma: no cover

+        elif proc is None:  # pragma: no cover [external]

             err_msg = f'Cannot spawn usable {exec_name}'

             raise CannotSpawnError(err_msg)

         else:

@@ -393,14 +393,14 @@ def spawn_named_agent(

                 ssh_auth_sock = tests.parse_sh_export_line(

                     ssh_auth_sock_line, env_name='SSH_AUTH_SOCK'

                 )

-            except ValueError:  # pragma: no cover

+            except ValueError:  # pragma: no cover [external]

                 err_msg = f'Cannot parse agent output: {ssh_auth_sock_line!r}'

                 raise CannotSpawnError(err_msg) from None

             pid_line = proc.stdout.readline()

             if (

                 'pid' not in pid_line.lower()

                 and '_pid' not in pid_line.lower()

-            ):  # pragma: no cover

+            ):  # pragma: no cover [external]

                 err_msg = f'Cannot parse agent output: {pid_line!r}'

                 raise CannotSpawnError(err_msg)

         monkeypatch = exit_stack.enter_context(pytest.MonkeyPatch.context())

@@ -418,7 +418,7 @@ def spawn_named_agent(

 @pytest.fixture

-def running_ssh_agent(  # pragma: no cover

+def running_ssh_agent(  # pragma: no cover [external]

     skip_if_no_af_unix_support: None,

 ) -> Iterator[tests.RunningSSHAgentInfo]:

     """Ensure a running SSH agent, if possible, as a pytest fixture.

@@ -473,7 +473,7 @@ def running_ssh_agent(  # pragma: no cover

 def spawn_ssh_agent(

     request: pytest.FixtureRequest,

     skip_if_no_af_unix_support: None,

-) -> Iterator[tests.SpawnedSSHAgentInfo]:  # pragma: no cover

+) -> Iterator[tests.SpawnedSSHAgentInfo]:  # pragma: no cover [external]

     """Spawn an isolated SSH agent, if possible, as a pytest fixture.

     Spawn a new SSH agent isolated from other SSH use by other

@@ -500,9 +500,9 @@ def spawn_ssh_agent(

         # fixtures of the same parameter set have run.  So set

         # SSH_AUTH_SOCK explicitly to the value saved at interpreter

         # startup.

-        if startup_ssh_auth_sock:  # pragma: no cover

+        if startup_ssh_auth_sock:  # pragma: no cover [external]

             monkeypatch.setenv('SSH_AUTH_SOCK', startup_ssh_auth_sock)

-        else:  # pragma: no cover

+        else:  # pragma: no cover [external]

             monkeypatch.delenv('SSH_AUTH_SOCK', raising=False)

         try:

             yield from spawn_named_agent(*request.param)

@@ -571,7 +571,7 @@ def ssh_agent_client_with_test_keys_loaded(  # noqa: C901

     try:

         for key_type, key_struct in tests.ALL_KEYS.items():

             private_key_data = key_struct.private_key_blob

-            if private_key_data is None:  # pragma: no cover

+            if private_key_data is None:  # pragma: no cover [failsafe]

                 continue

             request_code, payload = prepare_payload(

                 private_key_data, isolated=isolated, time_to_live=30

@@ -583,7 +583,9 @@ def ssh_agent_client_with_test_keys_loaded(  # noqa: C901

                         payload,

                         response_code=_types.SSH_AGENT.SUCCESS,

                     )

-                except ssh_agent.SSHAgentFailedError:  # pragma: no cover

+                except (

+                    ssh_agent.SSHAgentFailedError

+                ):  # pragma: no cover [external]

                     # Pageant can fail to accept a key for two separate

                     # reasons:

                     #

@@ -618,16 +620,16 @@ def ssh_agent_client_with_test_keys_loaded(  # noqa: C901

                 EOFError,

                 OSError,

                 ssh_agent.SSHAgentFailedError,

-            ):  # pragma: no cover

+            ):  # pragma: no cover [external]

                 pass

-            else:  # pragma: no cover

+            else:  # pragma: no cover [external]

                 successfully_loaded_keys.add(key_type)

         yield client

     finally:

         for key_type, key_struct in tests.ALL_KEYS.items():

             if not isolated and (

                 key_type in successfully_loaded_keys

-            ):  # pragma: no cover

+            ):  # pragma: no cover [external]

                 # The public key blob is the base64-encoded part in

                 # the "public key line".

                 public_key = base64.standard_b64decode(