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_context
DocumentContext
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.
- root_context
- 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.
- labelsDict[Tuple[str,str],
- 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’
- context
DocumentContext
The context for the document adding the label. (This may be different from the context of the root document, self.root_context)
- label_cls
Type[Label]
The label class (or subclass) to use in creating the label.
- Raises
- DuplicateLabel
DuplicateLabel
Raised if a label with the same id already exists in this label manager.
- DuplicateLabel
- 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
- context
DocumentContext
The context for the document adding the label. (This may be different from the context of the root document, self.root_context)
- Returns
- label
Type[Label]
The corresponding label.
- label
- Raises
- LabelNotFound
LabelNotFound
A LabelNotFound exception is raised if a label with the given id could not be found.
- LabelNotFound
- 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
- context
DocumentContext
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.
- labelsList[
- Raises
- LabelNotFound
LabelNotFound
A LabelNotFound exception is raised if a label with the given id could not be found.
- LabelNotFound
- 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.
- labelsList[
- 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’
- context
DocumentContext
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')