Tutorial Part 5: Package Distributions

The previous portions of this tutorial walked through the steps necessary to create an application and client that expose and access Geolocation lookup functionality via the DXL fabric. This portion of the tutorial walks through the steps necessary to package and distribute these components for use by others.

NOTE: The steps in this portion of the tutorial require the Sphinx Python Document Generator to be installed.

To install Sphinx, run the following command:

pip install sphinx

Create Application Distribution

In this step the redistributable packages for the application that exposes the Geolocation service will be created.

Create Distribution

To create the application distribution files, execute the following command from within the application directory (opendxl-geolocation\app):

python dist.py

The output should appear similar to the following:

Starting dist.
Making dist directory: opendxl-geolocation\app\dist
Calling sphinx-apidoc

...

Making dist zip
creating 'opendxl-geolocation\app\dist\myapp-python-dist-0.0.0.zip'

...

Making dist config zip
creating 'opendxl-geolocation\app\dist\myapp-python-dist-config-0.0.0.zip'

...

The distribution script for the application performed the following actions:

• The application directory and file structure is cleaned. This will result in any changes to the configuration and sample configuration files being reverted to the values in the associated "default" configuration files. Also, any extra files found in the configuration and 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 was created (app\dist).
• The documentation for the application was generated (from app\doc) and placed in the doc sub-directory of the distribution directory.
• The sample and its associated configuration files (from app\sample) were copied into the sample sub-directory of the distribution directory.
• The application libraries were created (.zip, .whl) and placed into the lib sub-directory of the distribution directory.
• The configuration files for the application (from app\config) were copied into the config sub-directory of the distribution directory.
• The README.html file from the app\doc\sdk directory was copied into the root of the distribution directory.
• The distribution file <app-name>-python-dist-<version>.zip was created and includes the generated documentation, samples, libraries, configuration files, and README files for the application. This distribution file contains all of the components necessary to install and run the application along with documentation providing installation and usage instructions.
• The distribution file <app-name>-python-dist-config-<version>.zip was created and only includes the configuration files for the application. This distribution file is useful in scenarios where the application is installed by means other than the full distribution (via a Docker image, PyPI, etc.).

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

Create Client Distribution

In this step the redistributable package for the client that is used to access the the Geolocation service will be created.

Create Distribution

To create the client distribution, execute the following command from within the client directory (opendxl-geolocation\client):

python dist.py

The output should appear similar to the following:

Starting dist.
Making dist directory: opendxl-geolocation\client\dist
Calling sphinx-apidoc

... 

Making dist zip
creating 'opendxl-geolocation\client\dist\geolocationclient-python-dist-0.0.0.zip'

...

The distribution script for the client performed the following actions:

• The client directory and file structure is cleaned. This will result in any changes to the sample configuration files being reverted to the values in the associated "default" configuration files. Also, any extra files found in the sample configuration directory will be removed. This cleaning is done to prevent private configuration settings and files from being included in the distribution.
• The distribution directory was created (client\dist).
• The documentation for the client was 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) were copied into the sample sub-directory of the distribution directory.
• The client libraries were created (.zip, .whl) and placed into the lib sub-directory of the distribution directory.
• The README.html file from the client\doc\sdk directory was copied into the root of the distribution directory.
• The distribution file <client-name>-python-dist-<version>.zip was 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.