tessl/pypi-borgbackup

Deduplicated, encrypted, authenticated and compressed backups

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Repository Management

Name: tessl/pypi-borgbackup
Author: tessl

Repository initialization, configuration, and maintenance operations for managing BorgBackup repositories.

import subprocess
import json

Capabilities

Repository Initialization

Initialize a new BorgBackup repository with specified encryption method.

def init_repository(repo_path: str, encryption: str = 'repokey', **options) -> None:
    """
    Initialize a new repository.
    
    Args:
        repo_path: Path to repository location
        encryption: Encryption mode ('none', 'keyfile', 'repokey', 'keyfile-blake2', 'repokey-blake2', 'authenticated', 'authenticated-blake2')
        **options: Additional options like append_only, storage_quota
    """
    cmd = ['borg', 'init', f'--encryption={encryption}']
    if options.get('append_only'):
        cmd.append('--append-only')
    if options.get('storage_quota'):
        cmd.extend(['--storage-quota', str(options['storage_quota'])])
    cmd.append(repo_path)
    subprocess.run(cmd, check=True)

Usage example:

import subprocess

# Initialize with repokey encryption
subprocess.run(['borg', 'init', '--encryption=repokey', '/backup/repo'], check=True)

# Initialize append-only repository
subprocess.run(['borg', 'init', '--encryption=repokey', '--append-only', '/backup/repo'], check=True)

# Initialize with storage quota (in bytes)
subprocess.run(['borg', 'init', '--encryption=repokey', '--storage-quota=10G', '/backup/repo'], check=True)

Repository Information

Get comprehensive information about a repository including encryption, cache, and statistics.

def get_repository_info(repo_path: str, json_output: bool = True) -> dict:
    """
    Get repository information.
    
    Args:
        repo_path: Path to repository
        json_output: Return structured JSON data
        
    Returns:
        Dictionary containing repository metadata, cache info, and encryption details
    """
    cmd = ['borg', 'info', repo_path]
    if json_output:
        cmd.append('--json')
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return json.loads(result.stdout) if json_output else result.stdout

Usage example:

import subprocess
import json

# Get repository info as JSON
result = subprocess.run(['borg', 'info', '--json', '/backup/repo'], 
                       capture_output=True, text=True, check=True)
repo_info = json.loads(result.stdout)

print(f"Repository ID: {repo_info['repository']['id']}")
print(f"Encryption: {repo_info['encryption']['mode']}")
print(f"Location: {repo_info['repository']['location']}")

Repository Verification

Check repository consistency and detect corruption.

def check_repository(repo_path: str, verify_data: bool = False, repair: bool = False) -> None:
    """
    Verify repository consistency.
    
    Args:
        repo_path: Path to repository
        verify_data: Verify data integrity (slower)
        repair: Attempt to repair inconsistencies
    """
    cmd = ['borg', 'check']
    if verify_data:
        cmd.append('--verify-data')
    if repair:
        cmd.append('--repair')
    cmd.append(repo_path)
    subprocess.run(cmd, check=True)

Usage example:

import subprocess

# Basic repository check
subprocess.run(['borg', 'check', '/backup/repo'], check=True)

# Check with data verification (slower but more thorough)
subprocess.run(['borg', 'check', '--verify-data', '/backup/repo'], check=True)

# Check and attempt repairs
subprocess.run(['borg', 'check', '--repair', '/backup/repo'], check=True)

Repository Configuration

Manage repository configuration and settings.

def configure_repository(repo_path: str, **config_options) -> None:
    """
    Configure repository settings.
    
    Args:
        repo_path: Path to repository
        **config_options: Configuration options to set
    """
    for key, value in config_options.items():
        cmd = ['borg', 'config', repo_path, key, str(value)]
        subprocess.run(cmd, check=True)

def get_repository_config(repo_path: str, key: str = None) -> str:
    """
    Get repository configuration value.
    
    Args:
        repo_path: Path to repository
        key: Specific configuration key (optional)
        
    Returns:
        Configuration value or all configuration if key not specified
    """
    cmd = ['borg', 'config', repo_path]
    if key:
        cmd.append(key)
    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
    return result.stdout.strip()

Usage example:

import subprocess

# Set repository configuration
subprocess.run(['borg', 'config', '/backup/repo', 'additional_free_space', '2G'], check=True)

# Get configuration value
result = subprocess.run(['borg', 'config', '/backup/repo', 'additional_free_space'], 
                       capture_output=True, text=True, check=True)
free_space = result.stdout.strip()

Repository Key Management

Manage repository encryption keys including export, import, and change operations.

def export_key(repo_path: str, output_file: str, paper: bool = False) -> None:
    """
    Export repository key.
    
    Args:
        repo_path: Path to repository
        output_file: Path to output key file
        paper: Export in paper format for printing
    """
    cmd = ['borg', 'key', 'export']
    if paper:
        cmd.append('--paper')
    cmd.extend([repo_path, output_file])
    subprocess.run(cmd, check=True)

def import_key(repo_path: str, key_file: str, paper: bool = False) -> None:
    """
    Import repository key.
    
    Args:
        repo_path: Path to repository
        key_file: Path to key file
        paper: Import from paper format
    """
    cmd = ['borg', 'key', 'import']
    if paper:
        cmd.append('--paper')
    cmd.extend([repo_path, key_file])
    subprocess.run(cmd, check=True)

def change_passphrase(repo_path: str) -> None:
    """
    Change repository passphrase.
    
    Args:
        repo_path: Path to repository
    """
    cmd = ['borg', 'key', 'change-passphrase', repo_path]
    subprocess.run(cmd, check=True)

def migrate_to_repokey(repo_path: str) -> None:
    """
    Migrate passphrase-mode repository to repokey.
    
    Args:
        repo_path: Path to repository
    """
    cmd = ['borg', 'key', 'migrate-to-repokey', repo_path]
    subprocess.run(cmd, check=True)

Usage example:

import subprocess

# Export key to file
subprocess.run(['borg', 'key', 'export', '/backup/repo', '/secure/backup-key.txt'], check=True)

# Export key in paper format
subprocess.run(['borg', 'key', 'export', '--paper', '/backup/repo', '/secure/backup-key-paper.txt'], check=True)

# Import key from file
subprocess.run(['borg', 'key', 'import', '/backup/repo', '/secure/backup-key.txt'], check=True)

# Change repository passphrase
subprocess.run(['borg', 'key', 'change-passphrase', '/backup/repo'], check=True)

# Migrate from keyfile to repokey mode
subprocess.run(['borg', 'key', 'migrate-to-repokey', '/backup/repo'], check=True)

Types

class RepositoryConfig:
    """Repository configuration structure"""
    def __init__(self):
        self.additional_free_space: str  # Additional free space to maintain
        self.append_only: bool           # Append-only mode
        self.storage_quota: str          # Storage quota limit
        
class EncryptionInfo:
    """Repository encryption information"""
    def __init__(self):
        self.mode: str          # Encryption mode
        self.keyfile: str       # Path to keyfile (if applicable)
        
class RepositoryStats:
    """Repository statistics"""
    def __init__(self):
        self.total_chunks: int
        self.total_csize: int       # Compressed size
        self.total_size: int        # Original size
        self.total_unique_chunks: int
        self.unique_csize: int      # Unique compressed size
        self.unique_size: int       # Unique original size

Install with Tessl CLI