First stable release almost ready

docs/howto/basic-napalm-getters.rst

@@ -8,13 +8,13 @@ Let's start by seeing how to work with the inventory. Let's assume the following
 
 * Hosts file:
 
-.. literalinclude:: ../../examples/hosts.yaml
+.. literalinclude:: ../../examples/inventory/hosts.yaml
    :name: hosts.yaml
    :language: yaml
 
 * Groups file:
 
-.. literalinclude:: ../../examples/groups.yaml
+.. literalinclude:: ../../examples/inventory/groups.yaml
    :name: groups.yaml
    :language: yaml
 

docs/ref/api/brigade.rst

@@ -1,3 +1,10 @@
+Data
+####
+
+.. autoclass:: brigade.core.Data
+   :members:
+   :undoc-members:
+
 Brigade
 #######
 

docs/ref/api/easy.rst

@@ -0,0 +1,6 @@
+Easy
+====
+
+.. automodule:: brigade.easy
+   :members:
+   :undoc-members:

docs/ref/api/index.rst

@@ -8,5 +8,6 @@ Brigade API Reference
    brigade
    configuration
    inventory
+   easy
    task
-   exceptions
+   exceptions

docs/ref/api/task.rst

@@ -18,3 +18,10 @@ AggregatedResult
 .. autoclass:: brigade.core.task.AggregatedResult
    :members:
    :undoc-members:
+
+MultiResult
+################
+
+.. autoclass:: brigade.core.task.MultiResult
+   :members:
+   :undoc-members:

docs/ref/functions/index.rst

@@ -0,0 +1,8 @@
+Functions
+=========
+
+.. toctree::
+   :maxdepth: 2
+   :glob:
+
+   *

docs/ref/functions/text.rst

@@ -0,0 +1,6 @@
+Text
+====
+
+.. automodule:: brigade.plugins.functions.text
+   :members:
+   :undoc-members:

docs/ref/index.rst

@@ -24,4 +24,5 @@ Reference Guides
    :caption: Plugins
 
    tasks/index
+   functions/index
    inventory/index

docs/ref/inventory/index.rst

@@ -1,3 +1,5 @@
+.. _ref-inventory:
+
 Inventory
 =========
 

docs/tutorials/intro/brigade.rst

@@ -0,0 +1,74 @@
+Brigade
+=======
+
+Now that we know how the inventory works let's create a brigade object we can start working with. There are two ways we can use:
+
+1. Using the :obj:`brigade.core.Brigade` directly, which is quite simple and the most flexible and versatile option.
+2. Using :obj:`brigade.easy.easy_brigade`, which is simpler and good enough for most cases.
+
+Using the "raw" API
+-------------------
+
+If you want to use the "raw" API you need two things:
+
+1. A configuration object.
+2. An inventory object.
+
+Once you have them, you can create the brigade object yourself. For example::
+
+	>>> from brigade.core import Brigade
+	>>> from brigade.core.configuration import Config
+	>>> from brigade.plugins.inventory.simple import SimpleInventory
+	>>>
+	>>> brigade = Brigade(
+	...     inventory=SimpleInventory("hosts.yaml", "groups.yaml"),
+	...     dry_run=False,
+	...     config=Config(raise_on_error=False),
+	... )
+	>>>
+
+Using ``easy_brigade``
+----------------------
+
+With :obj:`brigade.easy.easy_brigade` you only need to do::
+
+	>>> from brigade.easy import easy_brigade
+	>>> brigade = easy_brigade(
+	...         host_file="hosts.yaml", group_file="groups.yaml",
+	...         dry_run=True,
+	...         raise_on_error=False,
+	... )
+	>>>
+
+As you can see is not that different from above but you save a few imports.
+
+Brigade's Inventory
+-------------------
+
+Brigade's object will always have a reference to the inventory you can inspect and work with if you have the need. For instance::
+
+    >>> brigade.inventory
+    <brigade.plugins.inventory.simple.SimpleInventory object at 0x10606bf28>
+    >>> brigade.inventory.hosts
+    {'host1.cmh': Host: host1.cmh, 'host2.cmh': Host: host2.cmh, 'spine00.cmh': Host: spine00.cmh, 'spine01.cmh': Host: spine01.cmh, 'leaf00.cmh': Host: leaf00.cmh, 'leaf01.cmh': Host: leaf01.cmh, 'host1.bma': Host: host1.bma, 'host2.bma': Host: host2.bma, 'spine00.bma': Host: spine00.bma, 'spine01.bma': Host: spine01.bma, 'leaf00.bma': Host: leaf00.bma, 'leaf01.bma': Host: leaf01.bma}
+    >>> brigade.inventory.groups
+    {'all': Group: all, 'bma': Group: bma, 'cmh': Group: cmh}
+
+As you will see further on in the tutorial you will rarely need to work with the inventory yourself as brigade will take care of it for you automatically but it's always good to know you have it there if you need to.
+
+Filtering the hosts
+___________________
+
+As we could see in the :doc:`Inventory <inventory>` section we could filter hosts based on data and attributes. The brigade object can leverage on that feature to "replicate" itself with subsets of devices allowing you to group your devices and perform actions on them as you see fit::
+
+    >>> switches = brigade.filter(type="network_device")
+    >>> switches.inventory.hosts
+    {'spine00.cmh': Host: spine00.cmh, 'spine01.cmh': Host: spine01.cmh, 'leaf00.cmh': Host: leaf00.cmh, 'leaf01.cmh': Host: leaf01.cmh, 'spine00.bma': Host: spine00.bma, 'spine01.bma': Host: spine01.bma, 'leaf00.bma': Host: leaf00.bma, 'leaf01.bma': Host: leaf01.bma}
+    >>> switches_in_bma = switches.filter(site="bma")
+    >>> switches_in_bma.inventory.hosts
+    {'spine00.bma': Host: spine00.bma, 'spine01.bma': Host: spine01.bma, 'leaf00.bma': Host: leaf00.bma, 'leaf01.bma': Host: leaf01.bma}
+    >>> hosts = brigade.filter(type="host")
+    >>> hosts.inventory.hosts
+    {'host1.cmh': Host: host1.cmh, 'host2.cmh': Host: host2.cmh, 'host1.bma': Host: host1.bma, 'host2.bma': Host: host2.bma}
+
+All of the "replicas" of brigade will contain the same data and configuration, only the hosts will differ.

