API

class blockie.Block(template: str | ~pathlib.Path = '', name: str = '', config: ~blockie.blockie.BlockConfig = BlockConfig(tag_gen_var=<function BlockConfig.<lambda>>, tag_gen_blk_start=<function BlockConfig.<lambda>>, tag_gen_blk_end=<function BlockConfig.<lambda>>, tag_gen_blk_vari=<function BlockConfig.<lambda>>, autotag_align='+', autotag_vari='.', tab_size=4))

Block data corresponding to a part of the template within a block start and end tags.

config

A block configuration primarily defining the format of tags within a template.

Type:

BlockConfig

name

A block name. Usually set automatically by the get_subblock() method.

Type:

str

content

The generated block content, i.e., a template filled with data.

Type:

str

autotags

Enables the automatic tags (alignment, etc.) to be filled automatically.

Type:

bool

__init__(template: str | ~pathlib.Path = '', name: str = '', config: ~blockie.blockie.BlockConfig = BlockConfig(tag_gen_var=<function BlockConfig.<lambda>>, tag_gen_blk_start=<function BlockConfig.<lambda>>, tag_gen_blk_end=<function BlockConfig.<lambda>>, tag_gen_blk_vari=<function BlockConfig.<lambda>>, autotag_align='+', autotag_vari='.', tab_size=4)) → None

Initializes a new block object.

Parameters:

• template (str | Path) – Template string or a path to a text file template.

• name (str) – A block name.

• config (BlockConfig) – A block configuration (template tags format, tabulator size, etc.)

property parent: Block

A parent block.

property children: dict[str, Block]

A list of child subblocks extracted using a get_subblock() method.

property template: str

A block template string.

load_template(file_path: str | Path) → None

Loads the block template from a text file.

save_content(file_path: str | Path) → None

Saves the block content to a text file.

fill(data: dict | object, _Block__clone_idx: int = 0) → int | bool

Fills the block content using the data from a dictionary or an object.

The dictionary keys or object attribute names define the template variable or a block to be set. The dictionary or object attribute values are used according to the rules below:

• Strings, integers, floats, booleans -> Variable values.

• Dictionary or object -> Data to be filled into a child block in a current block.

• List or tuple -> Content of block clones. Each element must be a dictionary or object with data used a for filling one cloned instance of a block.

Two special key/attribute-value pairs can be used in a data dictionary or object:

• fill_hndl - func(block: Block, data: dict | object, clone_subidx: int) -> None function: A user-defined handler function with an access to the template block object and a data being filled usable for special low-level operations.

• vari_idx - int: A variation index to be set for a variation block type (see the vari_idx attribute of the :meth:set method).

Parameters:

• data – A dictionary or object with to be used for filling a block template.

• __clone_idx – An internal index of a block clone being filled.

Returns:

Internally used variation index for variation blocks being filled.

Return type:

int | bool

get_subblock(*subblock_names: str) → Block | list[Block] | None

Returns the specified child block object from the current block content. Each child is also automatically added into the children attribute of the current block.

Parameters:

subblock_names – The tag names of blocks to be extracted from a current block content.

Returns:

A Block object or a list of blocks if multiple subblock names are specified. None is returned if the specified block tags are not found.

set_variables(autoclone: bool = False, **name_value_kwargs) → None

Sets values into the specified variables within this block content.

Parameters:

• autoclone – Enables automatic clone of this block after setting all variables.

• name_value_kwargs – Keyword arguments representing variable name-value pairs, e.g., name="Thomas", surname="Anderson", age=37. Tuples or lists can be used as variable values, making this block to be automatically cloned after setting each element value.

set(vari_idx: int | bool = 0, all_children: bool = False, count: int = -1) → None

Sets the content of this block into its parent block content.

Parameters:

• vari_idx – An index of a variation block content (if any) to be set starting from 0. A negative index or boolean false causes the block to be cleared. A boolean true is the same as index 0.

• all_children – Enables setting of all child blocks of this block before setting it.

• count – The maximum number of blocks with the same name to be set (-1 = no limit).

set_subblock(*subblocks: Block | str) → None

Sets the content of specified child blocks into the content of the current block.

Parameters:

subblocks – The subblock object(s) or their names to be set.

clone(copies: int = 1, force: bool = False, passive: bool = False, set_children: bool = False) → None

Clones the block, i.e., virtually adds another copy of a block template after the existing block content making the new template copy ready to be filled with other values.

The clone is created only if blocks and variables are set after cloning. The child blocks are reset after cloning, unless the passive argument is set to True.

Parameters:

• copies – The number of template copies to be prepared. If > 1, then force and passive arguments are automatically False.

• force – Forces the clone to be created even if no variable or block is then set.

• passive – Enables cloning only if an active (non-passive) clone has been requested previously and no further clone is created.

• set_children – Enables setting of all child blocks to this parent block before cloning.

clear_variables(*var_names: str) → None

Clears the specified variables from this block content. Has the same effect as setting the variables to an empty string.

Parameters:

var_names – Names of the variables to be cleared.

clear(count: int = -1) → None

Clears the block from its parent block, i.e., sets the block to an empty string.

Parameters:

count – The maximum number of blocks with the same name to be cleared, -1 = all.

clear_subblock(*subblocks: Block | str) → None

Clears the content of specified child blocks from a current block content.

Parameters:

subblocks – Subblock object(s) or their names to be cleared.

reset(all_children: bool = True) → None

Resets the block content to the initial template.

Parameters:

all_children – Enables a reset of all child blocks too.

class blockie.BlockConfig(tag_gen_var: ~collections.abc.Callable[[str], str] = <function BlockConfig.<lambda>>, tag_gen_blk_start: ~collections.abc.Callable[[str], str] = <function BlockConfig.<lambda>>, tag_gen_blk_end: ~collections.abc.Callable[[str], str] = <function BlockConfig.<lambda>>, tag_gen_blk_vari: ~collections.abc.Callable[[str], str] = <function BlockConfig.<lambda>>, autotag_align: str = '+', autotag_vari: str = '.', tab_size: int = 4)

The template block configuration defining the format of tags and other template parts.

tag_gen_var

A tag generator function for a variable tag. Defaults to a lamba function converting a tag name name to a variable tag string <NAME>.

Type:

Callable[[str], str]

tag_gen_blk_start

A tag generator function for a block start tag. Defaults to a lamba function converting a tag name name to a block start tag string <NAME>.

Type:

Callable[[str], str]

tag_gen_blk_end

A tag generator function for a block end tag. Defaults to a lamba function converting a tag name name to a block end tag string </NAME>.

Type:

Callable[[str], str]

tag_gen_blk_vari

A tag generator function for a block variation tag. Defaults to a lamba function converting a tag name name to a block variation tag string <^NAME>.

Type:

Callable[[str], str]

autotag_align

The alignment automatic tag symbol. Defaults to +.

Type:

str

autotag_vari

The variation automatic tag symbol. Defaults to ..

Type:

str

tab_size

A tabulator size in the number of space characters. Used by the alignment automatic tag when tabulators are used for the alignment. Defaults to 4.

Type:

int