Label Manager

The manager for labels.

class disseminate.label_manager.label_manager.LabelManager(root_context)

Bases: object

Manage labels for a project (a document tree).

Parameters
root_contextDocumentContext

The context for the root document. The label manager does not own the context object, so only a weak reference to the context is stored.

Attributes
labelsDict[Tuple[str,str], Label]

A list of labels where the key is the (doc_id, label_id) and the values are the label objects.

add_content_label(id, kind, title, context)

Add content label.

See add_label() for usage details.

add_document_label(id, kind, title, context)

Add document label.

See add_label() for usage details.

add_label(id, kind, context, label_cls, *args, **kwargs)

Add a label.

Parameters
idstr

The unique identifier (within a project of documents) for the label. The id includes the label_id and possibly the doc_id of the label. ‘test.dm::intro’. (See parse_id for details) ex: ‘ch:nmr-introduction’

kindUnion[str, List[str], Tuple[str]]

The kind of the label. ex: ‘figure’, (‘heading’, ‘chapter’), ‘equation’

contextDocumentContext

The context for the document adding the label. (This may be different from the context of the root document, self.root_context)

label_clsType[Label]

The label class (or subclass) to use in creating the label.

Raises
DuplicateLabelDuplicateLabel

Raised if a label with the same id already exists in this label manager.

format_string(id, *keys, target=None)

Retrieve the formatted label string for a label.

Label format strings are intended to be replaced with the values of the label by replace_macros (replace_macros).

Parameters
idstr

The label of the label ex: ‘ch:nmr-introduction’

keysOptional[List[str], Tuple[str]]

If specified, use the given keys to find entries in the format_str dict. (see find_entry)

targetOptional[str]

If specified, try finding format strings for the given target.

get_label(id, register=True, context=None)

Return the label for the given label id.

Note

This function registers the added labels.

Parameters
idstr

The unique identifier (within a project of documents) for the label. The id includes the label_id and possibly the doc_id of the label. ‘test.dm::intro’. (See parse_id for details) ex: ‘ch:nmr-introduction’

registerOptional[bool]

If True, labels will be registered before doing the search

contextDocumentContext

The context for the document adding the label. (This may be different from the context of the root document, self.root_context)

Returns
labelType[Label]

The corresponding label.

Raises
LabelNotFoundLabelNotFound

A LabelNotFound exception is raised if a label with the given id could not be found.

get_labels_by_id(ids, register=True, context=None)

Return the labels with the given (optional) doc_ids and label_ids.

Parameters
idsUnion[str, Tuple[str]]

The unique identifiers (within a project of documents) for the label. The id includes the label_id and possibly the doc_id of the label. ‘test.dm::intro’. (See parse_id for details) ex: ‘ch:nmr-introduction’

registerOptional[bool]

If True, labels will be registered before doing the search

contextDocumentContext

The context for the document adding the label. (This may be different from the context of the root document, self.root_context)

Returns
labelsList[Type[Label]]

A list of label objects.

Raises
LabelNotFoundLabelNotFound

A LabelNotFound exception is raised if a label with the given id could not be found.

get_labels_by_kind(doc_id=None, kinds=None, register=True)

Return a filtered and sorted list of all labels for the given document and kinds.

Note

This function registers the added labels.

Parameters
doc_idOptional[str]

If specified, only label for the given document id will be returned. (This is used an alternative to the context.)

kindsOptional[Union[str, List[str], Tuple[str]]

If None, all label kinds are returned. If string, all labels matching the kind string will be returned. If a list of strings is returned, all labels matching all the kinds listed will be returned.

registerOptional[bool]

If True, labels will be registered before doing the search

Returns
labelsList[Type[Label]]

A list of label objects.

register(context=None)

Register the labels.

reset(doc_ids=None)

Reset the the labels.

Parameters
doc_idsUnion[str, List[str], Tuple[str]]

If specified, remove the labels for the given doc_ids

disseminate.label_manager.label_manager.parse_id(id, context=None)

Parses a label’s identifier into a doc_id and label_id.

Parameters
idstr

The unique identifier (within a project of documents) for the label. The id includes the label_id, and it might include the doc_id. ex: ‘test.dm::intro’. (See label_sep for details) ‘ch:nmr-introduction’

contextDocumentContext

The document context.

Returns
doc_id, label_idTuple[Union[str, None], str]

The doc_id and label_id from the label id.

Examples

>>> parse_id('intro')
(None, 'intro')
>>> parse_id('fig:diagram-1')
(None, 'fig:diagram-1')
>>> parse_id('test1.dm::fig:diagram-1')
('test1.dm', 'fig:diagram-1')