tox.ini

[tox]
description = Default tox environments list
envlist =
    code-style
    tests-core{-migration,-aviator,-stk,-vgt,}{-graphics,-nographics,-graphicsonly,}{-cov,-nocov,}{-linux,}
    tests-extensions{-graphs,}{-cov,}
    doc-style-{linux,windows}
    doc-{links,html,pdf}
    docker-build-{ubuntu,windows}_images
    docker-run-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host
    vulnerabilities-{code,deps}
    dist
skip_missing_interpreters = true
isolated_build = true
isolated_build_env = build

[testenv]
description = Test PySTK
    core: core
    extensions: extensions
    graphs: graphs
    aviator: aviator
    stk: stk
    vgt: vgt
    snippets: doc snippets
    migration: API migration assistant
    graphics: with graphics
    nographics: with no graphics
    graphicsonly: with graphics only
    linux: without Linux
    cov:  and measure coverage
basepython =
    test311: python3.11
    test312: python3.12
    test313: python3.13
    {style,tests,doc,vulnerabilities,dist}: python3
passenv =
    ANSYSLMD_LICENSE_FILE
    LD_LIBRARY_PATH
    STK_USER_HOME
    STK_INSTALL_DIR
    STK_CONFIG_DIR
    COVERAGE_FILE
    BUILD_API
    BUILD_EXAMPLES
    DISPLAY
setenv =
    PYTHONUNBUFFERED = yes

    # TODO: exclude plugins from the test run
    # https://github.com/ansys/pystk/issues/737
    PYTEST_EXCLUDE_FILES =
    aviator,stk,vgt,snippets: PYTEST_EXCLUDE_FILES = --exclude PluginTests

    # Target library and coverage configuration
    core: TARGET_LIBRARY = ansys.stk.core
    extensions: TARGET_LIBRARY = ansys.stk.extensions

    # Coverage configuration
    PYTEST_COV =
    cov: PYTEST_COV = --cov={env:TARGET_LIBRARY}

    # Test files
    PYTEST_TEST_FILES = tests
    aviator: PYTEST_TEST_FILES = {toxinidir}/tests/generated/aviator_tests
    stk: PYTEST_TEST_FILES = {toxinidir}/tests/generated/stk_tests
    vgt: PYTEST_TEST_FILES = {toxinidir}/tests/generated/vgt_tests
    snippets: PYTEST_TEST_FILES = {toxinidir}/tests/doc_snippets_tests
    migration: PYTEST_TEST_FILES = {toxinidir}/tests/api_migration_assistant_tests
    extensions: PYTEST_TEST_FILES = {toxinidir}/tests/extensions
    graphs: PYTEST_TEST_FILES = {toxinidir}/tests/extensions/data_analysis/graphs

    # Pytest extra arguments for tests requiring linux
    PYTEST_PLATFORM_OPTIONS =
    linux: PYTEST_PLATFORM_OPTIONS = --exclude ExcludeOnLinux --exclude SEET

    # Pytest extra arguments for tests requiring targets
    PYTEST_TARGET =
    graphics: PYTEST_TARGET = --target StkX
    nographics: PYTEST_TARGET = --target StkXNoGfx
    graphicsonly: PYTEST_TARGET = --target StkX

    # Pytest extra arguments for tests requiring graphics
    PYTEST_GRAPHICS_OPTIONS =
    extensions,graphs: PYTEST_GRAPHICS_OPTIONS = --mpl
    graphics: PYTEST_GRAPHICS_OPTIONS =
    nographics: PYTEST_GRAPHICS_OPTIONS = --exclude 'Graphics Tests' --exclude 'VO Tests'
    graphicsonly: PYTEST_GRAPHICS_OPTIONS = --include 'Graphics Tests' --include 'VO Tests' --deselect=area_target/area_target.py::EarlyBoundTests::test_AccessDataDisplay --deselect=mto/mto.py::EarlyBoundTests::test_VODefaultTrack --deselect=mto/mto.py::EarlyBoundTests::test_VOGlobalTrack --deselect=mto/mto.py::EarlyBoundTests::test_VOTrack --deselect=volumetric/volumetric

usedevelop = true
extras =
    snippets: grpc, extensions
    migration: migration
    extensions: extensions
dependency_groups =
    tests
