Merge b472b32 into f68ffee

docs/api_reference/database/lin_sched.rst

@@ -1,5 +1,5 @@
-nixnet.database.linsched
-========================
+nixnet.database.lin_sched
+=========================
 
 .. automodule:: nixnet.database._lin_sched
     :members:

docs/api_reference/database/lin_sched_entry.rst

@@ -1,5 +1,5 @@
-nixnet.database.linsched_entry
-==============================
+nixnet.database.lin_sched_entry
+===============================
 
 .. automodule:: nixnet.database._lin_sched_entry
     :members:

nixnet/_session/intf.py

@@ -139,7 +139,7 @@ def out_strm_list(self):
         .. note:: Only CAN and LIN interfaces currently support this property.
         '''
         for ref in _props.get_session_intf_out_strm_list(self._handle):
-            yield _frame.Frame(ref)
+            yield _frame.Frame(_handle=ref)
 
     @out_strm_list.setter
     def out_strm_list(self, value):

nixnet/database/__init__.py

@@ -3,7 +3,26 @@
 from __future__ import print_function
 
 
+from nixnet.database._cluster import Cluster
+from nixnet.database._database_object import DatabaseObject
+from nixnet.database._ecu import Ecu
+from nixnet.database._frame import Frame
+from nixnet.database._lin_sched import LinSched
+from nixnet.database._lin_sched_entry import LinSchedEntry
+from nixnet.database._pdu import Pdu
+from nixnet.database._signal import Signal
+from nixnet.database._subframe import SubFrame
 from nixnet.database.database import Database
 
 
-__all__ = ["Database"]
+__all__ = [
+    "Cluster",
+    "Database",
+    "DatabaseObject",
+    "Ecu",
+    "Frame",
+    "LinSched",
+    "LinSchedEntry",
+    "Pdu",
+    "Signal",
+    "SubFrame"]

nixnet/database/_cluster.py

@@ -11,21 +11,27 @@
 from nixnet import constants
 
 from nixnet.database import _collection
+from nixnet.database import _database_object
 from nixnet.database import _dbc_attributes
+from nixnet.database import _find_object
 from nixnet.database import _signal
 
 
-class Cluster(object):
+class Cluster(_database_object.DatabaseObject):
     """Database cluster"""
 
-    def __init__(self, handle):
-        # type: (int) -> None
+    def __init__(
+            self,
+            **kwargs  # type: int
+    ):
+        # type: (...) -> None
+        _database_object.DatabaseObject.__init__(self, **kwargs)
+        self._dbc_attributes = None  # type: typing.Optional[_dbc_attributes.DbcAttributeCollection]
+
         from nixnet.database import _ecu
         from nixnet.database import _frame
         from nixnet.database import _lin_sched
         from nixnet.database import _pdu
-        self._handle = handle
-        self._dbc_attributes = None  # type: typing.Optional[_dbc_attributes.DbcAttributeCollection]
         self._ecus = _collection.DbCollection(
             self._handle, constants.ObjectClass.ECU, _cconsts.NX_PROP_CLST_ECU_REFS, _ecu.Ecu)
         self._frames = _collection.DbCollection(
@@ -35,25 +41,6 @@ def __init__(self, handle):
         self._pdus = _collection.DbCollection(
             self._handle, constants.ObjectClass.PDU, _cconsts.NX_PROP_CLST_PDU_REFS, _pdu.Pdu)
 
-    def __eq__(self, other):
-        if isinstance(other, self.__class__):
-            return self._handle == other._handle
-        else:
-            return NotImplemented
-
-    def __ne__(self, other):
-        result = self.__eq__(other)
-        if result is NotImplemented:
-            return result
-        else:
-            return not result
-
-    def __hash__(self):
-        return hash(self._handle)
-
-    def __repr__(self):
-        return '{}(handle={})'.format(type(self).__name__, self._handle)
-
     def check_config_status(self):
         # type: () -> None
         """Check this cluster's configuration status.
@@ -66,7 +53,7 @@ def check_config_status(self):
         even if :any:`Database.show_invalid_from_open` is `False`.
 
         Raises:
-            XnetError: The cluster is incorrectly configured.
+            :any:`XnetError`: The cluster is incorrectly configured.
         """
         status_code = _props.get_cluster_config_status(self._handle)
         _errors.check_for_error(status_code)
@@ -86,6 +73,54 @@ def export(self, db_filepath):
         """
         _funcs.nxdb_save_database(self._handle, db_filepath)
 
+    def find(
+            self,
+            object_class,  # type: typing.Type[_database_object.DatabaseObject]
+            object_name,  # type: typing.Text
+    ):
+        # type: (...) -> _database_object.DatabaseObject
+        """Finds an object in the database.
+
+        This function finds a database object relative to this parent object.
+        This object may be a grandparent or great-grandparent.
+
+        If this object is a direct parent
+        (for example, :any:`Frame<_frame.Frame>` for :any:`Signal<_signal.Signal>`),
+        the ``object_name`` to search for can be short, and the search proceeds quickly.
+
+        If this object is not a direct parent
+        (for example, :any:`Database` for :any:`Signal<_signal.Signal>`),
+        the ``object_name`` to search for must be qualified such
+        that it is unique within the scope of this object.
+
+        For example, if the class of this object is :any:`Cluster`,
+        and ``object_class`` is :any:`Signal<_signal.Signal>`,
+        you can specify ``object_name`` of ``mySignal``,
+        assuming that signal name is unique to the cluster.
+        If not, you must include the :any:`Frame<_frame.Frame>` name as a prefix,
+        such as ``myFrameA.mySignal``.
+
+        NI-XNET supports the following subclasses of ``DatabaseObject`` as arguments for ``object_class``:
+
+        *   :any:`Cluster`
+        *   :any:`Frame<_frame.Frame>`
+        *   :any:`Pdu`
+        *   :any:`Signal<_signal.Signal>`
+        *   :any:`SubFrame`
+        *   :any:`Ecu`
+        *   :any:`LinSched`
+        *   :any:`LinSchedEntry`
+
+        Args:
+            object_class(``DatabaseObject``): The class of the object to find.
+            object_name(str): The name of the object to find.
+        Returns:
+            An instance of the found object.
+        Raises:
+            :any:`XnetError`: The object is not found.
+        """
+        return _find_object.find_object(self._handle, object_class, object_name)
+
     def merge(
             self,
             source_obj,
@@ -327,7 +362,7 @@ def sigs(self):
         # type: () -> typing.Iterable[_signal.Signal]
         """list of :any:`Signal<_signal.Signal>`: Returns a list of all :any:`Signal<_signal.Signal>` objects in this cluster."""  # NOQA: E501
         for handle in _props.get_cluster_sig_refs(self._handle):
-            yield _signal.Signal(handle)
+            yield _signal.Signal(_handle=handle)
 
     @property
     def can_io_mode(self):

nixnet/database/_collection.py

@@ -58,7 +58,7 @@ def __getitem__(self, index):
         """
         if isinstance(index, six.string_types):
             ref = _funcs.nxdb_find_object(self._handle, self._type, index)
-            return self._factory(ref)
+            return self._factory(_handle=ref)
         else:
             raise TypeError(index)
 
@@ -100,8 +100,8 @@ def add(self, name):
             name(str): Name of the new database object.
         """
         ref = _funcs.nxdb_create_object(self._handle, self._type, name)
-        return self._factory(ref)
+        return self._factory(_handle=ref)
 
     def _get_children(self):
         for ref in _cprops.get_database_ref_array(self._handle, self._prop_id):
-            yield self._factory(ref)
+            yield self._factory(_handle=ref)

nixnet/database/_database_object.py

@@ -0,0 +1,41 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import typing  # NOQA: F401
+
+from nixnet import _cconsts
+from nixnet import _errors
+
+
+class DatabaseObject(object):
+    """Database object base."""
+
+    def __init__(
+            self,
+            **kwargs  # type: int
+    ):
+        # type: (...) -> None
+        if not kwargs or '_handle' not in kwargs:
+            _errors.raise_xnet_error(_cconsts.NX_ERR_INVALID_PROPERTY_VALUE)
+
+        self._handle = kwargs['_handle']
+
+    def __eq__(self, other):
+        if isinstance(other, self.__class__):
+            return self._handle == typing.cast(DatabaseObject, other)._handle
+        else:
+            return NotImplemented
+
+    def __ne__(self, other):
+        result = self.__eq__(other)
+        if result is NotImplemented:
+            return result
+        else:
+            return not result
+
+    def __hash__(self):
+        return hash(self._handle)
+
+    def __repr__(self):
+        return '{}(handle={})'.format(type(self).__name__, self._handle)

nixnet/database/_ecu.py

@@ -9,37 +9,22 @@
 from nixnet import constants
 
 from nixnet.database import _cluster
+from nixnet.database import _database_object
 from nixnet.database import _dbc_attributes
 from nixnet.database import _frame
 
 
-class Ecu(object):
+class Ecu(_database_object.DatabaseObject):
     """Database ECU"""
 
-    def __init__(self, handle):
-        # type: (int) -> None
-        self._handle = handle
+    def __init__(
+            self,
+            **kwargs  # type: int
+    ):
+        # type: (...) -> None
+        _database_object.DatabaseObject.__init__(self, **kwargs)
         self._dbc_attributes = None  # type: typing.Optional[_dbc_attributes.DbcAttributeCollection]
 
-    def __eq__(self, other):
-        if isinstance(other, self.__class__):
-            return self._handle == other._handle
-        else:
-            return NotImplemented
-
-    def __ne__(self, other):
-        result = self.__eq__(other)
-        if result is NotImplemented:
-            return result
-        else:
-            return not result
-
-    def __hash__(self):
-        return hash(self._handle)
-
-    def __repr__(self):
-        return '{}(handle={})'.format(type(self).__name__, self._handle)
-
     def check_config_status(self):
         # type: () -> None
         """Check this ECU's configuration status.
@@ -52,7 +37,7 @@ def check_config_status(self):
         even if :any:`Database.show_invalid_from_open` is `False`.
 
         Raises:
-            XnetError: The ECU is incorrectly configured.
+            :any:`XnetError`: The ECU is incorrectly configured.
         """
         status_code = _props.get_ecu_config_status(self._handle)
         _errors.check_for_error(status_code)
@@ -66,7 +51,7 @@ def clst(self):
         You cannot change it afterwards.
         """
         handle = _props.get_ecu_clst_ref(self._handle)
-        return _cluster.Cluster(handle)
+        return _cluster.Cluster(_handle=handle)
 
     @property
     def comment(self):
@@ -123,7 +108,7 @@ def rx_frms(self):
         All frames an ECU receives in a given cluster must be defined in the same cluster.
         """
         for ref in _props.get_ecu_rx_frm_refs(self._handle):
-            yield _frame.Frame(ref)
+            yield _frame.Frame(_handle=ref)
 
     @rx_frms.setter
     def rx_frms(self, value):
@@ -140,7 +125,7 @@ def tx_frms(self):
         All frames an ECU transmits in a given cluster must be defined in the same cluster.
         """
         for ref in _props.get_ecu_tx_frm_refs(self._handle):
-            yield _frame.Frame(ref)
+            yield _frame.Frame(_handle=ref)
 
     @tx_frms.setter
     def tx_frms(self, value):

nixnet/database/_find_object.py

@@ -0,0 +1,54 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+
+import typing  # NOQA: F401
+
+from nixnet import _cconsts
+from nixnet import _errors
+from nixnet import _funcs
+from nixnet import constants
+from nixnet.database import _database_object  # NOQA: F401
+
+
+def find_object(
+        parent_handle,  # type: int
+        object_class,  # type: typing.Type[_database_object.DatabaseObject]
+        object_name,  # type: typing.Text
+):
+    # type: (...) -> _database_object.DatabaseObject
+    from nixnet.database._cluster import Cluster
+    from nixnet.database._ecu import Ecu
+    from nixnet.database._frame import Frame
+    from nixnet.database._lin_sched import LinSched
+    from nixnet.database._lin_sched_entry import LinSchedEntry
+    from nixnet.database._pdu import Pdu
+    from nixnet.database._signal import Signal
+    from nixnet.database._subframe import SubFrame
+
+    class_enum = constants.ObjectClass.CLUSTER  # arbitrary default value
+
+    if object_class is Cluster:
+        class_enum = constants.ObjectClass.CLUSTER
+    elif object_class is Ecu:
+        class_enum = constants.ObjectClass.ECU
+    elif object_class is Frame:
+        class_enum = constants.ObjectClass.FRAME
+    elif object_class is LinSched:
+        class_enum = constants.ObjectClass.LIN_SCHED
+    elif object_class is LinSchedEntry:
+        class_enum = constants.ObjectClass.LIN_SCHED_ENTRY
+    elif object_class is Pdu:
+        class_enum = constants.ObjectClass.PDU
+    elif object_class is Signal:
+        class_enum = constants.ObjectClass.SIGNAL
+    elif object_class is SubFrame:
+        class_enum = constants.ObjectClass.SUBFRAME
+    else:
+        _errors.raise_xnet_error(_cconsts.NX_ERR_INVALID_PROPERTY_VALUE)
+
+    found_handle = _funcs.nxdb_find_object(parent_handle, class_enum, object_name)
+    if found_handle == 0:
+        _errors.raise_xnet_error(_cconsts.NX_ERR_DATABASE_OBJECT_NOT_FOUND)
+
+    return object_class(_handle=found_handle)