Development

Editable Install

To install visionsim locally in an editable state with all required development dependencies, clone the repository, navigate to it and run:

$ pip install -e . --group dev --group docs

Similarly, to install visionsim in an editable manner within Blender’s runtime, you can do the following:

$ visionsim post-install --editable

Running Tests

We use pytest for testing, all tests can be ran directly using the pytest CLI from the project’s root, or equivalently using inv test. When running the tests, you can optionally pass in the name of a specific test file/test function and path to a install of Blender to test with, like so:

$ pytest tests/test_simulate.py --executable=<path-to-blender>

To ensure that there’s no conflicts due to different versions of the libraries between the server/client sides, a editable post-install task is run when starting the tests.

The -rP option is also helpful for seeing any stdout messages that are otherwise hidden.

Running CI Locally

You can run the CI locally using the ACT CLI, or use it’s vscode extension as a front end. Using the CLI, you can run all workflows that trigger on a push using act push. The following command will run the workflows and, if they fail, open an interactive shell into the latest container:

$ act push || docker exec -it `docker ps -q | head -n1` bash

Building the Documentation

In the project root, with visionsim installed with the dev dependencies, run:

$ inv clean build-docs --preview

Dev tools

We’re using invoke to manage common development and housekeeping tasks.

Make sure you have invoke installed then you can run any of the following tasks from the project root:

$ invoke --list
Available tasks:

  build-docs       Confirm docs can be built
  clean            Runs all clean sub-tasks
  clean-build      Clean up files from package building
  clean-docs       Clean up docs build
  clean-python     Clean up python file artifacts
  clean-tests      Clean up files from testing
  coverage         Create coverage report
  format           Format code (and sort imports)
  generate-stubs   Generate .pyi files to enable autocomplete of dynamic
                   attributes (eg for BlenderClients).
  lint             Lint code with ruff
  precommit        Run pre-commit hooks
  test             Run tests
  test-stubs
  type-check

It’s also recommended using the pre-commit hook that will lint/test/clean the code before every commit. For this make sure that invoke and pre-commit are installed (via pip) and then install the pre-hooks with:

$ pre-commit install

See pre-commit for more.

Release Process

To prepare for a new release, first ensure all tests, linting, formatting and typing checks pass, and update the documentation and version numbers accordingly. Then you’ll need to build the new source distribution and push it to PyPI using twine.

The up-to-date source on this is the python package authority, but you’ll have to first build the source distribution using:

$ python -m build

Then upload it to PyPI with twine:

$ python -m twine upload dist/*