Reference
=========

Loading sources
---------------

.. autofunction:: fabsync.load

.. autoclass:: fabsync.ItemSelector
   :members:

.. class:: fabsync.files.SyncedRoot

   The root of a loaded source tree. This is a subclass of
   :class:`~fabsync.files.SyncedItem`.


Syncing
-------

.. autofunction:: fabsync.isync

.. autofunction:: fabsync.sync

.. class:: fabsync.SyncResult

   The result of syncing a single item.

   .. attribute:: path
      :type: ~pathlib.PurePath

      The full path of the item on the remote host.

   .. attribute:: created
      :type: bool

      True if this item was created.

   .. attribute:: modified
      :type: bool

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

   .. attribute:: diff
      :type: bytes

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

   .. attribute:: item
      :type: ~fabsync.files.SyncedItem

      The item that was synced.

Errors and validation
---------------------

.. autoexception:: fabsync.config.ConfigError

.. autoexception:: fabsync.SyncError

.. autodata:: fabsync.config.schema
   :no-value:


Inspection
----------

These are functions that can help you inspect your configuration.

.. autofunction:: fabsync.files.table

.. autoclass:: fabsync.files.TableRow
   :members:
   :undoc-members:

.. autofunction:: fabsync.files.renderers

.. autofunction:: fabsync.files.tags


Lower-level utilities
---------------------

Additional functions available for investigating the source tree.

.. autofunction:: fabsync.files.walk

.. autofunction:: fabsync.files.select

.. class:: fabsync.files.SyncedItem

   A file or directory loaded from the source tree.

   .. attribute:: src
      :type: ~pathlib.Path

      The local path to the file or directory.

   .. attribute:: dest
      :type: ~pathlib.PurePath

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

   .. attribute:: opts
      :type: ~fabsync.config.Opts

      Metadata and configuration.

   .. attribute:: children
      :type: dict[str, ~fabsync.files.SyncedItem]

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

.. autoclass:: fabsync.config.Opts
   :members:


.. _sync-toml:

_sync.toml
----------

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

.. code-block:: toml

   # 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