Address Ed's comments.

- Undo renaming of get_cluster_pdus_reqd
- Move delayed imports to back references.
- Hold off on implementing Cluster.database back reference.

nixnet/_props.py

@@ -2504,7 +2504,7 @@ def get_cluster_pdu_refs(
     )
 
 
-def get_cluster_pdus_required(
+def get_cluster_pdus_reqd(
     ref,  # type: int
 ):
     # type: (...) -> bool

nixnet/database/_cluster.py

@@ -12,7 +12,6 @@
 from nixnet.database import _collection
 from nixnet.database import _dbc_attributes
 from nixnet.database import _signal
-from nixnet.database import database as db  # avoid conflict with property named 'database'
 
 
 class Cluster(object):
@@ -201,13 +200,10 @@ def config_status(self):
 
     @property
     def database(self):
-        # type: () -> db.Database
-        """:any:`Database`: Returns the cluster parent database.
-
-        The parent database is defined when the cluster object is created. You cannot change it afterwards.
-        """
+        # type: () -> int
+        # todo: return a Database object here
         handle = _props.get_cluster_database_ref(self._handle)
-        return db.Database(handle)
+        return handle
 
     @property
     def dbc_attributes(self):
@@ -313,7 +309,7 @@ def pdus_required(self):
         signals from the frame are still returned,
         but reading the property returns a warning.
         """
-        return _props.get_cluster_pdus_required(self._handle)
+        return _props.get_cluster_pdus_reqd(self._handle)
 
     @property
     def protocol(self):

nixnet/database/_frame.py

@@ -12,7 +12,6 @@
 from nixnet.database import _cluster
 from nixnet.database import _collection
 from nixnet.database import _dbc_attributes
-from nixnet.database import _pdu
 from nixnet.database import _signal
 
 
@@ -555,7 +554,8 @@ def mux_subframes(self):
 
     @property
     def pdus(self):
-        # type: () -> typing.Iterable[_pdu.Pdu]
+        # actually returns typing.Iterable[_pdu.Pdu], but avoiding a circular import
+        # type: () -> typing.Iterable[typing.Any]
         """list of :any:`Pdu`: Get or set a list that maps existing PDUs to a frame.
 
         A mapped PDU is transmitted inside the frame payload when the frame is transmitted.
@@ -588,12 +588,14 @@ def pdus(self):
         you can avoid using PDUs in the database API
         and create signals and subframes directly on a frame.
         """
+        from nixnet.database import _pdu
         for handle in _props.get_frame_pdu_refs(self._handle):
             yield _pdu.Pdu(handle)
 
     @pdus.setter
     def pdus(self, value):
-        # type: (typing.Iterable[_pdu.Pdu]) -> None
+        # value is actually typing.Iterable[_pdu.Pdu], but avoiding a circular import
+        # type: (typing.Iterable[typing.Any]) -> None
         handle_list = [pdu._handle for pdu in value]
         _props.set_frame_pdu_refs(self._handle, handle_list)
 
@@ -658,7 +660,8 @@ def pdu_update_bits(self, value):
     @property
     def variable_payload(self):
         # type: () -> bool
-        # CAR 690609: determine if this undocumented property should be documented.
+        # This property is currently not documented in the C API.
+        # If/when we have C API documentation, we should add it here too.
         return _props.get_frame_variable_payload(self._handle)
 
     @variable_payload.setter

nixnet/database/_pdu.py

@@ -9,7 +9,10 @@
 from nixnet import _props
 from nixnet import constants
 
+from nixnet.database import _cluster
 from nixnet.database import _collection
+from nixnet.database import _frame
+from nixnet.database import _signal
 
 
 class Pdu(object):
@@ -46,13 +49,11 @@ def __repr__(self):
 
     @property
     def cluster(self):
-        # actually returns _cluster.Cluster, but avoiding a circular import
-        # type: () -> typing.Any
+        # type: () -> _cluster.Cluster
         """:any:`Cluster`: Get the parent cluster in which the PDU has been created.
 
         You cannot change the parent cluster after creating the PDU object.
         """
-        from nixnet.database import _cluster
         handle = _props.get_pdu_cluster_ref(self._handle)
         return _cluster.Cluster(handle)
 
@@ -98,8 +99,7 @@ def config_status(self):
 
     @property
     def frames(self):
-        # actually returns _frame.Frame, but avoiding a circular import
-        # type: () -> typing.Iterable[typing.Any]
+        # type: () -> typing.Iterable[_frame.Frame]
         """list of :any:`Frame<_frame.Frame>`: Returns a list of all frames to which the PDU is mapped.
 
         A PDU is transmitted within the frames to which it is mapped.
@@ -110,7 +110,6 @@ def frames(self):
         and :any:`Frame.pdu_update_bits` properties.
         You can map one PDU to multiple frames.
         """
-        from nixnet.database import _frame
         for handle in _props.get_pdu_frm_refs(self._handle):
             yield _frame.Frame(handle)
 
@@ -186,8 +185,7 @@ def mux_is_muxed(self):
 
     @property
     def mux_data_mux_signal(self):
-        # actually returns _signal.Signal, but avoiding a circular import
-        # type: () -> typing.Any
+        # type: () -> _signal.Signal
         """:any:`Signal<_signal.Signal>`: Data multiplexer signal in the PDU.
 
         This property returns the reference to the data multiplexer signal.
@@ -202,7 +200,6 @@ def mux_data_mux_signal(self):
         Raises:
             XnetError: The data multiplexer is not defined in the PDU.
         """
-        from nixnet.database import _signal
         handle = _props.get_pdu_mux_data_mux_sig_ref(self._handle)
         if handle == 0:
             # A bit of an abuse of errors
@@ -211,8 +208,7 @@ def mux_data_mux_signal(self):
 
     @property
     def mux_static_signals(self):
-        # actually returns typing.Iterable[_signal.Signal], but avoiding a circular import
-        # type: () -> typing.Iterable[typing.Any]
+        # type: () -> typing.Iterable[_signal.Signal]
         """list of :any:`Signal<_signal.Signal>`: Returns a list of static signals in the PDU.
 
         Returns an list of signal objects in the PDU that do not depend
@@ -227,7 +223,6 @@ def mux_static_signals(self):
         If the PDU is not multiplexed,
         this property returns the same list as the :any:`Pdu.signals` property.
         """
-        from nixnet.database import _signal
         for handle in _props.get_pdu_mux_static_sig_refs(self._handle):
             yield _signal.Signal(handle)
 

nixnet/database/_signal.py

@@ -11,7 +11,6 @@
 
 from nixnet.database import _dbc_attributes
 from nixnet.database import _dbc_signal_value_table
-from nixnet.database import _pdu
 
 
 class Signal(object):
@@ -293,12 +292,14 @@ def num_bits(self, value):
 
     @property
     def pdu(self):
-        # type: () -> _pdu.Pdu
+        # actually returns _pdu.Pdu, but avoiding a circular import
+        # type: () -> typing.Any
         """:any:`Pdu`: Returns to the signal's parent PDU.
 
         The parent PDU is defined when the signal object is created.
         You cannot change it afterwards.
         """
+        from nixnet.database import _pdu
         ref = _props.get_signal_pdu_ref(self._handle)
         return _pdu.Pdu(ref)
 

nixnet/database/_subframe.py

@@ -10,7 +10,6 @@
 
 from nixnet.database import _collection
 from nixnet.database import _frame
-from nixnet.database import _pdu
 
 
 class SubFrame(object):
@@ -141,13 +140,15 @@ def name(self, value):
 
     @property
     def pdu(self):
-        # type: () -> _pdu.Pdu
+        # actually returns _pdu.Pdu, but avoiding a circular import
+        # type: () -> typing.Any
         """:any:`Pdu`: Returns the subframe's parent PDU.
 
         This property returns the reference to the subframe's parent PDU.
         The parent PDU is defined when the subframe object is created.
         You cannot change it afterwards.
         """
+        from nixnet.database import _pdu
         handle = _props.get_subframe_pdu_ref(self._handle)
         return _pdu.Pdu(handle)
 

nixnet/database/database.py

@@ -28,23 +28,16 @@ class Database(object):
         database_name(str): The database alias or file pathname to open.
     """
     def __init__(self, database_name):
-        # type: (typing.Union[int, typing.Text]) -> None
-        self.db_needs_closing = False  # To satisfy `__del__` in case nxdb_open_database throws
-
-        if isinstance(database_name, int):
-            # overload the 'database_name' parameter so the Cluster.database property
-            # can construct a database object from a handle instead of a path.
-            self._handle = database_name
-        else:
-            self._handle = _funcs.nxdb_open_database(database_name)
-            self.db_needs_closing = True
+        # type: (typing.Text) -> None
+        self._handle = None  # To satisfy `__del__` in case nxdb_open_database throws
+        self._handle = _funcs.nxdb_open_database(database_name)
 
         from nixnet.database import _cluster
         self._clusters = _collection.DbCollection(
             self._handle, constants.ObjectClass.CLUSTER, _cconsts.NX_PROP_DATABASE_CLST_REFS, _cluster.Cluster)
 
     def __del__(self):
-        if self.db_needs_closing:
+        if self._handle is not None:
             warnings.warn(
                 'Database was not explicitly closed before it was destructed. '
                 'Resources on the device may still be reserved.',
@@ -109,12 +102,11 @@ def close(self, close_all_refs=False):
         """
         if self._handle is None:
             warnings.warn(
-                'Attempting to close NI-XNET system but system was already '
+                'Attempting to close NI-XNET database but database was already '
                 'closed', errors.XnetResourceWarning)
             return
 
         _funcs.nxdb_close_database(self._handle, close_all_refs)
-        self.db_needs_closing = False
         self._handle = None
 
     def save(self, db_filepath=""):