Contributing

• Contributing
  • Setup
    • Using a dev container environment
    • Bring your own toolbox
  • Prepare
  • Build
  • Test
  • Docs

Setup

Building python bindings requires some extra setup.

For small or first-time contributions, we recommend the dev container method. Prefer to do it yourself? That's fine too!

Using a dev container environment

OpenDAL provides a pre-configured dev container that could be used in GitHub Codespaces, VSCode, JetBrains, JupyterLab. Please pick up your favourite runtime environment.

The fastest way is:

Bring your own toolbox

The python binding requires Python to be built. We recommend using the latest stable version for development.

[!TIP] We recommend to use uv to manage the Python packages and environments. You can install it by curl -LsSf https://astral.sh/uv/install.sh | sh.

Prepare

All operations were performed within a Python virtual environment (venv) to prevent conflicts with the system's Python environment or other project venvs.

OpenDAL specify the requires-python in pyproject.toml as >= 3.10. You can use uv venv --python 3.10 to setup the virtualenv for development.

To get ready for the development, kindly install all the required dependencies:

uv sync --all-groups --all-extras

Build

To build python binding only:

uv build

Note that uv will detect the related files and re-build this package when necessary.

[!NOTE] If you want to have a full-featured opendal, you can run uv build and install the wheel file in the dist directory.

Test

OpenDAL adopts pytest for behavior tests:

# To run `test_write.py` and use `fs` operator
OPENDAL_TEST=fs OPENDAL_FS_ROOT=/tmp uv run pytest -vk test_write

# To run `test_sync_write` in `test_write.py` and use `fs` operator
OPENDAL_TEST=fs OPENDAL_FS_ROOT=/tmp uv run pytest -v tests/test_write.py::test_sync_write

Docs

Build API docs:

uv run pdoc opendal