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/v0.1/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/v0.1/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.
FileDesc(fd)	Wrapper class for a file descriptor that closes it exactly once, either manually or upon object destruction.

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.

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 instance 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.FileDesc(fd)

Wrapper class for a file descriptor that closes it exactly once, either manually or upon object destruction.

Parameters

fd – file descriptor

close()

Ensure fd is closed; operation is idempotent and will call os.close() exactly once.