Click CLI Examples

gistfile1.txt

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click CLI Exploration\n",
    "===========\n",
    "\n",
    "Demonstrating option/argument callbacks, `click.ClickException` and why `sys.exit()` calls are unnecessary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import sys\n",
    "\n",
    "import click"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import click\n",
    "\n",
    "\n",
    "def _cb_to_int(ctx, param, value):\n",
    "    \n",
    "    \"\"\"\n",
    "    Click callback to cast a value to int.  Similar to `click.INT`.\n",
    "    \n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    ctx : click.Context\n",
    "        Ignored.\n",
    "    param : click.Parameter\n",
    "        Ignored.\n",
    "    value : str\n",
    "        Input string from the commandline.\n",
    "    \"\"\"\n",
    "    \n",
    "    try:\n",
    "        value = int(value)\n",
    "    except Exception:\n",
    "        raise click.BadParameter(\"couldn't convert to str: `{val}'\".format(val=value))\n",
    "    \n",
    "    return value\n",
    "\n",
    "\n",
    "@click.group()\n",
    "def cli():\n",
    "    pass\n",
    "\n",
    "@cli.command()\n",
    "@click.argument('arg')\n",
    "def exit_zero(arg):\n",
    "\n",
    "    \"\"\"\n",
    "    Click raises `SystemExit(0)` on success.\n",
    "    \"\"\"\n",
    "    \n",
    "    click.echo(\"exit_zero - input arg is: %s\" % arg)\n",
    "\n",
    "\n",
    "@cli.command()\n",
    "@click.argument('arg')\n",
    "def click_exception(arg):\n",
    "    \n",
    "    \"\"\"\n",
    "    Click raises `SystemExit(2)` for a `ClickException()`.\n",
    "    \"\"\"\n",
    "    \n",
    "    raise click.ClickException('Message froa click exception')\n",
    "\n",
    "    \n",
    "@cli.command()\n",
    "@click.argument('arg')\n",
    "def bad_parameter(arg):\n",
    "    \n",
    "    \"\"\"\n",
    "    Cick raises `SystemExit(2) for a `BadParameter()`.\n",
    "    \"\"\"\n",
    "    \n",
    "    raise click.BadParameter('Message from bad parameter')\n",
    "\n",
    "    \n",
    "@cli.command()\n",
    "@click.argument('arg', callback=_cb_to_int)\n",
    "def cb_success(arg):\n",
    "    \n",
    "    \"\"\"\n",
    "    Use a click callback to convert `arg` to an int\n",
    "    \"\"\"\n",
    "    \n",
    "    click.echo(type(arg))\n",
    "    click.echo(arg)\n",
    "\n",
    "\n",
    "@cli.command()\n",
    "@click.argument('arg')\n",
    "def exception(arg):\n",
    "    \n",
    "    \"\"\"\n",
    "    Raise a builtin exception.\n",
    "    \"\"\"\n",
    "    \n",
    "    raise ValueError('builtin exception message')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# There are already arguments in sys.argv from starting\n",
    "# IPython so we have to manually modify in order to get\n",
    "# the usage from cli()\n",
    "argv_backup = sys.argv\n",
    "sys.argv = ['1']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Usage: 1 [OPTIONS] COMMAND [ARGS]...\n",
      "\n",
      "Options:\n",
      "  --help  Show this message and exit.\n",
      "\n",
      "Commands:\n",
      "  bad_parameter    Cick raises `SystemExit(2) for a...\n",
      "  cb_success       Use a click callback to convert `arg` to an...\n",
      "  click_exception  Click raises `SystemExit(2)` for a...\n",
      "  exception        Raise a builtin exception.\n",
      "  exit_zero        Click raises `SystemExit(0)` on success.\n"
     ]
    },
    {
     "ename": "SystemExit",
     "evalue": "0",
     "output_type": "error",
     "traceback": [
      "An exception has occurred, use %tb to see the full traceback.\n",
      "\u001b[0;31mSystemExit\u001b[0m\u001b[0;31m:\u001b[0m 0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "To exit: use 'exit', 'quit', or Ctrl-D.\n"
     ]
    }
   ],
   "source": [
    "# Print the usage\n",
    "cli()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "exit_zero - input arg is: 1\n"
     ]
    },
    {
     "ename": "SystemExit",
     "evalue": "0",
     "output_type": "error",
     "traceback": [
      "An exception has occurred, use %tb to see the full traceback.\n",
      "\u001b[0;31mSystemExit\u001b[0m\u001b[0;31m:\u001b[0m 0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "To exit: use 'exit', 'quit', or Ctrl-D.\n"
     ]
    }
   ],
   "source": [
    "# Successful command\n",
    "exit_zero(sys.argv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Error: Message froa click exception\n"
     ]
    },
    {
     "ename": "SystemExit",
     "evalue": "1",
     "output_type": "error",
     "traceback": [
      "An exception has occurred, use %tb to see the full traceback.\n",
      "\u001b[0;31mSystemExit\u001b[0m\u001b[0;31m:\u001b[0m 1\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "To exit: use 'exit', 'quit', or Ctrl-D.\n"
     ]
    }
   ],
   "source": [
    "# Raise click.ClickException()\n",
    "click_exception(sys.argv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Usage: 1 [OPTIONS] ARG\n",
      "\n",
      "Error: Invalid value: Message from bad parameter\n"
     ]
    },
    {
     "ename": "SystemExit",
     "evalue": "2",
     "output_type": "error",
     "traceback": [
      "An exception has occurred, use %tb to see the full traceback.\n",
      "\u001b[0;31mSystemExit\u001b[0m\u001b[0;31m:\u001b[0m 2\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "To exit: use 'exit', 'quit', or Ctrl-D.\n"
     ]
    }
   ],
   "source": [
    "# Raise click.BadParameter\n",
    "bad_parameter(sys.argv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "<type 'int'>\n",
      "1\n"
     ]
    },
    {
     "ename": "SystemExit",
     "evalue": "0",
     "output_type": "error",
     "traceback": [
      "An exception has occurred, use %tb to see the full traceback.\n",
      "\u001b[0;31mSystemExit\u001b[0m\u001b[0;31m:\u001b[0m 0\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "To exit: use 'exit', 'quit', or Ctrl-D.\n"
     ]
    }
   ],
   "source": [
    "# Use a callback to convert the arg to an integer\n",
    "cb_success(sys.argv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "ename": "ValueError",
     "evalue": "builtin exception message",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m                                Traceback (most recent call last)",
      "\u001b[0;32m<ipython-input-10-ce6bcf2dc768>\u001b[0m in \u001b[0;36m<module>\u001b[0;34m()\u001b[0m\n\u001b[1;32m      1\u001b[0m \u001b[0;31m# Raise a builtin exception\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mexception\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0msys\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0margv\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;32m/usr/local/lib/python2.7/site-packages/click/core.pyc\u001b[0m in \u001b[0;36m__call__\u001b[0;34m(self, *args, **kwargs)\u001b[0m\n\u001b[1;32m    662\u001b[0m     \u001b[0;32mdef\u001b[0m \u001b[0m__call__\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m*\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    663\u001b[0m         \u001b[0;34m\"\"\"Alias for :meth:`main`.\"\"\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 664\u001b[0;31m         \u001b[0;32mreturn\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmain\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m*\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    665\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    666\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m/usr/local/lib/python2.7/site-packages/click/core.pyc\u001b[0m in \u001b[0;36mmain\u001b[0;34m(self, args, prog_name, complete_var, standalone_mode, **extra)\u001b[0m\n\u001b[1;32m    642\u001b[0m             \u001b[0;32mtry\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    643\u001b[0m                 \u001b[0;32mwith\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mmake_context\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mprog_name\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mextra\u001b[0m\u001b[0;34m)\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0mctx\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 644\u001b[0;31m                     \u001b[0mrv\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0minvoke\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mctx\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    645\u001b[0m                     \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mstandalone_mode\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    646\u001b[0m                         \u001b[0;32mreturn\u001b[0m \u001b[0mrv\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m/usr/local/lib/python2.7/site-packages/click/core.pyc\u001b[0m in \u001b[0;36minvoke\u001b[0;34m(self, ctx)\u001b[0m\n\u001b[1;32m    835\u001b[0m         \"\"\"\n\u001b[1;32m    836\u001b[0m         \u001b[0;32mif\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mcallback\u001b[0m \u001b[0;32mis\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0mNone\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 837\u001b[0;31m             \u001b[0;32mreturn\u001b[0m \u001b[0mctx\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0minvoke\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mcallback\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mctx\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mparams\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    838\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    839\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m/usr/local/lib/python2.7/site-packages/click/core.pyc\u001b[0m in \u001b[0;36minvoke\u001b[0;34m(*args, **kwargs)\u001b[0m\n\u001b[1;32m    462\u001b[0m             \u001b[0;32mtry\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    463\u001b[0m                 \u001b[0;32mwith\u001b[0m \u001b[0mctx\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 464\u001b[0;31m                     \u001b[0;32mreturn\u001b[0m \u001b[0mcallback\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m*\u001b[0m\u001b[0margs\u001b[0m\u001b[0;34m,\u001b[0m \u001b[0;34m**\u001b[0m\u001b[0mkwargs\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m    465\u001b[0m             \u001b[0;32mexcept\u001b[0m \u001b[0mTypeError\u001b[0m \u001b[0;32mas\u001b[0m \u001b[0me\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m    466\u001b[0m                 \u001b[0;32mif\u001b[0m \u001b[0;32mnot\u001b[0m \u001b[0minjected_arguments\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n",
      "\u001b[0;32m<ipython-input-3-71afb477b103>\u001b[0m in \u001b[0;36mexception\u001b[0;34m(arg)\u001b[0m\n\u001b[1;32m     83\u001b[0m     \"\"\"\n\u001b[1;32m     84\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m---> 85\u001b[0;31m     \u001b[0;32mraise\u001b[0m \u001b[0mValueError\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0;34m'builtin exception message'\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m",
      "\u001b[0;31mValueError\u001b[0m: builtin exception message"
     ]
    }
   ],
   "source": [
    "# Raise a builtin exception\n",
    "exception(sys.argv)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}