Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

docs: Add CONTRIBUTING for python #2188

Merged
merged 4 commits into from
May 1, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .devcontainer/post_create.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
75 changes: 75 additions & 0 deletions bindings/python/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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 Debian:

```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 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`](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
```