Core - Lib Module

anvil.lib.lib

A collection of useful functions and classes used throughout the program.

OUTPUT = Path('output') module-attribute

The project's output folder, for packages and local exports.

AnvilArchive

from_mapping(zip_name, dir_list) classmethod

Create a ZIP archive containing multiple directories and files.

Parameters:

Name	Type	Description	Default
zip_name	Path	The ZIP archive to write.	required
dir_list	dict[Path, PurePosixPath]	The folders and files to add, each mapped to the folder it goes in inside the archive.	required

Note

The target directories represent the structure inside the ZIP archive.

AnvilFormatter

convert_color(color, target=None) classmethod

Converts a color from any supported format to the target format.

Supported input formats: - Hex string: "#RRGGBB", "#RRGGBBAA", "#RGB", or "#RGBA" (short format) - RGB/RGBA (0-1): tuple of 3 or 4 floats in range [0, 1] - RGB255/RGBA255 (0-255): tuple of 3 or 4 ints in range [0, 255]

Parameters:

Name	Type	Description	Default
color	Color	The input color in any supported format.	required
target	Color | None	The target color type (RGB, RGBA, RGB255, RGBA255, HexRGB, or HexRGBA). If None, returns normalized version of input format.	None

Returns:

Name	Type	Description
Color	Color	The color converted to the target format.

Raises:

Type	Description
ValueError	If the color format is invalid or cannot be determined.
TypeError	If the color type is not supported.

Examples:

>>> convert_color("#FF0000", RGB)
(1.0, 0.0, 0.0)
>>> convert_color("#F00", RGB)
(1.0, 0.0, 0.0)
>>> convert_color("#F00")  # No target, normalizes to full hex
"#ff0000"
>>> convert_color((1.0, 0.0, 0.0), HexRGB)
"#ff0000"
>>> convert_color((1.0, 0.0, 0.0), HexRGBA)
"#ff0000ff"
>>> convert_color((255, 0, 0), RGB)
(1.0, 0.0, 0.0)
>>> convert_color((0.5, 0.5, 0.5), RGBA)
(0.5, 0.5, 0.5, 1.0)
>>> convert_color((128, 64, 32))  # No target, normalizes to RGB255
(128.0, 64.0, 32.0)

AnvilIO

file(name, content, directory, mode) classmethod

Create or modify a file with the given content.

Parameters:

Name	Type	Description	Default
name	str	The name of the file.	required
content	Any	The content of the file.	required
directory	str | Path	The folder where the file is created or modified.	required
mode	str	The file mode, either "w" (write) or "a" (append).	required

Note

The file content is converted to the appropriate format based on the file extension.

AnvilValidator

is_color_value(value) classmethod

Check if a value is a color value (not a texture file name). Returns True for RGB/RGBA tuples and hex color strings. Returns False for texture file names (plain strings without # prefix).

Directory

copy_files(old_dir, new_dir, target_file, rename=None) classmethod

Copies a file from one directory to another.

Parameters:

Name	Type	Description	Default
old_dir	str | Path	The path to the source directory.	required
new_dir	str | Path	The path to the destination directory.	required
target_file	str	The name of the file to be copied.	required
rename	str | None	The new name for the copied file. Defaults to None.	None

copy_folder(old_dir, new_dir) classmethod

Copies a folder and all its contents to a new location.

Parameters:

Name	Type	Description	Default
old_dir	str | Path	The path to the source directory.	required
new_dir	str | Path	The path to the destination directory.	required

create(path) classmethod

Creates a new directory, with its missing parents.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the new directory. A relative path is relative to the current folder.	required

move_folder(old_dir, new_dir) classmethod

Moves a folder and all its contents to a new location.

Parameters:

Name	Type	Description	Default
old_dir	str | Path	The path to the source directory.	required
new_dir	str | Path	The path to the destination directory.	required

clamp(value, _min, _max)

Clamps a value between a minimum and maximum limit.

Parameters:

Name	Type	Description	Default
value	float | int	The value to be clamped.	required
_min	float | int	The lower limit.	required
_max	float | int	The upper limit.	required

Returns:

Name	Type	Description
float	float | int	The clamped value.

frange(start, stop, num=1)

Generate a list of interpolated float values between start and stop.

Parameters:

Name	Type	Description	Default
start	int	The starting value.	required
stop	int	The ending value.	required
num	float	The number of values to generate. Defaults to 1.	1

Returns:

Type	Description
list[float]	list[float]: A list of interpolated values between start and stop.

process_subcommand(command, error_handle='Error', exit_on_error=False)

Executes a subprocess command with error handling.

Parameters:

Name	Type	Description	Default
command	str	The command to execute.	required
error_handle	str	Error message prefix. Defaults to "Error".	'Error'
exit_on_error	bool	Exit with the subprocess return code on failure instead of continuing (needed for CI so a failed build fails the job).	False

salt_from_str(s)

Generates a hash value from a string for use as a random seed.

Parameters:

Name	Type	Description	Default
s	str	The input string to hash.	required

Returns:

Name	Type	Description
int	int	A hash value derived from the input string.

validate_platform()

Validates that Anvil is running on a supported platform.

Only Linux, macOS, and Windows are supported.