The functions that propagates small changes in the library back to notebooks

The library is primarily developed in notebooks so any big changes should be made there. But sometimes, it's easier to fix small bugs or typos in the modules directly. script2notebook is the function that will propagate those changes back to the corresponding notebooks. Note that you can't create new cells with that functionality, so your corrections should remain limited.

Finding the way back to notebooks

We need to get the name of the object we are looking for, and then we'll try to find it in our index file.

get_name[source]

get_name(obj)

Get the name of obj

from nbdev.export import DocsTestClass
test_eq(get_name(in_ipython), 'in_ipython')
test_eq(get_name(DocsTestClass.test), 'test')

qual_name[source]

qual_name(obj)

Get the qualified name of obj

Qualified name is different from name in python for methods and properties:

test_eq(qual_name(DocsTestClass.test), 'DocsTestClass.test')

source_nb[source]

source_nb(func, is_name=None, return_all=False, mod=None)

Return the name of the notebook where func was defined

You can either pass an object or its name (by default is_name will look if func is a string or not to determine if it should be True or False, but you can override if there is some inconsistent behavior).

If passed a method of a class, the function will return the notebook in which the largest part of the function name was defined in case there is a monkey-matching that defines class.method in a different notebook than class. If return_all=True, the function will return a tuple with the name by which the function was found and the notebook.

For properties defined using property or our own add_props helper, we approximate the name by looking at their getter functions, since we don't seem to have access to the property name itself. If everything fails (a getter cannot be found), we return the name of the object that contains the property. This suffices for source_nb to work.

test_eq(source_nb(notebook2script), '00_export.ipynb')
test_eq(source_nb(DocsTestClass), '00_export.ipynb')
test_eq(source_nb(DocsTestClass.test), '00_export.ipynb')
assert source_nb(int) is None

Reading the library

If someone decides to change a module instead of the notebooks, the following functions help update the notebooks accordingly.

relimport2name[source]

relimport2name(name, mod_name)

Unwarps a relative import in name according to mod_name

When we say from

from .submodule import bla

in a module, it needs to be converted to something like

from module.submodule import bla

or

from module1.module2.submodule import bla

depending on where we are. This function deals with those imports renaming.

test_eq(relimport2name('.core', 'nbdev/data.py'), 'nbdev.core')
test_eq(relimport2name('.core', 'home/sgugger/fastai_dev/nbdev/nbdev/data.py'), 'nbdev.core')
test_eq(relimport2name('..core', 'nbdev/vision/data.py'), 'nbdev.core')
test_eq(relimport2name('.transform', 'nbdev/vision/data.py'), 'nbdev.vision.transform')
test_eq(relimport2name('..notebook.core', 'nbdev/data/external.py'), 'nbdev.notebook.core')

script2notebook[source]

script2notebook(fname=None, silent=False)

Update the notebooks from any changes made in the modules corresponding to fname

If fname is not specified, this will convert all modules and submodules in the lib_folder defined in setting.ini. Otherwise fname can be a single filename or a glob expression.

silent makes the command not print any statement.

Diff notebook - library

Before making a commit, you may want to check there is no diff between the exported library and the notebooks. You may also want to make this part of your CI, so that you don't accidentally merge a PR that introduces some changes between the two. This function is there to print this diff.

diff_nb_script[source]

diff_nb_script()

Print the diff between the notebooks and the library in lib_path

diff_nb_script()

If you receive an output, you'll need to either run notebook2script() or script2notebook() to fix the difference.