Abstract and Base Classes

ZAbstract

exception xettel.base.ZAbstract.UnresolvedLinks(unresolved: list[typing.Tuple[int, int]])

Exception for unresolved links

Parameters

unresolved (list[UnresolvedListItem]) – a list of tuples of ints (source of the link, destination of the link).

unresolved

a list of tuples of ints (source of the link, destination of the link).

Type

list[UnresolvedListItem]

class xettel.base.ZAbstract.ZettelAbstract(parent: xettel.base.ZAbstract.ZettelkastenAbstract, uid: int)

Abstraction for a single Zettel

Parameters

• parent (ZettelkastenAbstract) – Zettelkasten in which the Zettel is stored.

• uid (int) – uid of the Zettel

parent

the Zettelkasten in which this Zettel is stored.

Type

ZettelkastenAbstract

__uid

the uid of this Zettel.

Type

int

attributes

dict[str, Any]: the attributes of this Zettel

__links

set of the uids of the Zettels this Zettel points to.

Type

set[int]

__backlinks

set of the uids of the Zettels that point to this Zettel.

Type

set[int]

Raises

TypeError – if the parent is not an instance of ZettelkastenAbstract or if the uid is not an int.

add_backlink(uid: int) → None

Add an uid to the set of backlinks.

Parameters

uid (int) – an uid of a Zettel.

Raises

TypeError – if uid is not an int.

fetch_backlinks() → None

Fetch backlinks for current zettel.

This method is more efficient for a single zettel.

get_backlinks_uids() → set[int]

Get uids of Zettels that points to this Zettel.

Returns

a set of the uids of the Zettels that points to this one.

Return type

set[int]

get_links_uids() → set[int]

Get uids of the links in this zettel.

Returns

a set of the links from this zettel

Return type

set[int]

get_uid() → int

Get uid of Zettel.

Returns

the uid of the Zettel

Return type

int

get_uid_36() → str

Get uid of the Zettel in base 36.

Returns

the uid of the Zettel, in base 36.

Return type

str

initialise_contents() → None

Orderly initialise contents.

This method first parses attributes then parses the links.

abstract parse_attributes() → None

Parse attributes

abstract parse_links(links: collections.abc.Collection[int] = []) → None

Parse links with the given data

The abstract method defined here just sets the private attribute __links to the ones given by the argument links.

Parameters

links (Collection[int]) – a collection of ints.

propagate_backlinks() → None

Tries to set backlinks in zettels linked from this zettel.

Raises

UnresolvedLinks – if some links are unresolved, i.e. they point nowhere.

class xettel.base.ZAbstract.ZettelkastenAbstract

Abstraction for a Zettelkasten

zettels

a dictionnary of Zettels where each zettel is supposed to be indexed by its uid.

Type

dict[int, ZettelType]

add_zettel(zettel: xettel.base.ZAbstract.Z) → None

Add Zettel within the Zettelkasten, eventually replacing already existing Zettel with same UID

Parameters

zettel (ZettelType) – a Zettel

initialise_contents(setbacklinks: bool = True) → None

A posteriori setting of the contents.

Optionally set backlinks as well when useful. Defaults to True.

Parameters

setbacklinks (bool) – whether to set backlinks or not

set_backlinks() → None

Tries to set all backlinks, raise an exception if some links cannot be resolved.

This method is more efficient than using fetch_backlinks on all zettels

xettel.base.ZAbstract.intkey(key: Union[int, str]) → int

Convert a valid key to an int key

Parameters

key (ZKey) – A valid key, either a alphanumeric string which represents a number in base 36 or an int.

Returns

An int key.

Raises

TypeError – If the provided key is not valid.

ZettelFile

class xettel.base.ZettelFile.ZettelFile(parent: Zettelkasten, filename: str)

Abstraction for a single Zettel file

Parameters

• parent (Zettelkasten) – the Zettelkasten in which this Zettel is stored. The Zettelkasten must be a subclass of ZettelkastenFolder.

• filename (str) – the bare filename (not the whole path!). The filename must be of the form $UID-* where $UID is either a base36 8-char long string or a base10 12-digit long string.

extension

the extension of the files. This is a class attribute.

Type

str

abstract static export(zettel: xettel.base.ZAbstract.ZettelAbstract, force: bool = False) → None

