Yawning-Titan DB#

Yawning-Titan comes packages with a lightweight document database (See: TinyDB).

The YawningTitanDB class#

A base class, YawningTitanDB, exists that provides extended TinyDB functions __init__(), insert(), update(), upsert(), all(), get(), search(), count(), remove(), and close(), methods. All methods provided have either direct calls to their their TinyDB counterpart, or some custom Yawning-Titan login before the call. Methods have been defined as abstract methods to force sub-classes of YawningTitanDB to implement them. If functionality does not change, the implementations of the abstract methods can simple call super() to trigger the default logic.

When YawningTitanDB.__init__ is called, the name passed to it is used to generate a filepath using yawning_titan.DB_DIR. For example, calling YawningTitanDB("demo") would generate a TinyDB db .json file at:

  • Linux - ~/.local/share/yawning_titan/db/demo.json

  • Windows - ~/AppData/yawning_titan/yawning_titan/db/demo.json

  • MacOs - ~/Library/Application Support/yawning_titan/db/demo.json

The YawningTitanQuery class#

The YawningTitanQuery extends tinydb.queries.Query by implementing len_eq(), len_gt(), len_ge(), len_lt(), and len_le() functions to test the length of a field.

The EntryNodeCompatibilityQuery class#

The EntryNodeCompatibilityQuery extends tinydb.queries.Query by implementing works_with(). This function allows for the game mode to be checked against a provided Network or an integer number of entry nodes. Game modes where the number of entry nodes is unrestricted or the provided value falls within the restricted range will be returned.

The HighValueNodeCompatibilityQuery class#

The HighValueNodeCompatibilityQuery extends tinydb.queries.Query by implementing works_with(). This function allows for the game mode to be checked against a provided Network or an integer number of high value nodes. Game modes where the number of high value nodes is unrestricted or the provided value falls within the restricted range will be returned.

The NetworkNodeCompatibilityQuery class#

The NetworkNodeCompatibilityQuery extends tinydb.queries.Query by implementing works_with(). This function allows for the game mode to be checked against a provided Network or an integer number of total network nodes. Game modes where the number of total network nodes is unrestricted or the provided value falls within the restricted range will be returned.

The NetworkCompatibilityQuery class#

The NetworkCompatibilityQuery extends tinydb.queries.Query by implementing compatible_with(). This function allows for the game mode to be checked against a provided network. This query will check all restricted network attributes are compatible with the properties of the provided Network.

The NetworkDB and NetworkSchema classes#

The NetworkDB class, used for inserting, querying, updating, and deleting instances of Network, relies upon YawningTitanDB at NetworkDB._db. It wraps the YawningTitanDB functions, insert(), update(), upsert(), all(), get(), search(), count(), remove(), with the return types overridden to return Network. The NetworkDB class writes to a network.json file at:

  • Linux - ~/.local/share/yawning_titan/db/network.json

  • Windows - ~/AppData/yawning_titan/yawning_titan/db/network.json

  • MacOs - ~/Library/Application Support/yawning_titan/db/network.json

First, we must instantiate the NetworkDB with:

from yawning_titan.networks.network_db import NetworkDB
db = NetworkDB()

Next, we have the option to query the db with either the standard tinydb.queries.Query class, the extended YawningTitanQuery class, or by using the network config specific NetworkSchema class. Here we will use NetworkSchema. The NetworkSchema class has an attribute mapped to each attribute of Network as an instance of YawningTitanQuery. This gives direct access to the specific field within the TinyDB db file.

The following code blocks demonstrate how to use combinations of the NetworkSchema class to build a Query chain to query the NetworkDB.

Search for all network configs that have “1” as an entry node:

results = db.search(NetworkSchema.ENTRY_NODES.all(["1"]))

Search for all network configs that have “1” as both an entry node and a high value node:

results = db.search(
    NetworkSchema.ENTRY_NODES.all(["1"]))
    and (NetworkSchema.HIGH_VALUE_NODES.all(["1"])
)

Search for all network configs that have at least 3 high value nodes

results = db.search(NetworkSchema.ENTRY_NODES.len_ge(3))

The NetworkDB comes pre-packaged with default network functions:

There networks are stored in a ‘backup’ yawning_titan/networks/_package_data/network.json db file. If the default networks become corrupted, they can be reset using the reset_default_networks_in_db() function.

As a last resort, the entire db can be rebuilt using the rebuild_db() function.

Warning

This function completely rebuilds the database. Any custom networks saved in the db will be lost.

The GameModeDB and GameModeSchema classes#

The GameModeDB class, used for inserting, querying, updating, and deleting instances of GameMode, relies upon YawningTitanDB at GameModeDB._db. It wraps the YawningTitanDB functions, insert(), update(), upsert(), all(), get(), search(), count(), remove(), with the return types overridden to return GameMode. The GameModeDB class writes to a game_modes.json file at:

  • Linux - ~/.local/share/yawning_titan/db/game_modes.json

  • Windows - ~/AppData/yawning_titan/yawning_titan/db/game_modes.json

  • MacOs - ~/Library/Application Support/yawning_titan/db/game_modes.json

First, we must instantiate the GameModeDB with:

from yawning_titan.game_modes.game_mode_db import GameModeDB
db = GameModeDB()

Next, we have the option to query the db with either the standard tinydb.queries.Query class, the extended YawningTitanQuery class, or by using the game mode specific GameModeSchema class. Here we will use GameModeSchema. This class has an attribute mapped to each attribute of the attributes of GameMode (including all nested descendants) as an instance of YawningTitanQuery. This gives direct access to the specific field within the TinyDB db file.

The GameModeSchema also exposes features that allow for

The following code blocks demonstrate how to use combinations of the GameModeSchema class to build a Query chain to query the GameModeDB.

Search for all game modes where the red agent ignores defences:

results = db.search(GameModeSchema.CONFIGURATION.RED.AGENT_ATTACK.IGNORES_DEFENCES.all([True]))

Search for all game modes where the red agent ignores defences and where the red agents attack alwys succeeds:

results = db.search(
    GameModeSchema.CONFIGURATION.RED.AGENT_ATTACK.IGNORES_DEFENCES.all([True])
    and (GameModeSchema.CONFIGURATION.RED.AGENT_ATTACK.ALWAYS_SUCCEEDS.all([True])
)

Search for all game modes where the blue agent uses at least 3 deceptive nodes:

results = db.search(GameModeSchema.BLUE.ACTION_SET.DECEPTIVE_NODES.MAX_NUMBER.ge(3))

The GameModeDB comes pre-packaged with default game mode functions:

The game modes are stored in a ‘backup’ yawning_titan/game_modes/_package_data/game_modes.json db file. If the default networks become corrupted, they can be reset using the reset_default_game_modes_in_db() function.

As a last resort, the entire db can be rebuilt using the rebuild_db() function.

Warning

This function completely rebuilds the database. Any custom game modes saved in the db will be lost.