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.

contextType[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.

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.

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.

Parameters
tagOptional[Tag]

If specified, flatten the given tag, instead of this tag.

filter_tagsOptional[bool]

If True, only return a list of tag objects. Otherwise, include all content items, including strings and lists.

Returns
flattened_listList[Union[str, Tag]]

The flattened list.

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.

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.

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_clsTag

The base class for Tag objects.

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’

contextdocument.DocumentContext

The document’s context.

Returns
tagTag

An instance of a Tag subclass.

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.