Development Setup

PDDLSIM uses pyproject.toml and modern standards for managing dependencies, building, and publishing. Therefore, you can use any tool that supports these standards to work on PDDLSIM. You may also use pip, but note that currently, pip does not support PEP 735, which is used to specify development-only dependencies, such as pytest. While this shouldn't be relevant to your workflow, note that Hatchling is PDDLSIM's build backend.

Note

If you've worked with pyproject.toml based projects before, you might not need to read this. Simply make sure you look at the pyproject.toml file, and install using your tool of choice all of the dependencies you need.

To start, you need a copy of PDDLSIM's repository. If you are planning to contribute to PDDLSIM, you should first fork its repository, as described in Contributing. Otherwise, you can clone PDDLSIM using HTTPS, with:

git clone https://github.com/galk-research/pddlsim.git

Or using SSH, with:

git clone git@github.com:galk-research/pddlsim.git

To properly setup SSH with GitHub, read Connecting to GitHub with SSH.

Developing with uv

To use uv with the project, first install uv. Once you have uv installed and in your $PATH, run:

uv sync

to setup a Virtual Enviroment with all of PDDLSIM's dependencies. To avoid installing development dependencies, add the --no-dev flag. Additionally, you can prevent any local package from being installed in editable mode by using the --no-editable flag. Check out other options are by using the --help flag.

At this stage, you should be able to begin development with no issue. Make sure to use the newly created Python interpreter in your code editor. It should generally be in the .venv/ folder. Without registering the Virtual Environment with your editor, you might not be able to use some commands, from, for instance, development dependencies, in your shell.

Assuming your editor has no Python Virtual Environment integration, you can get the command for activating the Virtual Environment in your shell with:

uv venv

Then, run the printed command. This will put you inside of the Virtual Environment.

Important

Just running uv venv doesn't activate the Virtual Environment. You must take the text output by the command above, and run that, in your shell, to activate it.

Developing with pip

Note

pip does not support PEP 735, which is used to specify development-only dependencies. This means for instance, that you won't be able to use pytest, without manually installing it. This means looking at the pyproject.toml's [dependency-groups] and using that to guide manual installation.

pip is the de-facto standard for Python package management. We assume a sufficient version of pip, with PEP 621 support, is already installed, and do not detail the creation of a Virtual Environment. For creating a Virtual Environment, see this page. Note that you must use Python 3.13, or higher.

Warning

If you continue without creating a Virtual Environment, you will need either root access, for a global install, or will have to use the --user. Either way, pip will install the dependencies globally. This is not likely to be what you want.

First, we will install PDDLSIM's dependencies to our environment, by running:

pip install -e <PATH-TO-PDDLSIM-DIRECTORY>

where <PATH-TO-PDDLSIM-DIRECTORY> should be replaced by the path to the directory containing the PDDLSIM project's source files. Assuming this is the current working directory, one may run:

pip install -e .

Note that the above commands will install PDDLSIM in editable mode. This is generally preferred for development, as changing the project source files won't require rebuilding it for testing changes. You can drop the -e flag to install PDDLSIM regularly.

After this, assuming you need any development dependencies, to for example, run tests, format code, etc., you will need to install the development dependencies manually. They are found in pyproject.toml, under the [dependency-groups] table.

Developing with other standards-compliant project managers

Each project manager will have a slightly different process for setup, and so only general steps and information is laid out here:

1. Install Python, or setup a Python Virtual Environment with your tool of choice. Make sure you are using Python 3.13 or higher.
2. Install all of PDDLSIM's dependencies specified in its pyproject.toml with the corresponding command. Note that PEP 735, used for specifying development dependencies, is still relatively new, and your tool might not support it, so you might need to manually install PDDLSIM's development dependencies, by consulting its pyproject.toml file.
3. Register your Virutal Environment with your code editor, or activate the Virtual Environment in your shell.