Skip to main content
`Ctrl`+`K`

# jupyter_core package

## Subpackages

- jupyter_core.utils package
  - Module contents
    - `deprecation()`
    - `ensure_async()`
    - `ensure_dir_exists()`
    - `ensure_event_loop()`
    - `run_sync()`

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

    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:

    `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.

  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_pathstr or Path

    The absolute path to check for hidden directories.

  abs_rootstr or Path

    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.

  Finally, system-wide directories such as /usr/local/etc/jupyter are searched.

  Return type:

    `list`[`str`]

  Changed in version 5.8: On Windows, %PROGRAMDATA% will be used as a system-wide path only if the JUPYTER_USE_PROGRAMDATA env is set. By default, there is no system-wide config path on Windows.

  Examples:

      >>> jupyter_config_path()
      ['~/.jupyter', '~/.local/etc/jupyter', '/usr/local/etc/jupyter', '/etc/jupyter']

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.

  There are four sources of paths to search:

  - $JUPYTER_PATH environment variable (always highest priority)

  - user directories (e.g. ~/.local/share/jupyter)

  - environment directories (e.g. {sys.prefix}/share/jupyter)

  - system-wide paths (e.g. /usr/local/share/jupyter)

  JUPYTER_PATH environment variable has highest priority, if defined, and is purely additive.

  If the JUPYTER_PREFER_ENV_PATH environment variable is set, the environment-level directories will have priority over user-level directories. You can also set JUPYTER_PREFER_ENV_PATH=0 to explicitly prefer user directories. If Jupyter detects that you are in a virtualenv or conda environment, environment paths are also preferred to user paths, otherwise user paths are preferred to environment paths.

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

  Finally, system-wide directories, such as /usr/local/share/jupyter are searched.

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

  Changed in version 5.8: On Windows, %PROGRAMDATA% will be used as a system-wide path only if the JUPYTER_USE_PROGRAMDATA env is set. By default, there is no default system-wide path on Windows and the env path is used instead.

  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.

  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.

  The default is False.

  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:

    `str` | `None`

store the current version info of the jupyter_core.

## Module contents