commands =
    pytest {env:PYTEST_TEST_FILES} \
        {env:PYTEST_EXCLUDE_FILES} \
        {env:PYTEST_PLATFORM_OPTIONS} \
        {env:PYTEST_TARGET} \
        {env:PYTEST_GRAPHICS_OPTIONS} \
        {env:PYTEST_COV} \
        {posargs:-vvv}

[testenv:vulnerabilities-{code,deps}]
description = Checks vulnerabilities within the source code and its dependencies
skip_install = false
setenv =
    code: TOOL = bandit
    code: TOOL_OPTS = -c {toxinidir}/pyproject.toml -r {toxinidir}/src
    code: TOOL_REPORT = -o {toxinidir}/log/bandit.json -f json

    deps: TOOL = safety
    # PyPI vulnerability: https://data.safetycli.com/v/67599/97c
    deps: IGNORE_VULNERABILITIES = 67599
    deps: TOOL_OPTS = check -o bare --continue-on-error -i {env:IGNORE_VULNERABILITIES}
    deps: TOOL_REPORT = --save-json {toxinidir}/log/safety.json
dependency_groups =
    vulnerabilities
extras =
    all
commands =
    {env:TOOL} {env:TOOL_OPTS} {env:TOOL_REPORT}

[testenv:code-style]
description = Checks project code style
skip_install = true
deps =
    pre-commit
commands =
    pre-commit install
    pre-commit run --all-files --show-diff-on-failure

[testenv:doc-style-{linux,windows}]
description = Checks project documentation style
skip_install = true
dependency_groups =
    docstyle
allowlist_externals =
    find
    vale
    bash
    cmd
platform =
    linux: linux
    windows: win32
commands =
    linux: bash -c 'rst_files=$(find {toxinidir}/doc/source -type f -name "*.rst" ! -path "doc/source/api/*") && py_files=$(find {toxinidir}/examples -type f -name "*.py" ! -name "*_*") && vale_files="$rst_files $py_files" && vale sync --config="{toxinidir}/doc/.vale.ini" && vale --config="{toxinidir}/doc/.vale.ini" $rst_files'
    windows: cmd /c "dir /s /b {toxinidir}\doc\source\*.rst | findstr /v /i \doc\source\api\ > tmp_files.txt"
    # see .github/workflows/ci_cd_pr.yml#L135 - python examples are currently excluded
    #windows: cmd /c "dir /s /b {toxinidir}\examples\*.py | findstr /v /i examples.*_.* >> tmp_files.txt"
    windows: cmd /c "vale sync --config="{toxinidir}\doc\.vale.ini""
    windows: cmd /v:on /c "set vale_files="" && (for /f %i in (tmp_files.txt) do @set vale_files="%i" !vale_files!) && @del tmp_files.txt && vale --config="{toxinidir}\doc\.vale.ini" !vale_files!"

[testenv:doc-{clean,links,html,pdf,serve,snippets}]
description =
    clean: Clean rendered documentation
    links: Check documentation links
    html: Build HTML documentation
    pdf: Build PDF documentation
    snippets: Update documentation based on state of doc_snippets_tests directory
skip_install =
    clean, serve: true
allowlist_externals =
    pdflatex
setenv =
    SOURCE_DIR = doc/source
    BUILD_DIR = doc/_build
    STATIC_DIR = doc/source/_static
    links: BUILDER = linkcheck
    html: BUILDER = html
    pdf: BUILDER = latex
    links,html,pdf: BUILDER_OPTS = --color -v -j auto -W --keep-going
passenv =
    ANSYSLMD_LICENSE_FILE
    LD_LIBRARY_PATH
    STK_USER_HOME
    STK_INSTALL_DIR
    STK_CONFIG_DIR
    BUILD_API
    BUILD_EXAMPLES
    DISPLAY
    APPDATA
extras =
    extensions
    jupyter
dependency_groups =
    links,html,pdf: doc
commands =
    # Remove rendered documentation and additional static files
    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
    clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:STATIC_DIR}/artifacts"

    # Render documentation with desired builder
    links,html,pdf: python -m build "{toxinidir}" --outdir "{toxinidir}/{env:STATIC_DIR}/artifacts"
    links,html,pdf: sphinx-build -d "{toxworkdir}/doc_doctree" {env:SOURCE_DIR} "{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {env:BUILDER_OPTS} -b {env:BUILDER}

    # PDF documentation
    pdf: pdflatex -interaction=nonstopmode -output-directory="{toxinidir}/{env:BUILD_DIR}/{env:BUILDER}" {toxinidir}/{env:BUILD_DIR}/{env:BUILDER}/ansys-stk.tex

    # Serve HTML documentation
    serve: python -m http.server --directory "{toxinidir}/{env:BUILD_DIR}/html"

    # Run snippets updater tool
    snippets: python "{toxinidir}/scripts/python_snippets_updater.py"

