nbdev is getting a little %magic

• Overview
• How do I start using magic flags?
  • Can I use both comment and magic flags?
  • Why can't I see any "test" flags?
  • Can I use flags in any kind of cell?
  • Do magic flags work differently to comment flags?
• How do comment flags correspond to magic flags?
• Why might we add magic flags for _all_ and show_doc?
  • %nbev_add2__all__
  • %nbev_show_doc
  • class ArithmeticError[source]
    • ArithmeticError.mro[source]
    • ArithmeticError.__init__[source]
  • class ArithmeticError[source]
    • ArithmeticError.mro[source]
    • ArithmeticError.__init__[source]

Overview

nbdev is progressively getting magic commands that will eventually replace the special comments it currently uses, so you get autocomplete and documentation:

You'll also get feedback when flags are used incorrectly:

How do I start using magic flags?

Grab an editable install of nbdev then run nbdev_upgrade from the command line - this will update notebooks that use comment flags like:

#export special.module

to use magic flags:

%nbdev_export special.module

To make magic flags work, nbdev_upgrade might need to add a new code cell to the top of the notebook:

from nbdev import *

You can run nbdev_upgrade any number of times - which means you can update the same project every time new magic flags get added to nbdev.

Can I use both comment and magic flags?

Both comment and magic flags are currently supported and you can use both kinds in the same notebook.

Why can't I see any "test" flags?

If you don't see the test flags you need ...

... you'll probably need to update settings.ini then restart your notebook.

Test flags are configured in your settings.ini (set tst_flags, separating flags by a | if you have several of them).

When the nbdev.flags module is imported, test flags are created dynamically from your settings.ini. If tst_flags=slow|gpu, the following flags would be available:

%nbdev_slow_test
%nbdev_gpu_test

Can I use flags in any kind of cell?

Apart from #hide and %nbdev_hide, nbdev will ignore flags that are not in code cells. This means that you can use markdown cells for "developer-only" details and #hide them from the HTML docs.

Do magic flags work differently to comment flags?

Ideally, they would work the same but ... there is a difference when nbdev splits the source of a cell into flags and code;

If no magic flags are found, treat the first comment line as a flag

If magic flags are found, the flags part can contain multiple lines

This could make a difference because nbdev writes just the code part to both your library and HTML docs.

How do comment flags correspond to magic flags?

Comment flag	Magic flag
default_exp	nbdev_default_export	Define the name of the module everything should be exported in
exports	nbdev_export_and_show	Export and show code in the docs
exporti	nbdev_export_internal	Export but don’t show in docs and don’t add to __all__
export	nbdev_export	Export but don’t show in docs
hide_input	nbdev_hide_input	Do not show input of a test cell in docs
hide_output	nbdev_hide_output	Do not show output of a test cell in docs
hide	nbdev_hide	Do not show a test cell or markdown in docs
default_cls_lvl	nbdev_default_class_level	Define the default toc level of classes
collapse_output or collapse-output	nbdev_collapse_output	Inlcude output in the docs under a collapsable element
collapse_show or collapse-show	nbdev_collapse_input open	Inlcude intput in the docs under a collapsable element that is open by default
collapse_hide or collapse-hide	nbdev_collapse_input	Inlcude intput in the docs under a collapsable element
collapse	nbdev_collapse_input	Inlcude intput in the docs under a collapsable element

Why might we add magic flags for _all_ and show_doc?

One of the reasons for suggesting this is so that everything can be done via magic flags - rather than using flags for everything except _all_ and show_doc.

%nbev_add2__all__

here's what we do today

_all_ = ['progress_bar','master_bar']

but we could ...

%nbev_add2__all__ progress_bar,master_bar

This flag could

• check that everything exists and names are valid (when the cell is executed) and
• make it possible to tab-complete the items you're adding to __all__

The example above uses a line magic, so you'd have to move everything on line 3 up to line 2 but ... we could use a cell magic

%nbev_show_doc

here's what we do today

# nbdev removes show_doc cells, so we need to use a alias 
show__doc = show_doc

show__doc(ArithmeticError)

class ArithmeticError[source]

ArithmeticError() :: Exception

Base class for arithmetic errors.

show__doc(ArithmeticError.mro)

ArithmeticError.mro[source]

ArithmeticError.mro()

Return a type's method resolution order.

show__doc(ArithmeticError.__init__)

ArithmeticError.__init__[source]

ArithmeticError.__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

but we could ...

%nbev_show_doc ArithmeticError mro __init__

class ArithmeticError[source]

ArithmeticError() :: Exception

Base class for arithmetic errors.

ArithmeticError.mro[source]

ArithmeticError.mro()

Return a type's method resolution order.

ArithmeticError.__init__[source]

ArithmeticError.__init__(*args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

This flag could make it possible to "show doc" a class and any number of its methods with a single line of code.