Reference

Loading sources

fabsync.load(path, dest='/')[source]

Loads a file tree for syncing.

Parameters:

  • path (Path or str) – A path to the local file tree (usually relative).

  • dest (PurePath or str) – A remote path to sync to (usually absolute).

Return type:

SyncedRoot

class fabsync.ItemSelector(subpath=None, tags=frozenset({}), with_parents=True)[source]

Identifies a subset of items under a SyncedRoot.

This essentially defines a filter to apply when traversing the source tree. The default values match all items.

Parameters:
subpath: PurePath | None = None

A relative path into the source tree. We’ll traverse the tree from this point. If the path isn’t found, no items will be selected.

tags: AbstractSet[str] = frozenset({})

A set of tags to select. If empty, we will ignore tags. Otherwise, we’ll only include items with at least one matching tag.

with_parents: bool = True

If True (the default), we’ll ensure that any time we select an item, all of its parent directories are selected as well. Thus, if you select a specific file—by path, tag, etc.—you’re actually saying “select this item and all items necessary to reach it.”

classmethod new(subpath=None, tags=(), with_parents=True)[source]

Creates a new ItemSelector, with more flexible argument types.

Parameters:
Return type:

ItemSelector

class fabsync.files.SyncedRoot

The root of a loaded source tree. This is a subclass of SyncedItem.

Syncing

fabsync.isync(conn, root, selector=None, renderers=None, *, dry_run=False, no_chown=False)[source]

Synchronizes all or part of a local file tree with a remote host.

This processes files and directories lazily, yielding each result before proceeding to the next item. This is useful for communicating results in real time as well as potentially terminating the process before the end.

Parameters:

  • conn (Connection) – Usually a Fabric connection. If this is an invoke Context, we’ll operate locally instead.

  • root (SyncedRoot) – The root of the tree to sync. Get this from fabsync.load().

  • selector (ItemSelector) – Optional parameters to select a subset of the tree to sync.

  • renderers (dict) – Optional map of keys to render functions.

  • dry_run (bool) – If true, we will inspect the remote system and report changes, but nothing will be modified.

  • no_chown (bool) – If true, we will completely ignore file ownership. This is primarily useful in local mode, in which you likely don’t have permission for os.chown().

Return type:

Generator[SyncResult, None, None]

fabsync.sync(*args, **kwargs)[source]

Synchronizes all or part of a local file tree with a remote host.

This is just a wrapper around isync() that gathers up all of the results to return at the end.

Return type:

dict[PurePath, SyncResult]

class fabsync.SyncResult

The result of syncing a single item.

path: PurePath

The full path of the item on the remote host.

created: bool

True if this item was created.

modified: bool

True if this item was created or modified in any way.

diff: bytes

A diff of the original and uploaded content, if applicable.

item: SyncedItem

The item that was synced.

Errors and validation

exception fabsync.config.ConfigError(msg, path)[source]

An error processing a _sync.toml file.

Parameters:

  • msg (str)

  • path (Path)

exception fabsync.SyncError[source]

An unrecoverable error during sync.

fabsync.config.schema: dict

A JSON Schema describing the format of _sync.toml files.

Inspection

These are functions that can help you inspect your configuration.

fabsync.files.table(items, header=True, relative_src=False)[source]

A convenience function to generate human-readble data about items.

This can be used to inspect your configuration by printing a table to the terminal or any other output format you find convenient.

Parameters:

  • items (Iterable[SyncedItem]) – A collection of SyncedItem, presumably from walk() or select().

  • header (bool) – If True (the default), the first item will be a header row.

  • relative_src (bool) – If True, the src property of each row will be relative to the working directory.

Return type:

Iterator[TableRow]

class fabsync.files.TableRow(src, path, user, group, mode, renderer, diff, tags)[source]

Items generated by table().

Note that columns may be added in the future to include new features. Try not to make too many assumptions about this field list.

Parameters:
src: str

The local path

path: str

The remote path

user: str

User name or id

group: str

Group name or id

mode: str

Mode

renderer: str

Renderer name

diff: str

Does this item support diffs?

tags: str

Space-separated tags

fabsync.files.renderers(items)[source]

Returns the set of renderer names referenced by a collection of items.

Parameters:

items (Iterable[SyncedItem]) – A collection of SyncedItem, presumably from walk() or select().

