Update NbdevLookup to support import aliases and improve docstrings

nbdev/doclinks.py

@@ -22,6 +22,7 @@
 from pprint import pformat
 from urllib.parse import urljoin
 from functools import lru_cache
+from types import ModuleType
 
 # %% ../nbs/api/05_doclinks.ipynb
 def _sym_nm(klas, sym): return f'{unparse(klas).strip()}.{sym.name}'
@@ -166,6 +167,7 @@ def _find_mod(mod):
 
 @lru_cache(None)
 def _get_exps(mod):
+    "Get the line numbers for function and class definitions in module"
     mf = _find_mod(mod)
     if not mf: return {}
     txt = mf.read_text(encoding='utf-8')
@@ -181,6 +183,7 @@ def _lineno(sym, fname): return _get_exps(fname).get(sym, None) if fname else No
 
 # %% ../nbs/api/05_doclinks.ipynb
 def _qual_sym(s, settings):
+    "Get qualified nb, py, and github paths for a symbol s"
     if not isinstance(s,tuple): return s
     nb,py = s
     nbbase = urljoin(settings["doc_host"]+'/',settings["doc_baseurl"])
@@ -198,10 +201,9 @@ def _qual_syms(entries):
 _re_backticks = re.compile(r'`([^`\s]+?)(?:\(\))?`')
 
 # %% ../nbs/api/05_doclinks.ipynb
-@lru_cache(None)
 class NbdevLookup:
     "Mapping from symbol names to docs and source URLs"
-    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
+    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None):
         cfg = get_config()
         if strip_libs is None:
             try: strip_libs = cfg.get('strip_libs', cfg.get('lib_path', 'nbdev').name).split()
@@ -221,8 +223,13 @@ def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):
                             for k,v in dets.items()}
                 py_syms = merge(stripped, py_syms)
         self.syms = py_syms
-
-    def __getitem__(self, s): return self.syms.get(s, None)
+        self.aliases = {n:o.__name__ for n,o in (ns or {}).items() if isinstance(o, ModuleType)}
+
+    def __getitem__(self, s): 
+        if '.' in s:
+            pre,post = s.split('.', 1)
+            if pre in self.aliases: s = f"{self.aliases[pre]}.{post}"
+        return self.syms.get(s, None)
 
     def doc(self, sym):
         "Link to docs for `sym`"

nbs/api/05_doclinks.ipynb

@@ -40,7 +40,8 @@
     "\n",
     "from pprint import pformat\n",
     "from urllib.parse import urljoin\n",
-    "from functools import lru_cache"
+    "from functools import lru_cache\n",
+    "from types import ModuleType"
    ]
   },
   {
@@ -415,6 +416,7 @@
     "\n",
     "@lru_cache(None)\n",
     "def _get_exps(mod):\n",
+    "    \"Get the line numbers for function and class definitions in module\"\n",
     "    mf = _find_mod(mod)\n",
     "    if not mf: return {}\n",
     "    txt = mf.read_text(encoding='utf-8')\n",
@@ -448,6 +450,7 @@
    "source": [
     "#|export\n",
     "def _qual_sym(s, settings):\n",
+    "    \"Get qualified nb, py, and github paths for a symbol s\"\n",
     "    if not isinstance(s,tuple): return s\n",
     "    nb,py = s\n",
     "    nbbase = urljoin(settings[\"doc_host\"]+'/',settings[\"doc_baseurl\"])\n",
@@ -500,10 +503,9 @@
    "outputs": [],
    "source": [
     "#|export\n",
-    "@lru_cache(None)\n",
     "class NbdevLookup:\n",
     "    \"Mapping from symbol names to docs and source URLs\"\n",
-    "    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None):\n",
+    "    def __init__(self, strip_libs=None, incl_libs=None, skip_mods=None, ns=None):\n",
     "        cfg = get_config()\n",
     "        if strip_libs is None:\n",
     "            try: strip_libs = cfg.get('strip_libs', cfg.get('lib_path', 'nbdev').name).split()\n",
@@ -523,8 +525,13 @@
     "                            for k,v in dets.items()}\n",
     "                py_syms = merge(stripped, py_syms)\n",
     "        self.syms = py_syms\n",
-    "\n",
-    "    def __getitem__(self, s): return self.syms.get(s, None)\n",
+    "        self.aliases = {n:o.__name__ for n,o in (ns or {}).items() if isinstance(o, ModuleType)}\n",
+    "        \n",
+    "    def __getitem__(self, s): \n",
+    "        if '.' in s:\n",
+    "            pre,post = s.split('.', 1)\n",
+    "            if pre in self.aliases: s = f\"{self.aliases[pre]}.{post}\"\n",
+    "        return self.syms.get(s, None)\n",
     "\n",
     "    def doc(self, sym):\n",
     "        \"Link to docs for `sym`\"\n",
@@ -571,6 +578,14 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/home/nathan/miniconda3/envs/main/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+      "  from .autonotebook import tqdm as notebook_tqdm\n"
+     ]
+    },
     {
      "data": {
       "text/plain": [
@@ -753,7 +768,7 @@
       "text/markdown": [
        "---\n",
        "\n",
-       "[source](https://github.com/fastai/nbdev/blob/master/nbdev/doclinks.py#L249){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
+       "[source](https://github.com/fastai/nbdev/blob/master/nbdev/doclinks.py#L250){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
        "\n",
        "### NbdevLookup.linkify\n",
        "\n",
@@ -762,7 +777,7 @@
       "text/plain": [
        "---\n",
        "\n",
-       "[source](https://github.com/fastai/nbdev/blob/master/nbdev/doclinks.py#L249){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
+       "[source](https://github.com/fastai/nbdev/blob/master/nbdev/doclinks.py#L250){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
        "\n",
        "### NbdevLookup.linkify\n",
        "\n",
@@ -833,6 +848,34 @@
     "assert NbdevLookup().linkify(md) == md"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also use NbdevLookup with import aliases like the following:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'this is an aliased import link [`np.array`](https://numpy.org/doc/stable/reference/generated/numpy.array.html#numpy.array)'"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import numpy as np\n",
+    "NbdevLookup(ns=globals()).linkify('this is an aliased import link `np.array`')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -856,13 +899,6 @@
     "from nbdev._modidx import d\n",
     "assert d['syms']['nbdev.doclinks']['nbdev.doclinks.NbdevLookup'][0]"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {