Support for rest of the database API (non-RT)

[jashnani]

Implement the Database file API

• open_database
  • How does nxCreateSession know which database is :inmemory:? Is it one opened with "alias" being :inmemory:? If so, should we default open with :inmemory:?
• close_database
  • Should we expose "close all refs"?
• database properties
  • Ecu.lin_protocol_ver should return an enum #54 Ecu.lin_protocol_ver doesn't return an enum
  • Frame.pdu_* properties should be considered for a tuple #53 Frame.pdu_* should be a tuple
  • Ref properties get/set integers #48 Ref properties return objects
  • Cluster.pd_us_reqd has wrong word-splitting #209 PDU word splitting
• dbc attribute support
• save_database
• merge
• create_object
• Exposing descendant find #239 find_object
• delete_object
• create_session_by_ref
  • Should this be deferred to Unplanned?
    • Is there a use case that requires it?
    • Are there cases where this would be heavily used if available?

Parts to include:

• Implementation
• Type annotations
• Type conversions (like enums)
• Documentation
  • Be sure that the property names make sense to help catch issues like Cluster.pd_us_reqd has wrong word-splitting #209
  • Watch out for sentinel values that don't map well to the python API (example)
• Examples
• Tests

For RT database support, see #202.

[epage]

From @jashnani's research:

In C API, it looks like ‘nxdbCloseDatabase’ uses ‘nxDatabaseRef_t’ type. This type is used by other database objects as well (i.e. Cluster, Frame, PDU, etc.). This makes it ambiguous whether you need to call nxdbCloseDatabase on all objects or just the Database object.

In checking further, the object references are owned by the Database, should not be closed explicitly, and will be closed when the Database reference count drops to 0.

[epage]

From @jashnani's research:

nxdbOpenDatabase can take either an alias or a filepath. We've confirmed that you can open a database file that has not had nxdbAddAlias or nxdbDeploy called.

[epage]

A basic outline of database objects and their properties was added in #52.

This includes

• nxdbCloseDatabase
• nxdbSaveDatabase
• nxdbMerge

This lacks

• Tests
• Documentation
• Type annotations
• Type conversions (returning enums instead of ints, objects instead of ints)

[epage]

#210

• Rename save_database to save because the context makes that unambiguous
• Default save's filepath to a blank string for overwriting the current file
• Support nxdbCreateObject via parent.children.add("name")
• Support nxdbDeleteObject via del parent.children["name"]
• Support nxdbFindObject via parent.children["name"]
• Changed ref children from a generator to parent.children.__iter__

Things that are still missing

• Deleting objects by ref. This doesn't map as directly in python and the
  hope is no one needs it.
• All other ref properties returning objects. A lot of these have circular imports which
  will need to be addressed.
• Exposing descendant find (like myFrameA.mySignal). Via getitem, you can get a direct
  descendant by name but not indirect descendants. Each parent object
  will need an explicit find added to it. This will also run into
  problems with circular imports.

[epage]

• Question:
  • nxdbCreateObject lists what objects can be created under what parents (see nxdbCreateObject documentation)
    • Cluster:Signals makes it sound like you can create signals directly under clusters but that isn’t documented in nxdbCreateObject (see Signals documentation)
    • Frame MUX Signals or SubFrame Signals make it sound like you can create signals directly under Frame or SubFrame but that isn’t documented in nxdbCreateObject
      • See Mux:Static Signals documentation
      • See Dynamic Signals documentation
    • Which cases work and don’t work beyond what is documented in nxdbCreateObject?
• Answer:
  • Frame.signals and Cluster.signals are aggregates and not owning properties
  • SubFrame.dyn_sig_refs and Frame.mux_static_sig_refs is the parent of signals.

[epage]

#212 made some teaks to #210

[lilesj]

I suggest starting out with these examples for the database API:

• Dynamic Database Creation: Use the in-memory database to create a new CAN cluster and set cluster level properties such as baud rate. Then pro grammatically add frames to the cluster and then add signals to the frames. Finally, save/export the in-memory database to a database file. (Effectively combining the CAN Dynamic Database Creation and Editing a Database with IO Controls shipping examples)

• Managing Local Databases: An example that demonstrates how to add and remove database aliases from the local system.

[d-bohls]

#237 adds annotations and docs.

I'm creating separate issues for the remaining items so we can have better visibility into what's left.

#238
#239
#240
#241