Merge pull request #464 from seeM/delegates-docments-verbose

exclude `passed to {func}` from docments by passing `verbose=False` to `delegates`
AnswerDotAI · Aug 14, 2022 · 101c4f6 · 101c4f6
2 parents 881151d + db13d78
commit 101c4f6
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 131 deletions.
diff --git a/fastcore/docments.py b/fastcore/docments.py
@@ -155,10 +155,12 @@ def docments(elt, full=False, **kwargs):
     res = _docments(elt, **kwargs)
     if hasattr(elt, "__delwrap__"): #for delegates
         delwrap_dict = _docments(elt.__delwrap__, **kwargs)
+        verbose = getattr(elt,'__delopts__',{}).get('verbose',True)
         for k,v in res.items():
             if k in delwrap_dict and v["docment"] is None and k != "return":
                 if delwrap_dict[k]["docment"] is not None:
-                    v["docment"] = delwrap_dict[k]["docment"] + f" passed to `{qual_name(elt.__delwrap__)}`"
+                    v["docment"] = delwrap_dict[k]["docment"]
+                    if verbose: v["docment"]+=f" passed to `{qual_name(elt.__delwrap__)}`"
                 else: v['docment'] = f"Argument passed to `{qual_name(elt.__delwrap__)}`"
 
     if not full: res = {k:v['docment'] for k,v in res.items()}

diff --git a/fastcore/meta.py b/fastcore/meta.py
@@ -106,7 +106,10 @@ def _f(f):
     return _f
 
 # %% ../nbs/07_meta.ipynb 68
-def delegates(to=None, keep=False, but=None):
+def delegates(to:FunctionType=None, # Delegatee
+              keep=False, # Keep `kwargs` in decorated function?
+              but:list=None, # Exclude these parameters from signature
+              verbose=True): # Include `to` in docments?
     "Decorator: replace `**kwargs` in signature with params from `to`"
     if but is None: but = []
     def _f(f):
@@ -123,6 +126,7 @@ def _f(f):
         sigd.update(s2)
         if keep: sigd['kwargs'] = k
         else: from_f.__delwrap__ = to_f
+        from_f.__delopts__ = dict(verbose=verbose)
         from_f.__signature__ = sig.replace(parameters=sigd.values())
         return f
     return _f

diff --git a/nbs/06_docments.ipynb b/nbs/06_docments.ipynb
@@ -414,10 +414,12 @@
     "    res = _docments(elt, **kwargs)\n",
     "    if hasattr(elt, \"__delwrap__\"): #for delegates\n",
     "        delwrap_dict = _docments(elt.__delwrap__, **kwargs)\n",
+    "        verbose = getattr(elt,'__delopts__',{}).get('verbose',True)\n",
     "        for k,v in res.items():\n",
     "            if k in delwrap_dict and v[\"docment\"] is None and k != \"return\":\n",
     "                if delwrap_dict[k][\"docment\"] is not None:\n",
-    "                    v[\"docment\"] = delwrap_dict[k][\"docment\"] + f\" passed to `{qual_name(elt.__delwrap__)}`\"\n",
+    "                    v[\"docment\"] = delwrap_dict[k][\"docment\"]\n",
+    "                    if verbose: v[\"docment\"]+=f\" passed to `{qual_name(elt.__delwrap__)}`\"\n",
     "                else: v['docment'] = f\"Argument passed to `{qual_name(elt.__delwrap__)}`\"\n",
     "                    \n",
     "    if not full: res = {k:v['docment'] for k,v in res.items()}\n",
