btrsync.util

Various general purpose utility classes and functions.

Functions

bfs(childf, *nodes[, maxdepth, depth_markers])	Generic breadth-first search iterator over nodes using childf to determine child nodes.
dfs(childf, node)	Generic depth-first search iterator over node using childf to determine child nodes.
group(seq, *keys)	Group items in sequence seq by keys.
index(seq, *keys)	Index sequence seq with a series of keys.
is_subpath(p, *[, path])	Determine whether p is a subpath, i.e., p is relative and does not go above its parent directory.
path_merge(a, b, *[, root, path])	Join paths a and b after removing the longest prefix of b that is also a suffix of a.

btrsync.util.bfs(childf, *nodes, maxdepth=None, depth_markers=False)

Generic breadth-first search iterator over nodes using childf to determine child nodes.

Parameters

• childf – function such that childf(node) returns a sequence of child nodes

• nodes – the starting set of nodes for breadth-first search

• maxdepth – if not None, stop after returning nodes at this depth (nodes are at depth 0)

• depth_markers – if True, return a None as marker after exhausting all nodes at a particular depth

btrsync.util.dfs(childf, node)

Generic depth-first search iterator over node using childf to determine child nodes.

Parameters

• childf – function such that childf(node) returns a sequence of child nodes

• node – the starting node for depth-first search

btrsync.util.group(seq, *keys)

Group items in sequence seq by keys.

Parameters

• seq – the sequence to process

• keys – a sequence of functions that take an element from seq and return a group index

Returns

a list of dicts indexed by each key in keys, with values lists of elements from seq that share a group index

btrsync.util.index(seq, *keys)

Index sequence seq with a series of keys.

Parameters

• seq – the sequence to process

• keys – a sequence of functions that take an element from seq and return a unique index value

Returns

a list of dicts indexed by each key in keys, with values elements from seq

Raises

ValueError – if two elements of seq index to the same value for any of the keys

btrsync.util.is_subpath(p, *, path=<module 'posixpath' from '/home/docs/checkouts/readthedocs.org/user_builds/btrsync/envs/stable/lib/python3.7/posixpath.py'>)

Determine whether p is a subpath, i.e., p is relative and does not go above its parent directory.

Parameters

• p – the path to examine

• path – the path module to use (e.g. os.path, posixpath, etc.)

Returns

boolean whether p is a subpath

btrsync.util.path_merge(a, b, *, root='/', path=<module 'posixpath' from '/home/docs/checkouts/readthedocs.org/user_builds/btrsync/envs/stable/lib/python3.7/posixpath.py'>)

Join paths a and b after removing the longest prefix of b that is also a suffix of a.

Parameters

• a – the left-hand path to be merged

• b – the right-hand path to be merged

• root – the root directory for a beyond which one cannot go further up

• path – the path module to use (e.g. os.path, posixpath, etc.)

Returns

the merged path

Classes

Cmd(prg[, args])	Convenience class for parsing shell commands to and from a (program, arguments) representation.
FileFlow(f)	Flow sourced from a locally opened file.
Flow()	Abstract base class for a flow of bytes that can be exposed through different interfaces.
PipeFlow(f)	Flow sourced from the read end of a UNIX pipe.

class btrsync.util.Cmd(prg, args=())

Convenience class for parsing shell commands to and from a (program, arguments) representation.

classmethod from_cmdstr(cmd)

Parse a shell command string into a Cmd representation.

pipe_arg(pipe)

Return a new Cmd with a shell pipeline as last argument.

Parameters

pipe – sequence of Cmd that form the pipeline

Returns

the new Cmd instance

classmethod pipeline(pipe)

Parse a shell pipeline into a sequence of Cmd representations.

classmethod seq(seq)

Parse a sequence of shell command strings into Cmd representations.

shellify()

Return a properly shell-escaped command string form of self.

wrap(outer, *, shellfmt=False, endmark=None)

Return a new Cmd that passes self as arguments to outer.

Parameters

• outer – the outer command that receives self as arguments

• shellfmt – if True, pass a shell-escaped form of self as a single last argument to outer; if False, prg along with args are passed as individual arguments to outer

• endmark – if not None, append endmark as final argument to outer, after self

Returns

the new wrapped Cmd instance

class btrsync.util.FileFlow(f)

Flow sourced from a locally opened file.

Parameters

f – file-like object backed by a file descriptor

connect_fd()

Expose flow as a raw file descriptor.

Returns

a file-like object backed by a file descriptor

connect_pipe()

Expose flow as a UNIX pipe.

Returns

a file-like object backed by the read end of a UNIX pipe

connect_to_fd(f)

Direct flow to file-like object f that provides a file descriptor.

property count

Total bytes transmitted if stats is True, None otherwise.

pump()

Return a coroutine that handles data flow when run.

Raises

ValueError – if called before one of the connect_* methods

property stats

If True, count will tally bytes transmitted.

class btrsync.util.Flow

Abstract base class for a flow of bytes that can be exposed through different interfaces.

Flows are set up to expose a specific interface with one of the connect_* methods. Subsequently, running the coroutine returned by pump() handles I/O and any necessary processing. A tally of transmitted bytes can be found in count if stats is True.

abstract connect_fd()

Expose flow as a raw file descriptor.

Returns

a file-like object backed by a file descriptor

abstract connect_pipe()

Expose flow as a UNIX pipe.

Returns

a file-like object backed by the read end of a UNIX pipe

abstract connect_to_fd(f)

Direct flow to file-like object f that provides a file descriptor.

property count

Total bytes transmitted if stats is True, None otherwise.

pump()

Return a coroutine that handles data flow when run.

Raises

ValueError – if called before one of the connect_* methods

property stats

If True, count will tally bytes transmitted.

class btrsync.util.PipeFlow(f)

Flow sourced from the read end of a UNIX pipe.

Parameters

f – file-like object backed by a file descriptor of the read end of the pipe

connect_fd()

Expose flow as a raw file descriptor.

Returns

a file-like object backed by a file descriptor

connect_pipe()

Expose flow as a UNIX pipe.

Returns

a file-like object backed by the read end of a UNIX pipe

connect_to_fd(f)

Direct flow to file-like object f that provides a file descriptor.

property count

Total bytes transmitted if stats is True, None otherwise.

pump()

Return a coroutine that handles data flow when run.

Raises

ValueError – if called before one of the connect_* methods

property stats

If True, count will tally bytes transmitted.