Merge pull request #169 from rsomani95/param-repr

add __repr__ to Param for augmented function documentation

Author: jph00

fastcore/_nbdev.py

@@ -209,6 +209,7 @@
          "store_true": "08_script.ipynb",
          "store_false": "08_script.ipynb",
          "bool_arg": "08_script.ipynb",
+         "clean_type_str": "08_script.ipynb",
          "Param": "08_script.ipynb",
          "anno_parser": "08_script.ipynb",
          "args_from_prog": "08_script.ipynb",

fastcore/script.py

@@ -1,7 +1,7 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: nbs/08_script.ipynb (unless otherwise specified).
 
-__all__ = ['store_true', 'store_false', 'bool_arg', 'Param', 'anno_parser', 'args_from_prog', 'SCRIPT_INFO',
-           'call_parse']
+__all__ = ['store_true', 'store_false', 'bool_arg', 'clean_type_str', 'Param', 'anno_parser', 'args_from_prog',
+           'SCRIPT_INFO', 'call_parse']
 
 # Cell
 import inspect,functools
@@ -24,6 +24,13 @@ def bool_arg(v):
     "Use as `type` for `Param` to get `bool` behavior"
     return str2bool(v)
 
+# Cell
+def clean_type_str(x:str):
+    x = str(x)
+    x = re.sub("(class|function|__main__\.|\ at.*)", '', x)
+    x = re.sub("(<|>|'|\ )", '', x) # spl characters
+    return x
+
 # Cell
 class Param:
     "A parameter in a function used in `anno_parser` or `call_parse`"
@@ -44,6 +51,11 @@ def pre(self): return '--' if self.opt else ''
     @property
     def kwargs(self): return {k:v for k,v in self.__dict__.items()
                               if v is not None and k!='opt' and k[0]!='_'}
+    def __repr__(self):
+        if self.help is None and self.type is None: return ""
+        if self.help is None and self.type is not None: return f"{clean_type_str(self.type)}"
+        if self.help is not None and self.type is None: return f"<{self.help}>"
+        if self.help is not None and self.type is not None: return f"{clean_type_str(self.type)} <{self.help}>"
 
 # Cell
 def anno_parser(func, prog=None, from_name=False):
@@ -93,4 +105,4 @@ def _f(*args, **kwargs):
         setattr(mod, func.__name__, _f)
         SCRIPT_INFO.func = func.__name__
         return _f()
-    else: return _f
+    else: return _f

nbs/08_script.ipynb

@@ -189,6 +189,35 @@
     "    return str2bool(v)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#export\n",
+    "def clean_type_str(x:str):\n",
+    "    x = str(x)\n",
+    "    x = re.sub(\"(class|function|__main__\\.|\\ at.*)\", '', x)\n",
+    "    x = re.sub(\"(<|>|'|\\ )\", '', x) # spl characters\n",
+    "    return x"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Test: pass\n",
+    "\n",
+    "test_eq(clean_type_str(argparse.ArgumentParser), 'argparse.ArgumentParser')\n",
+    "test_eq(clean_type_str(Test), 'Test')\n",
+    "test_eq(clean_type_str(int), 'int')\n",
+    "test_eq(clean_type_str(float), 'float')\n",
+    "test_eq(clean_type_str(store_false), 'store_false')"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -214,7 +243,24 @@
     "    def pre(self): return '--' if self.opt else ''\n",
     "    @property\n",
     "    def kwargs(self): return {k:v for k,v in self.__dict__.items()\n",
-    "                              if v is not None and k!='opt' and k[0]!='_'}"
+    "                              if v is not None and k!='opt' and k[0]!='_'}\n",
+    "    def __repr__(self):\n",
+    "        if self.help is None and self.type is None: return \"\"\n",
+    "        if self.help is None and self.type is not None: return f\"{clean_type_str(self.type)}\"\n",
+    "        if self.help is not None and self.type is None: return f\"<{self.help}>\"\n",
+    "        if self.help is not None and self.type is not None: return f\"{clean_type_str(self.type)} <{self.help}>\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_eq(repr(Param(\"Help goes here\")), '<Help goes here>')\n",
+    "test_eq(repr(Param(\"Help\", int)), 'int <Help>')\n",
+    "test_eq(repr(Param(help=None, type=int)), 'int')\n",
+    "test_eq(repr(Param(help=None, type=None)), '')"
    ]
   },
   {
@@ -223,7 +269,31 @@
    "source": [
     "Each parameter in your function should have an annotation `Param(...)`. You can pass the following when calling `Param`: `help`,`type`,`opt`,`action`,`nargs`,`const`,`choices`,`required` (i.e. it takes the same parameters as `argparse.ArgumentParser.add_argument`, plus `opt`). Except for `opt`, all of these are just passed directly to `argparse`, so you have all the power of that module at your disposal. Generally you'll want to pass at least `help` (since this is provided as the help string for that parameter) and `type` (to ensure that you get the type of data you expect).\n",
     "\n",
-    "`opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastcore.script will set it for you automatically based on *default* values. You should provide a default (after the `=`) for any *optional* parameters. If you don't provide a default for a parameter, then it will be a *positional* parameter."
+    "`opt` is a bool that defines whether a param is optional or required (positional) - but you'll generally not need to set this manually, because fastcore.script will set it for you automatically based on *default* values. You should provide a default (after the `=`) for any *optional* parameters. If you don't provide a default for a parameter, then it will be a *positional* parameter.\n",
+    "\n",
+    "Param's `__repr__` also allows for more informative function annotation when looking up the function's doc using shift+tab. You see the type annotation (if there is one) and the accompanying help documentation with it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def f(required:Param(\"Required param\", int),\n",
+    "      a:Param(\"param 1\", bool_arg),\n",
+    "      b:Param(\"param 2\", str)=\"test\"):\n",
+    "    \"my docs\"\n",
+    "    ..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "f?"
    ]
   },
   {
@@ -431,6 +501,7 @@
       "Converted 03_xtras.ipynb.\n",
       "Converted 04_dispatch.ipynb.\n",
       "Converted 05_transform.ipynb.\n",
+      "Converted 06_logargs.ipynb.\n",
       "Converted 07_meta.ipynb.\n",
       "Converted 08_script.ipynb.\n",
       "Converted index.ipynb.\n"