Client Template

Jeremy Barlow edited this page Mar 27, 2018 · 37 revisions

Table of Contents

Overview

The "Client" template generates an OpenDXL "client wrapper". The purpose of a client wrapper is to allow users to access the features of a DXL fabric (services and events) without having to focus on lower-level details such as message topics, message formats, etc.

Examples of existing client wrappers include:

The name used to select the client template when invoking the OpenDXL Bootstrap application is client-template.

For example:

python -m dxlbootstrap client-template config\client-template.config myclient-output

Configuration File

The configuration file required to generate an "client" using the client-template is detailed below.

Example

The following is an example of a valid client-template configuration file.

[Client]
name=myclient
fullName=My DXL Client
clientClassName=MyClient
copyright=Copyright 2018

Client Section

The [Client] section is used to specify information about the client that is going to be generated.

Name Required Description
name yes The name of the client (will be used for the Python package name)
fullName yes The full name of the client
clientClassName yes The name of the client class (Python class name)
copyright no Copyright information for the client
installRequires no A comma delimited list of Python packages the client requires. These packages will be added to the appropriate files (setup.py, etc.)
languageVersion no The Python language version that the application requires. This is used to control the version information in the generated packaging and documentation files. Specify "2" (for Python 2.x only), "3" (for Python 3.x only), or "universal" (for both Python 2.x and Python 3.x). (Defaults to "2").
includeExampleMethod no Whether to include an example method in the client class that demonstrates wrapping a DXL service invocation. (defaults to "yes")

Output

The following file structure will be created in the specified output directory when the OpenDXL Bootstrap application is executed with the client-template.

<client_name>\
    __init__.py
    _version.py
    client.py
    _config\
        __init__.py
        sample\
            __init__.py
            dxlclient.config
doc\
    sdk\
        README.html
        index.rst
        ...
    conf.py
sample\
    basic\
        basic_sample.py
    common.py
    dxlclient.config        
clean.py
dist.py
LICENSE
MANIFEST.in
README
README.md
setup.py

Each of these files and directories are described in detail below.

Directory Name Description
\ The root directory containing all of the files and directories that were generated by running the OpenDXL Bootstrap application with the client-template template.
clean.py The clean.py script cleans the client directory and file structure. This will result in any changes to the sample configuration files being reverted to the values in the associated "default" configuration files (see \<client_name>\_config\ directory below). Also, any extra files found in the sample configuration directories will be removed. See the Clean Script section for detailed information regarding this script.
dist.py The dist.py script creates the redistributable package for the client. The first step this script performs is invoking the clean.py script (see Clean Script). See the Distribution Script section for detailed information regarding this script.
LICENSE License information for the client. This file should be updated to include license information related to the client.
MANIFEST.in This file is used to generate the MANIFEST file that contains the list of files that will be included in the Python client package. By default the manifest includes the LICENSE file.
README README information that is included with the Python client package. This file should be updated to include client-specific information.
README.md README information that is typically used to describe a repository that contains the client source code such as GitHub. This file should be updated to include client-specific information.
setup.py The setup script that is primarily used for building, distributing, and installing the client.
\<client_name>\ This directory is the client package that contains the generated client modules.
__init__.py Initialization module for the client package.
_version.py This file contains the version number for the client. The __version__ value should be updated to reflect the current version of the client.
client.py The client module that contains the generated main client class. The generated client class derives the Client base class which is a part of the OpenDXL Bootstrap library. For complete information regarding the Client base class see this page.
\<client_name>\_config\ This directory (and its sub-directories) contain the "default" configuration files for the client samples.
__init__.py Initialization module for the configuration package.
\<client_name>\_config\sample\ This directory contains the "default" configuration files for the samples.
__init__.py Initialization module for the sample configuration package.
dxlclient.config Configuration file that contains settings for configuring the DXL client to connect to the DXL fabric in the samples. This is the DXL client configuration file for the samples that will be included in the client distribution file (<client_name>-python-dist-<version>.zip) generated via the distribution script.
\doc\ The root documentation directory containing the source files for end-user client documentation. The documentation source files are written using reStructuredText and converted to final documentation using the Sphinx documentation generator.
conf.py The Sphinx build configuration file (contains configuration needed to customize Sphinx input and output behavior).
\doc\sdk\ Directory containing source files for end-user client documentation.
README.html HTML-based README file that will be copied to the root of the client distribution file (<client_name>-python-dist-<version>.zip) when the distribution script is executed.
index.rst The root (or main) documentation file written in reStructuredText. This file should provide links to the other documentation files.
... Several other documentation files are provided in the generated client including an overview of the client, installation and usage instructions, instructions for running samples, etc. All of these files are written in reStructuredText.
\sample\ This directory contains the samples for the client. These samples will be included in the client distribution file (<client_name>-python-dist-<version>.zip) when the distribution script is executed.
common.py The common module that is shared between the samples for the client. This module contains code to initialize logging and the location of the DXL client configuration to use in the samples.
dxlclient.config "Working" version of the DXL client configuration file for the samples. This file may be edited to allow for in-place testing of the client samples (see use in Tutorial). However, running the clean or distribution scripts will revert the values in this file to those contained in the "default" configuration file (see \<client_name>\_config\sample\ dxlclient.config file above).
\sample\basic\ Directory containing "basic" samples for the client.
basic_sample.py The "basic" sample that is generated for the client. By default, this client will invoke the example method of the client (if the includeExampleMethod was set to Yes in the client-template configuration file when generating the client).

