Merge pull request #230 from d-bohls/databaseDocumentation

docs(DB): Add a few docs for database.

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2017, National Instruments Corp.
+Copyright (c) 2017-2018, National Instruments Corp.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

docs/api_reference/database.rst

@@ -6,8 +6,10 @@ nixnet.database
    :caption: API Reference:
 
    database/cluster
+   database/database
    database/ecu
    database/frame
    database/signal
+   database/collection
    database/dbc_attributes
    database/dbc_signal_value_table

docs/api_reference/database/collection.rst

@@ -0,0 +1,7 @@
+nixnet.database.collection
+==========================
+
+.. automodule:: nixnet.database._collection
+    :members:
+    :inherited-members:
+    :show-inheritance:

docs/api_reference/database/database.rst

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

docs/conf.py

@@ -16,6 +16,7 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+from datetime import datetime
 import os
 import re
 import sys
@@ -50,8 +51,8 @@
 
 # General information about the project.
 project = u'nixnet'
-copyright = u'2017, National Instruments'
 author = u'National Instruments'
+copyright = u'2017-{}, {}'.format(datetime.now().year, author)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/examples/dynamic_database_creation.rst

@@ -7,11 +7,15 @@ used in a :any:`nixnet.session.SignalOutSinglePointSession` and
 :any:`nixnet.session.SignalInSinglePointSession` to write and then
 read a pair of signals.
 
+.. _can_dynamic_database_creation_label:
+
 CAN Dynamic Database Creation
 -----------------------------
 
 .. literalinclude:: ../../nixnet_examples/can_dynamic_database_creation.py
 
+.. _lin_dynamic_database_creation_label:
+
 LIN Dynamic Database Creation
 -----------------------------
 

nixnet/_session/base.py

@@ -353,8 +353,9 @@ def change_lin_schedule(self, sched_index):
         Args:
             sched_index(int): Index to the schedule table that the LIN master executes.
 
