jupyter_core package

Subpackages

Submodules

A base Application class for Jupyter applications.

All Jupyter applications should inherit from this.

class jupyter_core.application.JupyterApp(**kwargs: Any)

Bases: Application

Base class for Jupyter applications

aliases: t.Dict[str, t.Any] = {'config': 'JupyterApp.config_file', 'log-level': 'Application.log_level'}

the alias map for configurables Keys might strings or tuples for additional options; single-letter alias accessed like -v. Values might be like “Class.trait” strings of two-tuples: (Class.trait, help-text).

answer_yes

A boolean (True, False) trait.

config_dir

A trait for unicode strings.

config_file

A trait for unicode strings.

config_file_name

A trait for unicode strings.

property config_file_paths: list[str]
Return type

list[str]

data_dir

A trait for unicode strings.

description: t.Union[str, Unicode] = 'A Jupyter Application'
flags: t.Dict[str, t.Any] = {'debug': ({'Application': {'log_level': 10}}, 'set log level to logging.DEBUG (maximize logging output)'), 'generate-config': ({'JupyterApp': {'generate_config': True}}, 'generate default config file'), 'show-config': ({'Application': {'show_config': True}}, "Show the application's configuration (human-readable format)"), 'show-config-json': ({'Application': {'show_config_json': True}}, "Show the application's configuration (json format)"), 'y': ({'JupyterApp': {'answer_yes': True}}, 'Answer yes to any questions instead of prompting.')}
generate_config

A boolean (True, False) trait.

initialize(argv=None)

Initialize the application.

Return type

None

jupyter_path: list[str] | List

An instance of a Python list.

classmethod launch_instance(argv=None, **kwargs)

Launch an instance of a Jupyter Application

Return type

None

load_config_file(suppress_errors=True)

Load the config file.

By default, errors in loading config are handled, and a warning printed on screen. For testing, the suppress_errors option is set to False, so errors will make tests fail.

Return type

None

migrate_config()

Migrate config/data from IPython 3

Return type

None

name: t.Union[str, Unicode] = 'jupyter'
runtime_dir

A trait for unicode strings.

start()

Start the whole thing

Return type

None

subcommand

A trait for unicode strings.

write_default_config()

Write our default config to a .py config file

Return type

None

exception jupyter_core.application.NoStart

Bases: Exception

Exception to raise when an application shouldn’t start

The root jupyter command.

This does nothing other than dispatch to subcommands or output path info.

class jupyter_core.command.JupyterParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Bases: ArgumentParser

A Jupyter argument parser.

argcomplete()

Trigger auto-completion, if enabled

Return type

None

property epilog: str | None

Add subcommands to epilog on request

Avoids searching PATH for subcommands unless help output is requested.

Return type

UnionType[str, None]

jupyter_core.command.jupyter_parser()

Create a jupyter parser object.

Return type

JupyterParser

jupyter_core.command.list_subcommands()

List all jupyter subcommands

searches PATH for jupyter-name

Returns a list of jupyter’s subcommand names, without the jupyter- prefix. Nested children (e.g. jupyter-sub-subsub) are not included.

Return type

list[str]

jupyter_core.command.main()

The command entry point.

Return type

None

Migrating IPython < 4.0 to Jupyter

This copies configuration and resources to their new locations in Jupyter

Migrations:

  • .ipython/ - nbextensions -> JUPYTER_DATA_DIR/nbextensions - kernels -> JUPYTER_DATA_DIR/kernels

  • .ipython/profile_default/ - static/custom -> .jupyter/custom - nbconfig -> .jupyter/nbconfig - security/

    • notebook_secret, notebook_cookie_secret, nbsignatures.db -> JUPYTER_DATA_DIR

    • ipython_{notebook,nbconvert,qtconsole}_config.py -> .jupyter/jupyter_{name}_config.py

class jupyter_core.migrate.JupyterMigrate(**kwargs: Any)

Bases: JupyterApp

