Nested Parenthetical Madness
    Wondering what’s next for npm?Check out our public roadmap! »

    @krassowski/jupyterlab_go_to_definition
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0 • Public • Published

    Go to definition extension for JupyterLab

    Build Status codebeat badge Binder

    Jump to definition of a variable or function in JupyterLab notebook and file editor.

    Use Alt + click to jump to a definition using your mouse, or Ctrl + Alt + B keyboard-only alternative.

    Go to definition

    You can replace the key modifier for mouse click from Alt to Control, Shift, Meta or AltGraph in the settings (see remarks below).

    To jump back to the variable/function usage, use Alt + o.

    The plugin is language-agnostic, though optimized for Python and R. Support for other languages is possible (PRs welcome).

    Jumping to definitions in other files

    Python:

    • alt-click on the name of a module in Python (e.g. from x.y import z - alt-click on x or z) (new in v0.5)
    • alt-click on a class, function or method imported from any module (except for builtin modules written in C as such do not have a corresponding Python source file) in a notebook with active Python 3 kernel (new in v0.6)

    R (new in v0.5):

    • alt-click on source function (e.g. alt-clicking on source in source('test.R') will open test.R file)
    • alt-click on .from of import::here(x, y, .from='some_file.R')

    Background: there are two ways to solve the definitions location: static analysis and inspection performed in the kernel. The latter is more accurate, although it currently only works in notebooks (not in the file editor). For the implementation overview, please see the design page. In order to jump to a file outside of the JupyterLab project directory (e.g. the built-in Python libraries) a symlink-based workaround is required.

    Changing the modifiers key from alt

    Please go to Settings > Advanced Setting Editor > Go-to-definition and set a modifier of your choice in the User Preferences panel. For full list of physical keys mapped to the modifiers (which depend on your Operating System), please see the MDN documentation.

    Safari users: Safari does not implement MouseEvent.getModifierState (see #3), thus only Alt, Control, Shift and Meta are supported.

    Related extensions

    jupyterlab-lsp provides advanced autocompletion, code navigation, hover suggestions, linters, etc. It depends on this extension for the jumping functionality, thus all the jumps are recorded in a shared history and the "go back" option should work with jumps performed with both: shortcuts from this extension and context-menu actions of jupyterlab-lsp.

    Prerequisites

    • JupyterLab 1.0+

    Installation

    jupyter labextension install @krassowski/jupyterlab_go_to_definition

    To update already installed extension:

    jupyter labextension update @krassowski/jupyterlab_go_to_definition

    Development

    For a development install (requires npm version 4 or later), do the following in the repository directory:

    npm install
    npm run build
    jupyter labextension link .

    To rebuild the package and the JupyterLab app:

    npm run build
    jupyter lab build

    To run tests suite:

    npm test

    Adding support for additional languages

    Support for new languages should be provided by implementation of abstract LanguageAnalyzer class (in case of languages which support use of semicolons to terminate statements LanguageWithOptionalSemicolons helper class can be utilized).

    Each new language class needs to be included in chooseLanguageAnalyzer function and the developer needs to verify if setLanguageFromMime in fileeditor.ts will be able to recognize the language properly.

    Symlink workaround (jump to any file outside of the project root)

    JupyterLab attempts to protect users from accessing system files by restricting the accessible files to those within the directory it was started in (so called project root). If you wish to jump to files outside of the project root, you cold use a symlink workaround as follows:

    1. create .jupyter_symlinks in the top directory of your JupyterLab project, and
    2. symlink your home, usr, or any other location which includes the files that you wish to make possible to open in there. The Linux following commands demonstrate the idea:
    mkdir .jupyter_symlinks
    cd .jupyter_symlinks
    ln -s /home home
    ln -s /usr usr

    Which directories to symlink?

    To find out which paths you need to symlink for Python you could run python3 -v which will list where are the specific built-in modules imported from. Look out for lines like these:

    # /srv/conda/envs/notebook/lib/python3.7/__pycache__/_collections_abc.cpython-37.pyc matches /srv/conda/envs/notebook/lib/python3.7/_collections_abc.py 
    # code object from '/srv/conda/envs/notebook/lib/python3.7/__pycache__/_collections_abc.cpython-37.pyc' 
    import '_collections_abc' # <_frozen_importlib_external.SourceFileLoader object at 0x7f77ba22c400> 

    which mean that you want /srv/conda/envs/notebook/lib/python3.7/ to be symlinked to access _collections_abc. You can do this by:

    # still in .jupyter_symlinks 
    mkdir -p srv/conda/envs/notebook/lib
    # note: no slash (/) at the begining of the second path 
    ln -s /srv/conda/envs/notebook/lib/python3.7 srv/conda/envs/notebook/lib/python3.7

    Please note that not every Python built-in module has a corresponding Python file, as many are written in C for performance reasons.

    Install

    npm i @krassowski/jupyterlab_go_to_definition

    DownloadsWeekly Downloads

    946

    Version

    1.0.0

    License

    BSD-3-Clause

    Unpacked Size

    256 kB

    Total Files

    86

    Last publish

    Collaborators

    • avatar