-            The schedule tables are sorted the way they are returned from the database
-            with the `nixnet.database._cluster.Cluster.lin_schedules` property.
+                The schedule tables are sorted the way they are returned from the
+                database with the `nixnet.database._cluster.Cluster.lin_schedules`
+                property.
         """
         _funcs.nx_write_state(self._handle, constants.WriteState.LIN_SCHEDULE_CHANGE, _ctypedefs.u32(sched_index))
 

nixnet/database/_collection.py

@@ -13,6 +13,7 @@
 
 
 class DbCollection(collections.Mapping):
+    """Collection of Database objects."""
 
     def __init__(self, handle, db_type, prop_id, factory):
         # type: (int, constants.ObjectClass, int, typing.Any) -> None
@@ -48,6 +49,13 @@ def __iter__(self):
         return self.keys()
 
     def __getitem__(self, index):
+        """Return the database object.
+
+        Args:
+            Name of database object
+        Returns:
+            index(str): Name of database object.
+        """
         if isinstance(index, six.string_types):
             ref = _funcs.nxdb_find_object(self._handle, self._type, index)
             return self._factory(ref)
@@ -59,18 +67,38 @@ def __delitem__(self, index):
         _funcs.nxdb_delete_object(ref)
 
     def keys(self):
+        """Return database object names in the collection.
+
+        Yields:
+            An iterator to database object names in the collection.
+        """
         for child in self._get_children():
             yield child.name
 
     def values(self):
+        """Return database objects in the collection.
+
+        Yields:
+            An iterator to database objects in the collection.
+        """
         return self._get_children()
 
     def items(self):
+        """Return all database object names and objects in the collection.
+
+        Yields:
+            An iterator to tuple pairs of database object names and objects in the collection
+        """
         for child in self._get_children():
             yield child.name, child
 
     def add(self, name):
         # type: (typing.Text) -> typing.Any
+        """Add a new database object to the collection.
+
+        Args:
+            name(str): Name of the new database object.
+        """
         ref = _funcs.nxdb_create_object(self._handle, self._type, name)
         return self._factory(ref)
 

nixnet/database/database.py

@@ -16,7 +16,18 @@
 
 
 class Database(object):
-
+    """Opens a database file.
+
+    When an already open database is opened,
+    this class grants access to the same database and increases an internal reference counter.
+    A multiple referenced (open) database must be closed as many times as it has been opened.
+    Until it is completely closed, the access to this database remains granted,
+    and the database uses computer resources (memory and handles).
+    For more information, refer to :any:`Database.close`.
+
+    Args:
+        database_name(str): The database alias or file pathname to open.
+    """
     def __init__(self, database_name):
         # type: (typing.Text) -> None
         self._handle = None  # To satisfy `__del__` in case nxdb_open_database throws
@@ -57,6 +68,37 @@ def __repr__(self):
         return '{}(handle={})'.format(type(self).__name__, self._handle)
 
     def close(self, close_all_refs=False):
+        # type: (bool) -> None
+        """Closes the database.
+
+        For the case that different threads of an application are using the same database,
+        :any:`Database` and :any:`Database.close`
+        maintain a reference counter indicating how many times the database is open.
+        Every thread can open the database, work with it,
+        and close the database independently using ``close_all_refs`` set to ``False``.
+        Only the last call to :any:`Database.close` actually closes access to the database.
+
+        .. note:: ``Database.__exit__`` calls :any:`Database.close` with ``close_all_refs`` set to ``False``.
+            See examples of this in :ref:`can_dynamic_database_creation_label`
+            and :ref:`lin_dynamic_database_creation_label`.
+
+        Another option is that only one thread executes :any:`Database.close` once,
+        using ``close_all_refs`` set to ``True``, which closes access for all other threads.
+        This may be convenient when, for example,
+        the main program needs to stop all running threads
+        and be sure the database is closed properly,
+        even if some threads could not execute :any:`Database.close`.
+
+        Args:
+            close_all_refs(bool): Indicates that a database open multiple times
+                (refer to :any:`Database`) should be closed completely
+                (``close_all_refs`` is ``True``),
+                or just the reference counter should be decremented
+                (``close_all_refs`` is ``False``),
+                and the database remains open.
+                When the database is closed completely,
+                all references to objects in this database become invalid.
+        """
         if self._handle is None:
             warnings.warn(
                 'Attempting to close NI-XNET system but system was already '
@@ -69,20 +111,58 @@ def close(self, close_all_refs=False):
 
     def save(self, db_filepath=""):
         # type: (typing.Text) -> None
+        """Saves the open database to a FIBEX 3.1.0 file.
+
+        The file extension must be .xml. If the target file exists, it is overwritten.
+
+        XNET saves to the FIBEX file only features that XNET sessions use to communicate on the network.
+        If the original file was created using non-XNET software,
+        the target file may be missing details from the original file.
+        For example, NI-XNET supports only linear scaling.
+        If the original FIBEX file used a rational equation that cannot be expressed as a linear scaling,
+        XNET converts this to a linear scaling with factor 1.0 and offset 0.0.
+
+        If ``db_filepath`` is empty, the file is saved to the same FIBEX file specified when opened.
+        If opened as a file path, it uses that file path.
+        If opened as an alias, it uses the file path registered for that alias.
+
+        Saving a database is not supported under Real-Time (RT),
+        but you can deploy and use a database saved on Windows on a Real-Time (RT) target (refer to `Database.deploy`).
+
+        Args:
+            db_filepath(str): Contains the pathname to the database file or is
+                empty (saves to the original filepath).
+        """
         _funcs.nxdb_save_database(self._handle, db_filepath)
 
     @property
     def name(self):
+        # type: () -> typing.Text
         return _props.get_database_name(self._handle)
 
     @property
     def clusters(self):
+        # type: () -> _collection.DbCollection
+        """:any:`DbCollection`: Returns a collection of :any:`Cluster` objects in this database.
+
+        A cluster is assigned to a database when the cluster object is created.
+        You cannot change this assignment afterwards.
+
+        FIBEX and AUTOSAR files can contain any number of clusters,
+        and each cluster uses a unique name.
+
+        For CANdb (.dbc), LDF (.ldf), or NI-CAN (.ncd) files,
+        the file contains only one cluster, and no cluster name is stored in the file.
+        For these database formats, NI-XNET uses the name Cluster for the single cluster.
+        """
         return self._clusters
 
     @property
     def show_invalid_from_open(self):
+        # type: () -> bool
         return _props.get_database_show_invalid_from_open(self._handle)
 
     @show_invalid_from_open.setter
     def show_invalid_from_open(self, value):
+        # type: (bool) -> None
         _props.set_database_show_invalid_from_open(self._handle, value)

nixnet_examples/can_dynamic_database_creation.py

@@ -22,6 +22,7 @@ def main():
     input_interface = 'CAN2'
 
     # Open the default in-memory database.
+    # Database.close will be called by Database.__exit__ when exiting the 'with' block.
     with database.Database(database_name) as db:
 
         # Add a CAN cluster, a frame, and two signals to the database.

nixnet_examples/lin_dynamic_database_creation.py

@@ -26,6 +26,7 @@ def main():
     input_interface = 'LIN2'
 
     # Open the default in-memory database.
+    # Database.close will be called by Database.__exit__ when exiting the 'with' block.
     with database.Database(database_name) as db:
 
         # Add a LIN cluster, a frame, and two signals to the database.