Documentation for Liquidsoap interface
After talk with @Loxbie the description ticket description below is not up to date. Due to the dynamic approach of client class, we think more about providing detailed documentation, rather than changing implementation.
This ticket follows an exchange with @Loxbie. Currently commands to Engine Core/Liquidsoap are defined in Engine with Strings scattered all over the place.
To ensure the called commands are correctly named we want to add a static list of all used commands.
Proposal
- Add
Command
Enum incore/client.py
holding a list of all commands. - Replace all String definitions, method arguments and type information in the code with the new Command Enum value. E.g. Instead of
self.client.exec(self.mixer_id, "status", channel_number)
it would beself.client.exec(self.mixer_id, Command.STATUS, channel_number)
. Type ofdef exec(self, namespace: str, action: str, args: str = "") -> str:
would bedef exec(self, namespace: str, action: Command, args: str = "") -> str:
etc. - Add DocStrings explaining the commands in the Enum header
- Currently it is unclear how to deal with parameterized or namespaced commands, like the ones which use channels as a basis. They could be implemented using some placeholders in the enum attribute e.g.
VOLUME = "{channel_id}.volume"
orSTATUS = "{namespace}.status"
. Another simplified approach could be leaving the prefix completely out, but this doesn't fully support the aim of having an overview of the actual commands. It also reduces test-ability.
Alternatively the commands could be implemented in form of Class and in an OOP way, where each command represents a method. I have the feeling that this is too over-engineered and actually moves us away from the quick overview of available/used commands
Edited by David Trattnig