jupyter_server.services.contents package#

Submodules#

Classes for managing Checkpoints.

class jupyter_server.services.contents.checkpoints.AsyncCheckpoints(**kwargs)#

Bases: Checkpoints

Base class for managing checkpoints for a ContentsManager asynchronously.

async create_checkpoint(contents_mgr, path)#: Create a checkpoint.

async delete_all_checkpoints(path)#: Delete all checkpoints for the given path.

async delete_checkpoint(checkpoint_id, path)#: delete a checkpoint for a file

async list_checkpoints(path)#: Return a list of checkpoints for a given file

async rename_all_checkpoints(old_path, new_path)#: Rename all checkpoints for old_path to new_path.

async rename_checkpoint(checkpoint_id, old_path, new_path)#: Rename a single checkpoint from old_path to new_path.

async restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint

class jupyter_server.services.contents.checkpoints.AsyncGenericCheckpointsMixin#

Bases: GenericCheckpointsMixin

Helper for creating Asynchronous Checkpoints subclasses that can be used with any ContentsManager.

async create_checkpoint(contents_mgr, path)#

async create_file_checkpoint(content, format, path)#

Create a checkpoint of the current state of a file

Returns a checkpoint model for the new checkpoint.

async create_notebook_checkpoint(nb, path)#

Create a checkpoint of the current state of a file

Returns a checkpoint model for the new checkpoint.

async get_file_checkpoint(checkpoint_id, path)#

Get the content of a checkpoint for a non-notebook file.

Returns a dict of the form:

{
    'type': 'file',
    'content': <str>,
    'format': {'text','base64'},
}

async get_notebook_checkpoint(checkpoint_id, path)#

Get the content of a checkpoint for a notebook.

Returns a dict of the form:

{
    'type': 'notebook',
    'content': <output of nbformat.read>,
}

async restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint.

class jupyter_server.services.contents.checkpoints.Checkpoints(**kwargs)#

Bases: LoggingConfigurable

Base class for managing checkpoints for a ContentsManager.

Subclasses are required to implement:

create_checkpoint(self, contents_mgr, path) restore_checkpoint(self, contents_mgr, checkpoint_id, path) rename_checkpoint(self, checkpoint_id, old_path, new_path) delete_checkpoint(self, checkpoint_id, path) list_checkpoints(self, path)

create_checkpoint(contents_mgr, path)#: Create a checkpoint.

delete_all_checkpoints(path)#: Delete all checkpoints for the given path.

delete_checkpoint(checkpoint_id, path)#: delete a checkpoint for a file

list_checkpoints(path)#: Return a list of checkpoints for a given file

rename_all_checkpoints(old_path, new_path)#: Rename all checkpoints for old_path to new_path.

rename_checkpoint(checkpoint_id, old_path, new_path)#: Rename a single checkpoint from old_path to new_path.

restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint

class jupyter_server.services.contents.checkpoints.GenericCheckpointsMixin#

Bases: object

Helper for creating Checkpoints subclasses that can be used with any ContentsManager.

Provides a ContentsManager-agnostic implementation of create_checkpoint and restore_checkpoint in terms of the following operations:

create_file_checkpoint(self, content, format, path)
create_notebook_checkpoint(self, nb, path)
get_file_checkpoint(self, checkpoint_id, path)
get_notebook_checkpoint(self, checkpoint_id, path)

To create a generic CheckpointManager, add this mixin to a class that implement the above four methods plus the remaining Checkpoints API methods:

delete_checkpoint(self, checkpoint_id, path)
list_checkpoints(self, path)
rename_checkpoint(self, checkpoint_id, old_path, new_path)

create_checkpoint(contents_mgr, path)#

create_file_checkpoint(content, format, path)#

Create a checkpoint of the current state of a file

Returns a checkpoint model for the new checkpoint.

create_notebook_checkpoint(nb, path)#

Create a checkpoint of the current state of a file

Returns a checkpoint model for the new checkpoint.

get_file_checkpoint(checkpoint_id, path)#

Get the content of a checkpoint for a non-notebook file.

Returns a dict of the form:

{
    'type': 'file',
    'content': <str>,
    'format': {'text','base64'},
}

get_notebook_checkpoint(checkpoint_id, path)#

Get the content of a checkpoint for a notebook.

Returns a dict of the form:

{
    'type': 'notebook',
    'content': <output of nbformat.read>,
}

restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint.

File-based Checkpoints implementations.

class jupyter_server.services.contents.filecheckpoints.AsyncFileCheckpoints(**kwargs)#

Bases: FileCheckpoints, AsyncFileManagerMixin, AsyncCheckpoints

async checkpoint_model(checkpoint_id, os_path)#: construct the info dict for a given checkpoint

async create_checkpoint(contents_mgr, path)#: Create a checkpoint.

async delete_checkpoint(checkpoint_id, path)#: delete a file’s checkpoint

async list_checkpoints(path)#

list the checkpoints for a given file

This contents manager currently only supports one checkpoint per file.

async rename_checkpoint(checkpoint_id, old_path, new_path)#: Rename a checkpoint from old_path to new_path.

async restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint.

class jupyter_server.services.contents.filecheckpoints.AsyncGenericFileCheckpoints(**kwargs)#

Bases: AsyncGenericCheckpointsMixin, AsyncFileCheckpoints

Asynchronous Local filesystem Checkpoints that works with any conforming ContentsManager.

async create_file_checkpoint(content, format, path)#: Create a checkpoint from the current content of a file.

async create_notebook_checkpoint(nb, path)#: Create a checkpoint from the current content of a notebook.

async get_file_checkpoint(checkpoint_id, path)#: Get a checkpoint for a file.

async get_notebook_checkpoint(checkpoint_id, path)#: Get a checkpoint for a notebook.

class jupyter_server.services.contents.filecheckpoints.FileCheckpoints(**kwargs)#

Bases: FileManagerMixin, Checkpoints

A Checkpoints that caches checkpoints for files in adjacent directories.

Only works with FileContentsManager. Use GenericFileCheckpoints if you want file-based checkpoints with another ContentsManager.

checkpoint_dir#

The directory name in which to keep file checkpoints

This is a path relative to the file’s own directory.

By default, it is .ipynb_checkpoints

checkpoint_model(checkpoint_id, os_path)#: construct the info dict for a given checkpoint

checkpoint_path(checkpoint_id, path)#: find the path to a checkpoint

create_checkpoint(contents_mgr, path)#: Create a checkpoint.

delete_checkpoint(checkpoint_id, path)#: delete a file’s checkpoint

list_checkpoints(path)#

list the checkpoints for a given file

This contents manager currently only supports one checkpoint per file.

no_such_checkpoint(path, checkpoint_id)#

rename_checkpoint(checkpoint_id, old_path, new_path)#: Rename a checkpoint from old_path to new_path.

restore_checkpoint(contents_mgr, checkpoint_id, path)#: Restore a checkpoint.

root_dir#: A trait for unicode strings.

class jupyter_server.services.contents.filecheckpoints.GenericFileCheckpoints(**kwargs)#

Bases: GenericCheckpointsMixin, FileCheckpoints

Local filesystem Checkpoints that works with any conforming ContentsManager.

create_file_checkpoint(content, format, path)#: Create a checkpoint from the current content of a file.

create_notebook_checkpoint(nb, path)#: Create a checkpoint from the current content of a notebook.

get_file_checkpoint(checkpoint_id, path)#: Get a checkpoint for a file.

get_notebook_checkpoint(checkpoint_id, path)#: Get a checkpoint for a notebook.

Utilities for file-based Contents/Checkpoints managers.

class jupyter_server.services.contents.fileio.AsyncFileManagerMixin(**kwargs)#

Bases: FileManagerMixin

Mixin for ContentsAPI classes that interact with the filesystem asynchronously.

class jupyter_server.services.contents.fileio.FileManagerMixin(**kwargs)#

Bases: LoggingConfigurable, Configurable

Mixin for ContentsAPI classes that interact with the filesystem.

Provides facilities for reading, writing, and copying files.

Shared by FileContentsManager and FileCheckpoints.

Note

Classes using this mixin must provide the following attributes:

root_dirunicode: A directory against against which API-style paths are to be resolved.

log : logging.Logger

atomic_writing(os_path, *args, **kwargs)#: wrapper around atomic_writing that turns permission errors to 403. Depending on flag ‘use_atomic_writing’, the wrapper perform an actual atomic writing or simply writes the file (whatever an old exists or not)

