This is an automated email from the ASF dual-hosted git repository. xuanwo pushed a commit to branch add-contributing-for-pyhon in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
commit 7cae31e99efc6e41717288ff40d25769485d5353 Author: Xuanwo <[email protected]> AuthorDate: Mon May 1 20:38:07 2023 +0800 docs: Add CONTRIBUTING for python Signed-off-by: Xuanwo <[email protected]> --- .devcontainer/post_create.sh | 2 +- bindings/python/CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh index 1397aa47..b6459759 100644 --- a/.devcontainer/post_create.sh +++ b/.devcontainer/post_create.sh @@ -25,7 +25,7 @@ sudo apt update sudo apt install -y ruby-dev libclang-dev # Setup for python binding -sudo apt install -y python3-dev +sudo apt install -y python3-dev python3-pip python3-venv # Setup for nodejs binding curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs diff --git a/bindings/python/CONTRIBUTING.md b/bindings/python/CONTRIBUTING.md new file mode 100644 index 00000000..a3a0b217 --- /dev/null +++ b/bindings/python/CONTRIBUTING.md @@ -0,0 +1,75 @@ +# Contributing + +- [Setup](#setup) + - [Using a devcontainer environment](#using-a-devcontainer-environment) + - [Bring your own toolbox](#bring-your-own-toolbox) +- [Prepare](#prepare) +- [Build](#build) +- [Test](#test) +- [Docs](#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](https://containers.dev/) that could be used in [Github Codespaces](https://github.com/features/codespaces), [VSCode](https://code.visualstudio.com/), [JetBrains](https://www.jetbrains.com/remote-development/gateway/), [JuptyerLab](https://jupyterlab.readthedocs.io/en/stable/). Please pick up your favourite runtime environment. + +The fastest way is: + +[](https://codespaces.new/apache/incubator-opendal?quickstart=1&machine=standardLinux32gb) + +### 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 Debain: + +```shell +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 developement. + +After `venv` has been prepared, you can activate it by `source venv/bin/activate`. + +To simplify our work, we will utilize the tool [`maturin`](https://github.com/PyO3/maturin). Kindly install it beforehand. + +```shell +pip install maturin[patchelf] +``` + +## Build + +To build python binding: + +```shell +maturin develop +``` + +## Test + +OpenDAL adopts `behave` for behavior tests: + +```shell +maturin develop -E test +behave tests +``` + +## Docs + +Build API docs: + +```shell +maturin develop -E docs +pdoc opendal +```
