Disseminate

Document Processing

Installation

Markup Language

Projects

Interfaces

Development

Attributes

Attributes are modifiers to tags that change how a tag is rendered. Attributes are represented by ordered dicts that can validate their entries.

exception disseminate.attributes.AttributeFormatError

Bases: Exception

An error was encountered in the format of attributes

class disseminate.attributes.Attributes(*args, **kwargs)

Bases: dict

The attributes class is an ordered dict to manage and validate attribute entries.

Note

Attributes can either be key/value (ex: ‘class=media’) or positional (ex: ‘red’). For positional arguments, the values are PositionalValue class objects.

append(attr, value=<class 'disseminate.attributes.attributes._MissingAttribute'>)

Set a value by appending to it, if it already exists, or creating it if it doesn’t.

Parameters
attrstr

The attr (key) for the entry to set or append.

valueOptional[Any]

The value to set or append. If not specified, the attribute will be added as a positional argument

copy() → a shallow copy of D
filter(attrs=None, target=None, sep='.', sort_by_attrs=False, strip=True)

Create an Attributes dict with target-specific entries.

Parameters
attrsOptional[Union[str, List[Union[str, PositionalValue]]]]

Filter keys. If specified, only entries that match one of these keys will be returned.

targetOptional[str]

Filter targets. If specified, only entries general entries will be returned unless a target-specific entry is present, in which case it will be returned. For example, if entries for ‘class’ and ‘class.tex’ exist and target=’tex’, then the ‘class.tex’ entry will be returned as ‘class’. If target is None, then the ‘class’ entry will be returned.

sepOptional[str]

The separator character (or string) to use to separate the key and target.

sort_by_attrsOptional[bool]

If True, the returned attributes dict will have keys sorted in the same order as the attrs passed. Otherwise, the returned attributes dict will be sorted with keys in the same order as this attributes dict (default).

stripOptional[bool]

If True, strip all target-specific terminators from the returned attris dict.

Returns
attributesAttributes

A filtered attributes dict.

Examples

>>> attrs = Attributes('class=one tgt=default tgt.tex=tex')
>>> attrs.filter()  # python >= 3.6 should have ordered entries
Attributes{'class': 'one', 'tgt': 'default'}
>>> attrs.filter(target='tex', strip=False)
Attributes{'class': 'one', 'tgt.tex': 'tex'}
>>> attrs.filter(target='tex', strip=True)
Attributes{'class': 'one', 'tgt': 'tex'}
>>> attrs.filter(attrs='class')
Attributes{'class': 'one'}
>>> attrs.filter(attrs='tgt')
Attributes{'tgt': 'default'}
find_item(attr, target=None, default=None, sep='.')

Find the key in the attributes dict with or without the target specified.

This function will not modify the keys/values in this attributes dict.

Parameters
attrUnion[str, PositionalValue]

The key of the attribute to retrieve or the PositionalValue to retrieve.

targetOptional[str]

If specified, search for a key for the given target. ex: class.html with be returned for the ‘class’ key and ‘html’ target, if available, otherwise, the entry for ‘class’ will be returned.

defaultOptional[Any]

If the key is not found, return this value instead.

sepOptional[str]

The separator character (or string) to use to separate the key and target.

Returns
key, valueAny

The retrieved item.

Examples