hash_algorithm#: Hash algorithm to use for file content, support by hashlib

open(os_path, *args, **kwargs)#: wrapper around io.open that turns permission errors into 403

perm_to_403(os_path='')#: context manager for turning permission errors into 403.

use_atomic_writing#: By default notebooks are saved on disk on a temporary file and then if succefully written, it replaces the old ones. This procedure, namely ‘atomic_writing’, causes some bugs on file system without operation order enforcement (like some networked fs). If set to False, the new notebook is written directly on the old one which could fail (eg: full filesystem or quota )

async jupyter_server.services.contents.fileio.async_copy2_safe(src, dst, log=None)#

copy src to dst asynchronously

like shutil.copy2, but log errors in copystat instead of raising

async jupyter_server.services.contents.fileio.async_replace_file(src, dst)#: replace dst with src asynchronously

jupyter_server.services.contents.fileio.atomic_writing(path, text=True, encoding='utf-8', log=None, **kwargs)#

Context manager to write to a file only if the entire write is successful.

This works by copying the previous file contents to a temporary file in the same directory, and renaming that file back to the target if the context exits with an error. If the context is successful, the new data is synced to disk and the temporary file is removed.

Parameters:

path (str) – The target file to write to.
text (bool, optional) – Whether to open the file in text mode (i.e. to write unicode). Default is True.
encoding (str, optional) – The encoding to use for files opened in text mode. Default is UTF-8.
**kwargs – Passed to io.open().

jupyter_server.services.contents.fileio.copy2_safe(src, dst, log=None)#

copy src to dst

like shutil.copy2, but log errors in copystat instead of raising

jupyter_server.services.contents.fileio.path_to_intermediate(path)#

Name of the intermediate file used in atomic writes.

The .~ prefix will make Dropbox ignore the temporary file.

jupyter_server.services.contents.fileio.path_to_invalid(path)#: Name of invalid file after a failed atomic write and subsequent read.

jupyter_server.services.contents.fileio.replace_file(src, dst)#: replace dst with src

A contents manager that uses the local file system for storage.

class jupyter_server.services.contents.filemanager.AsyncFileContentsManager(**kwargs)#

Bases: FileContentsManager, AsyncFileManagerMixin, AsyncContentsManager

An async file contents manager.

async check_folder_size(path)#

limit the size of folders being copied to be no more than the trait max_copy_folder_size_mb to prevent a timeout error

Return type:: None

async copy(from_path, to_path=None)#: Copy an existing file or directory and return its new model. If to_path not specified, it will be the parent directory of from_path. If copying a file and to_path is a directory, filename/directoryname will increment from_path-Copy#.ext. Considering multi-part extensions, the Copy# part will be placed before the first dot for all the extensions except ipynb. For easier manual searching in case of notebooks, the Copy# part will be placed before the last dot. from_path must be a full path to a file or directory.

async delete_file(path)#: Delete file at path.

async dir_exists(path)#: Does a directory exist at the given path

async file_exists(path)#: Does a file exist at the given path

async get(path, content=True, type=None, format=None, require_hash=False)#

Takes a path for an entity and returns its model

Parameters:

path (str) – the API path that describes the relative path for the target
content (bool) – Whether to include the contents in the reply
type (str, optional) – The requested type - ‘file’, ‘notebook’, or ‘directory’. Will raise HTTPError 400 if the content doesn’t match.
format (str, optional) – The requested format for file contents. ‘text’ or ‘base64’. Ignored if this returns a notebook or directory model.
require_hash (bool, optional) – Whether to include the hash of the file contents.

Returns:

model – the contents model. If content=True, returns the contents of the file or directory as well.

Return type:

dict

async get_kernel_path(path, model=None)#: Return the initial API path of a kernel associated with a given notebook

async is_hidden(path)#: Is path a hidden directory or file

async rename_file(old_path, new_path)#: Rename a file.

async save(model, path='')#: Save the file model and return the model with no content.

class jupyter_server.services.contents.filemanager.FileContentsManager(**kwargs)#

Bases: FileManagerMixin, ContentsManager

A file contents manager.

always_delete_dir#: If True, deleting a non-empty directory will always be allowed. WARNING this may result in files being permanently removed; e.g. on Windows, if the data size is too big for the trash/recycle bin the directory will be permanently deleted. If False (default), the non-empty directory will be sent to the trash only if safe. And if delete_to_trash is True, the directory won’t be deleted.

