From 7cae31e99efc6e41717288ff40d25769485d5353 Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Mon, 1 May 2023 20:38:07 +0800 Subject: [PATCH 1/3] docs: Add CONTRIBUTING for python Signed-off-by: Xuanwo --- .devcontainer/post_create.sh | 2 +- bindings/python/CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 bindings/python/CONTRIBUTING.md diff --git a/.devcontainer/post_create.sh b/.devcontainer/post_create.sh index 1397aa471c2b..b645975955a3 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 000000000000..a3a0b2173196 --- /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: + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](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 +``` From 7f91b09102600e82c1b20f87730a1c195c6702c5 Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Mon, 1 May 2023 20:38:35 +0800 Subject: [PATCH 2/3] Update root Signed-off-by: Xuanwo --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 624abe8d81f9..2f5d2ae957ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,6 +94,7 @@ Some components may require specific setup steps. Please refer to their respecti - [Core](core/CONTRIBUTING.md) - [Node.js Binding](bindings/nodejs/CONTRIBUTING.md) +- [Python Binding](bindings/python/CONTRIBUTING.md) ## Code of Conduct From cfec6538a3461d1e432ed546ddd1f659330d6f4d Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Mon, 1 May 2023 20:38:47 +0800 Subject: [PATCH 3/3] Fix typo Signed-off-by: Xuanwo --- bindings/python/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bindings/python/CONTRIBUTING.md b/bindings/python/CONTRIBUTING.md index a3a0b2173196..5454729bd6c1 100644 --- a/bindings/python/CONTRIBUTING.md +++ b/bindings/python/CONTRIBUTING.md @@ -28,7 +28,7 @@ The `python` binding requires `Python` to be built. We recommend using the lates Most operating systems and distributions already have Python installed. If not, please install Python and its development tools first. -For Ubuntu and Debain: +For Ubuntu and Debian: ```shell sudo apt install -y python3-dev python3-pip python3-venv @@ -38,7 +38,7 @@ sudo apt install -y python3-dev python3-pip python3-venv 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. +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`.