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
orSymlink
.
- 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. If unset, batou will automatically determine if file content is sensitive if it shares words with secrets provided by the environment. This attribute can be set to True or False to make batou consider the file’s content as always or never sensitive, respectively. [Default: None]
- 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 tosource
.
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