extract_services_documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# README\n",
    "\n",
    "If no repo is present, the script will download it (it usually takes a while)\n",
    "\n",
    "* Supply a valid repo filepath for `FILEPATH` variable, ex: `\"apps/catalog/models.py\"`\n",
    "\n",
    "For every function present in FILEPATH, you get an object like this:\n",
    "~~~\n",
    "{\n",
    "    'name': 'get_external_order_mapping_list',\n",
    "    'has_docstring': False,\n",
    "    'docstring': None,\n",
    "    'arguments': [{'name': 'order_uuid', 'type': 'UUID, str'}],\n",
    "    'return_type': 'missing',\n",
    "    'score': 34.0\n",
    "}\n",
    "~~~"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "file score: 49.421\n",
      "total functions: 568\n",
      "great scores (> 90.0): 101 (17.78%)\n",
      "good scores (> 67.0): 101 (17.78%)\n",
      "low scores (<= 67.0): 467 (82.22%)\n",
      "super low scores (<= 33.0): 171 (30.11%)\n",
      "without docstring : 439 (77.29%)\n"
     ]
    }
   ],
   "source": [
    "import ast\n",
    "import os\n",
    "from operator import itemgetter\n",
    "from apps.patterns.analyzer import BaseFileAnalyzer\n",
    "from apps.structure import get_full_path\n",
    "\n",
    "class ServiceDocAnalyzer(BaseFileAnalyzer):\n",
    "    def __init__(self, *args, **kwargs):\n",
    "        self.doc_elements = []\n",
    "        super(ServiceDocAnalyzer, self).__init__(*args, **kwargs)\n",
    "        \n",
    "    def build_doc(self, payload):\n",
    "        self.doc_elements.append(payload)\n",
    "    \n",
    "    def get_analysis(self):\n",
    "        elements = sorted(self.doc_elements, key=itemgetter('name'))\n",
    "        avg_score = sum(list(map(lambda x: x[\"score\"], elements))) / len(elements)\n",
    "        return {\n",
    "            \"services\": elements,\n",
    "            \"global\": {\n",
    "                \"score\": avg_score\n",
    "            }\n",
    "        }\n",
    "    \n",
    "    def get_function_score(self, payload):\n",
    "        score = 100\n",
    "        if not payload.get('has_docstring'):\n",
    "            score -= 33\n",
    "            \n",
    "        arguments = payload.get('arguments', [])\n",
    "        if len(arguments) > 0:\n",
    "            missing_args = 0\n",
    "            for arg in arguments:\n",
    "                if arg.get(\"type\", \"missing\") == \"missing\":\n",
    "                    missing_args += 1\n",
    "            score_to_remove = 33*(missing_args/len(arguments)) \n",
    "            score -= score_to_remove\n",
    "        \n",
    "        if payload.get(\"return_type\") == \"missing\":\n",
    "            score -= 33\n",
    "        return score\n",
    "    \n",
    "    def get_processed_type(self, annotation):\n",
    "        if annotation is None:\n",
    "            return \"missing\"\n",
    "        if annotation.__class__ == ast.Name:\n",
    "            return annotation.id\n",
    "        if annotation.__class__ == ast.Attribute:\n",
    "            return annotation.attr\n",
    "        if annotation.__class__ == ast.Subscript:\n",
    "            inner_type = self.get_processed_type(annotation.slice)\n",
    "            outer_type = self.get_processed_type(annotation.value)\n",
    "            return f\"{outer_type}[{inner_type}]\"\n",
    "        if annotation.__class__ == ast.Str:\n",
    "            return annotation.s\n",
    "        if annotation.__class__ == ast.Num:\n",
    "            raise Exception(\"oops\", annotation, dir(annotation))\n",
    "        if annotation.__class__ == ast.Constant:\n",
    "            raise Exception(\"oops\", annotation, dir(annotation))\n",
    "        if annotation.__class__ == ast.NameConstant:\n",
    "            if annotation.value is None:\n",
    "                return \"None\"\n",
    "            else:\n",
    "                return annotation.value\n",
    "        if annotation.__class__ == ast.Index:\n",
    "            index_type = self.get_processed_type(annotation.value)\n",
    "            return index_type\n",
    "        if annotation.__class__ == ast.Tuple:\n",
    "            types = []\n",
    "            for expr in annotation.elts:\n",
    "                elts_type = self.get_processed_type(expr)\n",
    "                types.append(elts_type)\n",
    "            return \", \".join(types)\n",
    "        if annotation.__class__ == ast.Ellipsis:\n",
    "            return \"...\"\n",
    "        if annotation.__class__ == ast.List:\n",
    "            types = []\n",
    "            for expr in annotation.elts:\n",
    "                elts_type = self.get_processed_type(expr)\n",
    "                types.append(elts_type)\n",
    "            return \", \".join(types)\n",
    "        raise Exception(\"oops\", annotation, dir(annotation))\n",
    "        \n",
    "    def visit_FunctionDef(self, node):\n",
    "        arguments = [\n",
    "            {\n",
    "                \"name\": arg.arg,\n",
    "                \"type\": self.get_processed_type(arg.annotation),\n",
    "            }\n",
    "            for arg in node.args.args\n",
    "        ]\n",
    "        docstring = ast.get_docstring(node)\n",
    "        return_type = self.get_processed_type(node.returns)\n",
    "        payload = dict(\n",
    "            name=node.name,\n",
    "            has_docstring=False if docstring is None or docstring == \"\" else True,\n",
    "            docstring=docstring,\n",
    "            arguments=arguments,\n",
    "            return_type=return_type\n",
    "        )\n",
    "        score = self.get_function_score(payload)\n",
    "        payload[\"score\"] = score\n",
    "        self.build_doc(payload)\n",
    "        \n",
    "def percentage(num, den):\n",
    "    return round(num/den * 100, 2)\n",
    "\n",
    "# Check repo is download first\n",
    "from apps.patterns.git import repo_exists, clone_repo\n",
    "\n",
    "if not repo_exists():\n",
    "    clone_repo()\n",
    "\n",
    "FILEPATH = \"apps/orders/services.py\"\n",
    "full_file_path = get_full_path(file_path=FILEPATH)\n",
    "\n",
    "anlyzr = ServiceDocAnalyzer(entrypoint=full_file_path)\n",
    "anlyzr.start()\n",
    "all_doc = anlyzr.get_analysis()\n",
    "all_scores = list(map(lambda x: x['score'], all_doc['services']))\n",
    "print(f\"file score: {round(all_doc['global']['score'], 3)}\")\n",
    "print(f\"total functions: {len(all_scores)}\")\n",
    "\n",
    "great_score_limit = 90.0\n",
    "great_scores = list(filter(lambda x: x['score'] >= great_score_limit , all_doc['services']))\n",
    "print(f\"great scores (> {great_score_limit}): {len(great_scores)} ({percentage(len(great_scores), len(all_scores))}%)\")\n",
    "good_score_limit = 67.0\n",
    "good_scores = list(filter(lambda x: x['score'] > good_score_limit , all_doc['services']))\n",
    "print(f\"good scores (> {good_score_limit}): {len(good_scores)} ({percentage(len(good_scores), len(all_scores))}%)\")\n",
    "low_score_limit = 67.0\n",
    "super_low_score_limit = 33.0\n",
    "low_scores = list(filter(lambda x: x['score'] <= low_score_limit , all_doc['services']))\n",
    "print(f\"low scores (<= {low_score_limit}): {len(low_scores)} ({percentage(len(low_scores), len(all_scores))}%)\")\n",
    "super_low_scores = list(filter(lambda x: x['score'] <= super_low_score_limit , all_doc['services']))\n",
    "print(f\"super low scores (<= {super_low_score_limit}): {len(super_low_scores)} ({percentage(len(super_low_scores), len(all_scores))}%)\")\n",
    "\n",
    "without_docstring = list(filter(lambda x: not x['has_docstring'] , all_doc['services']))\n",
    "print(f\"without docstring : {len(without_docstring)} ({percentage(len(without_docstring), len(all_scores))}%)\")\n",
    "\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "({'name': 'get_external_order_mapping_list',\n",
       "  'has_docstring': False,\n",
       "  'docstring': None,\n",
       "  'arguments': [{'name': 'order_uuid', 'type': 'UUID, str'}],\n",
       "  'return_type': 'missing',\n",
       "  'score': 34.0},)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def analyze_function(doc_data, funct_name: str):\n",
    "    return tuple(filter(lambda x: x[\"name\"] == funct_name, doc_data.get('services', [])))\n",
    "\n",
    "analyze_function(all_doc, 'get_external_order_mapping_list')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Django Shell-Plus",
   "language": "python",
   "name": "django_extensions"
  },
  "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.7.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}