# The following environments are only for development purposes. Do not use in CI/CD.
# Using these during a CI/CD can lead to unexpected issues due to a Docker-In-Docker
# situation.

[testenv:docker-build-{ubuntu,windows}_images]
description = Build all Docker images for
    ubuntu_images: Ubuntu
    windows_images: Windows
skip_install = true
allowlist_externals =
    docker
    compose
commands =
    ubuntu_images: docker compose --file "{toxinidir}/docker/linux/ubuntu/docker-compose.yml" build
    windows_images: docker compose --file "{toxinidir}/docker/windows/docker-compose.yml" build --build-arg {posargs}

[testenv:docker-run-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Run a PySTK container with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
passenv =
    COLUMNS
    LINES
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    # Host platform specific arguments
    linux_host:   HOST_ARGS = --env DISPLAY={env:DISPLAY}
    windows_host: HOST_ARGS = -p 8888:8888
    # Ubuntu container
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    ubuntu_container: CONTAINER_ARGS = --volume "{toxinidir}:/home/stk/pystk"
    ubuntu_container: CONTAINER_CMD = /bin/bash -c "cd /home/stk && python -m venv .venv && source .venv/bin/activate && python -m pip install --upgrade pip && python -m pip install -e /home/stk/pystk[all] && cd /home/stk/pystk && python -m pip install --group tests . && python -m pip install --group doc ."
    ubuntu_container: WINDOWS_HOST_ROOT_CMD = /bin/bash -c "chown -R stk:stk /home/stk/pystk/tests"
    ubuntu_container: ROOT_USER = root
    # Windows container
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
    windows_container: CONTAINER_ARGS = --volume "{toxinidir}:C:\Users\STK\pystk"
    windows_container: CONTAINER_CMD = cmd /C "python -m venv .venv && cd pystk && chcp 65001 && call C:\Users\STK\.venv\Scripts\activate.bat && python -m pip install --upgrade pip && python -m pip install -e C:\Users\STK\pystk[all]  && python -m pip install --group tests . && python -m pip install --group doc ."
    windows_container: WINDOWS_HOST_ROOT_CMD = cmd /C "takeown /F C:\Users\STK\pystk\tests /R /D Y 2> nul"
    windows_container: ROOT_USER = STK
allowlist_externals =
    docker
commands =
    # Start a container with the desired configuration
    docker run \
        --detach --interactive --tty \
        --env ANSYSLMD_LICENSE_FILE={env:ANSYSLMD_LICENSE_FILE} \
        {env:HOST_ARGS} \
        {env:CONTAINER_ARGS} \
        --name stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} \
        ansys/stk-13.1:dev-{env:CONTAINER_OS}-python{env:PYTHON_VERSION}

    # HACK: a virtual environment fixes allows Jupyter Lab to operate as expected.
    # These issues may be raised because of the custom Python installation
    # in the Docker images.
    # TODO: Once gRPC is enabled, this should be revisited since Python will
    # no longer need to be installed inside the container.
    docker exec --interactive --tty -e COLUMNS=$COLUMNS -e LINES=$LINES \
        stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} {env:CONTAINER_CMD}

    # On Windows, the docker volume is exposed in the container with the owner and group
    # for all the files and directories set to root.
    # Change both to the "stk" user used to run the container, so tests relying
    # on file permissions work correctly.
    windows_host: docker exec --user {env:ROOT_USER} --interactive --tty stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} {env:WINDOWS_HOST_ROOT_CMD}

[testenv:docker-exec-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Execute a command in a PySTK container with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
passenv =
    COLUMNS
    LINES
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    # Ubuntu container
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    ubuntu_container: VENV_CMD = /bin/bash -c 'cd /home/stk && source .venv/bin/activate && {posargs}'
    # Windows container
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
    windows_container: VENV_CMD = cmd /C ""mode con:cols=100 lines=50 && chcp 65001 && call C:\\Users\\STK\\.venv\\Scripts\\activate.bat && {posargs}""
allowlist_externals =
    docker
commands =
    docker exec --interactive --tty -e COLUMNS=$COLUMNS -e LINES=$LINES \
        stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} {env:VENV_CMD}

