docs/howto/advanced_filtering.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Advanced filtering\n",
    "\n",
    "In this tutorial we are going to see how to use the ``F`` object to do advanced filtering of hosts. Let's start by initiating nornir and looking at the inventory:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nornir import InitNornir\n",
    "from nornir.core.filter import F\n",
    "\n",
    "nr = InitNornir(config_file=\"advanced_filtering/config.yaml\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\r\n",
      "cat:\r\n",
      "    groups:\r\n",
      "        - terrestrial\r\n",
      "        - mammal\r\n",
      "    data:\r\n",
      "        domestic: true\r\n",
      "        diet: omnivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 17\r\n",
      "            famous_members:\r\n",
      "                - garfield\r\n",
      "                - felix\r\n",
      "                - grumpy\r\n",
      "\r\n",
      "bat:\r\n",
      "    groups:\r\n",
      "        - terrestrial\r\n",
      "        - mammal\r\n",
      "    data:\r\n",
      "        domestic: false\r\n",
      "        fly: true\r\n",
      "        diet: carnivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 15\r\n",
      "            famous_members:\r\n",
      "                - batman\r\n",
      "                - count chocula\r\n",
      "                - nosferatu\r\n",
      "\r\n",
      "eagle:\r\n",
      "    groups:\r\n",
      "        - terrestrial\r\n",
      "        - bird\r\n",
      "    data:\r\n",
      "        domestic: false\r\n",
      "        diet: carnivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 50\r\n",
      "            famous_members:\r\n",
      "                - thorondor\r\n",
      "                - sam\r\n",
      "\r\n",
      "canary:\r\n",
      "    groups:\r\n",
      "        - terrestrial\r\n",
      "        - bird\r\n",
      "    data:\r\n",
      "        domestic: true\r\n",
      "        diet: herbivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 15\r\n",
      "            famous_members:\r\n",
      "                - tweetie\r\n",
      "\r\n",
      "caterpillaer:\r\n",
      "    groups:\r\n",
      "        - terrestrial\r\n",
      "        - invertebrate\r\n",
      "    data:\r\n",
      "        domestic: false\r\n",
      "        diet: herbivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 1\r\n",
      "            famous_members:\r\n",
      "                - Hookah-Smoking\r\n",
      "\r\n",
      "octopus:\r\n",
      "    groups:\r\n",
      "        - marine\r\n",
      "        - invertebrate\r\n",
      "    data:\r\n",
      "        domestic: false\r\n",
      "        diet: carnivore\r\n",
      "        additional_data:\r\n",
      "            lifespan: 1\r\n",
      "            famous_members:\r\n",
      "                - sharktopus\r\n"
     ]
    }
   ],
   "source": [
    "%cat advanced_filtering/inventory/hosts.yaml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "---\r\n",
      "mammal:\r\n",
      "    data:\r\n",
      "        reproduction: birth\r\n",
      "        fly: false\r\n",
      "\r\n",
      "bird:\r\n",
      "    data:\r\n",
      "        reproduction: eggs\r\n",
      "        fly: true\r\n",
      "\r\n",
      "invertebrate:\r\n",
      "    data:\r\n",
      "        reproduction: mitosis\r\n",
      "        fly: false\r\n",
      "\r\n",
      "terrestrial: {}\r\n",
      "marine: {}\r\n"
     ]
    }
   ],
   "source": [
    "%cat advanced_filtering/inventory/groups.yaml"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see we have built ourselves a collection of animals with different properties. The ``F`` object let's you access the magic methods of each types by just prepeding two underscores and the the name of the magic method. For instance, if you want to check if a list contains a particular element you can just prepend ``__contains``. Let's use this feature to retrieve all the animals that belong to the group ``bird``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['eagle', 'canary'])\n"
     ]
    }
   ],
   "source": [
    "birds = nr.filter(F(groups__contains=\"bird\"))\n",
    "print(birds.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also invert the ``F`` object by prepending ``~``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['cat', 'bat', 'caterpillaer', 'octopus'])\n"
     ]
    }
   ],
   "source": [
    "not_birds = nr.filter(~F(groups__contains=\"bird\"))\n",
    "print(not_birds.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also combine ``F`` objects and perform AND and OR operations with the symbols ``&`` and ``|`` (pipe) respectively:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['cat', 'eagle', 'canary'])\n"
     ]
    }
   ],
   "source": [
    "domestic_or_bird = nr.filter(F(groups__contains=\"bird\") | F(domestic=True))\n",
    "print(domestic_or_bird.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['cat'])\n"
     ]
    }
   ],
   "source": [
    "domestic_mammals = nr.filter(F(groups__contains=\"mammal\") & F(domestic=True))\n",
    "print(domestic_mammals.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As expected, you can combine all of the symbols:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['canary'])\n"
     ]
    }
   ],
   "source": [
    "flying_not_carnivore = nr.filter(F(fly=True) & ~F(diet=\"carnivore\"))\n",
    "print(flying_not_carnivore.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also access nested data the same way you access magic methods, by appending two underscores and the data you want to access. You can keep building on this as much as needed and even access the magic methods of the nested data. For instance, let's get the animals that have a lifespan greater or equal than 15:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['cat', 'bat', 'eagle', 'canary'])\n"
     ]
    }
   ],
   "source": [
    "long_lived = nr.filter(F(additional_data__lifespan__ge=15))\n",
    "print(long_lived.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are two extra facilities to help you working with lists; ``any`` and ``all``. Those facilities let's you send a list of elements and get the objects that has either any of the members or all of them. For instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['octopus'])\n"
     ]
    }
   ],
   "source": [
    "marine_and_invertebrates = nr.filter(F(groups__all=[\"marine\", \"invertebrate\"]))\n",
    "print(marine_and_invertebrates.inventory.hosts.keys())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['eagle', 'canary', 'caterpillaer', 'octopus'])\n"
     ]
    }
   ],
   "source": [
    "bird_or_invertebrates = nr.filter(F(groups__any=[\"bird\", \"invertebrate\"]))\n",
    "print(bird_or_invertebrates.inventory.hosts.keys())"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}