Exports Zettels.

The abstract method defined here does nothing.

Parameters

• zettel (ZA.ZettelAbstract) – a Zettel

• force (bool) – whether to override the destination even if it is newer than the Zettel’s file.

get_indexing_function(key: str) → Callable[[xapian.Document, xapian.TermGenerator, Any], None]

Returns the function needed to index data from the attributes given a lowered and whitespace-stripped (as in str.strip()) key.

Functions returned by this method must have the following signature: (xapian.Document, xapian.TermGenerator, value) -> None.

Parameters

key (str) – the key to the indexing function

Returns

The indexing function corresponding to the key.

index_attributes(document: xapian.Document, indexer: xapian.TermGenerator) → None

Indexes attributes of the Zettel in the Xapian database

Parameters

• document (xapian.Document) – the document in which to index attributes.

• indexer (xapian.TermGenerator) – the term generator with which xettel will generate terms for the document.

static index_path(doc: xapian.Document, idxr: xapian.TermGenerator, path: str) → None

Function that generates terms for a xapian document with its path.

Parameters

• doc (xapian.Document) – a Xapian document

• idxr (xapian.TermGenerator) – a Xapian term generator.

• path (str) – a path

abstract static issue_export_cmd(source: str, dest: str, env: dict[str, str], zinfo: dict[str, str]) → None

Execute the command to export Zettels.

The abstract method defined here does nothing.

Parameters

• source (str) – path of the Zettel

• dest (str) – where to export the Zettel

• env (dict[str, str]) – dictionnary of environement variables to pass to the command.

• zinfo (dict[str,str]) – additional information to feed the command, probably directly among the arguments of the command.

abstract parse_attributes() → None

This method assumes the file exists

prepare_data_for_xapian() → dict[str, typing.Any]

Builds a data dict to store in a xapian.Document

Returns

A dictionnary of keys and attributes to feed to Xapian.

classmethod set_queryparser_prefixes(queryparser: xapian.QueryParser) → None

Sets the prefixes for searching the metadata defined by this class into the queryparser.

The method defined here does nothing.

Parameters

queryparser (xapian.QueryParser) – the queryparser to feed information to.

abstract classmethod tag_export(tag: str, filecontents: list[typing.Tuple[str, str]]) → None

Exports a page of a list of Zettels having this tag.

The abstract method defined here does nothing.

Parameters

• tag (str) – the tag

• filecontents (list[Tuple[str, str]]) – a summary of the contents of the Zettels having this tag. The first component of the tuple is the path of the Zettel, the second may be its title.

to_xapian(indexer: xapian.TermGenerator) → xapian.Document

Export a Zettel as a new Xapian document

Parameters

indexer (xapian.TermGenerator) – a TermGenerator

Returns

A new Xapian document built from the data of the Zettel.

Zettelkasten

class xettel.base.Zettelkasten.Zettelkasten(zettel_impl: Optional[Type[xettel.base.Zettelkasten.Z]] = None)

Abstraction for a Zettelkasten folder

Keyword Arguments

• zettel_impl (Optional[Type[ZettelType], None]) – a class

• file. (implementing a generating a Zettel from a) –

folder

the path to the folder where Zettels are stored.

Type

str

zettel_impl

cf. the argument above.

Type

Optional[Type[ZettelType], None]

extension

the extension of the Zettels.

Type

str

add_zettel_from_file(filepath: str) → None

Add Zettel within the Zettelkasten from an existing file, eventually replacing already existing Zettel with same UID

Parameters

filepath (str) – the path to the Zettel

classmethod from_folder(folder: str, zettel_impl: Type[xettel.base.Zettelkasten.Z]) → Tuple[xettel.base.Zettelkasten.Zettelkasten[xettel.base.Zettelkasten.Z], list[typing.Tuple[int, int]]]

Class method for building a Zettelkasten for files in a folder

This method assumes all non-hidden files within a given folder are zettels.

It returns a tuple (ZK, List) consisting of the Zettelkasten and a list of unresolved links.

Parameters

• folder (str) – the path to the Zettelkasten

• zettel_impl – (Type[ZettelType]): a concrete subclass of ZettelFile.

Returns

The Zettelkasten built from the folder together with a list of unresolved links.

Raises

TypeError – if zettel_impl is not a concrete subclass of ZettelFile.