Tag¶
Core classes and functions for tags.
- class disseminate.tags.tag.Tag(name, content, attributes, context)¶
A tag to format text in the markup document.
- Parameters
- namestr
The name of the tag as used in the disseminate source. (ex: ‘body’)
- contentUnion[str, List[Union[str, list,
Tag
],Tag
] The contents of the tag. It can either be a string, a tag or a list of strings, tags and lists.
- attributesUnion[str,
Attributes
] The attributes of the tag. These are distinct from the Tag class attributes; they’re the customization attributes specified by the user to change the appearance of a rendered tag. However, some or all attributes may be used as tag attributes, depending on the settings.html_valid_attributes, settings.tex_valid_attributes and so on.
- context
Type[BaseContext]
The context with values for the document. The tag holds a weak reference to the context, as it doesn’t own the context.
- Attributes
- aliasesTuple[str]
A tuple of strings for other names a tag goes by
- hashOptional[str]
The hash for the tag’s contents before processing. This is useful for detecting changes in the string’s contents.
- html_namestr
If specified, use this name for the html tag. Otherwise, use name.
- tex_cmdstr
If specified, use this name to render the tex command.
- tex_envstr
If specified, use this name to render the tex environment.
- tex_paragraph_newlinesbool
If True (default), block tags within paragraphs will be typeset with a newline before and after. This is disable, for example, for equations.
- activebool
If True, the Tag can be used by the TagFactory.
- process_contentbool
If True, the contents of the tag will be parsed and processed into a tag tree (AST) by the ProcessContent processor on creation.
- process_typographybool
If True, the strings in contents of the tag will be parsed and processed for typography characters by the ProcessTypography processor on creation.
- include_paragraphsbool
If True, then the contents of this tag can be included in paragraphs. See
disseminate.tags.processors.process_paragraphs()
.- paragraph_rolestr
If this tag is directly within a paragraph, the type of paragraph may be specified with a string. The following options are possible:
None : The paragraph type has not been assigned
‘inline’ : The tag is within a paragraph that includes a mix of strings and tags
‘block’ : The tag is within its own paragraph.
- copy(new_context=None)¶
Create a copy of this tag and all sub-tabs.
The tag copy is a deep copy of the attributes and content, but the context is either kept the same or replaced with the specified new_context.
- Parameters
- new_contextOptional[
Type[BaseContext]
] The new context to replace, if specified.
- new_contextOptional[
- default_fmt(content=None, attributes=None)¶
Convert the tag to a text string.
Strips the tag information and simply return the content of the tag.
- Parameters
- contentOptional[Union[str, List[Union[str, list,
Tag
]]] Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.
- attributesOptional[Union[str,
Attributes
]] Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.
- contentOptional[Union[str, List[Union[str, list,
- Returns
- text_stringstr
A text string with the tags stripped.
- flatten(tag=None, filter_tags=True)¶
Generate a flat list with this tag and all sub-tags and elements.
- html_fmt(content=None, attributes=None, format_func='html_fmt', method='html', level=1)¶
Convert the tag to an html string or html element.
- Parameters
- contentOptional[Union[str, List[Union[str, list,
Tag
]]] Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.
- attributesOptional[Union[str,
Attributes
]] Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.
- format_funcOptional[str]
The format function to use with by formatted_content when formatting sub-tags.
- methodOptional[str]
The rendering method for the string. ex: ‘html’ or ‘xml’
- levelOptional[int]
The level of the tag.
- contentOptional[Union[str, List[Union[str, list,
- Returns
- htmlstr or html element
A string in HTML format or an HTML element (
lxml.builder.E
).
- property short¶
The short title for the tag
- tex_fmt(content=None, attributes=None, mathmode=False, level=1)¶
Format the tag in LaTeX format.
- Parameters
- contentOptional[Union[str, List[Union[str, list,
Tag
]]] Specify an alternative content from the tag’s content. It can either be a string, a tag or a list of strings, tags and lists.
- attributesOptional[Union[str,
Attributes
]] Specify an alternative attributes dict from the tag’s attributes. It can either be a string or an attributes dict.
- mathmodeOptional[bool]
If True, the tag will be rendered in math mode. Otherwise (default) latex text mode is assumed.
- levelOptional[int]
The level of the tag.
- contentOptional[Union[str, List[Union[str, list,
- Returns
- tex_stringstr
The formatted tex string.
- property title¶
A title string converted from the content
- xhtml_fmt(method='xhtml', format_func='xhtml_fmt', **kwargs)¶
Convert the tag to an xhtml string or html element.
- Returns
- xhtmlstr or xhtml element
A string in XHTML format or an XHTML element (
lxml.builder.E
).
- class disseminate.tags.tag.TagFactory¶
Generates the appropriate tag for a given tag type.
The tag factory instantiates tags based on loaded modules and initialization parameters.
- Parameters
- tag_base_cls
Tag
The base class for Tag objects.
- tag_base_cls
- classmethod tag(tag_name, tag_content, tag_attributes, context)¶
Return the approriate tag, given a tag_name and tag_content.
A tag subclass, rather than the Tag base class, will be returned if
A tag subclass with the tag_name (or with an alias) is available.
The tag subclass has an ‘active’ attribute that is True
The tag’s name isn’t listed in the ‘inactive_tags’ set in the context.
- Parameters
- tag_namestr
The name of the tag. ex: ‘bold’, ‘b’
- tag_contentUnion[str, list]
The content of the tag. ex: ‘this is bold’
- tag_attributesstr
The attributes of a tag. ex: ‘width=32pt’
- context
document.DocumentContext
The document’s context.
- Returns
- tag
Tag
An instance of a Tag subclass.
- tag
- classmethod tag_class(tag_name, context)¶
Retrieve the tag class for the given tag_name
- classmethod tag_classes()¶
A dict of all the active Tag subclasses.