tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Ecological Tutorial\n",
    "\n",
    "## Getting Started\n",
    "\n",
    "Before we start to set some environment variables, note than in a real application this would be set outside of your application."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ[\"INTEGER_LIST\"] = \"[1, 2, 3, 4, 5]\"\n",
    "os.environ[\"DICTIONARY\"] = \"{'key': 'value'}\"\n",
    "os.environ[\"INTEGER\"] = \"42\"\n",
    "os.environ[\"BOOLEAN\"] = \"False\"\n",
    "os.environ[\"OVERRIDE_DEFAULT\"] = \"This is NOT the default value\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's create a configuration class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import ecological\n",
    "\n",
    "class Configuration(ecological.Config):\n",
    "    integer_list: list\n",
    "    integer: int\n",
    "    dictionary: dict\n",
    "    boolean: bool\n",
    "    with_default: str = \"This is the default value\"\n",
    "    override_default: str = \"This is the default value\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Easy right?\n",
    "Now that we created the configuration class. Let's look at what's inside:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1, 2, 3, 4, 5]\n",
      "<class 'list'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.integer_list))\n",
    "print(type(Configuration.integer_list))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n",
      "<class 'int'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.integer))\n",
    "print(type(Configuration.integer))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'key': 'value'}\n",
      "<class 'dict'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.dictionary))\n",
    "print(type(Configuration.dictionary))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n",
      "<class 'bool'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.boolean))\n",
    "print(type(Configuration.boolean))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'This is the default value'\n",
      "<class 'str'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.with_default))\n",
    "print(type(Configuration.with_default))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'This is NOT the default value'\n",
      "<class 'str'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(Configuration.override_default))\n",
    "print(type(Configuration.override_default))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see all the values where cast from `str` to the expected types, and if a default value is set it will be used if the corresponding environment variable doesn't exist."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Typing Support\n",
    "\n",
    "**Ecological** also supports some of the types defined in [PEP 484](https://www.python.org/dev/peps/pep-0484/), for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from typing import List, Dict\n",
    "\n",
    "class ConfigurationTyping(ecological.Config):\n",
    "    integer_list: List\n",
    "    dictionary: Dict"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As expected the variables were converted to the real types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[1, 2, 3, 4, 5]\n",
      "<class 'list'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationTyping.integer_list))\n",
    "print(type(ConfigurationTyping.integer_list))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'key': 'value'}\n",
      "<class 'dict'>\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationTyping.dictionary))\n",
    "print(type(ConfigurationTyping.dictionary))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Prefixed Configuration\n",
    "\n",
    "You can also decide to prefix your application configuration, for example, to avoid collisions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "os.environ[\"HOME\"] = \"/home/myuser/\"\n",
    "os.environ[\"VALUE\"] = \"Not Prefixed\"\n",
    "os.environ[\"CONFIG_HOME\"] = \"/app/home\"\n",
    "os.environ[\"CONFIG_VALUE\"] = \"Prefixed\"\n",
    "\n",
    "class ConfigurationPrefix(ecological.Config, prefix=\"config\"):\n",
    "    home: str\n",
    "    value: str"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case the `home` and `value` properties will be fetched from the `CONFIG_HOME` and `CONFIG_VALUE` environment properties:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'/app/home'\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationPrefix.home))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'Prefixed'\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationPrefix.value))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Fine-grained control\n",
    "\n",
    "You can control how the configuration properties are set by providing a ecological.Variable instance as the default value.\n",
    "\n",
    "`ecological.Variable` receives the following parameters:\n",
    "\n",
    "`variable_name` (optional) - exact name of the environment variable that will be used.\n",
    "`default` (optional) - default value for the property if it isn't set.\n",
    "`transform` (optional) - function that converts the string in the environment to the value and type you expect in your application. The default `transform` function will try to cast the string to the annotation type of the property.\n",
    "\n",
    "### Transformation function\n",
    "\n",
    "The transformation function receive two parameters, a string representation with the raw value, and a wanted_type with the value of the annotation (usually, but not necessarily a type)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "os.environ[\"Integer\"] = \"42\"\n",
    "\n",
    "def times_2(value, wanted_type):\n",
    "    assert wanted_type is int\n",
    "    return int(value) * 2\n",
    "\n",
    "class ConfigurationVariable(ecological.Config, prefix=\"this_is_going_to_be_ignored\"):\n",
    "    integer = ecological.Variable(\"Integer\", transform=lambda v, wt: int(v))\n",
    "    integer_x2: int = ecological.Variable(\"Integer\", transform=times_2)\n",
    "    integer_as_str: str = ecological.Variable(\"Integer\", transform=lambda v, wt: v)\n",
    "    boolean: bool = ecological.Variable(\"404\", default=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`integer`, `integer_x2` and `integer_as_str` will use the same enviroment variable but return different values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationVariable.integer))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "84\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationVariable.integer_x2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "'42'\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationVariable.integer_as_str))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the environment variable `404` is not set, `boolean` will have the default value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "False\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationVariable.boolean))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Nested Configuration\n",
    "\n",
    "`ecological.Config` also supports nested configurations, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "os.environ[\"INTEGER\"] = \"42\"\n",
    "os.environ[\"NESTED_BOOLEAN\"] = \"True\"\n",
    "\n",
    "class ConfigurationNested(ecological.Config):\n",
    "    integer: int\n",
    "\n",
    "    class Nested(ecological.Config, prefix='nested'):\n",
    "        boolean: bool"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This way you can group related configuration properties hierarchically:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "42\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationNested.integer))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "print(repr(ConfigurationNested.Nested.boolean))"
   ]
  }
 ],
 "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.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}