feat(API): Adding partial database API support

MANIFEST.in

@@ -3,4 +3,5 @@ include LICENSE
 include nixnet/VERSION
 recursive-include nixnet *.py
 recursive-include nixnet_examples *.py
+include nixnet_examples/databases/custom_database.dbc
 recursive-include tests *.py

docs/api_reference.rst

@@ -9,6 +9,7 @@ API Reference
    :caption: Table of Contents:
 
    api_reference/session
+   api_reference/system
    api_reference/convert
    api_reference/constants
    api_reference/types

docs/api_reference/databases.rst

@@ -0,0 +1,7 @@
+nixnet.session.databases
+========================
+
+.. automodule:: nixnet.system.databases
+    :members:
+    :inherited-members:
+    :show-inheritance:

docs/api_reference/system.rst

@@ -0,0 +1,13 @@
+nixnet.system
+=============
+
+.. automodule:: nixnet.system
+    :members:
+    :show-inheritance:
+    :inherited-members:
+
+.. toctree::
+   :maxdepth: 3
+   :caption: API Reference:
+
+   databases

docs/examples.rst

@@ -12,4 +12,5 @@ Examples
    examples/stream_io
    examples/single_point_io
    examples/conversion
-   examples/can_lin_diff
+   examples/can_lin_diff
+   examples/programmatic_databases

docs/examples/programmatic_databases.rst

@@ -0,0 +1,8 @@
+Programmatic Database Usage
+===========================
+
+This example uses :any:`nixnet.system.databases.Databases` to demonstrate how
+databases can be programmatically added and used in a system.
+
+.. literalinclude:: ../../nixnet_examples/programmatic_database_usage.py
+   :pyobject: main

nixnet/_funcs.py

@@ -712,3 +712,45 @@ def nxdb_undeploy(
         database_alias_ctypes,
     )
     _errors.check_for_error(result.value)
+
+
+def nxdb_get_database_list(
+    ip_address,  # type: typing.Text
+    size_of_alias_buffer,  # type: int
+    size_of_filepath_buffer,  # type: int
+):
+    # type: (...) -> typing.Tuple[typing.List[typing.Text], typing.List[typing.Text], int]
+    ip_address_ctypes = _ctypedefs.char_p(ip_address.encode('ascii'))
+    size_of_alias_buffer_ctypes = _ctypedefs.u32(size_of_alias_buffer)
+    size_of_filepath_buffer_ctypes = _ctypedefs.u32(size_of_filepath_buffer)
+    alias_buffer_ctypes = ctypes.create_string_buffer(size_of_alias_buffer)
+    filepath_buffer_ctypes = ctypes.create_string_buffer(size_of_filepath_buffer)
+    number_of_databases_ctypes = _ctypedefs.u32()
+    result = _cfuncs.lib.nxdb_get_database_list(
+        ip_address_ctypes,
+        size_of_alias_buffer_ctypes,
+        alias_buffer_ctypes,
+        size_of_filepath_buffer_ctypes,
+        filepath_buffer_ctypes,
+        number_of_databases_ctypes,
+    )
+    _errors.check_for_error(result.value)
+    alias_buffer = alias_buffer_ctypes.value.decode("ascii")
+    filepath_buffer = filepath_buffer_ctypes.value.decode("ascii")
+    return alias_buffer, filepath_buffer, number_of_databases_ctypes.value
+
+
+def nxdb_get_database_list_sizes(
+    ip_address,  # type: typing.Text
+):
+    # type: (...) -> typing.Tuple[int, int]
+    ip_address_ctypes = _ctypedefs.char_p(ip_address.encode('ascii'))
+    size_of_alias_buffer_ctypes = _ctypedefs.u32()
+    size_of_filepath_buffer_ctypes = _ctypedefs.u32()
+    result = _cfuncs.lib.nxdb_get_database_list_sizes(
+        ip_address_ctypes,
+        size_of_alias_buffer_ctypes,
+        size_of_filepath_buffer_ctypes,
+    )
+    _errors.check_for_error(result.value)
+    return size_of_alias_buffer_ctypes.value, size_of_filepath_buffer_ctypes.value

nixnet/nxdb.py

@@ -23,18 +23,6 @@ def delete_object(db_object_ref):
     _funcs.nxdb_delete_object(db_object_ref)
 
 
