CMCore

Presentation

CMCore is a Python package designed to manage the different low-level GAP Audio Framework objects from a high-level point of view.

It allows to create graphs and components thanks to an easy to use API, and to

As such, it allows the user to create, edit, manage graphs, nodes and component, as well as import and export configuration files for those objects.

Structure

  • src/cmcore contains the source code of the module,

  • examples presents a number of examples of use of the module,

  • src/tests contains all the tests to be able to test the module during its development.

API structure

All the files described in the following section are located in the src/cmcore folder.

__init__.py

This is the base file of the module. Importing the CMCore module allows the user to directly use all the objects and functions declared in that file.

  • __version__

  • Node is the class used to declare nodes and graphs. NodeInput & NodeOutput their inputs and outputs (see below).

  • Component is the main component class. Parameter, Implementation, ComponentInput and ComponentOutput are objects contained in that class (see below).

  • import_graph & import_component are bot functions that can be used to respectively import a graph or component from a .graph or .comp file. It will work with both v1 (YAML) and v0 (JSON) files.

__version__.py

This file indirectly manages the version of the module.

The actual version is managed in setup.cfg configuration file, at the root of the module.

gdrc.py

This file loads and manages the configuration file “~/.gdrc”. That configuration file contains component_libraries_paths, a list of all locations where CMCore will look for component templates.

components.py

This file declares and manages the Component object class, and other objects and methods related to it.

The main methods of the Component object are:

  • Those used to manage the object’s attributes.

    • If an attribute is a single value, it will typically be set through a Component.set_<attribute>(**attribute_properties) method.

    • If an attribute is a collection, like a list of values or a dictionary, it will have three main methods:

      • add_<attribute>(**attribute_properties), which will add one item to the collection of attributes.

      • add_<attributes>(attribute1, attribute2, ...) adds as many pre-formatted attributes to the collection as the user wishes. Its upside is to be able to avoid several uses of the add_attributes method, its downside is that it requires the attribute to be correctly formatted.

      • pop_<attributes>(attribute1, attribute2, ...), which works like Python’s own pop method: it will remove the named attribute from the collection and will return them in a list.

  • the Component.read(component_dict) method converts component_dict to a correctly formatted Component object.

The main objects declared are:

  • Parameter is the parameter object class, used to declare all the parameters a parent component can have.

  • Implementation describes the various implementations a parent component can have.

  • ComponentInput and ComponentOutput are twin objects, in the sense that they share all methods and attributes. They’re used to declare a component inputs and outputs, and their properties.

All those objects have different attributes, which can all be set at intialization or through similar API methods as the ones used in Component.

nodes.py

This file declares and manages the Node object class, and other objects and methods related to it. It is used to manage graphs, nodes, subgraphes and subnodes. When a node is declared with a template, it also fetches the aforementioned template from the GAP SDK, and uses it to self-populate.

The main methods of the Node object are:

  • Those used to manage the object’s attributes.

    • If an attribute is a single value, it will typically be set through a set_<attribute>(**attribute_properties) method.

    • If an attribute is a collection, like a list of values or a dictionary, it will have three main methods:

      • add_<attribute>(**attribute_properties), which will add one item to the collection of attributes.

      • add_<attributes>(attribute1, attribute2, ...) adds as many pre-formatted attributes to the collection as the user wishes. Its upside is to be able to avoid several uses of the add_attributes method, its downside is that it requires the attribute to be correctly formatted.

      • pop_<attributes>(attribute1, attribute2, ...), which works like Python’s own pop method: it will remove the named attribute from the collection and will return them in a list.

  • the Node.read(node_dict) method converts node_dict to a correctly formatted Node object.

The two objects used in Node are ComponentInput and ComponentOutput. They also are twin objects, meaning that they share all methods and attributes. They’re used to declare a node inputs and outputs, and their properties.

All those objects have different attributes, which can all be set at intialization or through similar API methods as the ones used in Node.

generic_io.py

Used to manage the import and dump functions for both graphs and components, in both v1 (YAML) and v0 (JSON). The main functions and methods declared in that file are:

  • import_graph: converts a v1 or v0 graph to a populated Node object.

  • import_component: converts a v1 or v0 component to a populated Component object.

  • <node>.dump: generates a v1 or v0 component .graph file from a populated Node object.

  • <component>.dump: generates a v1 or v0 component .comp file from a populated Component object.

yaml_io.py and json_io.py

Respectively for imports and dumps of v1 (YAML) and v0 (JSON, deprecrated) files.

errors.py

Custom errors

utils.py

Collection of utility functions, potentially used by any other part of the code.

compat_v0.py

Collection of functions used to keep the compatibility with the v0 file system.

Using

The only pre-requisite to be able to use CMCore is to source the GAP SDK.

Examples

Examples on how to use the library.

Testing

All the CMCore tests are located in “src/tests”. All tests can be ran through the script “run.py”.

Visual Studio Code content

The vscode folder contains a workspace dedicated to the development and debug tasks and profiles for this module on Visual Studio Code (VSCode):

  • cmcore.code-worksace is the VSCode workspace

  • launch.json contains the launch tasks:

    • package cmcore allows to update the CMCore Python package

    • package cmcore (editable) updates the CMCore Python package in editable mode, for debug purposes.

  • tasks.json contains one task, CMCore: Current File, which updates CMCore in editable mode and runs the selected script.