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.

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

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("test.Add"), 'test.ipynb')
test_eq(source_nb("Add"), 'ToImport.ipynb')
test_eq(source_nb("Operator"), 'test.ipynb')
test_eq(source_nb("MulDiv"), 'test.ipynb')
assert source_nb(int) is None

---------------------------------------------------------------------------
AssertionError                            Traceback (most recent call last)
<ipython-input-10-e5991e20c770> in <module>
----> 1 test_eq(source_nb("test.Add"), 'test.ipynb')
      2 test_eq(source_nb("Add"), 'ToImport.ipynb')
      3 test_eq(source_nb("Operator"), 'test.ipynb')
      4 test_eq(source_nb("MulDiv"), 'test.ipynb')
      5 assert source_nb(int) is None

~/Code/classes/jlab_3.8/lib/python3.8/site-packages/fastcore/test.py in test_eq(a, b)
     33 def test_eq(a,b):
     34     "`test` that `a==b`"
---> 35     test(a,b,equals, '==')
     36 
     37 # Cell

~/Code/classes/jlab_3.8/lib/python3.8/site-packages/fastcore/test.py in test(a, b, cmp, cname)
     23     "`assert` that `cmp(a,b)`; display inputs and `cname or cmp.__name__` if it fails"
     24     if cname is None: cname=cmp.__name__
---> 25     assert cmp(a,b),f"{cname}:\n{a}\n{b}"
     26 
     27 # Cell

AssertionError: ==:
None
test.ipynb

Reading the library

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

nbdev_update_lib[source]

nbdev_update_lib(fname:"A python filename or glob to convert"=None, silent:"Don't print results"=False)

Propagates any change in the modules matching fname to the notebooks that created them

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 & trust notebooks

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.

nbdev_diff_nbs[source]

nbdev_diff_nbs()

Prints the diff between an export of the library in notebooks and the actual modules

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

nbdev_diff_nbs()

nbdev_trust_nbs[source]

nbdev_trust_nbs(fname:"A notebook name or glob to convert"=None, force_all:"Trust even notebooks that haven't changed"=False)

Trust notebooks matching fname

nbdev_trust_nbs()