# Developer Guide for Fluid Python SDK

## Set up the development environment

[fluid-client-python](https://github.com/fluid-cloudnative/fluid-client-python) is a git submodule
of [fluid-cloudnative/fluid](https://github.com/fluid-cloudnative/fluid).

Git clone the full repository by running the following command:

```
mkdir <workspace>
cd <workspace>
git clone --recursive https://github.com/fluid-cloudnative/fluid.git
```

Checkout fluid-client-python to the latest commit:

```
pushd . && cd fluid/sdk/python && git checkout master && popd
```

## Sync Fluid API

Most code in this Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech/)
project.
Run the following command to sync the latest Fluid API to the Python package:

```
make gen-sdk
```

## Locally debug the Python SDK

It is recommended to install Fluid Python SDK in a development mode (a.k.a. editable install) for easier debugging.

```
cd fluid/sdk/python
pip install -e .
```

Now starts the Python interpreter and you can import the SDK:

```
>>> from fluid import FluidClient
...
```

# Publish Fluid Python SDK to PyPI (or Test PyPI)

1. Push commits to the `master` branch or `release-X` branch (e.g. `release-1.0`)

2. Publish the latest Fluid Python SDK as a release candidate to Test PyPI

   The project leverages [setuptools_scm](https://github.com/pypa/setuptools_scm) to automatically generate the version
   number from the latest git tag.
   So for a release candidate version, tag the latest commit with `vX.Y.Z-rcN` and use `git push --tags` to trigger
   a [GitHub Workflow](https://github.com/fluid-cloudnative/fluid-client-python/blob/master/.github/workflows/release.yml)
   to automatically build and publish the package to Test PyPI.
   For example:
    ```
   git tag v1.0.1-rc1
   git push --tags origin
   ```

3. Install and verify the release candidate package
    ```
    pip install --upgrade --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple fluid-pysdk==v1.0.1-rc1
    ```

4. Cut a release and publish it to PyPi

   Similarly, to cut a release and publish it to PyPi, tag the latest commit with `vX.Y.Z` or `vX.Y.Z.postN`(See [Versioning](../../README.md#Versioning)) and use `git push --tags` to
   trigger
   a [GitHub Workflow](https://github.com/fluid-cloudnative/fluid-client-python/blob/master/.github/workflows/release.yml)
   to automatically build and publish the package to PyPi.
   For example:
    ```
    # first release (compatible APIs with Fluid v1.0.1)
    git tag v1.0.1
   
    # second release (compatible APIs with Fluid v1.0.1)
    git tag v1.0.1.post1
   
    git push --tags origin
    ```

> [!IMPORTANT]
> PyPi does not allow re-uploading the same version. Make sure you are incrementing the version number before tagging
> any commits.