API
While most users will interact with BundleWrap through the bw
command line utility, you can also use it from your own code to extract data or further automate config management tasks.
Even within BundleWrap itself (e.g. templates, libs, and hooks) you are often given repo and/or node objects to work with. Their methods and attributes are documented below.
Some general notes on using BundleWrap's API:
- There can be an arbitrary amount of
bundlewrap.repo.Repository
objects per process. - Repositories are read as needed and not re-read when something changes. Modifying files in a repo during the lifetime of the matching Repository object may result in undefined behavior.
Example
Here's a short example of how to use BundleWrap to get the uptime for a node.
from bundlewrap.repo import Repository
repo = Repository("/path/to/my/repo")
node = repo.get_node("mynode")
uptime = node.run("uptime")
print(uptime.stdout)
Reference
bundlewrap.repo.Repository(path)
The starting point of any interaction with BundleWrap. An object of this class represents the repository at the given path.
.groups
A list of all groups in the repo (instances of bundlewrap.group.Group
)
.group_names
A list of all group names in this repo.
.nodes
A list of all nodes in the repo (instances of bundlewrap.node.Node
)
.node_names
A list of all node names in this repo
.revision
The current git, hg or bzr revision of this repo. None
if no SCM was detected.
.get_group(group_name)
Returns the Group object for the given name.
.get_node(node_name)
Returns the Node object with the given name.
.nodes_in_all_groups(group_names)
Returns a list of Node objects where every node is a member of every group name given.
.nodes_in_any_group(group_names)
Returns all Node objects that are a member of at least one of the given group names.
.nodes_in_group(group_name)
Returns a list of Node objects in the named group.
bundlewrap.node.Node()
A system managed by BundleWrap.
.bundles
A list of all bundles associated with this node (instances of bundlewrap.bundle.Bundle
)
.groups
A list of bundlewrap.group.Group
objects this node belongs to
.hostname
The DNS name BundleWrap uses to connect to this node
.items
A list of items on this node (instances of subclasses of bundlewrap.items.Item
)
.metadata
A dictionary of custom metadata, merged from information in nodes.py and groups.py
.name
The internal identifier for this node
.download(remote_path, local_path)
Downloads a file from the node.
remote_path
Which file to get from the node
local_path
Where to put the file
.get_item(item_id)
Get the Item object with the given ID (e.g. "file:/etc/motd").
.has_bundle(bundle_name)
True
if the node has a bundle with the given name.
.has_any_bundle(bundle_names)
True
if the node has a bundle with any of the given names.
.in_group(group_name)
True
if the node is in a group with the given name.
.in_any_group(group_names)
True
if the node is in a group with any of the given names.
.run(command, may_fail=False)
Runs a command on the node. Returns an instance of bundlewrap.operations.RunResult
.
command
What should be executed on the node
may_fail
If False
, bundlewrap.exceptions.RemoteException
will be raised if the command does not return 0.
.upload(local_path, remote_path, mode=None, owner="", group="")
Uploads a file to the node.
local_path
Which file to upload
remote_path
Where to put the file on the target node
mode
File mode, e.g. "0644"
owner
Username of the file owner
group
Group name of the file group
bundlewrap.group.Group
A user-defined group of nodes.
.name
The name of this group
.nodes
A list of all nodes in this group (instances of bundlewrap.node.Node
, includes subgroup members)