check_folder_size(path)#: limit the size of folders being copied to be no more than the trait max_copy_folder_size_mb to prevent a timeout error

copy(from_path, to_path=None)#: Copy an existing file or directory and return its new model. If to_path not specified, it will be the parent directory of from_path. If copying a file and to_path is a directory, filename/directoryname will increment from_path-Copy#.ext. Considering multi-part extensions, the Copy# part will be placed before the first dot for all the extensions except ipynb. For easier manual searching in case of notebooks, the Copy# part will be placed before the last dot. from_path must be a full path to a file or directory.

delete_file(path)#: Delete file at path.

delete_to_trash#: If True (default), deleting files will send them to the platform’s trash/recycle bin, where they can be recovered. If False, deleting files really deletes them.

dir_exists(path)#

Does the API-style path refer to an extant directory?

API-style wrapper for os.path.isdir

Parameters:: path (str) – The path to check. This is an API path (/ separated, relative to root_dir).
Returns:: exists – Whether the path is indeed a directory.
Return type:: bool

exists(path)#

Returns True if the path exists, else returns False.

API-style wrapper for os.path.exists

Parameters:: path (str) – The API path to the file (with ‘/’ as separator)
Returns:: exists – Whether the target exists.
Return type:: bool

file_exists(path)#

Returns True if the file exists, else returns False.

API-style wrapper for os.path.isfile

Parameters:: path (str) – The relative path to the file (with ‘/’ as separator)
Returns:: exists – Whether the file exists.
Return type:: bool

get(path, content=True, type=None, format=None, require_hash=False)#

Takes a path for an entity and returns its model

Parameters:

path (str) – the API path that describes the relative path for the target
content (bool) – Whether to include the contents in the reply
type (str, optional) – The requested type - ‘file’, ‘notebook’, or ‘directory’. Will raise HTTPError 400 if the content doesn’t match.
format (str, optional) – The requested format for file contents. ‘text’ or ‘base64’. Ignored if this returns a notebook or directory model.
require_hash (bool, optional) – Whether to include the hash of the file contents.

Returns:

model – the contents model. If content=True, returns the contents of the file or directory as well.

Return type:

dict

get_kernel_path(path, model=None)#: Return the initial API path of a kernel associated with a given notebook

info_string()#: Get the information string for the manager.

is_hidden(path)#

Does the API style path correspond to a hidden directory or file?

Parameters:: path (str) – The path to check. This is an API path (/ separated, relative to root_dir).
Returns:: hidden – Whether the path exists and is hidden.
Return type:: bool

is_writable(path)#

Does the API style path correspond to a writable directory or file?

Parameters:: path (str) – The path to check. This is an API path (/ separated, relative to root_dir).
Returns:: hidden – Whether the path exists and is writable.
Return type:: bool

max_copy_folder_size_mb#: The max folder size that can be copied

rename_file(old_path, new_path)#: Rename a file.

root_dir#: A trait for unicode strings.

save(model, path='')#: Save the file model and return the model with no content.

Tornado handlers for the contents web service.

Preliminary documentation at ipython/ipython

class jupyter_server.services.contents.handlers.CheckpointsHandler(application, request, **kwargs)#

Bases: ContentsAPIHandler

A checkpoints API handler.

get(path='')#: get lists checkpoints for a file

post(path='')#: post creates a new checkpoint

class jupyter_server.services.contents.handlers.ContentsAPIHandler(application, request, **kwargs)#

Bases: APIHandler

A contents API handler.

auth_resource = 'contents'#

class jupyter_server.services.contents.handlers.ContentsHandler(application, request, **kwargs)#

Bases: ContentsAPIHandler

A contents handler.

delete(path='')#: delete a file in the given path

get(path='')#

Return a model for a file or directory.

A directory model contains a list of models (without content) of the files and directories it contains.

location_url(path)#

Return the full URL location of a file.

Parameters:: path (unicode) – The API path of the file, such as “foo/bar.txt”.

patch(path='')#: PATCH renames a file or directory without re-uploading content.

post(path='')#

Create a new file in the specified path.

POST creates new files. The server always decides on the name.