A Jupyter Migration App.

description: t.Union[str, Unicode] = '\n    Migrate configuration and data from .ipython prior to 4.0 to Jupyter locations.\n\n    This migrates:\n\n    - config files in the default profile\n    - kernels in ~/.ipython/kernels\n    - notebook javascript extensions in ~/.ipython/extensions\n    - custom.js/css to .jupyter/custom\n\n    to their new Jupyter locations.\n\n    All files are copied, not moved.\n    If the destinations already exist, nothing will be done.\n    '
name: t.Union[str, Unicode] = 'jupyter-migrate'
start()

Start the application.

Return type

None

jupyter_core.migrate.get_ipython_dir()

Return the IPython directory location.

Not imported from IPython because the IPython implementation ensures that a writable directory exists, creating a temporary directory if not. We don’t want to trigger that when checking if migration should happen.

We only need to support the IPython < 4 behavior for migration, so importing for forward-compatibility and edge cases is not important.

Return type

str

jupyter_core.migrate.migrate()

Migrate IPython configuration to Jupyter

Return type

bool

jupyter_core.migrate.migrate_config(name, env)

Migrate a config file.

Includes substitutions for updated configurable names.

Return type

list[Any]

jupyter_core.migrate.migrate_dir(src, dst)

Migrate a directory from src to dst

Return type

bool

jupyter_core.migrate.migrate_file(src, dst, substitutions=None)

Migrate a single file from src to dst

substitutions is an optional dict of {regex: replacement} for performing replacements on the file.

Return type

bool

jupyter_core.migrate.migrate_one(src, dst)

Migrate one item

dispatches to migrate_dir/_file

Return type

bool

jupyter_core.migrate.migrate_static_custom(src, dst)

Migrate non-empty custom.js,css from src to dst

src, dst are ‘custom’ directories containing custom.{js,css}

Return type

bool

Path utility functions.

jupyter_core.paths.envset(name, default=False)

Return the boolean value of a given environment variable.

An environment variable is considered set if it is assigned to a value other than ‘no’, ‘n’, ‘false’, ‘off’, ‘0’, or ‘0.0’ (case insensitive)

If the environment variable is not defined, the default value is returned.

Return type

Optional[bool, None]

jupyter_core.paths.exists(path)

Replacement for os.path.exists which works for host mapped volumes on Windows containers

Return type

bool

jupyter_core.paths.get_file_mode(fname)

Retrieves the file mode corresponding to fname in a filesystem-tolerant manner.

Parameters

fnameunicode

The path to the file to get mode from

rtype

int

jupyter_core.paths.get_home_dir()

Get the real path of the home directory

Return type

str

jupyter_core.paths.is_file_hidden(abs_path, stat_res=None)

Is a file hidden?

This only checks the file itself; it should be called in combination with checking the directory containing the file.

Use is_hidden() instead to check the file and its parent directories.

Parameters

abs_pathunicode

The absolute path to check.

stat_resos.stat_result, optional

The result of calling stat() on abs_path. If not passed, this function will call stat() internally.

rtype

bool

jupyter_core.paths.is_file_hidden_posix(abs_path, stat_res=None)

Is a file hidden?

This only checks the file itself; it should be called in combination with checking the directory containing the file.

Use is_hidden() instead to check the file and its parent directories.

Parameters

abs_pathunicode

The absolute path to check.

stat_resos.stat_result, optional

The result of calling stat() on abs_path. If not passed, this function will call stat() internally.

rtype

bool

jupyter_core.paths.is_file_hidden_win(abs_path, stat_res=None)

Is a file hidden?

This only checks the file itself; it should be called in combination with checking the directory containing the file.

Use is_hidden() instead to check the file and its parent directories.

Parameters

abs_pathunicode

The absolute path to check.

stat_resos.stat_result, optional

The result of calling stat() on abs_path. If not passed, this function will call stat() internally.

rtype

bool

jupyter_core.paths.is_hidden(abs_path, abs_root='')

