btrsync.cli

Command line interface to btrsync. Run as main with ‘-h’ for usage information.

Functions

cli_main(argv)	Parse command-line arguments from argv and run do_btrsync().
cli_parser()	Return an argparse-like parser for btrsync's command-line options.
dest_root(loc[, rootopts, rootargs])	Process a destination location string, returning a tuple of (btrfs_root, receive_path).
do_btrsync(*, src_coros, dst_coro, incls, ...)	Perform btrsync from srcs to dst.
dump_root(odir[, inner_coro, rootopts, rootargs])	Return a (root, receive_path) pair for dumping a stream to a local file.
format_transfer(volpaths, parent, destdir, *)	Format the paths that make up a transfer for display on the command line.
humanbytes(n[, sep])	Represent n bytes in human-readable form using IEC units (i.e., KiB, MiB, etc.).
main()	Call cli_main() with sys.argv.
parse_root(locstr)	Parse a location string into a protocol string and btrfs root options.
process_args(cliargs)	Process argparse-style output into arguments for do_btrsync().
src_root(loc[, rootopts, rootargs])	Process a source location string, returning a tuple of (btrfs_root, matcher_instance).

btrsync.cli.cli_main(argv)

Parse command-line arguments from argv and run do_btrsync().

btrsync.cli.cli_parser()

Return an argparse-like parser for btrsync’s command-line options.

async btrsync.cli.dest_root(loc, rootopts={}, rootargs={})

Process a destination location string, returning a tuple of (btrfs_root, receive_path).

async btrsync.cli.do_btrsync(*, src_coros, dst_coro, incls, excls, auto, confirm, syncer, syncopts, transfer, transopts)

Perform btrsync from srcs to dst.

Parameters

• src_coros – sequence of coroutines that return (source_root, matcher) pairs

• dst_coro – coroutine that returns a (destination_root, receive_path) pair

• incls – list of globs matching subvolumes to include in the sync

• excls – list of globs matching subvolumes to exclude from the sync

• auto – if False do a dry run, if None ask for confirmation, if True proceed without asking

• confirm – Confirm-like class to handle user interaction for confirmation

• syncer – btrsync.sync.BtrSync-like class to use for sync

• syncopts – keyword arguments to pass to syncer

• transfer – btrsync.sync.Transfer-like class to use for sync

• transopts – keyword arguments to pass to transfer

async btrsync.cli.dump_root(odir, inner_coro=None, rootopts={}, rootargs={})

Return a (root, receive_path) pair for dumping a stream to a local file.

btrsync.cli.format_transfer(volpaths, parent, destdir, *, verb=False)

Format the paths that make up a transfer for display on the command line.

Parameters

• volpaths – sequence of paths to send

• parent – parent to use for incremental send, or None for full send

• destdir – destination directory used for receive

• verb – if True include more details

Returns

formatted string

btrsync.cli.humanbytes(n, sep=' ')

Represent n bytes in human-readable form using IEC units (i.e., KiB, MiB, etc.).

Parameters

• n – the number of bytes to represent

• sep – separator between numeric value and unit

Returns

human-readable representation as string

btrsync.cli.main()

Call cli_main() with sys.argv.

btrsync.cli.parse_root(locstr)

Parse a location string into a protocol string and btrfs root options.

Parameters

locstr – the location string to parse

Returns

a tuple (protocol, root_options, root_arguments): the protocol to pass to btrsync.sync.default_root() to obtain a root factory, the arguments to pass to the root factory to obtain a root class, and the location to pass to the root class, respectively.

btrsync.cli.process_args(cliargs)

Process argparse-style output into arguments for do_btrsync().

async btrsync.cli.src_root(loc, rootopts={}, rootargs={})

Process a source location string, returning a tuple of (btrfs_root, matcher_instance).

Classes

BaseMatch()	Match against a set of include and exclude globs.
CliProgress(*args, **kwargs)	Transfer class that periodically reports progress on stdout.
Confirm(src, *args, **kwargs)	Handle the UI aspects of confirming a sync via the command line.
IncrSync(src, dst, *[, srckeys, dstkeys])	btrsync.sync.BtrSync class that skips non-incremental transfers.
SSHLoc(user, host, port)	Convenience class to parse, store, and validate SSH location parameters.
SingleMatch(path)	Match a single path, accounting for include and exclude globs, and stop all processing afterwards.
UnderGlob(glob)	Match all paths that are below or matching a particular glob, further accounting for include and exclude globs.

class btrsync.cli.BaseMatch

Match against a set of include and exclude globs.

If no include globs are given, match all not explicitly excluded.

base_match(path)

Return the form of path to be matched against includes and excludes, or None to exclude it outright.

By default return path unaltered; override to change behavior.

exclude(*globs)

Add globs to the list of excluded globs.

include(*globs)

Add globs to the list of included globs.

match(path)

Return True if path matches against base_match() and current includes and excludes, False otherwise.

stop(paths)

Return True if further processing should stop after handling paths, or False if it should continue.

By default always return False.

class btrsync.cli.CliProgress(*args, **kwargs)

Transfer class that periodically reports progress on stdout.

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.cli.Confirm(src, *args, **kwargs)

Handle the UI aspects of confirming a sync via the command line.

Parameters

src – the SOURCE command line argument currently being processed

confirm()

Called after preview() to give final confirmation.

Returns

'Y' to proceed with sync, 'S' to skip the current source and continue with the next, and 'N' to immediately abort

err(e, *args)

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

head()

Called at the beginning to print a header.

preview()

Called after the dry run sync finishes to print a preview of the transfers to be performed.

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)

Transfer function as expected by btrsync.sync.BtrSync.sync() that only logs transfers.

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.cli.IncrSync(src, dst, *, srckeys=None, dstkeys=None)

btrsync.sync.BtrSync class that skips non-incremental transfers.

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.cli.SSHLoc(user: str, host: str, port: str)

Convenience class to parse, store, and validate SSH location parameters.

asdict()

Return parameters of self in the form of a dict.

classmethod parse_ssh(locstr)

Parse a SSH location from a user@hostname form.

classmethod parse_url(netloc)

Parse a SSH location from a URL netloc component.

validate()

Validate SSH parameters: host cannot be empty, and user or port, if specified, cannot be empty.

Returns

self

Raises

ValueError – for invalid parameters

class btrsync.cli.SingleMatch(path)

Match a single path, accounting for include and exclude globs, and stop all processing afterwards.

Parameters

path – the target path to match

base_match(path)

Match a single path and return it unaltered.

exclude(*globs)

Add globs to the list of excluded globs.

include(*globs)

Add globs to the list of included globs.

match(path)

Return True if path matches against base_match() and current includes and excludes, False otherwise.

stop(paths)

Return True to stop immediately after processing the target path.

class btrsync.cli.UnderGlob(glob)

Match all paths that are below or matching a particular glob, further accounting for include and exclude globs.

Parameters

glob – a shell-like glob matching the path prefix of targets

base_match(path)

Match everything below the base glob, and return a path relative to it.

exclude(*globs)

Add globs to the list of excluded globs.

include(*globs)

Add globs to the list of included globs.

match(path)

Return True if path matches against base_match() and current includes and excludes, False otherwise.

stop(paths)

Return True if further processing should stop after handling paths, or False if it should continue.

By default always return False.