Clean Script (clean.py)

This script cleans the client directory and file structure. This will result in any changes to the sample configuration files being reverted to the values in the associated "default" configuration files (see \<client_name>\_config\ directory above). Also, any extra files found in the sample configuration directories will be removed. Finally, any compiled Python files (.pyc) found in the client directory structure will be removed.

To run the script, execute the following command from the root of the generated client:

python clean.py

The purpose of this script is to remove any private configuration settings and files from the client structure. Thus, this script should be executed every time the client is about to be checked into a source code repository.

Distribution Script (dist.py)

This script generates the redistributable package of the client for use by others.

To run the script, execute the following command from the root of the generated client:

python dist.py

The distribution script for the client performs the following actions:

  • The client directory and file structure is cleaned (see clean script). This will result in any changes to the "working" sample configuration files being reverted to the values in the associated "default" configuration files. Also, any extra files found in the sample configuration directories will be removed. This cleaning is done to prevent private configuration settings and files from being included in the distribution.
  • The distribution directory is created (client\dist).
  • The documentation for the client is generated (from client\doc) and placed in the doc sub-directory of the distribution directory.
  • The sample and its associated configuration files (from client\sample) are copied into the sample sub-directory of the distribution directory.
  • The client libraries is created (.zip, .whl) and placed into the lib sub-directory of the distribution directory.
  • The README.html file from the client\doc\sdk directory is copied into the root of the distribution directory.
  • The distribution file <client_name>-python-dist-<version>.zip is created and includes the generated documentation, samples, libraries, and README files for the client. This distribution file contains all of the components necessary to install the client along with documentation providing installation and usage instructions.

At this point, the distribution file <client_name>-python-dist-<version>.zip can be distributed which contains the client libraries and documentation including installation and usage instructions.

Example Usage

The OpenDXL Bootstrap distribution contains an example "client" template configuration (client-template.config) which is located in the config directory. The example client that is generated contains a single method (my_example_method) which invokes the DXL broker health service and returns its response as a Python dictionary (dict).

Install OpenDXL Bootstrap

The first step is to install the OpenDXL Bootstrap application.

  1. Ensure the OpenDXL Bootstrap application prerequisites have been met.

  2. Download the latest release of the OpenDXL Bootstrap application (dxlbootstrap-python-dist-<version>.zip).

  3. Extract the distribution file (.zip).

  4. Use pip to install the Python wheel (.whl) file located in the lib directory of the extracted distribution.

    pip install dxlbootstrap-<version>-py2.py3-none-any.whl

Generate Client

To generate the example client execute the following command:

python -m dxlbootstrap client-template config\client-template.config myclient-output

The arguments are as follows:

  • client-template: The type of template to use (in this case "client")
  • config\client-template.config: The location of the configuration file that provides information about the client that is to be generated
  • myclient-output: The location to output the generated client

The directory structure and files generated in the output directory (client-output) are described in detail in the output section, above.

Run Generated Sample

A default sample is generated by the client template that invokes the method exposed by the generated client (my_example_method) and displays the contents of the returned Python dictionary (dict).

Prior to running the generated sample, the dxlclient.config file located in the myclient-output\sample directory must be modified to include the information necessary to connect the sample to the DXL fabric.

The steps to populate this configuration file are the same as those documented in the OpenDXL Python SDK, see the OpenDXL Python SDK Samples Configuration page for more information.

To run the sample execute the following command from within the myclient-output directory:

python sample\basic\basic_sample.py

The output from running this command should appear similar to the following:

Response:
{
    "connectedClients": 4,
    "incomingMessages": 0,
    "ipe": {
        "fabrics": {},
        "patterns": {},
        "plugins": {
            "epo": {
                "displayName": "epo",
                "properties": {}
            }
        },
        "properties": {}
    },
    "localServiceCounter": 2,
    "outgoingMessages": 0,
    "startTime": 1489613767
}

The output above shows the health information for the broker the sample client connected to.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.