Managing files and directories

Files and Templates

The File component has been developed with Puppet’s file type in mind. It accepts a very similar parameter set and has almost identical features.

You can use it to manage files, directories, and symlinks, and you can specify content (literally or as Jinja templates). You can also manage the Unix attributes and control whether leading directories should be managed or not.

The most basic usage is simply:

self += File('myfile')

This example creates a file at work/mycomponent/myfile, taking the contents from a file of the same name in the component’s directory (i.e. components/mycomponent/myfile). By default, the source file is run through Jinja, with the file’s parent component made available as component.

class batou.lib.file.File(path)

Creates a file. The main parameter for File is the target path. A File instance has an attribute path containing the full, absolute path to the resulting file.

File accepts the following additional parameters:

source

Filename of the source file to be used as the File’s content (absolute path or relative to the component’s directory). [Default: same as target path]

content

Literal file contents as a string.

is_template

Process file contents as Jinja template. [Default: True]

template_context

Object to make available as component to the Jinja template. [Default: File’s parent component]

template_args

Dict of additional arguments to make available to the Jinja template.

encoding

Encoding for the file contents [Default: utf-8]

owner

Unix owner username.

group

Unix group name.

mode

Unix permission mode. Can be given as an integer value (0o755) or as an octal integer string (‘755’) or as a unix mode string similar to the output of ls -l (‘rwx–x–x’).

leading

Create leading directories that were given in the target path. [Default: False]

ensure

Type of object to be created: ‘file’, ‘directory’, or ‘symlink’. This is useful for complex situations (e.g. creating a symlink with special ownership), for simple situations it’s probably more readable to use Directory or Symlink.

link_to

Source of symlink (for ensure = ‘symlink’)

sensitive_data

Mark a file as sensitive so its content is not exposed by the (diff-)output of batou. This is useful in situations where the rendered file contains a password or other sensitive data. [Default: False]

class batou.lib.file.BinaryFile(path)

Subclass of batou.lib.file.File. Creates a non-template binary file.

Directories

class batou.lib.file.Directory(path)

Creates a directory. The main parameter is the target path.

source

Path to a source directory whose contents are to be synchronized to the target path (uses rsync internally).

exclude

List of file names or patterns that should not be synchronized to the target path (passed to rsync as --exclude argument, see the rsync documentation for details).

class Symlink(target, source)

Creates a symlink at target by linking to source.

Removing files

Removal of obsolete things is a difficult topic in the convergence paradigm. If in the past we created a file foo, but now it is not used anymore, the code that originally said, “please manage foo”, will not be there anymore. This means that nobody knows that the file foo that is still lying around on the production system is not actually in use anymore. In most cases, a few stray files do not matter, but in case they do, the deployment code has to explicitly state that something should not be present anymore.

class batou.lib.file.Purge(pattern)

Ensures that a set of files (given as a glob pattern) does not exist.

Extracting archive files

batou can extract archive files in Tar, Zip, and DMG (on OSX target machines) format:

class batou.lib.archive.Extract(archive)

The main parameter is the archive filename (relative to the component’s directory). The archive format is determined according to the file name extension (‘.tar’, ‘.tar.gz’, ‘.tgz’, ‘.tar.bz2’, ‘.tar.xz’ use tar, ‘.zip’ uses unzip and ‘.dmg’ uses hdiutil). The following additional parameters are supported:

target

Target directory to extract the archive into. Directory is created if it does not exist (compare create_target_dir). [Default: base name of the archive file]

create_target_dir

Extract into the directory given in target. Set to False to extract directly into the work directory. [Default: True]

strip

Only for tar archives: number of directories contained in the archive to strip off (see the tar documentation for details) [Default: 0]

VFS mapping (TODO)

XXX writeme