docs/tutorials/intro/index.rst

@@ -13,6 +13,9 @@ We're glad you made it here! This is a great place to learn the basics of Brigad
    Brigade at a glance <overview>
    100% Python <python>
    Installation guide <install>
-   Creating an inventory <inventory>
-   Exploring the inventory <explore>
-   Running tasks <run>
+   inventory
+   brigade
+   running_tasks
+   running_tasks_different_hosts
+   running_tasks_grouping
+   running_tasks_errors

docs/tutorials/intro/inventory.rst

@@ -1,2 +1,131 @@
-Creating an inventory for Brigade
-=================================
+The Inventory
+=============
+
+The inventory is arguably the most important piece of Brigade. The inventory organizes hosts and makes sure tasks have the correct data for each host.
+
+You can create the inventory in different ways, depending on your data source. To see the available plugins you can use go to the :ref:`ref-inventory` reference guide.
+
+.. note:: For this and the subsequent sections of this tutorial we are going to use the :obj:`SimpleInventory <brigade.plugins.inventory.simple.SimpleInventory>` with the data located in ``/examples/inventory/``. We will also use the ``Vagrantfile`` located there so you should be able to reproduce everything. You can head to `Hosts/Groups contents`_ to see the contents of the file just for reference.
+
+First, let's create the inventory::
+
+	>>> from brigade.plugins.inventory.simple import SimpleInventory
+	>>> inventory = SimpleInventory(host_file="hosts.yaml", group_file="groups.yaml")
+
+Now let's inspect the hosts and groups we have::
+
+	>>> inventory.hosts
+	{'host1.cmh': Host: host1.cmh, 'host2.cmh': Host: host2.cmh, 'spine00.cmh': Host: spine00.cmh, 'spine01.cmh': Host: spine01.cmh, 'leaf00.cmh': Host: leaf00.cmh, 'leaf01.cmh': Host: leaf01.cmh, 'host1.bma': Host: host1.bma, 'host2.bma': Host: host2.bma, 'spine00.bma': Host: spine00.bma, 'spine01.bma': Host: spine01.bma, 'leaf00.bma': Host: leaf00.bma, 'leaf01.bma': Host: leaf01.bma}
+	>>> inventory.groups
+	{'all': Group: all, 'bma': Group: bma, 'cmh': Group: cmh}
+
+As you probably noticed both ``hosts`` and ``groups`` are dictionaries so you can iterate over them if you want to.
+
+Data
+----
+
+Let's start by grabbing a host:
+
+	>>> h = inventory.hosts['host1.cmh']
+	>>> print(h)
+	host1.cmh
+
+Now, let's check some attributes::
+
+	>>> h["site"]
+	'cmh'
+	>>> h.data["role"]
+	'host'
+	>>> h["domain"]
+	'acme.com'
+	>>> h.data["domain"]
+	Traceback (most recent call last):
+	  File "<stdin>", line 1, in <module>
+	KeyError: 'domain'
+	>>> h.group["domain"]
+	'acme.com'
+
+What does this mean? You can access host data in two ways:
+
+1. As if the host was a dictionary, i.e., ``h["domain"]`` in which case the inventory will resolve the groups and use data inherited from them (in our example ``domain`` is coming from the parent group).
+2. Via the ``data`` attribute in which case there is no group resolution going on so ``h["domain"]`` fails is that piece of data is not directly assigned to the host.
+
+Most of the time you will care about the first option but if you ever need to get data only from the host you can do it without a hassle.
+
+Finally, the host behaves like a python dictionary so you can iterate over the data as such::
+
+	>>> h.keys()
+	dict_keys(['name', 'group', 'asn', 'vlans', 'site', 'role', 'brigade_nos', 'type'])
+	>>> h.values()
+	dict_values(['host1.cmh', 'cmh', 65000, {100: 'frontend', 200: 'backend'}, 'cmh', 'host', 'linux', 'host'])
+	>>> h.items()
+	dict_items([('name', 'host1.cmh'), ('group', 'cmh'), ('asn', 65000), ('vlans', {100: 'frontend', 200: 'backend'}), ('site', 'cmh'), ('role', 'host'), ('brigade_nos', 'linux'), ('type', 'host')])
+	>>> for k, v in h.items():
+	...     print(k, v)
+	...
+	name host1.cmh
+	group cmh
+	asn 65000
+	vlans {100: 'frontend', 200: 'backend'}
+	site cmh
+	role host
+	brigade_nos linux
+	type host
+	>>>
+
+.. note:: You can head to :obj:`brigade.core.inventory.Host` and :obj:`brigade.core.inventory.Group` for details on all the available attributes and functions for each ``host`` and ``group``.
+
+Filtering the inventory
+-----------------------
+
+You won't always want to operate over all hosts, sometimes you will want to operate over some of them based on some attributes. In order to do so the inventory can help you filtering based on it's attributes. For instance::
+
+	>>> inventory.hosts.keys()
+	dict_keys(['host1.cmh', 'host2.cmh', 'spine00.cmh', 'spine01.cmh', 'leaf00.cmh', 'leaf01.cmh', 'host1.bma', 'host2.bma', 'spine00.bma', 'spine01.bma', 'leaf00.bma', 'leaf01.bma'])
+	>>> inventory.filter(site="bma").hosts.keys()
+	dict_keys(['host1.bma', 'host2.bma', 'spine00.bma', 'spine01.bma', 'leaf00.bma', 'leaf01.bma'])
+	>>> inventory.filter(site="bma", role="spine").hosts.keys()
+	dict_keys(['spine00.bma', 'spine01.bma'])
+	>>> inventory.filter(site="bma").filter(role="spine").hosts.keys()
+	dict_keys(['spine00.bma', 'spine01.bma'])
+
+Note in the last line that the filter is cumulative so you can do things like this:
+
+	>>> cmh = inventory.filter(site="cmh")
+	>>> cmh.hosts.keys()
+	dict_keys(['host1.cmh', 'host2.cmh', 'spine00.cmh', 'spine01.cmh', 'leaf00.cmh', 'leaf01.cmh'])
+	>>> cmh_eos = cmh.filter(brigade_nos="eos")
+	>>> cmh_eos.hosts.keys()
+	dict_keys(['spine00.cmh', 'leaf00.cmh'])
+	>>> cmh_eos.filter(role="spine").hosts.keys()
+	dict_keys(['spine00.cmh'])
+
+This should give you enough room to build groups in any way you want.
+
+Advanced filtering
+__________________
+
+You can also do more complex filtering by using functions or lambdas::
+
+	>>> def has_long_name(host):
+	...     return len(host.name) == 11
+	...
+	>>> inventory.filter(filter_func=has_long_name).hosts.keys()
+	dict_keys(['spine00.cmh', 'spine01.cmh', 'spine00.bma', 'spine01.bma'])
+	>>> inventory.filter(filter_func=lambda h: len(h.name) == 9).hosts.keys()
+	dict_keys(['host1.cmh', 'host2.cmh', 'host1.bma', 'host2.bma'])
+
+Not the most useful example but it should be enough to illustrate how it works.
+
+
+Hosts/Groups contents
+---------------------
+
+
+* ``hosts.yaml``
+
+.. literalinclude:: ../../../examples/inventory/hosts.yaml
+
+* ``groups.yaml``
+
+.. literalinclude:: ../../../examples/inventory/groups.yaml