Is a file hidden or contained in a hidden directory?

This will start with the rightmost path element and work backwards to the given root to see if a path is hidden or in a hidden directory. Hidden is determined by either name starting with ‘.’ or the UF_HIDDEN flag as reported by stat.

If abs_path is the same directory as abs_root, it will be visible even if that is a hidden folder. This only checks the visibility of files and directories within abs_root.

Parameters

abs_pathunicode

The absolute path to check for hidden directories.

abs_rootunicode

The absolute path of the root directory in which hidden directories should be checked for.

rtype

bool

jupyter_core.paths.issue_insecure_write_warning()

Issue an insecure write warning.

Return type

None

jupyter_core.paths.jupyter_config_dir()

Get the Jupyter config directory for this platform and user.

Returns JUPYTER_CONFIG_DIR if defined, otherwise the appropriate directory for the platform.

Return type

str

jupyter_core.paths.jupyter_config_path()

Return the search path for Jupyter config files as a list.

If the JUPYTER_PREFER_ENV_PATH environment variable is set, the environment-level directories will have priority over user-level directories.

If the Python site.ENABLE_USER_SITE variable is True, we also add the appropriate Python user site subdirectory to the user-level directories.

Return type

List[str]

jupyter_core.paths.jupyter_data_dir()

Get the config directory for Jupyter data files for this platform and user.

These are non-transient, non-configuration files.

Returns JUPYTER_DATA_DIR if defined, else a platform-appropriate path.

Return type

str

jupyter_core.paths.jupyter_path(*subdirs)

Return a list of directories to search for data files

JUPYTER_PATH environment variable has highest priority.

If the JUPYTER_PREFER_ENV_PATH environment variable is set, the environment-level directories will have priority over user-level directories.

If the Python site.ENABLE_USER_SITE variable is True, we also add the appropriate Python user site subdirectory to the user-level directories.

If *subdirs are given, that subdirectory will be added to each element.

Examples:

>>> jupyter_path()
['~/.local/jupyter', '/usr/local/share/jupyter']
>>> jupyter_path('kernels')
['~/.local/jupyter/kernels', '/usr/local/share/jupyter/kernels']
Return type

List[str]

jupyter_core.paths.jupyter_runtime_dir()

Return the runtime dir for transient jupyter files.

Returns JUPYTER_RUNTIME_DIR if defined.

The default is now (data_dir)/runtime on all platforms; we no longer use XDG_RUNTIME_DIR after various problems.

Return type

str

jupyter_core.paths.prefer_environment_over_user()

Determine if environment-level paths should take precedence over user-level paths.

Return type

bool

jupyter_core.paths.secure_write(fname, binary=False)

Opens a file in the most restricted pattern available for writing content. This limits the file mode to 0o0600 and yields the resulting opened filed handle.

Parameters

fnameunicode

The path to the file to write

binary: boolean

Indicates that the file is binary

rtype

Iterator[Any]

jupyter_core.paths.use_platform_dirs()

Determine if platformdirs should be used for system-specific paths.

We plan for this to default to False in jupyter_core version 5 and to True in jupyter_core version 6.

Return type

bool

jupyter_core.paths.win32_restrict_file_to_user(fname)

Secure a windows file to read-only access for the user. Follows guidance from win32 library creator: http://timgolden.me.uk/python/win32_how_do_i/add-security-to-a-file.html

This method should be executed against an already generated file which has no secrets written to it yet.

Parameters

fnameunicode

The path to the file to secure

rtype

None

display environment information that is frequently used to troubleshoot installations of Jupyter or IPython

jupyter_core.troubleshoot.get_data()

returns a dict of various user environment data

Return type

Dict[str, Any]

jupyter_core.troubleshoot.main()

print out useful info

Return type

None

jupyter_core.troubleshoot.subs(cmd)

get data from commands that we need to run outside of python

Return type

Optional[str, None]

store the current version info of the jupyter_core.

Module contents