fixes #687

Author: jph00

fastcore/_modidx.py

@@ -253,7 +253,8 @@
                                    'fastcore.docments.get_source': ('docments.html#get_source', 'fastcore/docments.py'),
                                    'fastcore.docments.isdataclass': ('docments.html#isdataclass', 'fastcore/docments.py'),
                                    'fastcore.docments.parse_docstring': ('docments.html#parse_docstring', 'fastcore/docments.py'),
-                                   'fastcore.docments.qual_name': ('docments.html#qual_name', 'fastcore/docments.py')},
+                                   'fastcore.docments.qual_name': ('docments.html#qual_name', 'fastcore/docments.py'),
+                                   'fastcore.docments.sig2str': ('docments.html#sig2str', 'fastcore/docments.py')},
             'fastcore.docscrape': {},
             'fastcore.foundation': { 'fastcore.foundation.CollBase': ('foundation.html#collbase', 'fastcore/foundation.py'),
                                      'fastcore.foundation.CollBase.__delitem__': ( 'foundation.html#collbase.__delitem__',

fastcore/docments.py

@@ -5,7 +5,7 @@
 # %% ../nbs/04_docments.ipynb 2
 from __future__ import annotations
 
-import re,ast
+import re,ast,inspect
 from tokenize import tokenize,COMMENT
 from ast import parse,FunctionDef,AsyncFunctionDef,AnnAssign
 from io import BytesIO
@@ -20,7 +20,7 @@
 
 # %% auto 0
 __all__ = ['empty', 'docstring', 'parse_docstring', 'isdataclass', 'get_dataclass_source', 'get_source', 'get_name', 'qual_name',
-           'docments', 'extract_docstrings']
+           'docments', 'sig2str', 'extract_docstrings']
 
 # %% ../nbs/04_docments.ipynb
 def docstring(sym):
@@ -180,13 +180,37 @@ def _update_docments(f, r):
     if not full: r = {k:v['docment'] for k,v in r.items()}
     return AttrDict(r)
 
+# %% ../nbs/04_docments.ipynb
+def sig2str(func):
+    "Generate function signature with docments as comments"
+    docs = docments(func, full=True)
+    params = []
+    for k,v in docs.items():
+        if k == 'return': continue
+        anno = getattr(v['anno'], '__name__', str(v['anno'])) if v['anno'] != inspect._empty else ''
+        if '|' in str(v['anno']): anno = str(v['anno'])
+        p = k + (f':{anno}' if anno and anno != 'inspect._empty' else '')
+        if v['default'] != inspect._empty:
+            d = getattr(v['default'], '__name__', v['default']) if hasattr(v['default'], '__name__') else v['default']
+            p += f'={d}' if d is not None else '=None'
+        if v['docment']: p += f' # {v["docment"]}'
+        params.append(p)
+    
+    ret = docs.get('return', {})
+    ret_str = ':'
+    if ret and ret.get('anno')!=inspect._empty:
+        ret_str = f"->{getattr(ret['anno'], '__name__', str(ret['anno']))}" + (f': # {ret["docment"]}' if ret.get('docment') else ':')
+    doc_str = f'    "{func.__doc__}"' if func.__doc__ else ''
+    return f"def {func.__name__}(\n    " + ",\n    ".join(params) + f"\n){ret_str}\n{doc_str}"
+
 # %% ../nbs/04_docments.ipynb
 def _get_params(node):
     params = [a.arg for a in node.args.args]
     if node.args.vararg: params.append(f"*{node.args.vararg.arg}")
     if node.args.kwarg: params.append(f"**{node.args.kwarg.arg}")
     return ", ".join(params)
 
+# %% ../nbs/04_docments.ipynb
 class _DocstringExtractor(ast.NodeVisitor):
     def __init__(self): self.docstrings,self.cls,self.cls_init = {},None,None
 

nbs/04_docments.ipynb

@@ -27,7 +27,7 @@
     "#|export\n",
     "from __future__ import annotations\n",
     "\n",
-    "import re,ast\n",
+    "import re,ast,inspect\n",
     "from tokenize import tokenize,COMMENT\n",
     "from ast import parse,FunctionDef,AsyncFunctionDef,AnnAssign\n",
     "from io import BytesIO\n",
@@ -840,7 +840,7 @@
      "output_type": "stream",
      "text": [
       "The sum of two numbers.\n",
-      "    \n",
+      "\n",
       "    Used to demonstrate numpy-style docstrings.\n",
       "\n",
       "Parameters\n",
@@ -1019,7 +1019,8 @@
     "\n",
     "@delegates(_a)\n",
     "def _b(b:str, # Second\n",
-    "       **kwargs): \n",
+    "       **kwargs\n",
+    "      ): # Return nothing\n",
     "    return b, (_a(**kwargs)) \n",
     "\n",
     "docments(_b)"
@@ -1073,7 +1074,7 @@
     "@delegates(_c)\n",
     "def _d(c:int, # First\n",
     "       b:str, **kwargs\n",
-    "      )->int:\n",
+    "      )->int: # Return an int\n",
     "    return c, _c(b, **kwargs)"
    ]
   },
@@ -1090,6 +1091,58 @@
     "test_eq(docments(_d, full=True).keys() & _argset, _argset) # _d has the args a,b,c and return"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def sig2str(func):\n",
+    "    \"Generate function signature with docments as comments\"\n",
+    "    docs = docments(func, full=True)\n",
+    "    params = []\n",
+    "    for k,v in docs.items():\n",
+    "        if k == 'return': continue\n",
+    "        anno = getattr(v['anno'], '__name__', str(v['anno'])) if v['anno'] != inspect._empty else ''\n",
+    "        if '|' in str(v['anno']): anno = str(v['anno'])\n",
+    "        p = k + (f':{anno}' if anno and anno != 'inspect._empty' else '')\n",
+    "        if v['default'] != inspect._empty:\n",
+    "            d = getattr(v['default'], '__name__', v['default']) if hasattr(v['default'], '__name__') else v['default']\n",
+    "            p += f'={d}' if d is not None else '=None'\n",
+    "        if v['docment']: p += f' # {v[\"docment\"]}'\n",
+    "        params.append(p)\n",
+    "    \n",
+    "    ret = docs.get('return', {})\n",
+    "    ret_str = ':'\n",
+    "    if ret and ret.get('anno')!=inspect._empty:\n",
+    "        ret_str = f\"->{getattr(ret['anno'], '__name__', str(ret['anno']))}\" + (f': # {ret[\"docment\"]}' if ret.get('docment') else ':')\n",
+    "    doc_str = f'    \"{func.__doc__}\"' if func.__doc__ else ''\n",
+    "    return f\"def {func.__name__}(\\n    \" + \",\\n    \".join(params) + f\"\\n){ret_str}\\n{doc_str}\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "def _d(\n",
+      "    b:str # Second,\n",
+      "    a:int=2 # Third,\n",
+      "    c:int # First\n",
+      ")->int: # Return an int\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(sig2str(_d))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -1108,8 +1161,16 @@
     "    params = [a.arg for a in node.args.args]\n",
     "    if node.args.vararg: params.append(f\"*{node.args.vararg.arg}\")\n",
     "    if node.args.kwarg: params.append(f\"**{node.args.kwarg.arg}\")\n",
-    "    return \", \".join(params)\n",
-    "\n",
+    "    return \", \".join(params)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
     "class _DocstringExtractor(ast.NodeVisitor):\n",
     "    def __init__(self): self.docstrings,self.cls,self.cls_init = {},None,None\n",
     "\n",