empty

Author: jph00

fastcore/_nbdev.py

@@ -244,6 +244,7 @@
          "gather_attrs": "05_transform.ipynb",
          "gather_attr_names": "05_transform.ipynb",
          "Pipeline": "05_transform.ipynb",
+         "empty": "06_docments.ipynb",
          "docments": "06_docments.ipynb",
          "test_sig": "07_meta.ipynb",
          "FixSigMeta": "07_meta.ipynb",

fastcore/docments.py

@@ -1,8 +1,13 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: nbs/06_docments.ipynb (unless otherwise specified).
 
-__all__ = ['docments']
+
+from __future__ import annotations
+
+
+__all__ = ['empty', 'docments']
 
 # Cell
+#nbdev_comment from __future__ import annotations
 from tokenize import tokenize,COMMENT
 from ast import parse,FunctionDef
 from io import BytesIO
@@ -37,6 +42,9 @@ def _param_locs(s, returns=True):
     if returns and defn.returns: res[defn.returns.lineno] = 'return'
     return res
 
+# Cell
+empty = Parameter.empty
+
 # Cell
 def _get_comment(line, arg, comments, parms):
     if line in comments: return comments[line].strip()
@@ -48,7 +56,7 @@ def _get_comment(line, arg, comments, parms):
     return dedent('\n'.join(reversed(res))) if res else None
 
 def _get_full(anno, name, default, docs):
-    if anno==Parameter.empty and default!=Parameter.empty: anno = type(default)
+    if anno==empty and default!=empty: anno = type(default)
     return AttrDict(docment=docs.get(name), anno=anno, default=default)
 
 # Cell
@@ -58,14 +66,14 @@ def docments(s, full=False, returns=True, eval_str=False):
     comments = {o.start[0]:_clean_comment(o.string) for o in _tokens(s) if o.type==COMMENT}
     parms = _param_locs(s, returns=returns)
     docs = {arg:_get_comment(line, arg, comments, parms) for line,arg in parms.items()}
-    if not full: return docs
+    if not full: return AttrDict(docs)
 
     if isinstance(s,str): s = eval(s)
     sig = signature(s)
     res = {arg:_get_full(p.annotation, p.name, p.default, docs) for arg,p in sig.parameters.items()}
-    if returns: res['return'] = _get_full(sig.return_annotation, 'return', Parameter.empty, docs)
+    if returns: res['return'] = _get_full(sig.return_annotation, 'return', empty, docs)
     if eval_str:
         hints = type_hints(s)
         for k,v in res.items():
             if k in hints: v['anno'] = hints.get(k)
-    return res
+    return AttrDict(res)

nbs/06_docments.ipynb

@@ -25,6 +25,7 @@
    "outputs": [],
    "source": [
     "#export\n",
+    "from __future__ import annotations\n",
     "from tokenize import tokenize,COMMENT\n",
     "from ast import parse,FunctionDef\n",
     "from io import BytesIO\n",
@@ -151,6 +152,16 @@
     "    return res"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#export\n",
+    "empty = Parameter.empty"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -168,7 +179,7 @@
     "    return dedent('\\n'.join(reversed(res))) if res else None\n",
     "\n",
     "def _get_full(anno, name, default, docs):\n",
-    "    if anno==Parameter.empty and default!=Parameter.empty: anno = type(default)\n",
+    "    if anno==empty and default!=empty: anno = type(default)\n",
     "    return AttrDict(docment=docs.get(name), anno=anno, default=default)"
    ]
   },
@@ -185,17 +196,17 @@
     "    comments = {o.start[0]:_clean_comment(o.string) for o in _tokens(s) if o.type==COMMENT}\n",
     "    parms = _param_locs(s, returns=returns)\n",
     "    docs = {arg:_get_comment(line, arg, comments, parms) for line,arg in parms.items()}\n",
-    "    if not full: return docs\n",
+    "    if not full: return AttrDict(docs)\n",
     "\n",
     "    if isinstance(s,str): s = eval(s)\n",
     "    sig = signature(s)\n",
     "    res = {arg:_get_full(p.annotation, p.name, p.default, docs) for arg,p in sig.parameters.items()}\n",
