read

Reading a notebook, and initial bootstrapping for notebook exporting

Helpers


create_output

 create_output (txt, mime)

Add a cell output containing txt of the mime text MIME sub-type


show_src

 show_src (src, lang='python')
show_src("print(create_output('text', 'text/plain'))")
print(create_output('text', 'text/plain'))

Config

nbdev allows per-user and per-repo settings files in the ConfigParser format, conveniently read and written using fastcore’s Config class. Settings are searched in the following order:

  • Default settings: see nbdev_create_config for a full reference of possible settings and their defaults
  • Repo settings: settings.ini file in the root of each project
  • User settings: settings.ini file following the XDG base directory specification, by default: ~/.config/nbdev/settings.ini

nbdev_create_config

 nbdev_create_config (user:str, author:str, author_email:str,
                      description:str, path:str='.',
                      cfg_name:str='settings.ini', lib_name:str=None,
                      branch='master',
                      git_url='https://github.com/%(user)s/%(lib_name)s',
                      custom_sidebar:<functionbool_arg>=False,
                      nbs_path='.', lib_path='%(lib_name)s',
                      doc_path='_docs', tst_flags='', version='0.0.1',
                      doc_host='https://%(user)s.github.io',
                      doc_baseurl='/%(lib_name)s',
                      keywords='nbdevjupyternotebookpython',
                      license='apache2', copyright:str=None, status='3',
                      min_python='3.7', audience='Developers',
                      language='English',
                      recursive:<functionbool_arg>=False,
                      black_formatting:<functionbool_arg>=False,
                      readme_nb='index.ipynb', title='%(lib_name)s',
                      allowed_metadata_keys='',
                      allowed_cell_metadata_keys='', jupyter_hooks=True,
                      clean_ids=True)

Create a config file

Type Default Details
user str Repo username
author str Package author’s name
author_email str Package author’s email address
description str Short summary of the package
path str . Path to create config file
cfg_name str settings.ini Name of config file to create
lib_name str None Package name, defaults to local repo folder name passed to apply_defaults
branch str master Repo default branch passed to apply_defaults
git_url str https://github.com/%(user)s/%(lib_name)s Repo URL passed to apply_defaults
custom_sidebar bool_arg False Create custom sidebar? passed to apply_defaults
nbs_path str . Path to notebooks passed to apply_defaults
lib_path str %(lib_name)s Path to package root passed to apply_defaults
doc_path str _docs Path to rendered docs passed to apply_defaults
tst_flags str Test flags passed to apply_defaults
version str 0.0.1 Version of this release passed to apply_defaults
doc_host str https://%(user)s.github.io Hostname for docs passed to apply_defaults
doc_baseurl str /%(lib_name)s Base URL for docs passed to apply_defaults
keywords str nbdev jupyter notebook python Package keywords passed to apply_defaults
license str apache2 License for the package passed to apply_defaults
copyright str None Copyright for the package, defaults to ‘current_year onwards, author’ passed to apply_defaults
status str 3 Development status PyPI classifier passed to apply_defaults
min_python str 3.7 Minimum Python version PyPI classifier passed to apply_defaults
audience str Developers Intended audience PyPI classifier passed to apply_defaults
language str English Language PyPI classifier passed to apply_defaults
recursive bool_arg False Include subfolders in notebook globs? passed to apply_defaults
black_formatting bool_arg False Format libraries with black? passed to apply_defaults
readme_nb str index.ipynb Notebook to export as repo readme passed to apply_defaults
title str %(lib_name)s Quarto website title passed to apply_defaults
allowed_metadata_keys str Preserve the list of keys in the main notebook metadata passed to apply_defaults
allowed_cell_metadata_keys str Preserve the list of keys in cell level metadata passed to apply_defaults
jupyter_hooks bool True Run Jupyter hooks? passed to apply_defaults
clean_ids bool True Remove ids from plaintext reprs? passed to apply_defaults

This is a wrapper for fastcore’s save_config_file with nbdev’s required settings. It is also installed as a CLI command. The table above also serves as a full reference of nbdev’s settings (excluding the path and cfg_name parameters which decide where the config file is saved). For more about PyPI classifiers, see Classifiers.

test_eq(_nbdev_config_file(), Path.cwd().parent/'settings.ini')

get_config

 get_config (cfg_name='settings.ini', path=None)

Config for ini file found in path (defaults to cwd)

get_config searches for repo settings.ini in the current directory, and then in all parent directories, stopping when it is found. Default values for optional settings are applied to the resulting Config, see nbdev_create_config for a full reference of nbdev’s settings.

cfg_name = 'test_settings.ini'
nbdev_create_config('fastai','author','[email protected]','description','..',cfg_name)
cfg = get_config(cfg_name)
test_eq(cfg.lib_name, 'nbdev')
test_eq(cfg.git_url, 'https://github.com/fastai/nbdev')
cwd = Path.cwd()
test_eq(cfg.config_path, cwd.parent.absolute())
test_eq(cfg.path('lib_path'), cwd.parent/'nbdev')
test_eq(cfg.path('nbs_path'), cwd.parent)
test_eq(cfg.path('doc_path'), cwd.parent/'_docs')
cfg.config_file.unlink()
get_config.cache_clear()

config_key

 config_key (c, default=None, path=True, missing_ok=None)

Look for key c in settings.ini and fail gracefully if not found and no default provided

Exporting a basic module


add_init

 add_init (path)

Add __init__.py in all subdirs of path containing python files if it’s not there already

Python modules require a __init.py__ file in all directories that are modules. We assume that all directories containing a python file (including in subdirectories of any depth) is a module, and therefore add a __init__.py to each.

with tempfile.TemporaryDirectory() as d:
    d = Path(d)
    (d/'a/b').mkdir(parents=True)
    (d/'a/b/f.py').touch()
    (d/'a/c').mkdir()
    add_init(d)
    assert not (d/'a/c'/_init).exists(), "Should not add init to dir without py file"
    for e in [d, d/'a', d/'a/b']: assert (e/_init).exists(),f"Missing init in {e}"

write_cells

 write_cells (cells, hdr, file, offset=0)

Write cells to file along with header hdr starting at index offset (mainly for nbdev internal use)


basic_export_nb

 basic_export_nb (fname, name, dest=None)

Basic exporter to bootstrap nbdev

This is a simple exporter with just enough functionality to correctly export this notebook, in order to bootstrap the creation of nbdev itself.