derivepassphrase.git

@@ -2,6 +2,10 @@

 title: Reference overview

 ---

+## Interfaces

+

+* [SSH agent socket providers][sasp]

+

 ## Man pages

 * [`derivepassphrase(1)`][top_man]: Derive a strong passphrase, deterministically, from a master secret.

@@ -20,11 +24,13 @@ title: Reference overview

     * [`derivepassphrase.ssh_agent`][]: A bare-bones SSH agent client supporting signing and key listing.

     * [`derivepassphrase._types`][]: Types used by `derivepassphrase`.

     * [`derivepassphrase.vault`][]: Python port of the vault(1) password generation scheme.

+* `derivepassphrase-sshagentsocketproviders`: Definitions for `derivepassphrase`'s SSH agent socket providers.

 ## Technical prerequisites

 * [Prerequisites for using `derivepassphrase vault` with an SSH key][PREREQ_SSH_KEY]

+  [sasp]: ssh-agent-socket-providers.md

   [top_man]: derivepassphrase.1.md

   [vault_man]: derivepassphrase-vault.1.md

   [export_man]: derivepassphrase-export.1.md

@@ -1 +1 @@

-Subproject commit 0d39dfbd44b85f90f7a3aa4ec5062158d59750d1

+Subproject commit 7d58f514bb48f92e10365719d73a2217e89fdc9d

@@ -75,6 +75,7 @@ plugins:

           show_object_full_path: false

           show_root_members_full_path: false

           show_root_heading: true

+          show_root_toc_entry: true

           show_symbol_type_heading: true

           show_symbol_type_toc: true

           members_order: 'source'

@@ -104,6 +105,8 @@ nav:

     - how-tos/passphrase-rotation.md

   - Reference:

     - reference/index.md

+    - Interfaces:

+      - SSH agent socket providers: reference/ssh-agent-socket-providers.md

     - Man pages:

       - 'derivepassphrase(1)': reference/derivepassphrase.1.md

       - 'derivepassphrase-vault(1)': reference/derivepassphrase-vault.1.md

@@ -116,6 +119,7 @@ nav:

       - Submodule ssh_agent: reference/derivepassphrase.ssh_agent.md

       - Submodule _types: reference/derivepassphrase._types.md

       - Submodule vault: reference/derivepassphrase.vault.md

+    - 'API docs: Module derivepassphrase_sshagentsocketprovider': reference/derivepassphrase_sshagentsocketprovider.md

     - Technical prerequisites:

       - 'Using derivepassphrase vault with an SSH key': reference/prerequisites-ssh-key.md

   - Design & Background:

@@ -19,6 +19,8 @@ nav:

     - how-tos/passphrase-rotation.md

   - Reference:

     - reference/index.md

+    - Interfaces:

+      - SSH agent socket providers: reference/ssh-agent-socket-providers.md

     - Man pages:

       - 'derivepassphrase(1)': reference/derivepassphrase.1.md

       - 'derivepassphrase-vault(1)': reference/derivepassphrase-vault.1.md

@@ -31,6 +33,7 @@ nav:

       - Submodule ssh_agent: reference/derivepassphrase.ssh_agent.md

       - Submodule _types: reference/derivepassphrase._types.md

       - Submodule vault: reference/derivepassphrase.vault.md

+    - 'API docs: Module derivepassphrase_sshagentsocketprovider': reference/derivepassphrase_sshagentsocketprovider.md

     - Technical prerequisites:

       - 'Using derivepassphrase vault with an SSH key': reference/prerequisites-ssh-key.md

     - 'Internal API docs: Submodule derivepassphrase._internals':

@@ -379,7 +379,7 @@ else:  # pragma: unless the-annoying-os no cover

 class WindowsNamedPipeHandle:

     """A Windows named pipe handle.

-    This handle implements the [`SSHAgentSocket`][_types.SSHAgentSocket]

+    This handle implements the [`SSHAgentSocket`][d_sasp.SSHAgentSocket]

     interface.  It is only constructable if the Python installation can

     successfully call into the Annoying OS `kernel32.dll` library via

     [`ctypes`][].

@@ -17,9 +17,20 @@ if TYPE_CHECKING:

 # Semantic versioning.

 __version__ = "1.0a1"

-# For later major versions, we would choose a different entry point

-# group name.

 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

@@ -85,3 +96,4 @@ class SSHAgentSocketProviderEntry(NamedTuple):

     key: str

     """"""

     aliases: tuple[str, ...]

+    """"""