-    "    if returns: res['return'] = _get_full(sig.return_annotation, 'return', Parameter.empty, docs)\n",
+    "    if returns: res['return'] = _get_full(sig.return_annotation, 'return', empty, docs)\n",
     "    if eval_str:\n",
     "        hints = type_hints(s)\n",
     "        for k,v in res.items():\n",
     "            if k in hints: v['anno'] = hints.get(k)\n",
-    "    return res"
+    "    return AttrDict(res)"
    ]
   },
   {
@@ -212,6 +223,13 @@
    "outputs": [
     {
      "data": {
+      "text/markdown": [
+       "```json\n",
+       "{ 'a': 'the 1st number to add',\n",
+       "  'b': 'the 2nd number to add',\n",
+       "  'return': 'the result of adding `a` to `b`'}\n",
+       "```"
+      ],
       "text/plain": [
        "{'a': 'the 1st number to add',\n",
        " 'b': 'the 2nd number to add',\n",
@@ -242,7 +260,7 @@
     {
      "data": {
       "text/plain": [
-       "{'a': int, 'return': int}"
+       "{'a': 'int', 'return': 'int'}"
       ]
      },
      "execution_count": null,
@@ -269,14 +287,14 @@
     {
      "data": {
       "text/markdown": [
-       "- docment: the 1st number to add\n",
-       "- anno: <class 'int'>\n",
-       "- default: <class 'inspect._empty'>"
+       "```json\n",
+       "{ 'anno': 'int',\n",
+       "  'default': <class 'inspect._empty'>,\n",
+       "  'docment': 'the 1st number to add'}\n",
+       "```"
       ],
       "text/plain": [
-       "- docment: the 1st number to add\n",
-       "- anno: <class 'int'>\n",
-       "- default: <class 'inspect._empty'>"
+       "{'docment': 'the 1st number to add', 'anno': 'int', 'default': inspect._empty}"
       ]
      },
      "execution_count": null,
@@ -303,14 +321,14 @@
     {
      "data": {
       "text/markdown": [
-       "- docment: the 1st number to add\n",
-       "- anno: <class 'int'>\n",
-       "- default: <class 'inspect._empty'>"
+       "```json\n",
+       "{ 'anno': <class 'int'>,\n",
+       "  'default': <class 'inspect._empty'>,\n",
+       "  'docment': 'the 1st number to add'}\n",
+       "```"
       ],
       "text/plain": [
-       "- docment: the 1st number to add\n",
-       "- anno: <class 'int'>\n",
-       "- default: <class 'inspect._empty'>"
+       "{'docment': 'the 1st number to add', 'anno': int, 'default': inspect._empty}"
       ]
      },
      "execution_count": null,
@@ -353,6 +371,15 @@
    "outputs": [
     {
      "data": {
+      "text/markdown": [
+       "```json\n",
+       "{ 'a': 'The first operand',\n",
+       "  'b': 'This is the second of the operands to the *addition* operator.\\n'\n",
+       "       'Note that passing a negative value here is the equivalent of the '\n",
+       "       '*subtraction* operator.',\n",
+       "  'return': \"The result is calculated using Python's builtin `+` operator.\"}\n",
+       "```"
+      ],
       "text/plain": [
        "{'a': 'The first operand',\n",
        " 'b': 'This is the second of the operands to the *addition* operator.\\nNote that passing a negative value here is the equivalent of the *subtraction* operator.',\n",
@@ -401,9 +428,38 @@
    "outputs": [
     {
      "data": {
+      "text/markdown": [
+       "```json\n",
+       "{'a': 'First operand', 'b': '2nd operand', 'self': None}\n",
+       "```"
+      ],
+      "text/plain": [
+       "{'self': None, 'a': 'First operand', 'b': '2nd operand'}"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "docments(Adder)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "```json\n",
+       "{'return': 'Integral result of addition operator', 'self': None}\n",
+       "```"
+      ],
       "text/plain": [
-       "({'self': None, 'a': 'First operand', 'b': '2nd operand'},\n",
-       " {'self': None, 'return': 'Integral result of addition operator'})"
+       "{'self': None, 'return': 'Integral result of addition operator'}"
       ]
      },
      "execution_count": null,
@@ -412,7 +468,7 @@
     }
    ],
    "source": [
-    "docments(Adder),docments(Adder.calculate)"
+    "docments(Adder.calculate)"
    ]
   },
   {