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.

Most operating systems and distributions already have Python installed. If not, please install Python and its development tools first.

For Ubuntu and Debian:

sudo apt install -y python3-dev python3-pip python3-venv

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.7. You can use python -m venv venv to setup virtualenv to start development.

After venv has been prepared, you can activate it by source venv/bin/activate.

To simplify our work, we will utilize the tool maturin. Kindly install it beforehand.

pip install maturin[patchelf]

Build

To build python binding only:

maturin build

To build and install python binding directly in the current virtualenv:

maturin develop

Note: maturin develop will be faster, but doesn't support all the features. In most development cases, we recommend using maturin develop.

Test

OpenDAL adopts pytest for behavior tests:

maturin develop -E test
# To run `test_write.py` and use `fs` operator
OPENDAL_TEST=fs OPENDAL_FS_ROOT=/tmp pytest -vk test_write

Docs

Build API docs:

maturin develop -E docs
pdoc opendal