persistent_ssh_agent.core module

Core SSH management module.

备注

For SSHConfig class documentation, see persistent_ssh_agent.config.SSHConfig

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

基类：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.

参数:

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

返回:

Hostname if valid URL, None otherwise

返回类型:

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

参数:

• 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)

返回:

Command result object or None if failed

示例

>>> 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.

参数:

hostname -- Hostname to set up SSH for

返回:

True if setup successful

返回类型:

bool

exception persistent_ssh_agent.core.SSHError

基类：Exception

Base exception for SSH-related errors.