MSL Resources

MSL Resources are specific classes that are used to communicate with the equipment.

Creating a new MSL Resource

When adding a new MSL Resource class to the repository the following steps should be performed. Please follow the style guide.

Note

If you do not want to upload the new MSL Resource class to the repository then you only need to write the code found in Step 5 to use your class in your own programs.

  1. Create a fork of the repository.

  2. If you are adding a new MSL Resource for equipment from a manufacturer that does not already exist in the msl/equipment/resources directory then create a new Python package in msl/equipment/resources using the name of the manufacturer as the package name.

  3. Create a new Python module, in the package from Step 2, using the model number of the equipment as the name of the module.

  4. If a msl.equipment.exceptions class has not been created for this manufacture then create a new exception handler class using the name of the manufacturer in the class name.

  5. Create a new connection class within the module that you created in Step 3. The class must be a subclass of one of the Connection Classes.

    # msl/equipment/resources/<manufacturer>/<model_number>.py
#
from msl.equipment.resources import register
from msl.equipment.exceptions import TheErrorClassFromStep4  # this is optional
from msl.equipment.connection_xxx import ConnectionXxx  # replace xxx with the Connection subclass

# Register your class so that MSL-Equipment knows that it exists
@register(manufacturer='a regex pattern', model='a regex pattern')  # can include a `flags` kwarg
class ModelNumber(ConnectionXxx):  # change ModelNumber and ConnectionXxx

    def __init__(self, record):
        """Edit the docstring...

        Do not instantiate this class directly. Use the :meth:`~.EquipmentRecord.connect`
        method to connect to the equipment.

        Parameters
        ----------
        record : :class:`~.EquipmentRecord`
            A record from an :ref:`equipment-database`.
        """
        super(ModelNumber, self).__init__(record)  # change ModelNumber

        # the following is optional, the default exception handler is MSLConnectionError
        self.set_exception_class(TheErrorClassFromStep4)  # change TheErrorClassFromStep4

  6. Add at least one example for how to use the new MSL Resource in msl/examples/equipment. Follow the template of the other examples in this package for naming conventions and for showing how to use the new MSL Resource.

  7. Create tests for the new MSL Resource. The tests cannot be dependent on whether the equipment is physically connected to the computer running the test (ideally the examples that you write in Step 6 will demonstrate that communicating with the equipment works). The very minimal test to create is to add a test case to the def test_find_resource_class() function for ensuring that your class is returned for various values of manufacturer and model. Run the tests using python setup.py test (ideally you would run the tests for all currently-supported versions of Python, see also condatests.py).

  8. Add .rst documentation files for the new MSL Resource to the docs/_api folder. You can either run python setup.py apidoc to automatically generate the .rst documentation files or you can create the necessary .rst files manually. Running python setup.py apidoc will generate .rst files for all modules in MSL-Equipment in the docs/_autosummary folder. Only copy the .rst files that are associated with your new MSL Resource to the docs/_api folder. After copying the files you can delete the docs/_autosummary folder before running python setup.py docs to build the documentation, otherwise you will get numerous warnings. If you want to manually create the .rst files then look in the docs/_api folder for examples from other MSL Resources.

  9. If you created a new package in Step 2 then you need to add the new package to the toctree of the Subpackages section in docs/_api/msl.equipment.resources.rst. Insert the name of the new MSL Resource package in the file alphabetically. If you forget to do this step then a warning will appear when building the documentation to help remind you to do it. If you did not create a new package in Step 2 then add the .rst file from Step 8 to the Subpackages section in the appropriate msl.equipment.resources.*.rst file.

  10. Add the new MSL Resource class, alphabetically, to the list of MSL Resources in docs/resources.rst. Follow the template that is used for the other MSL Resources listed in this file.

  11. Add yourself to AUTHORS.rst and add a note in CHANGES.rst that you created this new Resource. These files are located in the root directory of the MSL-Equipment package.

  12. If running the tests pass and building the docs show no errors/warnings then create a pull request.