development.md

template-python development

The following instructions are useful during development.

Note: This has been tested on Linux and Darwin/macOS. It has not been tested on Windows.

Prerequisites for development

🤔 The following tasks need to be complete before proceeding. These are "one-time tasks" which may already have been completed.

1. The following software programs need to be installed:
   1. git
   2. make
   3. docker
   4. sphinx

Install Senzing C library

Since the Senzing library is a prerequisite, it must be installed first.

1. Verify Senzing C shared objects, configuration, and SDK header files are installed.

   1. /opt/senzing/er/lib
   2. /opt/senzing/er/sdk/c
   3. /etc/opt/senzing

2. If not installed, see How to Install Senzing for Python Development.

Install Git repository

1. Identify git repository.

   export GIT_ACCOUNT=senzing-garage
   export GIT_REPOSITORY=template-python
   export GIT_ACCOUNT_DIR=~/${GIT_ACCOUNT}.git
   export GIT_REPOSITORY_DIR="${GIT_ACCOUNT_DIR}/${GIT_REPOSITORY}"
   

2. Using the environment variables values just set, follow steps in clone-repository to install the Git repository.

Dependencies

1. A one-time command to install dependencies needed for make targets. Example:

   cd ${GIT_REPOSITORY_DIR}
   make dependencies-for-development
   

2. Install dependencies needed for Python code. Example:

   cd ${GIT_REPOSITORY_DIR}
   make dependencies
   

Lint

1. Run linting. Example:

   cd ${GIT_REPOSITORY_DIR}
   make lint
   

Build

Not applicable.

Run

1. Run program. Example:

   cd ${GIT_REPOSITORY_DIR}
   make run
   

2. Clean up. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean
   

Test

1. Run tests. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean setup test
   

Coverage

Create a code coverage map.

1. Run Go tests. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean setup coverage
   

   A web-browser will show the results of the coverage. The goal is to have over 80% coverage.

Documentation

1. View documentation. Example:

   cd ${GIT_REPOSITORY_DIR}
   make clean documentation
   

2. If a web page doesn't appear, run the following command and paste the results into a web browser's address bar.

   echo "file://${GIT_REPOSITORY_DIR}/docs/build/html/index.html"

Docker

1. Use make target to run a docker images that builds RPM and DEB files. Example:

   cd ${GIT_REPOSITORY_DIR}
   make docker-build
   

2. Run docker container. Example:

   docker run --rm senzing/template-python
   

3. Optional: Test using docker-compose. Example:

   cd ${GIT_REPOSITORY_DIR}
   make docker-test
   

Package

1. Build the wheel file for distribution. Example:

   cd ${GIT_REPOSITORY_DIR}
   make package
   

2. Activate virtual environment.

   cd ${GIT_REPOSITORY_DIR}
   source .venv/bin/activate
   

3. Verify that template-python is not installed. Example:

   python3 -m pip freeze | grep -e template-python -e template_python
   

   Nothing is returned.

4. Install directly from wheel file. Example:

   python3 -m pip install ${GIT_REPOSITORY_DIR}/dist/*.whl
   

5. Verify that template-python is installed. Example:

   python3 -m pip freeze | grep -e template-python -e template_python
   

   Example return:

   template-python @ file:///home/senzing/senzing-garage.git/sz-sdk-python-abstract/dist/template_python-0.0.1-py3-none-any.whl#sha256=2a4e5218d66d5be60ee31bfad5943e6611fc921f28a4326d9594ceceae7e0ac1

6. If applicable, run the application. Example:

   template_python
   

7. Uninstall the template-python python package. Example:

   python3 -m pip uninstall template-python
   

8. Deactivate virtual environment.

   deactivate
   

Test publish

⚠️ This test can only be performed once per versioned release.

1. Test publishing wheel file to Test PyPi. Example:

   cd ${GIT_REPOSITORY_DIR}
   make publish-test
   

2. Visit Test PyPi and search for package.

References

1. bandit
2. black
3. coverage
4. flake8
5. isort
6. mypy
7. pylint
8. pytest
9. sphinx