API design guidelines

• The Python APIs will be "Pythonic"

  • Follow Python coding conventions
  • Use classes to represent each API session
  • Expose API properties as properties of Session
  • Use context managers where appropriate:
    • Session lifetime
    • Acquisition / Generation control
  • Use Exceptions for errors
  • Use warnings package for warnings
  • Handle memory allocation
  • Return values rather than modify references
  • Use native Python datatypes as much as possible

• The APIs will be a close 1-to-1 mapping of the C APIs

  • Method names will be derived from C function names
  • Enums:
    • Names will be derived from LabVIEW control names (C API has no enums)
    • Values will be derived from C constant names

• Deviate from the C APIs in the following ways

  • No support for external calibration
  • Don't include obsolete functions / properties
    • Anything obsoleted after initial release will need to be handled differently
  • Don't include functions that are simple wrappers around setting/getting an attribute
    • Redundancy means confusion
    • Don't get type safety benefit that you get in C function
  • If there's debate on whether a function should be included or not, then don't.
    • Trivial to add if needed.
    • Hard to remove once added.

• Have default values for methods

  • For the most part, defaults are a subset of the defaults in the corresponding LabVIEW VIs
    • Don't have as many defaults as LabVIEW APIs, where they went overboard.
    • Deviate from LabVIEW defaults only in very specific cases (i.e. open session with reset=False)

• Provide high-performance alternative to Python lists for reading/writing waveforms

  • Based on numpy arrays
  • "Advanced" API for users who need it or care about it

We acknowledge that we could go further and provide more OOP abstractions or improve the signatures of some functions if we were designing these Python APIs by hand. For example, we could provide classes for NI-FGEN's frequency lists, scripts, etc. However, in order to reduce the scope of the project and make code-generation viable, we have decided against it.