python/argparse.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Click [here](https://medium.com/@morihosseini/python-argparse-crafting-elegant-command-line-interfaces-21e7c40ccc91) to access the associated Medium article."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import argparse"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basic usage\n",
    "\n",
    "## Positional Arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 85,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "$ python my_script.py input.txt output.md\n",
      "\n",
      "input_file:  input.txt\n",
      "output_file: output.md\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(\n",
    "    prog=\"awesome\", description=\"My Awesome CLI Tool\"\n",
    ")\n",
    "parser.add_argument(\"input_file\", help=\"Path to the input file\")\n",
    "parser.add_argument(\"output_file\", help=\"Path to the output file\")\n",
    "\n",
    "args = parser.parse_args([\"input.txt\", \"output.md\"])\n",
    "print(\"$ python my_script.py input.txt output.md\\n\")\n",
    "print(\"input_file: \", args.input_file)\n",
    "print(\"output_file:\", args.output_file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional Arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 116,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--verbose] [--format {json,csv}]\n",
      "\n",
      "My Awesome CLI Tool.\n",
      "\n",
      "options:\n",
      "  -h, --help           show this help message and exit\n",
      "  --verbose            Enable verbose mode\n",
      "  --format {json,csv}  Output format\n",
      "\n",
      "Example: $ python awesome.py --verbose --format=csv\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(\n",
    "    prog=\"awesome\",\n",
    "    description=\"My Awesome CLI Tool.\",\n",
    "    epilog=\"Example: $ python awesome.py --verbose --format=csv\",\n",
    ")\n",
    "parser.add_argument(\n",
    "    \"--verbose\", action=\"store_true\", help=\"Enable verbose mode\"\n",
    ")\n",
    "parser.add_argument(\n",
    "    \"--format\", choices=[\"json\", \"csv\"], default=\"json\", help=\"Output format\"\n",
    ")\n",
    "\n",
    "parser.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Default Values"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 102,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0.5\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\n",
    "    \"--threshold\", type=float, default=0.5, help=\"Threshold value\"\n",
    ")\n",
    "\n",
    "args = parser.parse_args([])\n",
    "print(args.threshold)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Advanced usage\n",
    "\n",
    "## Subparsers"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 120,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      ":::: Main parser help ::::::::::::::::::\n",
      "usage: awesome [-h] {train,predict} ...\n",
      "\n",
      "My Awesome CLI Tool\n",
      "\n",
      "options:\n",
      "  -h, --help       show this help message and exit\n",
      "\n",
      "Subcommands:\n",
      "  {train,predict}\n",
      "    train          Train a machine learning model\n",
      "    predict        Make predictions using a trained model\n",
      "\n",
      "\n",
      ":::: Train parser help ::::::::::::::::::\n",
      "usage: awesome train [-h] [--data DATA] [--model MODEL]\n",
      "\n",
      "options:\n",
      "  -h, --help     show this help message and exit\n",
      "  --data DATA    Path to training data\n",
      "  --model MODEL  Path to save the trained model\n",
      "\n",
      "Example: $ python awesome.py train --data=data.csv --model=model.pkl\n",
      "\n",
      "\n",
      ":::: Predict parser help ::::::::::::::::::\n",
      "usage: awesome predict [-h] [--input INPUT] [--output OUTPUT]\n",
      "\n",
      "options:\n",
      "  -h, --help       show this help message and exit\n",
      "  --input INPUT    Path to input data\n",
      "  --output OUTPUT  Path to save predictions\n",
      "\n",
      "Example: $ python awesome.py predict --input=data.csv --output=pred.csv\n"
     ]
    }
   ],
   "source": [
    "# Create the main parser\n",
    "parser = argparse.ArgumentParser(\n",
    "    prog=\"awesome\", description=\"My Awesome CLI Tool\"\n",
    ")\n",
    "\n",
    "# Create subparsers\n",
    "subparsers = parser.add_subparsers(title=\"Subcommands\", dest=\"subcommand\")\n",
    "\n",
    "# Create a subparser for the \"train\" command\n",
    "train_parser = subparsers.add_parser(\n",
    "    \"train\",\n",
    "    help=\"Train a machine learning model\",\n",
    "    epilog=\"Example: \"\n",
    "    \"$ python awesome.py train --data=data.csv --model=model.pkl\"\n",
    ")\n",
    "train_parser.add_argument(\"--data\", help=\"Path to training data\")\n",
    "train_parser.add_argument(\"--model\", help=\"Path to save the trained model\")\n",
    "\n",
    "# Create a subparser for the \"predict\" command\n",
    "predict_parser = subparsers.add_parser(\n",
    "    \"predict\",\n",
    "    help=\"Make predictions using a trained model\",\n",
    "    epilog=\"Example: \"\n",
    "    \"$ python awesome.py predict --input=data.csv --output=pred.csv\"\n",
    ")\n",
    "predict_parser.add_argument(\"--input\", help=\"Path to input data\")\n",
    "predict_parser.add_argument(\"--output\", help=\"Path to save predictions\")\n",
    "\n",
    "print(\":::: Main parser help ::::::::::::::::::\")\n",
    "parser.print_help()\n",
    "\n",
    "print(\"\\n\\n:::: Train parser help ::::::::::::::::::\")\n",
    "train_parser.print_help()\n",
    "\n",
    "print(\"\\n\\n:::: Predict parser help ::::::::::::::::::\")\n",
    "predict_parser.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom Argument Types"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 150,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "$ python awesome.py --epochs=-2\n",
      "\n",
      "Error: -2 is not a positive integer\n"
     ]
    }
   ],
   "source": [
    "def valid_positive_int(value):\n",
    "    try:\n",
    "        int_value = int(value)\n",
    "        if int_value <= 0:\n",
    "            print(f\"Error: {value} is not a positive integer\")\n",
    "        return int_value\n",
    "    except ValueError:\n",
    "        print(f\"Error: {value} is not a valid integer\")\n",
    "\n",
    "\n",
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\"--epochs\", type=valid_positive_int, default=10)\n",
    "\n",
    "print(\"$ python awesome.py --epochs=-2\\n\")\n",
    "args = parser.parse_args([\"--epochs=-2\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Argument Groups"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 170,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--hidden_units HIDDEN_UNITS]\n",
      "               [--learning_rate LEARNING_RATE] [--batch_size BATCH_SIZE]\n",
      "               [--epochs EPOCHS]\n",
      "\n",
      "options:\n",
      "  -h, --help            show this help message and exit\n",
      "\n",
      "Model Configuration:\n",
      "  --hidden_units HIDDEN_UNITS\n",
      "                        Number of hidden units\n",
      "  --learning_rate LEARNING_RATE\n",
      "                        Learning rate\n",
      "\n",
      "Training Configuration:\n",
      "  --batch_size BATCH_SIZE\n",
      "                        Batch size\n",
      "  --epochs EPOCHS       Number of epochs\n",
      "\n",
      "Example: $ python awesome.py --hidden_units=64 --epochs=20\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(\n",
    "    prog=\"awesome\",\n",
    "    epilog=\"Example: $ python awesome.py --hidden_units=64 --epochs=20\",\n",
    ")\n",
    "\n",
    "group = parser.add_argument_group(\"Model Configuration\")\n",
    "group.add_argument(\n",
    "    \"--hidden_units\", type=int, default=128, help=\"Number of hidden units\"\n",
    ")\n",
    "group.add_argument(\n",
    "    \"--learning_rate\", type=float, default=0.001, help=\"Learning rate\"\n",
    ")\n",
    "\n",
    "group = parser.add_argument_group(\"Training Configuration\")\n",
    "group.add_argument(\"--batch_size\", type=int, default=32, help=\"Batch size\")\n",
    "group.add_argument(\"--epochs\", type=int, default=10, help=\"Number of epochs\")\n",
    "\n",
    "parser.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Mutually Exclusive Arguments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 178,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--train | --predict]\n",
      "awesome: error: argument --predict: not allowed with argument --train\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "exclusive_group = parser.add_mutually_exclusive_group()\n",
    "exclusive_group.add_argument(\n",
    "    \"--train\", action=\"store_true\", help=\"Train the model\"\n",
    ")\n",
    "exclusive_group.add_argument(\n",
    "    \"--predict\", action=\"store_true\", help=\"Make predictions\"\n",
    ")\n",
    "\n",
    "try:\n",
    "    # $ python awesome.py --train --predict\n",
    "    parser.parse_args([\"--train\", \"--predict\"])\n",
    "except SystemExit:\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Best Practices\n",
    "\n",
    "## Descriptive Help Messages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 179,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--input INPUT] [--output OUTPUT]\n",
      "\n",
      "options:\n",
      "  -h, --help       show this help message and exit\n",
      "  --input INPUT    Path to input data (required)\n",
      "  --output OUTPUT  Path to save results (optional)\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\"--input\", help=\"Path to input data (required)\")\n",
    "parser.add_argument(\"--output\", help=\"Path to save results (optional)\")\n",
    "\n",
    "parser.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Validating Input with `choices`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 184,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--format {json,csv}]\n",
      "awesome: error: argument --format: invalid choice: 'tsv' (choose from 'json', 'csv')\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\n",
    "    \"--format\", choices=[\"json\", \"csv\"], default=\"json\", help=\"Output format\"\n",
    ")\n",
    "\n",
    "try:\n",
    "    # $ python awesome.py --format=tsv\n",
    "    parser.parse_args([\"--format=tsv\"])\n",
    "except SystemExit:\n",
    "    pass"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using `metavar` for User-Friendly Argument Names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 185,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--input data_file]\n",
      "\n",
      "options:\n",
      "  -h, --help         show this help message and exit\n",
      "  --input data_file  Path to input data\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\"--input\", metavar=\"data_file\", help=\"Path to input data\")\n",
    "\n",
    "parser.print_help()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## File Input/Output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 202,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h] [--input INPUT] [--output OUTPUT]\n",
      "\n",
      "options:\n",
      "  -h, --help       show this help message and exit\n",
      "  --input INPUT    Input file\n",
      "  --output OUTPUT  Output file\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(prog=\"awesome\")\n",
    "parser.add_argument(\"--input\", type=argparse.FileType(\"r\"), help=\"Input file\")\n",
    "parser.add_argument(\n",
    "    \"--output\", type=argparse.FileType(\"w\"), help=\"Output file\"\n",
    ")\n",
    "\n",
    "parser.print_help()\n",
    "\n",
    "# Uncomment the following lines to write to output.txt\n",
    "# args = parser.parse_args([\"--output=output.txt\"])\n",
    "# args.output.write(\"Hello, World!\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documenting Your CLI Tool"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 204,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "usage: awesome [-h]\n",
      "\n",
      "My Awesome CLI Tool: Perform magic with data!\n",
      "\n",
      "options:\n",
      "  -h, --help  show this help message and exit\n"
     ]
    }
   ],
   "source": [
    "parser = argparse.ArgumentParser(\n",
    "    prog=\"awesome\", description=\"My Awesome CLI Tool: Perform magic with data!\"\n",
    ")\n",
    "\n",
    "parser.print_help()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}