POST /api/contents/path: New untitled, empty file or directory.
POST /api/contents/path: with body {“copy_from” : “/path/to/OtherNotebook.ipynb”} New copy of OtherNotebook in path

put(path='')#

Saves the file in the location specified by name and path.

PUT is very similar to POST, but the requester specifies the name, whereas with POST, the server picks the name.

PUT /api/contents/path/Name.ipynb: Save notebook at path/Name.ipynb. Notebook structure is specified in content key of JSON request body. If content is not specified, create a new empty notebook.

class jupyter_server.services.contents.handlers.ModifyCheckpointsHandler(application, request, **kwargs)#

Bases: ContentsAPIHandler

A checkpoints modification handler.

delete(path, checkpoint_id)#: delete clears a checkpoint for a given file

post(path, checkpoint_id)#: post restores a file from a checkpoint

class jupyter_server.services.contents.handlers.NotebooksRedirectHandler(application, request, **kwargs)#

Bases: JupyterHandler

Redirect /api/notebooks to /api/contents

SUPPORTED_METHODS = ('GET', 'PUT', 'PATCH', 'POST', 'DELETE')#

delete(path)#: Handle a notebooks redirect.

get(path)#: Handle a notebooks redirect.

patch(path)#: Handle a notebooks redirect.

post(path)#: Handle a notebooks redirect.

put(path)#: Handle a notebooks redirect.

class jupyter_server.services.contents.handlers.TrustNotebooksHandler(application, request, **kwargs)#

Bases: JupyterHandler

Handles trust/signing of notebooks

post(path='')#: Trust a notebook by path.

jupyter_server.services.contents.handlers.validate_model(model, expect_content=False, expect_hash=False)#

Validate a model returned by a ContentsManager method.

If expect_content is True, then we expect non-null entries for ‘content’ and ‘format’.

If expect_hash is True, then we expect non-null entries for ‘hash’ and ‘hash_algorithm’.

class jupyter_server.services.contents.largefilemanager.AsyncLargeFileManager(**kwargs)#

Bases: AsyncFileContentsManager

Handle large file upload asynchronously

async save(model, path='')#: Save the file model and return the model with no content.

class jupyter_server.services.contents.largefilemanager.LargeFileManager(**kwargs)#

Bases: FileContentsManager

Handle large file upload.

save(model, path='')#: Save the file model and return the model with no content.

A base class for contents managers.

class jupyter_server.services.contents.manager.AsyncContentsManager(**kwargs)#

Bases: ContentsManager

Base class for serving files and directories asynchronously.

checkpoints#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

checkpoints_class#: A trait whose value must be a subclass of a specified class.

checkpoints_kwargs#

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

async copy(from_path, to_path=None)#

Copy an existing file and return its new model.

If to_path not specified, it will be the parent directory of from_path. If to_path is a directory, filename will increment from_path-Copy#.ext. Considering multi-part extensions, the Copy# part will be placed before the first dot for all the extensions except ipynb. For easier manual searching in case of notebooks, the Copy# part will be placed before the last dot.

from_path must be a full path to a file.

async create_checkpoint(path)#: Create a checkpoint.

async delete(path)#: Delete a file/directory and any associated checkpoints.

async delete_checkpoint(checkpoint_id, path)#: Delete a checkpoint for a path by id.

async delete_file(path)#: Delete the file or directory at path.

async dir_exists(path)#

Does a directory exist at the given path?

Like os.path.isdir

Override this method in subclasses.

Parameters:: path (str) – The path to check
Returns:: exists – Whether the path does indeed exist.
Return type:: bool

async exists(path)#

Does a file or directory exist at the given path?

Like os.path.exists

Parameters:: path (str) – The API path of a file or directory to check for.
Returns:: exists – Whether the target exists.
Return type:: bool

async file_exists(path='')#

Does a file exist at the given path?

Like os.path.isfile

Override this method in subclasses.

Parameters:: path (str) – The API path of a file to check for.
Returns:: exists – Whether the file exists.
Return type:: bool

async get(path, content=True, type=None, format=None, require_hash=False)#

Get a file or directory model.

Parameters:

require_hash (bool) – Whether the file hash must be returned or not.
2.11* (*Changed in version) –

async increment_filename(filename, path='', insert='')#

Increment a filename until it is unique.

Parameters:

