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)#

Bases: Application

Base class for Jupyter applications

aliases: StrDict = {'config': 'JupyterApp.config_file', 'log-level': 'Application.log_level'}#
answer_yes#

Answer yes to any prompts.

config_dir#

A trait for unicode strings.

config_file#

Full path of a config file.

config_file_name#

Specify a config file to load.

property config_file_paths: list[str]#
data_dir#

A trait for unicode strings.

description: str | Unicode[str, str | bytes] = 'A Jupyter Application'#
flags: StrDict = {'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#

Generate default config file.

initialize(argv=None)#

Initialize the application.

Return type:

None

jupyter_path#

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: str | Unicode[str, str | bytes] = '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

class jupyter_core.application.JupyterAsyncApp(**kwargs)#

Bases: JupyterApp

A Jupyter application that runs on an asyncio loop.

description: str | Unicode[str, str | bytes] = 'An Async Jupyter Application'#
async initialize_async(argv=None)#

Initialize the application asynchronoously.

Return type:

None

classmethod launch_instance(argv=None, **kwargs)#

Launch an instance of an async Jupyter Application

Return type:

None

name: str | Unicode[str, str | bytes] = 'jupyter_async'#
async start_async()#

Run the application in an event loop.

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.

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)#

Bases: JupyterApp

A Jupyter Migration App.

description: str | Unicode[str, str | bytes] = '\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: str | Unicode[str, str | bytes] = '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]

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.

Return type:

int

Parameters#

fnameunicode

The path to the file to get mode from

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.

Return type:

bool

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.

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.

Return type:

bool

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.

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.

Return type:

bool

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.

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.

Return type:

bool

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.

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']
:rtype: :sphinx_autodoc_typehints_type:`\:py\:class\:\`list\`\\ \\\[\:py\:class\:\`str\`\]`
>>> jupyter_path('kernels')
['~/.local/jupyter/kernels', '/usr/local/share/jupyter/kernels']
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.

Return type:

Iterator[Any]

Parameters#

fnameunicode

The path to the file to write

binary: boolean

Indicates that the file is binary

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.

Return type:

None

Parameters#

fnameunicode

The path to the file to secure

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]

store the current version info of the jupyter_core.

Module contents#