zim.notebook.notebook.Notebook

class documentation

class Notebook(ConnectorMixin, SignalEmitter): (source)

Class Method	`new_from_dir`	No summary
Method	`__init__`	No summary
Method	`__repr__`	Undocumented
Method	`delete_page`	Delete a page from the notebook
Method	`delete_page_iter`	Like `delete_page()`
Method	`eval_new_page_template`	Undocumented
Method	`get_attachments_dir`
Method	`get_home_page`	Returns a `Page` object for the home page
Method	`get_new_page`	Like get_page() but guarantees the page does not yet exist by adding a number to the name to make it unique.
Method	`get_page`	Get a `Page` object for a given path
Method	`get_page_template_name`	Returns the name of the template to use for a new page. (To get the contents of the template directly, see `get_template()`)
Method	`get_template`	Get a template for the intial text on new pages @param path: a `Path` object @returns: a `ParseTree` object
Method	`move_page`	Move and/or rename a page in the notebook
Method	`move_page_iter`	Like `move_page()` but yields pages that are being updated if `update_links` is `True`
Method	`on_properties_changed`	Undocumented
Method	`relative_filepath`	Get a file path relative to the notebook or page
Method	`resolve_file`	Resolve a file or directory path relative to a page or Notebook
Method	`store_page`	Save the data from the page in the storage backend
Method	`store_page_async`	Undocumented
Method	`suggest_link`	No summary
Method	`trash_page`	Move a page to Trash
Method	`trash_page_iter`	Like `trash_page()`
Method	`wait_for_store_page_async`	Undocumented
Class Variable	`__signals__`	Undocumented
Instance Variable	`cache_dir`	Undocumented
Instance Variable	`config`	Undocumented
Instance Variable	`document_root`	Undocumented
Instance Variable	`folder`	Undocumented
Instance Variable	`icon`	Undocumented
Instance Variable	`index`	Undocumented
Instance Variable	`interwiki`	Undocumented
Instance Variable	`layout`	Undocumented
Instance Variable	`links`	Undocumented
Instance Variable	`name`	Undocumented
Instance Variable	`pages`	Undocumented
Instance Variable	`properties`	Undocumented
Instance Variable	`readonly`	Undocumented
Instance Variable	`state`	Undocumented
Instance Variable	`tags`	Undocumented
Property	`info`	The `NotebookInfo` object for this notebook
Property	`uri`	Returns a file:// uri for this notebook that can be opened by zim
Method	`_delete_page`	Undocumented
Method	`_deleted_page`	Undocumented
Method	`_move_file_and_folder`	Undocumented
Method	`_move_links_in_page`	Undocumented
Method	`_reload_pages_in_cache`	Undocumented
Method	`_remove_links_in_page`	Undocumented
Method	`_resolve_abs_file`	Undocumented
Method	`_store_page_async_finished`	Undocumented
Method	`_store_page_async_thread_main`	Undocumented
Method	`_trash_page`	Undocumented
Method	`_update_link_tag`	Undocumented
Method	`_update_links_in_moved_page`	Undocumented
Method	`_update_links_to_moved_page`	Undocumented
Method	`_update_moved_page`	Undocumented
Instance Variable	`_operation_check`	Undocumented
Instance Variable	`_page_cache`	Undocumented

Inherited from ConnectorMixin:

Method	`connectto`	Connect to signals of another object E.g.:
Method	`connectto_all`	Convenience method to combine multiple calls to `connectto()`.
Method	`disconnect_all`	Disconnect all signals that have been connected with `connectto` and friends. Typically called when you want to destroy this object.
Method	`disconnect_from`	Disc all signals that have been connected with `connectto` and friends to a specific object.
Method	`_disconnect_from`	Undocumented
Instance Variable	`_connected_signals`	Undocumented

Inherited from SignalEmitter:

Method	`__new__`	Undocumented
Method	`block_signals`	Returns a context manager for blocking one or more signals
Method	`connect`	Register a handler for a specific object.
Method	`connect_after`	Like `connect()` but handler will be called after default handler
Method	`disconnect`	Undocumented
Method	`emit`	Undocumented
Method	`emit_return_first`	Emits a signal and stops emission on the first handler that returns a not-None value.
Method	`emit_return_iter`	Returns an generator that calls one handler on each iteration and yields the return values. This allows aggregating return values.
Method	`_connect`	Undocumented
Method	`_setup_signal`	Undocumented
Method	`_teardown_signal`	Undocumented

@classmethod
def new_from_dir(klass, dir): (source)

Constructor to create a notebook based on a specific file system location. Since the file system is an external resource, this method will return unique objects per location and keep (weak) references for re-use.

Parameters
klass	Undocumented
dir	a `Folder` object
Returns
a `Notebook` object

def __init__(self, cache_dir, config, folder, layout, index): (source)

Constructor

Parameters
cache_dir	a `Folder` object used for caching the notebook state
config	a `NotebookConfig` object
folder	a `Folder` object for the notebook location
layout	a `NotebookLayout` object
index	an `Index` object