filename (unicode) – The name of a file, including extension
path (unicode) – The API path of the target’s directory
insert (unicode) – The characters to insert after the base filename

Returns:

name – A filename that is unique, based on the input filename.

Return type:

unicode

async is_hidden(path)#

Is path a hidden directory or file?

Parameters:: path (str) – The path to check. This is an API path (/ separated, relative to root dir).
Returns:: hidden – Whether the path is hidden.
Return type:: bool

async list_checkpoints(path)#: List the checkpoints for a path.

async new(model=None, path='')#

Create a new file or directory and return its model with no content.

To create a new untitled entity in a directory, use new_untitled.

async new_untitled(path='', type='', ext='')#

Create a new untitled file or directory in path

path must be a directory

File extension can be specified.

Use new to create files with a fully specified path (including filename).

async rename(old_path, new_path)#: Rename a file and any checkpoints associated with that file.

async rename_file(old_path, new_path)#: Rename a file or directory.

async restore_checkpoint(checkpoint_id, path)#: Restore a checkpoint.

async save(model, path)#

Save a file or directory model to path.

Should return the saved model with no content. Save implementations should call self.run_pre_save_hook(model=model, path=path) prior to writing any data.

async trust_notebook(path)#

Explicitly trust a notebook

Parameters:: path (str) – The path of a notebook

async update(model, path)#

Update the file’s path

For use in PATCH requests, to enable renaming a file without re-uploading its contents. Only used for renaming at the moment.

class jupyter_server.services.contents.manager.ContentsManager(**kwargs)#

Bases: LoggingConfigurable

Base class for serving files and directories.

This serves any text or binary file, as well as directories, with special handling for JSON notebook documents.

Most APIs take a path argument, which is always an API-style unicode path, and always refers to a directory.

unicode, not url-escaped
‘/’-separated
leading and trailing ‘/’ will be stripped
if unspecified, path defaults to ‘’, indicating the root path.

allow_hidden#: Allow access to hidden files

check_and_sign(nb, path='')#

Check for trusted cells, and sign the notebook.

Called as a part of saving notebooks.

Parameters:

nb (dict) – The notebook dict
path (str) – The notebook’s path (for logging)

checkpoints#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

checkpoints_class#: A trait whose value must be a subclass of a specified class.

checkpoints_kwargs#

An instance of a Python dict.

One or more traits can be passed to the constructor to validate the keys and/or values of the dict. If you need more detailed validation, you may use a custom validator method.

Changed in version 5.0: Added key_trait for validating dict keys.

Changed in version 5.0: Deprecated ambiguous trait, traits args in favor of value_trait, per_key_traits.

copy(from_path, to_path=None)#

Copy an existing file and return its new model.

from_path must be a full path to a file.

create_checkpoint(path)#: Create a checkpoint.

delete(path)#: Delete a file/directory and any associated checkpoints.

delete_checkpoint(checkpoint_id, path)#

delete_file(path)#: Delete the file or directory at path.

dir_exists(path)#

Does a directory exist at the given path?

Like os.path.isdir

Override this method in subclasses.

Parameters:: path (str) – The path to check
Returns:: exists – Whether the path does indeed exist.
Return type:: bool

emit(data)#: Emit event using the core event schema from Jupyter Server’s Contents Manager.

event_logger#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

event_schema_id = 'https://events.jupyter.org/jupyter_server/contents_service/v1'#

exists(path)#

Does a file or directory exist at the given path?

Like os.path.exists

Parameters:: path (str) – The API path of a file or directory to check for.
Returns:: exists – Whether the target exists.
Return type:: bool

file_exists(path='')#

Does a file exist at the given path?

Like os.path.isfile

Override this method in subclasses.

Parameters:: path (str) – The API path of a file to check for.
Returns:: exists – Whether the file exists.
Return type:: bool

files_handler_class#

handler class to use when serving raw file requests.

Default is a fallback that talks to the ContentsManager API, which may be inefficient, especially for large files.

Local files-based ContentsManagers can use a StaticFileHandler subclass, which will be much more efficient.

Access to these files should be Authenticated.

files_handler_params#

Extra parameters to pass to files_handler_class.

For example, StaticFileHandlers generally expect a path argument specifying the root directory from which to serve files.

get(path, content=True, type=None, format=None, require_hash=False)#