>>> attrs = Attributes('class="general" class.html="specific" pos')
>>> attrs.find_item('class')
('class', 'general')
>>> attrs.find_item('class.html')
('class.html', 'specific')
>>> attrs.find_item('class', target='html')
('class.html', 'specific')
>>> attrs.find_item('class', target='tex')
('class', 'general')
>>> attrs.find_item('pos')
('pos', <class ...StringPositionalValue'>)
>>> attrs.find_item('missing')
get(attr, target=None, default=None, sep='.')

Retrieve an entry by target-specific key, if available and specified, or by key.

As opposed to the find_item method, this function will strip the target-specific terminators of returned values

Parameters
attrUnion[str, PositionalValue]

The key of the attribute to retrieve or the PositionalValue to retrieve.

targetOptional[str]

If specified, search for a key for the given target. ex: class.html with be returned for the ‘class’ key and ‘html’ target, if available, otherwise, the entry for ‘class’ will be returned.

defaultOptional[Any]

If the key is not found, return this value instead.

sepOptional[str]

The separator character (or string) to use to separate the key and target.

Returns
valueAny

The retrieved value. If the entry is a positional attribute, PositionalValue will be returned.

Examples

>>> attrs = Attributes('class="general" class.html="specific" pos')
>>> attrs.get('class')
'general'
>>> attrs.get('class.html')
'specific'
>>> attrs.get('class', target='html')
'specific'
>>> attrs.get('class', target='tex')
'general'
>>> attrs.get('pos')
<class ...StringPositionalValue'>
>>> attrs.get('missing')
property html

Format the attributes for html.

Notes

  • This function won’t strip target tags (‘.html’), and a filter for the ‘.html’ target should be applied before using this property

load(s, sep='.')

Parses an attribute string into key/values for the Attributes dict.

Parameters
s: str

Input string of attributes. Attributes come in two forms: positional attributes and keyword attributes (kwargs), and attributes strings have the following form: “key1=value1 key2=value2 value3”

sepOptional[str]

The separator character (or string) to use to separate the key and target.

Examples

>>> attrs = Attributes()
>>> attrs.load("key1=val1 val2")
>>> attrs
Attributes{'key1': 'val1', 'val2': <class '...StringPositionalValue'>}
strip(sep='.')

Replace the entries in this attributes dict without the target-specific terminators.

property tex_arguments

Format arguments for tex.

Notes

  • This function won’t strip target tags (‘.tex’), and a filter for the ‘.tex’ target should be applied before using this property

Examples

>>> Attributes('width=302 3').tex_arguments
'{302}{3}'
property tex_optionals

Format optional arguments for tex.

Notes

  • This function won’t strip target tags (‘.tex’), and a filter for the ‘.tex’ target should be applied before using this property

Examples

>>> Attributes('width=302 3').tex_optionals
'[width=302, 3]'
totuple()

Return a tuple for an attributes dict

Examples

>>> attrs = Attributes("key1=val1 val2")
>>> attrs.totuple()
(('key1', 'val1'), 'val2')

Classes and methods to manage tag attributes

disseminate.attributes.attributes.is_target_specific(attr, sep='.')

Tests whether the given attribute is a target-specific attribute.

Parameters
attrUnion[str, PositionalValue]

The key of the attribute to retrieve or the PositionalValue to retrieve.

sepOptional[str]

The separator character (or string) to use to separate the key and target.

Returns
is_target_specificbool

True if the attr is a target-specific attribute

Examples

>>> is_target_specific(3)
False
>>> is_target_specific('pos')
False
>>> is_target_specific('pos.tex')
True
>>> is_target_specific('/usr/docs/text.tex')  # not quoted
True
>>> is_target_specific('"/usr/docs/text.tex"')  # quoted
False
disseminate.attributes.attributes.strip_attr(attr, sep='.')

Strip a target-specific terminator from the given attr.

Parameters
attrUnion[str, PositionalValue]

The key of the attribute to retrieve or the PositionalValue to retrieve.

sepOptional[str]

The separator character (or string) to use to separate the key and target.

Returns
stripped_attrstr

The attribute with the target-specific terminator stripped.

Examples

>>> strip_attr(3)
3
>>> strip_attr('143')
'143'
>>> strip_attr('width.tex')
'width'
>>> strip_attr('width')
'width'
>>> strip_attr('my_file.pdf#link-anchor')
'my_file.pdf#link-anchor'
>>> strip_attr('my_file.pdf#link-anchor.tex')
'my_file.pdf#link-anchor'