Installation/Updates

See the following instructions on how to install or update the package from common sources like PyPI. Developers can also install the packages with development dependencies. In case of local development, see the additional sections on how to run unit tests, type checks or how to build the documentation to create all the build artifacts.

See the list of necessary dependencies.

Using PIP to Install from PyPI

The following instruction are using PIP (Package Installer for Python) as a package manager and PyPI (Python Package Index) as a source of Python packages.

PIP might download further packages as listed in package dependencies.

Installing a Wheel Package from PyPI using PIP

Users can install the pyTooling package as a minimal installation or the package with extensions (packaging, terminal, yaml) installing further dependencies. In case the provided extensions are not needed, it keeps the list of dependencies low - especially the minimal installation is still dependency free.

See pyTooling Package (Mandatory) for more details.

# Basic pyTooling package
pip3 install pyTooling

# Alternatively
python3 -m pip install pyTooling

# With setuptools support for pyTooling.Packaging
pip3 install pyTooling[packaging]

# Alternatively
python3 -m pip install pyTooling[packaging]

# With color support for pyTooling.TerminalUI
pip3 install pyTooling[terminal]

# Alternatively
python3 -m pip install pyTooling[terminal]

# With YAML support for pyTooling.Configuration.YAML
pip3 install pyTooling[yaml]

# Alternatively
python3 -m pip install pyTooling[yaml]

# Basic pyTooling package
pip install pyTooling

# Alternatively
py -m pip install pyTooling

# With setuptools support for pyTooling.Packaging
pip install pyTooling[packaging]

# Alternatively
py -m pip install pyTooling[packaging]

# With color support for pyTooling.TerminalUI
pip install pyTooling[terminal]

# Alternatively
py -m pip install pyTooling[terminal]

# With YAML support for pyTooling.Configuration.YAML
pip install pyTooling[yaml]

# Alternatively
py -m pip install pyTooling[yaml]

Developers can install the pyTooling package itself or the package with further dependencies for documentation generation (doc), running unit tests (test) or just all (all) dependencies.

See Dependencies for more details.

# Basic pyTooling package
pip3 install pyTooling

# Alternatively
python3 -m pip install pyTooling

# Install with dependencies to generate documentation
pip3 install pyTooling[doc]

# Alternatively
python3 -m pip install pyTooling[doc]

# Install with dependencies to run unit tests
pip3 install pyTooling[test]

# Alternatively
python3 -m pip install pyTooling[test]

# Install with all developer dependencies
pip3 install pyTooling[all]

# Alternatively
python3 -m pip install pyTooling[all]

# Basic pyTooling package
pip install pyTooling

# Alternatively
py -m pip install pyTooling

# Install with dependencies to generate documentation
pip install pyTooling[doc]

# Alternatively
py -m pip install pyTooling[doc]

# Install with dependencies to run unit tests
pip install pyTooling[test]

# Alternatively
py -m pip install pyTooling[test]

# Install with all developer dependencies
pip install pyTooling[all]

# Alternatively
py -m pip install pyTooling[all]

Referencing the package in requirements.txt

When pyTooling is used by another Python package, it’s recommended to list the dependency to the pyTooling package in a requirements.txt file.

requirements.txt

pyTooling ~= 8.0

Updating from PyPI using PIP

# Update pyTooling
pip3 install -U pyTooling

# Alternatively
python3 -m pip install -U pyTooling

# Update pyTooling
pip install -U pyTooling

# Alternatively
py -m pip install -U pyTooling

Uninstallation using PIP

# Uninstall pyTooling
pip3 uninstall pyTooling

# Alternatively
python3 -m pip uninstall pyTooling

# Uninstall pyTooling
pip uninstall pyTooling

# Alternatively
py -m pip uninstall pyTooling

Running unit tests

This package is provided with unit tests for pytest. The provided testcases can be executed locally for testing or development purposes. In addition, code coverage including branch coverage can be collected using Coverage.py. All steps provide appropriate artifacts as XML or HTML reports. The artifact output directories are specified in pyproject.toml.