Return type:

frozenset[str]

fabsync.files.tags(items)[source]

Returns the set of tags referenced by a collection of items.

Parameters:

items (Iterable[SyncedItem]) – A collection of SyncedItem, presumably from walk() or select().

Return type:

frozenset[str]

Lower-level utilities

Additional functions available for investigating the source tree.

fabsync.files.walk(top)[source]

Generates a simple depth-first traversal of the items rooted at top.

Parameters:

top (SyncedItem) – The starting point.

Return type:

Iterator[SyncedItem]

fabsync.files.select(root, selector)[source]

Traverses the file tree, returning only items that match selector.

Parameters:
Return type:

Iterator[SyncedItem]

class fabsync.files.SyncedItem

A file or directory loaded from the source tree.

src: Path

The local path to the file or directory.

dest: PurePath

The remote (target) path of the file or directory.

opts: Opts

Metadata and configuration.

children: dict[str, SyncedItem]

A map of (local) file and directory names to items directly underneath it.

class fabsync.config.Opts(name, user=-1, group=-1, perms=-1, tags=frozenset({}), renderer='', vars=<factory>, diff=True, ignore=False)[source]

Normalized options for a file or directory.

Parameters:
name: str

The unqualified name of the item, used to build the remote path.

user: str | int = -1

The user (name or ID) that should own this item.

group: str | int = -1

The group (name or ID) that should own this item.

perms: int = -1

The permissions to set.

tags: AbstractSet[str] = frozenset({})

Tags identifying this item for selection.

renderer: str = ''

The name of the renderer (ignored by directories).

vars: Mapping[str, Any]

Additional context for the render function.

diff: bool = True

True if this file can be diffed (ignored by directories).

_sync.toml

Every directory in the source tree may have a _sync.toml to add configuration and metadata.

# Keys at the top level of _sync.toml pertain to the immediate parent
# directory.

# Override the name of this directory. The default is to use the local name
# on disk. This must be a valid non-special file system name. In other
# words, no path separators and you can't use '.' or '..'. If you manage to
# do something sneaky with this, I don't want to hear your tale of woe.
name = 'etc'

# The user and group of this directory. These can be names or uid/gid
# numbers. Set to -1 (the default) to leave them unspecified.
user = 'root'
group = 0

# Permissions for chmod. This must be an integer, usually expressed in
# octal. Set to -1 (the default) to leave it unspecified.
perms = 0o755

# Directories and files can be tagged so that you can sync a specific
# subset of the tree. Tags accumulate, so this adds 'tag1' to any tags that
# were inherited from a [defaults] section. Tags can be removed with a
# hyphen prefix. A tag of '-' removes all inherited tags.
tags = ['tag1', '-tagX']

# Directories (and files) can be ignored. This is useful in rare cases and can
# serve as an escape hatch if you need to hide one or more files temporarily
# without removing them from version control. Ignoring a directory prunes the
# entire subtree.
ignore = false

# Settings for files in this directory. Keys are (local) file names and
# values are maps like the top level of this config. Note that these apply
# to files only: entries for child directories are ignored.
[files]
'pf.conf' = { user = 'root', group = 0, perms = 0o640 }
dot-something = { name = '.something' }

# Naturally, you can also give files their own sections. Filenames with dots
# (probably most of them) will of course need to be quoted.
[files.'sudoers']
user = 0
group = 'wheel'
perms = 0o440
tags = ['-', 'tag3']
ignore = false

# When we upload a file, we normally provide a diff of the changes. If you
# have files that can't or shouldn't be diffed, you can disable this.
diff = false

# Files can be passed through a rendering function before being uploaded.
# This is just an arbitrary name; when syncing, you'll need to supply a
# dictionary mapping your renderer names to actual functions.
renderer = 'jinja2'

# The render function will also receive a dictionary with file-specific
# render context. Vars can also be added to [defaults] and will be
# shallow-merged.
[files.'sudoers'.vars]
sudoers.alice = 'nopasswd'
sudoers.bob = true

# Settings that will serve as defaults for this directory and all
# directories and files under it. Values are the same as above.
[defaults]
user = -1
group = -1
dir_perms = -1
file_perms = -1
tags = ['tag2']
renderer = ''
vars = {}
diff = true