persistent_ssh_agent.core module

Core SSH management module.

class persistent_ssh_agent.core.PersistentSSHAgent(config: SSHConfig | None = None, expiration_time: int = 86400, reuse_agent: bool = True)

Bases: object

Handles persistent SSH agent operations and authentication.

This class manages SSH agent persistence across sessions by saving and restoring agent information. It also handles SSH key management and authentication for various operations including Git.

extract_hostname(url: str) → str | None

Extract hostname from SSH URL (public method).

This is a public wrapper around the extract_hostname function in utils.

Parameters:

url – SSH URL to extract hostname from (e.g., git@github.com:user/repo.git)

Returns:

Hostname if valid URL, None otherwise

Return type:

str

run_git_command_passwordless(command: List[str], username: str | None = None, password: str | None = None, prefer_ssh: bool = True) → object | None

Run any Git command with automatic passwordless authentication.

This method intelligently chooses between SSH and credential helper authentication to execute Git commands without requiring manual password input.

Authentication Strategy: 1. If prefer_ssh=True (default):

• Try SSH authentication first (if SSH is set up for the detected host)

• Fall back to credential helper if SSH fails

2. If prefer_ssh=False: - Try credential helper first (if credentials are available) - Fall back to SSH if credential helper fails

Parameters:

• command – Git command as list (e.g., [‘git’, ‘clone’, ‘repo_url’])

• username – Git username (optional, uses GIT_USERNAME env var if not provided)

• password – Git password/token (optional, uses GIT_PASSWORD env var if not provided)

• prefer_ssh – Whether to prefer SSH over credential helper (default: True)

Returns:

Command result object or None if failed

Example

>>> agent = PersistentSSHAgent()
>>> # Clone with SSH (if available) or credentials
>>> result = agent.run_git_command_passwordless(['git', 'clone', 'git@github.com:user/repo.git'])
>>> # Force credential helper first
>>> result = agent.run_git_command_passwordless(
...     ['git', 'pull'], username='user', password='token', prefer_ssh=False
... )

setup_ssh(hostname: str) → bool

Set up SSH authentication for a host.

Parameters:

hostname – Hostname to set up SSH for

Returns:

True if setup successful

Return type:

bool

exception persistent_ssh_agent.core.SSHError

Bases: Exception

Base exception for SSH-related errors.