CONTRIBUTING.md

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