Ensure unit testing requirements are installed.

cd <pyTooling>

# Running unit tests using pytest
pytest -raP --color=yes tests/unit

cd <pyTooling>

# Running unit tests using pytest
pytest -raP --color=yes --junitxml=report/unit/unittest.xml --template=html1/index.html --report=report/unit/html/index.html --split-report tests/unit

cd <pyTooling>

# Running unit tests with code coverage using Coverage.py
coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests/unit

# Write coverage report to console"
coverage report

# Convert coverage report to HTML
coverage html

# Convert coverage report to XML (Cobertura)
coverage xml

cd <pyTooling>

# Running unit tests using pytest
pytest -raP --color=yes tests\unit

cd <pyTooling>

# Running unit tests using pytest
pytest -raP --color=yes --junitxml=report\unit\unittest.xml --template=html1\index.html --report=report\unit\html\index.html --split-report tests\unit

cd <pyTooling>

# Running unit tests with code coverage using Coverage.py
coverage run --data-file=.coverage --rcfile=pyproject.toml -m pytest -ra --tb=line --color=yes tests\unit

# Write coverage report to console"
coverage report

# Convert coverage report to HTML
coverage html

# Convert coverage report to XML (Cobertura)
coverage xml

Running type checks

This package is provided with type checks. These can be executed locally for testing or development purposes using mypy. The artifact output directory is specified in pyproject.toml.

Ensure unit testing requirements are installed.

cd <pyTooling>

# Running type checking using mypy
export MYPY_FORCE_COLOR=1
mypy -p pyTooling

cd <pyTooling>

# Running type checking using mypy
$env:MYPY_FORCE_COLOR = 1
mypy -p pyTooling

Building documentation

The documentation can be build locally using Sphinx. It can generate HTML and LaTeX outputs. In an additional step, the LaTeX output can be translated to a PDF file using a LaTeX environment like MiKTeX.

Ensure documentation requirements are installed.

cd <pyTooling>

# Adding package root to PYTHONPATH
export PYTHONPATH=$(pwd)
cd doc

# Building documentation using Sphinx
sphinx-build -v -n -b html -d _build/doctrees -j $(nproc) -w _build/html.log . _build/html

cd <pyTooling>

# Adding package root to PYTHONPATH
export PYTHONPATH=$(pwd)
cd doc

# Building documentation using Sphinx
sphinx-build -v -n -b latex -d _build/doctrees -j $(nproc) -w _build/latex.log . _build/latex

Todo

Describe LaTeX to PDF conversion on Linux using Miktex.

Hint

A Miktex installation is required.

cd <pyTooling>

# Building documentation using Sphinx
.\doc\make.bat html --verbose

cd <pyTooling>

# Building documentation using Sphinx
.\doc\make.bat latex --verbose

Todo

Describe LaTeX to PDF conversion on Windows using Miktex.

Hint

A Miktex installation is required.

Local Packaging and Installation via PIP

For development and bug fixing it might be handy to create a local wheel package and also install it locally on the development machine. The following instructions will create a local wheel package (*.whl) and then use PIP to install it. As a user might have a pyTooling installation from PyPI, it’s recommended to uninstall any previous pyTooling packages. (This step is also needed if installing an updated local wheel file with same version number. PIP will not detect a new version and thus not overwrite/reinstall the updated package contents.)

Ensure packaging requirements are installed.

cd <pyTooling>

# Package the code in a wheel (*.whl)
python3 -m build --wheel

# Uninstall the old package
python3 -m pip uninstall -y pyTooling

# Install from wheel
python3 -m pip install ./dist/pyTooling-8.0.0-py3-none-any.whl

cd <pyTooling>

# Package the code in a wheel (*.whl)
py -m build --wheel

# Uninstall the old package
py -m pip uninstall -y pyTooling

# Install from wheel
py -m pip install .\dist\pyTooling-8.0.0-py3-none-any.whl

Note

The legacy ways of building a package using setup.py bdist_wheel and installation using setup.py install is not recommended anymore.