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. nbdev_update_lib 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.
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.
from nbdev.export import DocsTestClass
test_eq(get_name(in_ipython), 'in_ipython')
test_eq(get_name(DocsTestClass.test), 'test')
Qualified name is different from name in python for methods and properties:
test_eq(qual_name(DocsTestClass.test), 'DocsTestClass.test')
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
If someone decides to change a module instead of the notebooks, the following functions help update the notebooks accordingly.
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')
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.
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.
If you receive an output, you'll need to either run notebook2script() or nbdev_update_lib() to fix the difference.