Usage¶

This library can be used in multiple ways. You can load .frb board files, .yaml descriptor files, and .zip bundle files respectively. You can also load bundles from a directory of files, and you can run validation tests on any or all of these files, as well.

Loading Boards¶

You can use this library to load CSMM-compatible board bundles, as well as Fortune Avenue-compatible .frb files, and CSMM-comatible.yaml descriptor files. This guide will walk you through all of them, so feel free to skip to the section most relevant to you.

How to Load a Board¶

The method will differ slightly depending on the files available to you.

.zip board bundle file¶

Python 3.10+

from cs_board_tools.io import read_zip


def test_reading_zip_file():
    filename="WiiU.zip"
    bundles = read_zip(filename)
    board_bundle = bundles[0]

The read_zip function returns a list of Bundles. In the example above, that list would contain only one Bundle (for the Wii U board), but you could, in theory, zip up a number of boards together and get results for all of them at the same time.

a list of files in a directory¶

Python 3.10+

from cs_board_tools.io import read_files


def reading_list_of_files():
    files=["WiiU.yaml", "WiiU.png", "WiiU.webp", "WiiU.frb"]
    bundles = read_files(files)
    board_bundle = bundles[0]

The read_files function also returns a list of Bundles.

.yaml file only¶

Python 3.10+

from cs_board_tools.io import read_yaml


def reading_yaml():
    filename="WiiU.yaml"
    descriptor = read_yaml(f"./tests/artifacts/{filename}")

When loading a .yaml descriptor file, the object returned is a MapDescriptor object, rather than a full bundle. As such, the read_yaml function returns just that.

.frb file only¶

Python 3.10+

from cs_board_tools.io import read_frb


def reading_frb():
    filename="WiiU.frb"
    frb = read_frb(f"./tests/artifacts/{filename}")

The read_frb function returns a BoardFile object, representing only the data that is stored in the .frb file directly.

Validating Boards¶

Validating boards is incredibly simple!

How to Validate a Board¶

To validate a board, you must first load it. Please see the Loading Boards section for more information. Once you have your list of Bundles, you can pass them in for validation like so:

Python 3.10+

from cs_board_tools.io import read_zip
from cs_board_tools.validation import validate_board_bundle

filename = "WiiU.zip"
bundles = read_zip(filename)          # load the bundle
result = validate_board_bundle(bundles) # validate it

Now, you can get all of the validation details from that object.

Python 3.10+

# print any error messages
print(result.error_messages)

# print only the first error message
print(result.error_messages[0])

# there are also lists for warnings and informational messages, too.
print(result.informational_messages)
print(result.warning_messages)

#print the number of tests with errors or warnings
print(result.issue_count)

# print the number of successful tests
print(result.success_count)

# print the status of the Door and Dice check
print(result.boards[].door.status)

The next section contains charts showing in detail the attributes available in this result ValidationResultBundle object, as well as the attributes available in the objects nested within. These objects give you access to all of the result data from the validation operation.

Object Attributes¶

ValidationResultBundle (top-level object)¶

attribute	type	description
error_count	int	Number of errors.
warning_count	int	Number of warnings.
issue_count	int	(errors + warnings)
success_count	int	Number of successful tasks.
total_count	int	Total tasks. (successful and not)
error_messages	list[str]	All error messages in list form.
informational_messages	list[str]	All informational messages in list form.
warning_messages	list[str]	All warning messages in list form.
boards	list[ValidationResult]	List of objects representing the results for each board.

ValidationResult (board-level object)¶

attribute	type	description
board_name	str	The name of the board that the validation results pertain to.
paths	int	The maximum number of paths for any square on the board.
error_count	int	Number of errors.
warning_count	int	Number of warnings.
issue_count	int	(errors + warnings)
success_count	int	Number of successful tasks.
total_count	int	Total tasks. (successful and not)
board_configuration	CheckResult	The results of the Board Configuration checks.
consistency	CheckResult	The results of the frb/yaml consistency check.
icon	CheckResult	The results of the Board Icon check.
max_paths	CheckResult	The results of the max paths check.
music_download	CheckResult	The results of the music download check.
naming	CheckResult	The results of the naming convention check.
screenshots	CheckResult	The results of the max paths check.
venture	CheckResult	The results of the venture card check.
yaml	CheckResult	The results of the yaml validation check.
error_messages	list[str]	All error messages in list form.
informational_messages	list[str]	All informational messages in list form.
warning_messages	list[str]	All warning messages in list form.

CheckResult (individual check-level)¶

attribute	type	description
data	any	Can store anything you would like. Currently only used by the Max Paths check to return that value.
status	str	`OK`, `WARNING`, `ERROR`, or `SKIPPED`
error_messages	list[str]	A list of `error` messages.
informational_messages	list[str]	A list of `informational` messages.
warning_messages	list[str]	A list of `warning` messages.

CLI¶

cs-board-tools can be used from the terminal to display information about Fortune Avenue-compatible .frb files, CSMM-compatible .yaml descriptor files, or Board Bundles either via .zip archive files, or by reading in files from a directory. It has two main commands: display and validate, and they work the same regardless of the type of input file you are passing in.

Displaying¶

Validating¶

Optional Flags¶

The Validation function supports a number of optional flags to change the behavior of the tests. These flags are detailed in the table below for easy reference.

short flag	long flag	description
`-g`	`--gdrive-api-key`	Allows specifying a Google Drive API key for the Music Download test.
`-sbc`	`--skip-board-configuration-test`	Skips the Board Configuration tests.
`-sct`	`--skip-consistency-test`	Skips the Consistency tests.
`-sdt`	`--skip-music-download-test`	Skips the Music Download tests.
`-sit`	`--skip-icon-test`	Skips the Board Icon tests.
`-snt`	`--skip-naming-convention-test`	Skips the Naming Convention tests.
`-spt`	`--skip-max-paths-test`	Skips the Max Paths tests.
`-sst`	`--skip-screenshot-test`	Skips the Screenshot tests.
`-svt`	`--skip-venture-card-test`	Skips the Venture Card tests.
`-sw`	`--skip-warnings`	Silences warnings from output.