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¶
-
class
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)¶ Get the group object with the given name.
Parameters: group_name (str) – Name of the desired group Returns: The group object for the given name Return type: bundlewrap.group.Group
-
get_node
(node_name)¶ Get the node object with the given name.
Parameters: node_name (str) – Name of the desired node Returns: The node object for the given name Return type: bundlewrap.node.Node
-
nodes_in_all_groups
(group_names)¶ Returns a list of nodes where every node is a member of every group given.
Parameters: group_names (list) – Names of groups to search for common nodes. Returns: All nodes common to all given groups. Return type: list
-
nodes_in_any_group
(group_names)¶ Returns all nodes that are a member of at least one of the given groups.
Parameters: group_names (list) – Names of groups to search for nodes. Returns: All nodes present in at least one group. Return type: generator
-
nodes_in_group
(group_name)¶ Returns a list of nodes in the given group.
Parameters: group_name (str) – Name of the group. Returns: All nodes in that group. Return type: list
-
-
class
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
)
-
name
¶ The internal identifier for this node
-
download
(remote_path, local_path)¶ Downloads a file from the node.
Parameters: - remote_path (str) – Which file to get from the node
- local_path (str) – Where to put the file
-
get_item
(item_id)¶ Get the item object with the given ID (e.g. “file:/etc/motd”).
Parameters: item_id (str) – ID of the desired item Returns: The item object for the given ID Return type: instances of subclasses of bundlewrap.items.Item
-
has_bundle
(bundle_name)¶ True
if the node has a bundle with the given name.Parameters: bundle_name (str) – Name of the bundle to look for Return type: bool
-
has_any_bundle
(bundle_names)¶ True
if the node has a bundle with any of the given names.Parameters: bundle_names (list) – List of bundle names to look for Return type: bool
-
in_group
(group_name)¶ True
if the node is in a group with the given name.Parameters: group_name (str) – Name of the group to look for Return type: bool
-
in_any_group
(group_names)¶ True
if the node is in a group with any of the given names.Parameters: group_names (list) – List of group names to look for Return type: bool
-
run
(command, may_fail=False)¶ Runs a command on the node.
Parameters: - command (str) – What should be executed on the node
- may_fail (bool) – If
False
,bundlewrap.exceptions.RemoteException
will be raised if the command does not return 0.
Returns: An object that holds the return code as well as captured stdout and stderr
Return type: bundlewrap.operations.RunResult
-
upload
(local_path, remote_path, mode=None, owner="", group="")¶ Uploads a file to the node.
Parameters: - local_path (str) – Which file to upload
- remote_path (str) – Where to put the file on the target node
- mode (str) – File mode, e.g. “0644”
- owner (str) – Username of the file owner
- group (str) – Group name of the file group
-
-
class
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)
-