@@ -906,7 +908,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Docments even works with `@delegates`:"
+    "Docments even works with `delegates`:"
    ]
   },
   {
@@ -915,34 +917,30 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "#|hide\n",
-    "\n",
-    "# Test delegates\n",
-    "from fastcore.meta import delegates\n",
-    "def _a(\n",
-    "    a:int=2, # First\n",
-    "):\n",
-    "    return a\n",
+    "from fastcore.meta import delegates"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def _a(a:int=2): return a # First\n",
     "\n",
     "@delegates(_a)\n",
-    "def _b(\n",
-    "    b:str, # Second\n",
-    "    **kwargs\n",
-    "):\n",
-    "    return b, (_a(**kwargs))\n",
-    "\n",
-    "def _c(\n",
-    "    b:str, # Second\n",
-    "    a:int=2, # Blah\n",
-    "):\n",
-    "    return b, a\n",
-    "@delegates(_c)\n",
-    "def _d(\n",
-    "    c:int, # First\n",
-    "    b:str,\n",
-    "    **kwargs\n",
-    "):\n",
-    "    return c, _c(b, **kwargs)"
+    "def _b(b:str, **kwargs): return b, (_a(**kwargs)) # Second"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#|hide\n",
+    "test_eq(docments(_a, full=True)['a']['docment'],'First')\n",
+    "test_eq(docments(_b, full=True)['a']['docment'],'First passed to `_a`')"
    ]
   },
   {
@@ -954,17 +952,11 @@
      "data": {
       "text/markdown": [
        "```json\n",
-       "{ 'a': {'anno': 'int', 'default': 2, 'docment': 'First'},\n",
-       "  'return': { 'anno': <class 'inspect._empty'>,\n",
-       "              'default': <class 'inspect._empty'>,\n",
-       "              'docment': None}}\n",
+       "{'a': 'First passed to `_a`', 'b': 'Second', 'return': None}\n",
        "```"
       ],
       "text/plain": [
-       "{'a': {'docment': 'First', 'anno': 'int', 'default': 2},\n",
-       " 'return': {'docment': None,\n",
-       "  'anno': inspect._empty,\n",
-       "  'default': inspect._empty}}"
+       "{'b': 'Second', 'a': 'First passed to `_a`', 'return': None}"
       ]
      },
      "execution_count": null,
@@ -973,7 +965,63 @@
     }
    ],
    "source": [
-    "docments(_a, full=True)"
+    "docments(_b)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#|hide\n",
+    "def _c(b:str, # Second\n",
+    "       a:int=2): return b, a # Third\n",
+    "\n",
+    "@delegates(_c)\n",
+    "def _d(c:int, # First\n",
+    "       b:str, **kwargs): return c, _c(b, **kwargs)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#|hide\n",
+    "test_eq(docments(_c, full=True)['b']['docment'],'Second')\n",
+    "test_eq(docments(_d, full=True)['b']['docment'],'Second passed to `_c`')\n",
+    "_argset = {'a', 'b', 'c', 'return'}\n",
+    "test_eq(docments(_d, full=True).keys() & _argset, _argset) # _d has the args a,b,c and return"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you pass `verbose=False` to `delegates`, the `'passed to `{func}`'` part will be excluded from docments:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@delegates(_a, verbose=False)\n",
+    "def _e(b:str, **kwargs): return b, (_a(**kwargs)) # Second, not passed"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#|hide\n",
+    "test_eq(docments(_e, full=True)['a']['docment'],'First')\n",
+    "test_eq(docments(_e, full=True)['b']['docment'],'Second, not passed')"
    ]
   },
   {
@@ -985,25 +1033,11 @@
      "data": {
       "text/markdown": [
        "```json\n",
-       "{ 'a': {'anno': 'int', 'default': 2, 'docment': 'Blah passed to `_c`'},\n",
-       "  'b': { 'anno': 'str',\n",
-       "         'default': <class 'inspect._empty'>,\n",
-       "         'docment': 'Second passed to `_c`'},\n",
-       "  'c': {'anno': 'int', 'default': <class 'inspect._empty'>, 'docment': 'First'},\n",
-       "  'return': { 'anno': <class 'inspect._empty'>,\n",
-       "              'default': <class 'inspect._empty'>,\n",
-       "              'docment': None}}\n",
+       "{'a': 'First', 'b': 'Second, not passed', 'return': None}\n",
        "```"
       ],
       "text/plain": [
-       "{'c': {'docment': 'First', 'anno': 'int', 'default': inspect._empty},\n",
-       " 'b': {'docment': 'Second passed to `_c`',\n",
-       "  'anno': 'str',\n",
-       "  'default': inspect._empty},\n",
-       " 'a': {'docment': 'Blah passed to `_c`', 'anno': 'int', 'default': 2},\n",
-       " 'return': {'docment': None,\n",
-       "  'anno': inspect._empty,\n",
-       "  'default': inspect._empty}}"
+       "{'b': 'Second, not passed', 'a': 'First', 'return': None}"
       ]
      },
      "execution_count": null,
@@ -1012,20 +1046,7 @@
     }
    ],
    "source": [
-    "docments(_d, full=True)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "test_eq(docments(_b, full=True)['a']['docment'],'First passed to `_a`')\n",
-    "test_eq(docments(_c, full=True)['b']['docment'],'Second')\n",
-    "test_eq(docments(_d, full=True)['b']['docment'], 'Second passed to `_c`')\n",
-    "_argset = {'a', 'b', 'c', 'return'}\n",
-    "test_eq(set(docments(_d, full=True).keys()).intersection(_argset), _argset) # _d has the args a,b,c and return"
+    "docments(_e)"
    ]
   },
   {
@@ -1039,27 +1060,7 @@
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Converted 00_test.ipynb.\n",
-      "Converted 01_basics.ipynb.\n",
-      "Converted 02_foundation.ipynb.\n",
-      "Converted 03_xtras.ipynb.\n",
-      "Converted 03a_parallel.ipynb.\n",
-      "Converted 03b_net.ipynb.\n",
-      "Converted 04_dispatch.ipynb.\n",
-      "Converted 05_transform.ipynb.\n",
-      "Converted 06_docments.ipynb.\n",
-      "Converted 07_meta.ipynb.\n",
-      "Converted 08_script.ipynb.\n",
-      "Converted index.ipynb.\n",
-      "Converted parallel_win.ipynb.\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "#|hide\n",
     "#|eval: false\n",