[testenv:docker-lab-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Run Jupyter Lab in a PySTK container with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    # Host platform specific arguments
    linux_host:   HOST_ARGS =
    windows_host: HOST_ARGS =
    # Ubuntu container
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    ubuntu_container: LAB_CMD = /bin/bash -c 'cd /home/stk && source .venv/bin/activate && jupyter lab {env:HOST_ARGS} --ip=0.0.0.0 --port 8888 --no-browser --NotebookApp.token=pystk --notebook-dir=/home/stk/pystk'
    # Windows container
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
    windows_container: LAB_CMD = cmd -c "chcp 65001 && call C:\Users\STK\.venv\Scripts\activate.bat && python -m jupyter lab --ip=0.0.0.0 --port 8888 --no-browser --NotebookApp.token=pystk --notebook-dir=C:\Users\STK\pystk"
allowlist_externals =
    docker
commands =
    docker exec --interactive --tty \
        stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} {env:LAB_CMD}

[testenv:docker-novnc-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Expose the PySTK container UI with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
allowlist_externals =
    docker
commands =
    ubuntu_container: docker exec --interactive --tty --user root stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} \
    ubuntu_container:     /bin/bash -c ' \
    ubuntu_container:         apt-get update -y; \
    ubuntu_container:         apt-get install -y sudo sed fluxbox novnc python3-websockify python3-numpy x11vnc xterm; \
    ubuntu_container:         usermod -aG sudo stk; \
    ubuntu_container:         echo "stk:stk" | chpasswd; \
    ubuntu_container:         echo "stk ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers; \
    ubuntu_container:         sed -i \
    ubuntu_container:             "s/this.attach(new WebSocket(uri, protocols));/this.attach(new WebSocket(uri, ['"'"'binary'"'"', '"'"'base64'"'"']));/g" \
    ubuntu_container:             /usr/share/novnc/core/websock.js \
    ubuntu_container:     '
            # See https://techglimpse.com/openstack-novnc-code-400-base64-protocol-error/

    docker exec --interactive --tty stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION} \
        /bin/bash -i -c ' \
            fluxbox -display :0 & \
            x11vnc -forever -shared -display :0 & \
            xterm -e "source ${HOME}/.venv/bin/activate; $SHELL" & \
            sleep 8; \
            echo "***************************************************"; \
            echo "* Navigate to http://127.0.0.1:8888/vnc_auto.html *"; \
            echo "***************************************************"; \
            websockify --web=/usr/share/novnc/ 8888 localhost:5900 \
        '

[testenv:docker-stop-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Stop the PySTK container with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    # Ubuntu container
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    # Windows container
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
allowlist_externals =
    docker
commands =
    docker stop stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION}

[testenv:docker-rm-py3{10,11,12,13}-{ubuntu,windows}_container-{linux,windows}_host]
description = Remove the PySTK container with
    py310: Python 3.10
    py311: Python 3.11
    py312: Python 3.12
    py313: Python 3.13
    ubuntu_container: and Ubuntu
    windows_container: and Windows
    linux_host: in a Linux host
    windows_host: in a Windows host
skip_install = true
platform =
    windows_host: win32
    linux_host: linux
setenv =
    # Python version selector
    py310: PYTHON_VERSION = 3.10
    py311: PYTHON_VERSION = 3.11
    py312: PYTHON_VERSION = 3.12
    py313: PYTHON_VERSION = 3.13
    # Linux Ubuntu container
    ubuntu_container: CONTAINER_OS = ubuntu22.04
    # Windows container
    windows_container: CONTAINER_OS = windowsservercore-ltsc2019
allowlist_externals =
    docker
commands =
    docker rm --force stk-{env:CONTAINER_OS}-python{env:PYTHON_VERSION}

[testenv:dist{-wheels,-source,}]
description = Build
    dist: wheel and source distribution artifacts
    wheel: wheel distribution artifact
    sdist: source distribution artifact
skip_install = true
deps =
    build
setenv:
    wheel: BUILD_CMD = --wheel
    source: BUILD_CMD = --sdist
commands =
    python -m build --outdir {toxinidir}/dist {env:BUILD_CMD} {toxinidir}