yaml.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# YAML for Python\n",
    "\n",
    "**YAML** is a human-readable data serialization language.\n",
    "\n",
    "The official documentation says:\n",
    "\n",
    ">YAML™ (rhymes with “camel”) is a human-friendly, cross language, Unicode based data serialization language designed around the common native data structures of agile programming languages.\n",
    "\n",
    "This article discusses the scenarios where we may require YAML and how to use it with Python!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. JSON vs YAML\n",
    "\n",
    "JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. \n",
    "\n",
    "A basic JSON structure might look like:\n",
    "\n",
    "```\n",
    "{'Name': 'Nikhil',\n",
    " 'age': 20,\n",
    " 'handles': {'facebook': 'nikhilkingh97',\n",
    "  'github': 'nikhilkumarsingh',\n",
    "  'youtube': 'IndianPythonista'},\n",
    " 'languages': {'markup': ['HTML', 'XML', 'AIML'],\n",
    "  'programming': ['C', 'C++', 'Python', 'javascript']}\n",
    "  }\n",
    "```\n",
    "\n",
    "Since the basic Python data structures(like lists and dictionaries) follow the JSON format inherently, we may represent above JSON structure as a Python data structure:\n",
    "\n",
    "```python\n",
    "data = { 'Name': 'Nikhil',\n",
    "         'age': 20,\n",
    "         'handles': {'facebook': 'nikhilkingh97',\n",
    "          'github': 'nikhilkumarsingh',\n",
    "          'youtube': 'IndianPythonista'},\n",
    "         'languages': {'markup': ['HTML', 'XML', 'AIML'],\n",
    "          'programming': ['C', 'C++', 'Python', 'javascript']}\n",
    "          }\n",
    "```\n",
    "\n",
    "Now, you may notice that as we keep on increasing the complexity of above strucure, readability decreases!\n",
    "\n",
    "It is because the design goal of JSON is to make it simple and universal. Hence, it is easier to generate and parse but at the cost of human readability.\n",
    "\n",
    "This is where **YAML** comes into picture!\n",
    "\n",
    "YAML's design goal is human readability and support for serializability of native data strucutres in agile programming languages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. JSON to YAML"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Consider the data structure shown as an example in last section. If we need to present it to a user in a more readable way, we have two ways of doing that:\n",
    "\n",
    "- Use print function with some pretty formatting\n",
    "\n",
    "- Convert JSON to YAML format.\n",
    "\n",
    "The latter solution is a one-liner hence desirable!\n",
    "\n",
    "### Installation\n",
    "\n",
    "In order to use YAML in python, you need to install a third-party python library called **PyYAML**.\n",
    "\n",
    "One can install it using a simple pip command:\n",
    "```\n",
    "pip install pyyaml\n",
    "```\n",
    "\n",
    "### Usage\n",
    "\n",
    "Let us consider a simple example to convert JSON structure to YAML format now:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = { 'Name': 'Nikhil',\n",
    "         'age': 20,\n",
    "         'handles': {'facebook': 'nikhilkingh97',\n",
    "          'github': 'nikhilkumarsingh',\n",
    "          'youtube': 'IndianPythonista'},\n",
    "         'languages': {'markup': ['HTML', 'XML', 'AIML'],\n",
    "          'programming': ['C', 'C++', 'Python', 'javascript']}\n",
    "          }"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets go through above code now:\n",
    "\n",
    "- Firstly, we imported the PyYAML library using:\n",
    "   ```\n",
    "   import yaml\n",
    "   ```\n",
    "- Then, in order to convert a python data structure to a YAML string, we use **dump** function:\n",
    "    ```\n",
    "    yaml.dump(data, default_flow_style=False)\n",
    "    ```\n",
    "   The **default_flow_style** does not convert nested blocks to YAML format. So, for a better representation, we set \n",
    "   it to **False**."
   ]
  }
 ],
 "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}