From ff77f6cabf097b483d74ae121cb8c8f7fe6fb814 Mon Sep 17 00:00:00 2001 From: seem Date: Sun, 14 Aug 2022 10:25:21 +1000 Subject: [PATCH] exclude `passed to {func}` from docments by passing `verbose=True` to `delegates` --- fastcore/_modidx.py | 2 +- fastcore/docments.py | 4 +- fastcore/meta.py | 6 +- nbs/06_docments.ipynb | 177 +++++++++++++++++++++--------------------- nbs/07_meta.ipynb | 80 ++++++++++--------- 5 files changed, 137 insertions(+), 132 deletions(-) diff --git a/fastcore/_modidx.py b/fastcore/_modidx.py index 44a27b7b5..a9e947249 100644 --- a/fastcore/_modidx.py +++ b/fastcore/_modidx.py @@ -31,7 +31,7 @@ 'title': 'fastcore', 'tst_flags': '', 'user': 'fastai', - 'version': '1.5.17'}, + 'version': '1.5.18'}, 'syms': { 'fastcore.all': {}, 'fastcore.basics': { 'fastcore.basics.AttrDict': 'https://fastcore.fast.ai/basics.html#attrdict', 'fastcore.basics.AttrDict.copy': 'https://fastcore.fast.ai/basics.html#attrdict.copy', diff --git a/fastcore/docments.py b/fastcore/docments.py index 6bbb9f5af..2809a1d27 100644 --- 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 index 60b7cb46e..6d2ada07f 100644 --- 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 index be1594248..fd3b2a0bd 100644 --- 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': ,\n", - " 'default': ,\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': ,\n", - " 'docment': 'Second passed to `_c`'},\n", - " 'c': {'anno': 'int', 'default': , 'docment': 'First'},\n", - " 'return': { 'anno': ,\n", - " 'default': ,\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", diff --git a/nbs/07_meta.ipynb b/nbs/07_meta.ipynb index 28a16736c..a1531d181 100644 --- a/nbs/07_meta.ipynb +++ b/nbs/07_meta.ipynb @@ -120,18 +120,21 @@ { "data": { "text/markdown": [ - "

class FixSigMeta[source]

\n", + "---\n", "\n", - "> FixSigMeta(**`name`**, **`bases`**, **`dict`**) :: `type`\n", + "### FixSigMeta\n", + "\n", + "> FixSigMeta (name, bases, dict)\n", "\n", "A metaclass that fixes the signature on classes that override `__new__`" ], "text/plain": [ - "" + "" ] }, + "execution_count": null, "metadata": {}, - "output_type": "display_data" + "output_type": "execute_result" } ], "source": [ @@ -199,7 +202,7 @@ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": null, @@ -332,18 +335,21 @@ { "data": { "text/markdown": [ - "

class PrePostInitMeta[source]

\n", + "---\n", + "\n", + "### PrePostInitMeta\n", "\n", - "> PrePostInitMeta(**`name`**, **`bases`**, **`dict`**) :: [`FixSigMeta`](/meta.html#FixSigMeta)\n", + "> PrePostInitMeta (name, bases, dict)\n", "\n", "A metaclass that calls optional `__pre_init__` and `__post_init__` methods" ], "text/plain": [ - "" + "" ] }, + "execution_count": null, "metadata": {}, - "output_type": "display_data" + "output_type": "execute_result" } ], "source": [ @@ -440,18 +446,21 @@ { "data": { "text/markdown": [ - "

class NewChkMeta[source]

\n", + "---\n", "\n", - "> NewChkMeta(**`name`**, **`bases`**, **`dict`**) :: [`FixSigMeta`](/meta.html#FixSigMeta)\n", + "### NewChkMeta\n", + "\n", + "> NewChkMeta (name, bases, dict)\n", "\n", "Metaclass to avoid recreating object passed to constructor" ], "text/plain": [ - "" + "" ] }, + "execution_count": null, "metadata": {}, - "output_type": "display_data" + "output_type": "execute_result" } ], "source": [ @@ -601,18 +610,21 @@ { "data": { "text/markdown": [ - "

class BypassNewMeta[source]

\n", + "---\n", + "\n", + "### BypassNewMeta\n", "\n", - "> BypassNewMeta(**`name`**, **`bases`**, **`dict`**) :: [`FixSigMeta`](/meta.html#FixSigMeta)\n", + "> BypassNewMeta (name, bases, dict)\n", "\n", "Metaclass: casts `x` to this class if it's of type `cls._bypass_type`" ], "text/plain": [ - "" + "" ] }, + "execution_count": null, "metadata": {}, - "output_type": "display_data" + "output_type": "execute_result" } ], "source": [ @@ -866,7 +878,10 @@ "outputs": [], "source": [ "#|export\n", - "def delegates(to=None, keep=False, but=None):\n", + "def delegates(to:FunctionType=None, # Delegatee\n", + " keep=False, # Keep `kwargs` in decorated function?\n", + " but:list=None, # Exclude these parameters from signature\n", + " verbose=True): # Include `to` in docments?\n", " \"Decorator: replace `**kwargs` in signature with params from `to`\"\n", " if but is None: but = []\n", " def _f(f):\n", @@ -883,6 +898,7 @@ " sigd.update(s2)\n", " if keep: sigd['kwargs'] = k\n", " else: from_f.__delwrap__ = to_f\n", + " from_f.__delopts__ = dict(verbose=verbose)\n", " from_f.__signature__ = sig.replace(parameters=sigd.values())\n", " return f\n", " return _f" @@ -953,7 +969,7 @@ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": null, @@ -985,7 +1001,7 @@ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": null, @@ -1017,7 +1033,7 @@ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": null, @@ -1051,7 +1067,7 @@ { "data": { "text/plain": [ - "" + "" ] }, "execution_count": null, @@ -1420,25 +1436,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 07_meta.ipynb.\n", - "Converted 08_script.ipynb.\n", - "Converted index.ipynb.\n" - ] - } - ], + "outputs": [], "source": [ "#|hide\n", "#|eval: false\n",