Get a file or directory model.

Parameters:

require_hash (bool) – Whether the file hash must be returned or not.
2.11* (*Changed in version) –

get_extra_handlers()#

Return additional handlers

Default: self.files_handler_class on /files/.*

get_kernel_path(path, model=None)#

Return the API path for the kernel

KernelManagers can turn this value into a filesystem path, or ignore it altogether.

The default value here will start kernels in the directory of the notebook server. FileContentsManager overrides this to use the directory containing the notebook.

hide_globs#: Glob patterns to hide in file and directory listings.

increment_filename(filename, path='', insert='')#

Increment a filename until it is unique.

Parameters:

filename (unicode) – The name of a file, including extension
path (unicode) – The API path of the target’s directory
insert (unicode) – The characters to insert after the base filename

Returns:

name – A filename that is unique, based on the input filename.

Return type:

unicode

info_string()#: The information string for the manager.

is_hidden(path)#

Is path a hidden directory or file?

Parameters:: path (str) – The path to check. This is an API path (/ separated, relative to root dir).
Returns:: hidden – Whether the path is hidden.
Return type:: bool

list_checkpoints(path)#

log_info()#: Log the information string for the manager.

mark_trusted_cells(nb, path='')#

Mark cells as trusted if the notebook signature matches.

Called as a part of loading notebooks.

Parameters:

nb (dict) – The notebook object (in current nbformat)
path (str) – The notebook’s path (for logging)

new(model=None, path='')#

Create a new file or directory and return its model with no content.

To create a new untitled entity in a directory, use new_untitled.

new_untitled(path='', type='', ext='')#

Create a new untitled file or directory in path

path must be a directory

File extension can be specified.

Use new to create files with a fully specified path (including filename).

notary#

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Subclasses can declare default classes by overriding the klass attribute

post_save_hook#

Python callable or importstring thereof

to be called on the path of a file just saved.

This can be used to process the file on disk, such as converting the notebook to a script or HTML via nbconvert.

It will be called as (all arguments passed by keyword):

hook(os_path=os_path, model=model, contents_manager=instance)

path: the filesystem path to the file just written
model: the model representing the file
contents_manager: this ContentsManager instance

pre_save_hook#

Python callable or importstring thereof

To be called on a contents model prior to save.

This can be used to process the structure, such as removing notebook outputs or other side effects that should not be saved.

It will be called as (all arguments passed by keyword):

hook(path=path, model=model, contents_manager=self)

model: the model to be saved. Includes file contents. Modifying this dict will affect the file that is stored.
path: the API path of the save destination
contents_manager: this ContentsManager instance

preferred_dir#: Preferred starting directory to use for notebooks. This is an API path (/ separated, relative to root dir)

register_post_save_hook(hook)#: Register a post save hook.

register_pre_save_hook(hook)#: Register a pre save hook.

rename(old_path, new_path)#: Rename a file and any checkpoints associated with that file.

rename_file(old_path, new_path)#: Rename a file or directory.

restore_checkpoint(checkpoint_id, path)#: Restore a checkpoint.

root_dir#: A trait for unicode strings.

run_post_save_hook(model, os_path)#: Run the post-save hook if defined, and log errors

run_post_save_hooks(model, os_path)#: Run the post-save hooks if any, and log errors

run_pre_save_hook(model, path, **kwargs)#: Run the pre-save hook if defined, and log errors

run_pre_save_hooks(model, path, **kwargs)#: Run the pre-save hooks if any, and log errors

save(model, path)#

Save a file or directory model to path.

Should return the saved model with no content. Save implementations should call self.run_pre_save_hook(model=model, path=path) prior to writing any data.

should_list(name)#: Should this file/directory name be displayed in a listing?

trust_notebook(path)#

Explicitly trust a notebook

Parameters:: path (str) – The path of a notebook

untitled_directory#: The base name used when creating untitled directories.

untitled_file#: The base name used when creating untitled files.

untitled_notebook#: The base name used when creating untitled notebooks.

update(model, path)#

Update the file’s path

For use in PATCH requests, to enable renaming a file without re-uploading its contents. Only used for renaming at the moment.

validate_notebook_model(model, validation_error=None)#: Add failed-validation message to model

jupyter_server.services.contents package#

Submodules#

Module contents#