Tag

class exporter.tag.Tag(gdocs, dataset_id)

A tag for inserting content into a template.

Parameters:

• gdocs (Gdocs) – a Google API client

• dataset_id (int) – the dataset’s ID

name: str | None = None

The tag’s name.

argument_names: Set[str] = {}

The names of all arguments.

argument_required: Set[str] = {}

The names of required arguments.

argument_validators: Dict[str, Callable[[str], bool]] = {}

A mapping of argument names to validation functions.

argument_validation_messages: Dict[str, str] = {}

A mapping of argument names to failure messages.

argument_converters: Dict[str, Callable[[str], Any]] = {}

A mapping of argument names to conversion functions.

argument_defaults: Dict[str, Any] = {}

set_argument(name, value)

Set an argument.

The argument’s name is checked against declared arguments, and its value is checked with the declared validator, if any. Its value is converted with the declared converter, if any.

Parameters:

• name (str) – the argument’s name

• value (Any) – the argument’s value

Raises:

TagArgumentError – if the name is unrecognized or the value is invalid

Return type:

None

finalize_arguments()

Set unused arguments to default values.

Raises:

TagArgumentError – if a value is invalid

Return type:

None

validate_and_render(data)

Check for missing arguments, and call and return render().

Raises:

MissingArgumentError – if arguments are missing

Parameters:

data (Dict[str, Any])

Return type:

Any

render(data)

Render the tag.

Parameters:

data (Dict[str, Any]) – the data (“context”) provided by another tag

Return type:

Any

class exporter.tag.LeafTag(gdocs, dataset_id)

A leaf tag renders itself, using the data (“context”) provided by a template tag.

Parameters:

• gdocs (Gdocs)

• dataset_id (int)

render(data)

Render the tag.

Parameters:

data (Dict[str, Any]) – the data (“context”) provided by a template tag

Return type:

str | Element | List[Element]

class exporter.tag.TemplateTag(gdocs, dataset_id)

A template tag renders a template, stored as a document in Google Docs. The template can contain sub-tags.

Parameters:

• gdocs (Gdocs) – a Google API client

• dataset_id (int) – the dataset’s ID

default_template: str | None = None

The default value of the template argument.

tags: Tuple[Type[Tag], ...] = ()

The sub-tags supported by the template tag.

get_context()

Return the data (“context”) to be provided to sub-tags.

Return type:

Dict[str, Any]

get_tags_mapping(texts)

Extract and instantiate the tags in the template.

Also return the names of any checks that cannot be computed. The corresponding tags are replaced with error template tags.

Parameters:

texts (List[Element]) – the text nodes from the template that contain tags

Raises:

• TagSyntaxError – if a sub-tag is malformed

• UnknownTagError – if a sub-tag’s name is unrecognized

• TagArgumentError – if a sub-tag’s argument is invalid

Return type:

Tuple[Dict[str, Tag], List[str]]

render(data)

Read the template’s content, extract its sub-tags, recursively call the sub-tags’ validate_and_render() method, and merge the results into the content.

Parameters:

data (Dict[str, Any]) – the data (“context”) provided by another template tag

Raises:

• MissingArgumentError – if a leaf tag’s argument is missing

• ValueError – if a leaf tag’s render() method has an invalid return value

• TagError – if a template tag or its sub-tags caused an error

Return type:

Tuple[Element, List[str]]

class exporter.tag.TagExpression(name, arguments)

A representation of the tag as expressed in the template.

Parameters:

• name (str) – The tag’s name

• arguments (Dict[str, str]) – The tag’s arguments

name: str

arguments: Dict[str, str]

classmethod parse(string)

Parse the string as a tag.

Parameters:

string (str) – the full tag, starting with {%

Raises:

TagSyntaxError – if the tag is malformed

Return type:

TagExpression

exporter.tag.template(_name, _default_template, _tags)

Build a TemplateTag by decorating a get_context() implementation.

Parameters:

• _name (str) – the tag’s name

• _default_template (str) – the default value of the template argument

• _tags (Tuple[Type[Tag], ...]) – the tag’s sub-tags

Return type:

Callable[[Callable[[TemplateTag], Dict[str, Any]]], Type[TemplateTag]]

exporter.tag.leaf(_name)

Build a LeafTag by decorating a render() implementation.

Parameters:

_name (str) – the tag’s name

Return type:

Callable[[Callable[[LeafTag, Dict[str, Any]], str | Element | List[Element]]], Type[LeafTag]]

exporter.tag.argument(name, default=None, required=False, choices=None, type=None, nonzero=False)

Add an argument to the tag.

Parameters:

• name (str) – the argument’s name

• default (Any | None) – the argument’s default value

• required (bool) – whether the argument is required

• choices (Set[str] | Dict[str, Any] | None) – the argument’s allowed values

• type (Type[int] | None) – the argument’s allowed type

• nonzero (bool) – whether the argument can be 0 (if type=int)

Return type:

Callable[[Type[Tag]], Type[Tag]]

exporter.tag.generate_error_template_tag(message)

Build a TemplateTag for the error template and set the error message.

Parameters:

message (str)

Return type:

Type[TemplateTag]

exporter.tag.value_tag

alias of _Tag