API Metadata

Overview

API Metadata is extracted using internal tools at NI. This produces several files which are then uploaded to this Git repository. Since these files are generated, they should not be manually changed, as any edits will be lost next time new versions of the files are uploaded. The files contain simple Python dictionaries and their contents are hopefully self-explanatory.

• src//metadata/functions.py
• src//metadata/enums.py
• src//metadata/attributes.py

In addition, the following files are also sourced in the Git repository, but are hand-coded by the nimi-python developers.

• src//metadata/config.py: General driver information.
• src//metadata/init.py: Makes it simple for the nimi-python code generator to load the metadata.
• src//metadata/attributes_addon.py: Additions / overrides applied on top of attribute metadata (as loaded from attributes.py)
• src//metadata/functions_addon.py: Additions / overrides applied on top of function metadata (as loaded from attributes.py)

These "add on" files are important because the Python API is "richer" in a sense than the source of the extracted metadata (based on the C API). In Python, memory management is done for the client. In Python, we want to leverage enums. In Python, you can have default values for arguments. This is the sort of thing we need to include in this "add on" Pythons-specific metadata.

Size info

In our C APIs, all memory management is left to the client. Through documentation, the client learns what needs to be done. In the nimi-python case, we want our Python bindings to handle all buffer allocation.

We do this by specifying parameter metadata which the code generator uses in order to create the correct code in the generated Python bindings. Array and string parameters have this metadata:

{'is_buffer': True}

We specify a size metadata which points to a dictionary with two keys: mechanism and value.

These are the valid values for the size metadata:

  'fixed':        The size is known at compile time, usually defined by the API.
                  'value' should be an int indicating the size that the passed-in array must have.
  'passed-in':    The size of the array parameter is specified in another parameter.
                  'value' should be the name of the parameter through which this is specified.
                  This is used in functions in which the array is returned, so the array input
                  parameter is omitted from the public Python API.
  'ivi-dance':    The size is determined by calling into the function using a size of zero and
                  interpreting the return value as a size rather than an error.
                  'value' should be the name of the parameter through which the size (0 the first
                  call, then the real value on the second call) is passed in.
                  This is used in functions in which the array is returned, so the array input
                  parameter is omitted from the public Python API.
        'len':    Used for input arrays, the size is determined by calling len() on the parameter.
                  The size parameter from the C function is omitted from the public Python API.