-def add_alias64(
-        database_alias,
-        database_filepath,
-        default_baud_rate):
-    _funcs.nxdb_add_alias64(database_alias, database_filepath, default_baud_rate)
-
-
-def remove_alias(
-        database_alias):
-    _funcs.nxdb_remove_alias(database_alias)
-
-
 def deploy(
         ip_address,
         database_alias,
@@ -46,13 +34,3 @@ def undeploy(
         ip_address,
         database_alias):
     _funcs.nxdb_undeploy(ip_address, database_alias)
-
-
-def get_database_list(
-        ip_address,
-        size_of_alias_buffer,
-        alias_buffer,
-        size_of_filepath_buffer,
-        filepath_buffer,
-        number_of_databases):
-    raise NotImplementedError("Placeholder")

nixnet/system/databases.py

@@ -0,0 +1,145 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import collections
+import typing  # NOQA: F401
+
+import six
+
+from nixnet import _funcs
+
+
+class Databases(collections.Mapping):
+    """Database aliases."""
+
+    def __init__(self, handle):
+        self._handle = handle
+
+    def __repr__(self):
+        return 'System.Databases(handle={0})'.format(self._handle)
+
+    def __get_database_list(self, ip_address):
+        alias_buffer_size, filepath_buffer_size = _funcs.nxdb_get_database_list_sizes(ip_address)
+        aliases, filepaths, _ = _funcs.nxdb_get_database_list(ip_address, alias_buffer_size, filepath_buffer_size)
+        return list(zip(aliases.split(","), filepaths.split(",")))
+
+    def __len__(self):
+        return len(self.__get_database_list(''))
+
+    def __iter__(self):
+        return self.keys()
+
+    def __getitem__(self, index):
+        # type: (str) -> Database
+        """Return the Database object associated with the specified alias.
+
+            Args:
+                index(str): The value of the index (alias name).
+        """
+        if isinstance(index, six.string_types):
+            for alias, filepath in self.__get_database_list(''):
+                if alias == index:
+                    return self._create_item(alias, filepath)
+            else:
+                raise KeyError('Database alias %s not found in the system' % index)
+        else:
+            raise TypeError(index)
+
+    def __delitem__(self, index):
+        # type: (str) -> None
+        """Delete/Remove a database alias from the system.
+
+        This function removes the alias from NI-XNET, but does not affect the
+        database text file. It just removes the alias association to the
+        database file path.
+
+        This function is supported on Windows only, and the alias is removed
+        from Windows only (not RT targets). Use 'undeploy' to remove an alias
+        from a Real-Time (RT) target.
+
+        Args:
+            index(str): The name of the alias to delete.
+        """
+        _funcs.nxdb_remove_alias(index)
+
+    def _create_item(self, database_alias, database_filepath):
+        return Database(database_alias, database_filepath)
+
+    def keys(self):
+        """Return all keys (alias names) used in the Databases object.
+
+            Yields:
+                An iterator to all the keys in the Database object.
+        """
+        for alias, _ in self.__get_database_list(''):
+            yield alias
+
+    def values(self):
+        """Return all Database objects in the system.
+
+            Yields:
+                An iterator to all the values in the Databases object.
+        """
+        for alias, filepath in self.__get_database_list(''):
+            yield self._create_item(alias, filepath)
+
+    def items(self):
+        """Return all aliases and database objects associated with those aliases in the system.
+
+            Yields:
+                An iterator to tuple pairs of alias and database objects in the system.
+        """
+        for alias, filepath in self.__get_database_list(''):
+            yield alias, self._create_item(alias, filepath)
+
+    def add_alias(self, database_alias, database_filepath, default_baud_rate):
+        # type: (str, str, int) -> None
+        """Add a new alias with baud rate size of up to 64 bits to a database file.
+
+        NI-XNET uses alias names for database files. The alias names provide a
+        shorter name for display, allow for changes to the file system without
+        changing the application.
+
+        This function is supported on Windows only.
+
+        Args:
+            database_alias(str): Provides the desired alias name. Unlike the names of
+                other XNET database objects, the alias name can use special
+                characters such as space and dash. Commas are not allowed in the
+                alias name. If the alias name already exists, this function
+                changes the previous filepath to the specified filepath.
+            database_filepath(str): Provides the path to the CANdb, FIBEX, or LDF
+                file. Commas are not allowed in the filepath name.
+            default_baud_rate(int): Provides the default baud rate, used when
+                filepath refers to a CANdb database (.dbc) or an NI-CAN database
+                (.ncd). These database formats are specific to CAN and do not
+                specify a cluster baud rate. Use this default baud rate to
+                specify a default CAN baud rate to use with this alias. If
+                database_filepath refers to a FIBEX database (.xml) or LIN LDF
+                file, the default_baud_rate parameter is ignored. The FIBEX and
+                LDF database formats require a valid baud rate for every
+                cluster, and NI-XNET uses that baud rate as the default.
+        """
+        _funcs.nxdb_add_alias64(database_alias, database_filepath, default_baud_rate)
+
+
+class Database(object):
+    """Database alias."""
+
+    def __init__(
+            self,
+            database_alias,
+            database_filepath,
+    ):
+        self._database_alias = database_alias
+        self._database_filepath = database_filepath
+
+    def __repr__(self):
+        return 'System.Database(alias={}, filepath={})'.format(self._database_alias, self._database_filepath)
+
+    @property
+    def filepath(self):
+        # type: () -> str
+        """str: Get the filepath associated with the Database object"""
+        return self._database_filepath

nixnet/system/system.py

@@ -13,6 +13,7 @@
 
 from nixnet.system import _device
 from nixnet.system import _interface
+from nixnet.system import databases
 
 
 class System(object):
@@ -21,6 +22,7 @@ def __init__(self):
         # type: () -> None
         self._handle = None  # To satisfy `__del__` in case nx_system_open throws
         self._handle = _funcs.nx_system_open()
+        self._databases = databases.Databases(self._handle)
 
     def __del__(self):
         if self._handle is not None:
@@ -67,6 +69,11 @@ def close(self):
 
         self._handle = None
 
+    @property
+    def databases(self):
+        """:any:`nixnet.system.databases.Databases`: Operate on systems's database's aliases"""
+        return self._databases
+
     @property
     def dev_refs(self):
         # type: () -> typing.Iterable[_device.Device]