API Reference¶

This page explains fnb's internal APIs and class structure. Use this reference when extending fnb or using it from other projects.

Package Overview¶

fnb consists of the following modules:

cli: CLI entry point (Typer-based)
options: Shared typer.Option() definitions for CLI consistency
config: Configuration models (Pydantic-based)
reader: Configuration file loading and discovery
gear: rsync execution engine (SSH automation with pexpect)
fetcher: Remote fetch operations
backuper: Local backup operations
uploader: Local-to-remote upload operations
generator: Configuration file generation
env: .env loading and SSH password lookup orchestration
keychain: macOS Keychain password source
gpg: GPG-encrypted password file source

Configuration Management¶

config module¶

::: fnb.config

Configuration File Loading¶

reader module¶

::: fnb.reader

rsync Execution Engine¶

gear module¶

::: fnb.gear

Fetch Operations¶

fetcher module¶

::: fnb.fetcher

Backup Operations¶

backuper module¶

::: fnb.backuper

Upload Operations¶

uploader module¶

::: fnb.uploader

Configuration File Generation¶

generator module¶

::: fnb.generator

CLI Interface¶

cli module¶

::: fnb.cli

Environment Variable Handling¶

env module¶

::: fnb.env

keychain module¶

::: fnb.keychain

gpg module¶

::: fnb.gpg

Usage Examples¶

Basic Programmatic Usage¶

from pathlib import Path
from fnb.reader import ConfigReader
from fnb.fetcher import run as run_fetch
from fnb.backuper import run as run_backup

# Load configuration
reader = ConfigReader(Path("./config.toml"))

# Get tasks
fetch_task = reader.config.get_task_by_label("fetch", "docs")
backup_task = reader.config.get_task_by_label("backup", "docs")

# Execute fetch
if fetch_task and fetch_task.enabled:
    print(f"Fetching {fetch_task.label}...")
    run_fetch(fetch_task, dry_run=False)

# Execute backup
if backup_task and backup_task.enabled:
    print(f"Backing up {backup_task.label}...")
    run_backup(backup_task, dry_run=False)

Custom Configuration Extension¶

from typing import Optional
from pydantic import Field
from fnb.config import RsyncTaskConfig

class ExtendedTaskConfig(RsyncTaskConfig):
    """Extended task configuration with notification options"""
    notify_email: Optional[str] = Field(None, description="Email address for completion notifications")
    notify_on_error: bool = Field(True, description="Whether to send notifications on error")
    retention_days: Optional[int] = Field(None, description="Number of days to retain backups")

Batch Processing Example¶

from fnb.reader import ConfigReader
from fnb.fetcher import run as run_fetch
from fnb.backuper import run as run_backup

def run_all_tasks(config_path: str, dry_run: bool = True):
    """Execute all tasks sequentially"""
    reader = ConfigReader(config_path)

    # Execute all fetch tasks
    for task in reader.config.get_enabled_tasks("fetch"):
        print(f"Fetching: {task.label}")
        run_fetch(task, dry_run=dry_run)

    # Execute all backup tasks
    for task in reader.config.get_enabled_tasks("backup"):
        print(f"Backing up: {task.label}")
        run_backup(task, dry_run=dry_run)