Interfaces

These are the interfaces / abstract base classes (abc.ABC) used across the project. Generally, where Adapters/Blocks/Interpreters/Nodes are interacted with, these ABCs are used as the interface.

For example, the concrete TagScriptInterpreter (itself a subclass of InterpreterABC) gets passed a sequence of BlockABC on instantiation and does not “know about” any concrete blocks like MathBlock.

class ya_tagscript.interfaces.AdapterABC

Abstract base class for all adapter classes.

abstractmethod get_value(ctx: Context) → str | None

Gets the stored value based on the provided Context

Parameters:

ctx (Context) – The current interpretation Context

Returns:

The adapter’s value as a string. None if the adapter rejected the context as invalid.

Return type:

str | None

class ya_tagscript.interfaces.BlockABC

Abstract base class for all block types.

All blocks must inherit from this class and implement the _accepted_names property and process() method.

requires_any_parameter: bool = False

Indicates that this block requires a non-None parameter (default: False).

Note

Subclasses must override this if they require this restriction.

requires_nonempty_parameter: bool = False

Indicates that this block requires a non-None AND non-empty parameter (default: False).

When set to True, this implies requires_any_parameter is also True.

Note

Subclasses must override this if they require this restriction.

requires_any_payload: bool = False

Indicates that this block requires a non-None payload (default: False).

Note

Subclasses must override this if they require this restriction.

requires_nonempty_payload: bool = False

Indicates that this block requires a non-None AND non-empty payload (default: False).

When set to True, this implies requires_any_payload is also True.

Note

Subclasses must override this if they require this restriction.

abstract property _accepted_names: set[str] | None

A set of all valid block names (all lowercase) or None if no block names can be defined (e.g. variable getter blocks).

Returns:

A set of lowercase strings representing possible acceptable block declarations that can be handled by this block. May be None if the block does not have predefined names (e.g. variable getter blocks).

Return type:

set[str] | None

abstractmethod process(ctx: Context) → str | None

Execute the block’s processing logic on the provided Context

Parameters:

ctx (Context) – The Context to process

Returns:

The string result of processing the Context. May be None if the block has rejected the Context as invalid.

Return type:

str | None

will_accept(ctx: Context) → bool

Checks whether this block can process the provided Context

The default check works like this:

1. name_match: Current node’s declaration is not None and its lowercased version appears in the block’s _accepted_names property.

2. param_match: Parameter requirements:

   1. If requires_any_parameter is set to True, check that parameter is not None.

   2. If requires_nonempty_parameter is set to True, check that parameter is not None and that parameter is not an empty string.

   3. If neither is set, set to True to pass the check.

3. payload_match: Payload requirements:

   1. If requires_any_payload is set to True, check that payload is not None.

   2. If requires_nonempty_payload is set to True, check that payload is not None and that payload is not an empty string.

   3. If neither is set, set to True to pass the check.

4. Return name_match and param_match and payload_match.

Note

If a subclass requires a different check, it must override this method and provide its own check.

Parameters:

ctx (Context) – The Context for which to check if the block will accept it

Returns:

Whether the block will accept processing of the Context

Return type:

bool

class ya_tagscript.interfaces.InterpreterABC(blocks: Sequence[BlockABC])

blocks: Sequence[BlockABC]

The blocks being used by this interpreter instance

work_limit: int | None

The approximate maximum number of characters this interpreter will process before aborting the processing (see also: “work limit” in the Glossary)

total_work: int

The total number of characters this interpreter has processed so far (This is reset to 0 at the beginning and end of each call to process())

abstractmethod __init__(blocks: Sequence[BlockABC]) → None

Constructs an interpreter with the provided block configurations

Parameters:

blocks (Sequence[BlockABC]) – The blocks this interpreter should use for interpretation

abstractmethod process(input_string: str, seed_variables: Mapping[str, AdapterABC] | None = None, extra_kwargs: Mapping[str, Any] | None = None, work_limit: int | None = None) → Response

Instruct the interpreter to process the input_string with the current block configuration.

Parameters:

• input_string (str) – The script to process

• seed_variables (Mapping[str, AdapterABC] | None) – A mapping of predefined variables (default: None)

• extra_kwargs (Mapping[str, Any] | None) – A mapping of extra arguments (default: None)

• work_limit (int | None) –

  The approximate character limit at which to abort processing and error out (default: None)

  Note: This is only an approximate limit because a defined block may be short enough to still be allowed under the limit but then end up outputting a lot more text, shooting past the limit. The interpreter checks the limit after each node has been processed. This check is performed even during nested/recursive blocks, so one massive block with lots of nested blocks should still be cut off sufficiently early.

Returns:

The output of the script as processed

Return type:

Response

class ya_tagscript.interfaces.NodeABC

Represents a section of the input, either recognized as pure text or a TagScript block.

type: NodeType

The type of Node (either NodeType.BLOCK or NodeType.TEXT)

text_value: str | None

The NodeType.TEXT type node’s contained string. Always None for NodeType.BLOCK nodes.

declaration: str | None

The NodeType.BLOCK node’s declaration. Always None for nodes of type NodeType.TEXT.

parameter: str | None

The NodeType.BLOCK node’s parameter. Always None for nodes of type NodeType.TEXT.

payload: str | None

The NodeType.BLOCK node’s payload. Always None for nodes of type NodeType.TEXT.

output: str | None = None

The NodeType.BLOCK node’s output once interpreted. None before interpretation of the node is complete (and always None for nodes of type NodeType.TEXT).

abstractmethod as_raw_string() → str

Returns the node’s raw string representation (basically the text that this node was created from).

Returns:

The node’s raw string representation

Return type:

str

abstractmethod classmethod block(*, declaration: str, parameter: str | None, payload: str | None) → NodeABC

Convenience method to create a node of type NodeType.BLOCK with its exact required parameters.

Parameters:

• declaration (str) – The block declaration

• parameter (str | None) – The block parameter

• payload (str | None) – The block payload

Returns:

The NodeABC with a type of NodeType.BLOCK

Return type:

NodeABC

abstractmethod classmethod text(*, text_value: str) → NodeABC

Convenience method to create a node of type NodeType.TEXT with its exact required parameters.

Parameters:

text_value (str) – The text node’s string value

Returns:

The NodeABC with a type of NodeType.BLOCK

Return type:

NodeABC

enum ya_tagscript.interfaces.NodeType(value)

Represents possible types of NodeABC

• NodeType.BLOCK — A (possible) TagScript block node

• NodeType.TEXT — A pure text node

Valid values are as follows:

BLOCK = <NodeType.BLOCK: 1>

TEXT = <NodeType.TEXT: 2>