btrsync.sync

Btrfs subvolume synchronization.

Functions

default_root(protocol)

Get the default btrfs root used to handle protocol.

btrsync.sync.default_root(protocol)

Get the default btrfs root used to handle protocol.

Parameters

protocol – btrfs protocol to use; valid values are 'local', 'ssh', 'file', and 'file-dump'.

Returns

appropriate btrsync.sync.root.BtrfsRoot subclass factory for protocol

Raises

ValueError – if protocol is unknown

Classes

BtrSync(src, dst, *[, srckeys, dstkeys])	Base class containing logic to sync btrfs subvolumes from a source root to a destination root.
ProgressTransfer(*[, period, prog_seq])	Transfer class providing a mechanism for logging transfer progress.
Transfer(*[, recvpath, replicate_dirs])	Base class implementing a transfer as required by BtrSync.sync().

class btrsync.sync.BtrSync(src, dst, *, srckeys=None, dstkeys=None)

Base class containing logic to sync btrfs subvolumes from a source root to a destination root.

Parameters

• src – source btrfs root (btrsync.sync.root.BtrfsRoot-like instance)

• dst – destination btrfs root (btrsync.sync.root.BtrfsRoot-like instance)

• srckeys – key functions to be applied to the subvolumes of src, if None use default key functions

• dstkeys – key functions to be applied to the subvolumes of dst, if None use default key functions

Key functions take a subvolume as argument and return a value that is then used for equality testing. Two subvolumes are considered equal if any of their key values compare equal and are not None. The default key functions return the UUID and received UUID of subvolumes.

static check(vol, parent)

Return True if the sync of vol with COW parent parent should proceed.

parent(vol)

Return the COW parent of vol to be used as basis for incremental send, or None if unavailable.

static stop(vols)

Called after vols have been synced; return True if sync should immediately stop.

async sync(trans, *, batch=False, parallel=False, transfer_existing=False, volgroups=None, target=None, parent=None, check=None, stop=None)

Perform synchronization of subvolumes.

Returns whether the sync was successful and all error handling is delegated to trans.

Parameters

• trans – Transfer-like object to perform the actual send/receive operations

• batch – if True, batch together multiple volumes into a single transfer

• parallel – if True, run independent transfers in parallel

• transfer_existing – if True, consider for transfer volumes that already exist on the destination

• volgroups – override for volgroups()

• target – override for target()

• parent – override for parent()

• check – override for check()

• stop – override for stop()

Returns

True if sync successful, False if errors occured

static target(vol)

Return True if vol is to be considered for sync.

static volgroups(roots)

Iterate over roots and their descendants in groups of COW-independent volumes.

class btrsync.sync.ProgressTransfer(*, period=1, prog_seq=[], **kwargs)

Transfer class providing a mechanism for logging transfer progress.

Parameters

• period – time, in seconds, between progress reporting events

• prog_seq – sequence to be cycled through to indicate activity

• kwargs – additional keyword arguments to pass to the superclass Transfer’s constructor

err(e, *args)

Called on encountering an exception e; expected to log the error and return successfully.

async progress(flow, seq)

Implement progress reporting every period seconds.

async report(vols, par, src, dst)

Called at the start of a transfer of volumes vols with parent par from src to dst.

async report_done(vols, par, src, dst)

Called when the transfer of volumes vols with parent par from src to dst has finished.

async report_progress(total, prev, seq)

Called on every progress reporting event.

Parameters

• total – currrent total bytes transferred

• prev – value of total from previous call

• seq – sequence to indicate activity

async transf(vols, par, src, dst)

Progress reporting transfer function, as expected by .BtrSync.sync.

Parameters

• vols – the subvolumes to transfer

• par – the parent subvolume to use for an incremental transfer

• src – the source btrfs root

• dst – the destination btrfs root

Raises

asyncio.CancelledError – if any error has occurred, after logging it with err()

async try_await(aw)

Try awaiting awaitable aw, converting any exceptions to asyncio.CancelledError.

Exceptions raised by aw will be logged by err().

async try_gather(*coroutines)

Try running and waiting for all coroutines, canceling all upon error.

Exceptions raised by the tasks will be logged by err().

Raises

asyncio.CancelledError – if any tasks raise an exception

class btrsync.sync.Transfer(*, recvpath='.', replicate_dirs=False)

Base class implementing a transfer as required by BtrSync.sync().

Parameters

• recvpath – the path that transfers are received into

• replicate_dirs – if True adapt recvpath to recreate the sent volumes’ directory structure

err(e, *args)

Called on encountering an exception e; expected to log the error and return successfully.

async report(vols, par, src, dst)

Called at the start of a transfer of volumes vols with parent par from src to dst.

async report_done(vols, par, src, dst)

Called when the transfer of volumes vols with parent par from src to dst has finished.

async transf(vols, par, src, dst)

Minimal quiet transfer function, as expected by BtrSync.sync().

Parameters

• vols – the subvolumes to transfer

• par – the parent subvolume to use for an incremental transfer

• src – the source btrfs root

• dst – the destination btrfs root

Raises

asyncio.CancelledError – if any error has occured, after logging it with err()

async try_await(aw)

Try awaiting awaitable aw, converting any exceptions to asyncio.CancelledError.

Exceptions raised by aw will be logged by err().

async try_gather(*coroutines)

Try running and waiting for all coroutines, canceling all upon error.

Exceptions raised by the tasks will be logged by err().

Raises

asyncio.CancelledError – if any tasks raise an exception

Modules

btrsync.sync.root

Generic interface to a btrfs filesystem.