7. API

class blockie.Block(template: str | Path = '', name: str = '', config: BlockConfig | None = None)

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

class FillState(clone_idx: int = 0, vari_idx: int = 0, var_set: bool = False)

Internal fill() method state variaable used between its recursive calls.

__init__(clone_idx: int = 0, vari_idx: int = 0, var_set: bool = False) → None

__init__(template: str | Path = '', name: str = '', config: BlockConfig | None = None) → 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, subrefs: bool = True) → None

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 to be used for filling a block template.

• subrefs – Enables filling of hierarchical block or variable subreferences in variable values, e.g. PARENT_BLOCK.CHILD_BLOCK.CHILD_VAR.

get_subblock(subblock_name: str) → Block

Returns the specified child block object from the this block content. Each child is also automatically added into the children attribute of this block. If the specified block is not found, then a block object with empty name and template is returned.

Parameters:

subblock_name – The tag name of a block to be extracted from a this block content.

Returns:

A Block object. If the subblock is not found, then the returned block object has an empty name and template.

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

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.

Returns:

True if any variable has been set. False is returned otherwise.

set(vari_idx: int | bool = 0, all_children: bool = False, count: int = -1, enable_autotags: bool = True) → 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).

• enable_autotags – Enable setting of autotags if they are enabled in self.config.

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) → bool

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.

Returns:

True if any variable has been cleared. False is returned otherwise.

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>>, tag_implct_iter: str = '*', autotag_blk_var: str = '@', autotag_align: str = '+', autotag_vari: str = '.', subelem_sep: str = '.', tab_size: int = 4, enable_autotags: bool = True)

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 variable name name to 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 block name name to 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 block name name to 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 block name name to string <^NAME>.

Type:

Callable[[str], str]

tag_implct_iter

The implicit iterator tag symbol. Defaults to *.

Type:

str

autotag_blk_var

The block variable automatic tag symbol. Defaults to @.

Type:

str

autotag_align

The alignment automatic tag symbol. Defaults to +.

Type:

str

autotag_vari

The variation automatic tag symbol. Defaults to ..

Type:

str

subelem_sep

A subelement reference separator. 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

enable_autotags

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

Type:

bool