def __repr__(self): (source)

Undocumented

@assert_index_uptodate
@notebook_state
def delete_page(self, path, update_links=True): (source)

Delete a page from the notebook

Parameters
path	a `Path` object
update_links	if `True` pages linking to the deleted page will be updated and the link are removed.
Returns
`True` when the page existed and was deleted, `False` when the page did not exist in the first place. Raises an error when delete failed.
Unknown Field: emits
delete-page before the actual delete
deleted-page after successfull deletion

@assert_index_uptodate
@notebook_state
def delete_page_iter(self, path, update_links=True): (source)

Like delete_page()

def eval_new_page_template(self, path, template): (source)

Undocumented

def get_attachments_dir(self, path): (source)

def get_home_page(self): (source)

Returns a Page object for the home page

def get_new_page(self, path): (source)

Like get_page() but guarantees the page does not yet exist by adding a number to the name to make it unique.

This method is intended for cases where e.g. a automatic script wants to store a new page without user interaction. Conflicts are resolved automatically by appending a number to the name if the page already exists. Be aware that the resulting Page object may not match the given Path object because of this.

Parameters
path	a `Path` object
Returns
a `Page` object

def get_page(self, path): (source)

Get a Page object for a given path

Typically a Page object will be returned even when the page does not exist. In this case the hascontent attribute of the Page will be False and get_parsetree() will return None. This means that you do not have to create a page explicitly, just get the Page object and store it with new content (if it is not read-only of course).

However in some cases this method will return None. This means that not only does the page not exist, but also that it can not be created. This should only occur for certain special pages and depends on the store implementation.

Parameters
path	a `Path` object
Returns
a `Page` object or `None`

def get_page_template_name(self, path=None): (source)

Returns the name of the template to use for a new page. (To get the contents of the template directly, see get_template())

def get_template(self, path): (source)

Get a template for the intial text on new pages

Parameters
path	a `Path` object
Returns
a `ParseTree` object

def move_page(self, path, newpath, update_links=True, update_heading=False): (source)

Move and/or rename a page in the notebook

Parameters
path	a `Path` object for the old/current page name
newpath	a `Path` object for the new page name
update_links	if `True` all links from and to this page and any of it's children will be updated to reflect the new page name
update_heading	if `True` the heading of the page will be changed to the basename of the new path The original page `path` does not have to exist, in this case only the link update will done. This is useful to update links for a placeholder.
Raises
`PageExistsError`	if `newpath` already exists
Unknown Field: emits
move-page before the move
moved-page after successfull move

@assert_index_uptodate
@notebook_state
def move_page_iter(self, path, newpath, update_links=True, update_heading=False): (source)

Like move_page() but yields pages that are being updated if update_links is True

def on_properties_changed(self, properties): (source)

Undocumented

def relative_filepath(self, file, path=None): (source)

def resolve_file(self, filename, path=None): (source)

Resolve a file or directory path relative to a page or Notebook

This method is intended to lookup file links found in pages and turn resolve the absolute path of those files.

File URIs and paths that start with '~/' or '~user/' are considered absolute paths. Also windows path names like 'C:\user' are recognized as absolute paths.

Paths that starts with a '/' are taken relative to the to the document root - this can e.g. be a parent directory of the notebook. Defaults to the filesystem root when no document root is set. (So can be relative or absolute depending on the notebook settings.)

Paths starting with any other character are considered attachments. If path is given they are resolved relative to the attachment folder of that page, otherwise they are resolved relative to the notebook folder - if any.

Paths ending with a "/" or "" are considered folders.

The file is resolved purely based on the path, it does not have to exist at all. However if a folder of the name exists a Folder object is returned instead of a file.

Parameters
filename	the (relative) file path or uri as string
path	a `Path` object for the page
Returns
a `File` or `Folder` object.

@notebook_state
def store_page(self, page): (source)

Save the data from the page in the storage backend

Parameters
page	a `Page` object
Unknown Field: emits
store-page before storing the page
stored-page on success

@notebook_state
def store_page_async(self, page, parsetree): (source)

Undocumented

def suggest_link(self, source, word): (source)

Suggest a link Path for 'word' or return None if no suggestion is found. By default we do not do any suggestion but plugins can register handlers to add suggestions using the 'suggest-link' signal.

@assert_index_uptodate
@notebook_state
def trash_page(self, path, update_links=True): (source)

Move a page to Trash

Like delete_page() but will use the system Trash (which may depend on the OS we are running on). This is used in the interface as a more user friendly version of delete as it is undoable.

Parameters
path	a `Path` object
update_links	if `True` pages linking to the deleted page will be updated and the link are removed.
Returns
`True` when the page existed and was deleted, `False` when the page did not exist in the first place. Raises an error when trashing failed.
Raises
`TrashNotSupportedError`	if trashing is not supported by the storage backend or when trashing is explicitly disabled for this notebook.
Unknown Field: emits
delete-page before the actual delete
deleted-page after successfull deletion