sshagentsocketprovider/src/derivepassphrase_sshagentsocketprovider/__init__.py (11972bb) - derivepassphrase.git

__init__.py

Blame History Raw

# SPDX-FileCopyrightText: 2026 Marco Ricci <software@the13thletter.info>
#
# SPDX-License-Identifier: Zlib

"""Definitions for `derivepassphrase`'s SSH agent socket providers."""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol

from typing_extensions import NamedTuple, runtime_checkable

if TYPE_CHECKING:

from typing_extensions import Any, Buffer

# Semantic versioning.
__version__ = "1.0"

ENTRY_POINT_GROUP_NAME = "derivepassphrase.ssh_agent_socket_providers"
"""
The name of the entry point group for SSH agent socket providers.

We pledge to not change the interface of the entry point (name, type of
the referred object) in a backwards-incompatible way without both

1. increasing the major version number of the package, and
  2. changing the entry point name.

(We cannot, however, guarantee that all consumers of this API will
continue to support superseded entry point definitions forever.  That is
up to the individual API consumer to decide.)
"""

@runtime_checkable
class SSHAgentSocket(Protocol):
    """An abstract networking socket connected to an SSH agent.

The abstract socket supports the [`sendall`][socket.socket.sendall]
    and a [`recv`][socket.socket.recv] operation, with the same
    signatures and semantics as for "real" sockets.  The abstract socket
    also supports use as a context manager, for automatically closing
    the socket upon exiting the context.

"""

def __enter__(self) -> Any:  # noqa: ANN401
        """Returns self."""

# mypy/typeshed has a *very* lax annotation of
    # socket.socket.__exit__, which we need to be compatible with.
    # *sigh*
    def __exit__(self, *args: object) -> bool | None:
        """Closes the socket."""

def sendall(self, data: Buffer, flags: int = 0, /) -> None:
        """Like [socket.socket.sendall][]."""

def recv(self, bufsize: int, flags: int = 0, /) -> bytes:
        """Like [socket.socket.recv][]."""

@runtime_checkable
class SSHAgentSocketProvider(Protocol):
    """A callable that provides an SSH agent socket."""
    def __call__(self) -> SSHAgentSocket:
        """Returns an SSH agent socket when called without arguments."""

# For later major versions, we would define a new type.  For minor
# versions, we may add new fields.
class SSHAgentSocketProviderEntry(NamedTuple):
    """Registry information for the table of SSH agent socket providers.

Third-party developers can register new socket providers for
    auto-discovery by setting up an entry point named
    [`derivepassphrase.ssh_agent_socket_providers`][ENTRY_POINT_GROUP_NAME],
    referencing an instance of this class.  `derivepassphrase` will
    then add appropriate entries to the registry.

Attributes:
        provider: The callable that provides the socket.
        key: The table key which this entry is registered as.
        aliases: Other keys that shall point to this entry's key.

Note:
        The socket provider registry table uses the key as the key, and
        the provider as the value. It does not store this info object
        directly.

"""

provider: SSHAgentSocketProvider
    """"""
    key: str
    """"""
    aliases: tuple[str, ...]
    """"""

derivepassphrase.git

Release 1.0 of the SSH agent socket API