Skip to content

developer_guide.md

Latest commit

 

History

History
174 lines (118 loc) · 7.48 KB

developer_guide.md

File metadata and controls

174 lines (118 loc) · 7.48 KB

SaaS API for Python — Developer Guide

Git Pre-Commit Hooks

saas-api-python includes a file .pre-commit-config.yaml.

The following command installs the pre-commit hooks, see also framework pre-commmit and Git documentation on Customizing Git Git Hooks:

poetry run -- pre-commit install

When the hooks are installed, then git will run each of the hooks on the resp. stage, e.g. before executing a commit. The Hooks include linting, code-formating and generating the api for each commit, so it stays up to date.

Generate the API Model

The model layer of this API has been generated from the OpenAPI specification in JSON format of the SaaS API https://cloud.exasol.com/openapi.json using openapi-python-client.

See also API Documentation and Swagger UI.

In order to regenerate the model layer please use the following command line:

poetry run -- nox -s api:generate

Check API Outdated

The CI checks include a check "Check API Outdated" (file check-api-outdated.yml, uses nox task api:check-outdated), which regenerates the api, and checks it against the api version commited to GitHub.

If this check fails, it is likely for one of the following causes:

  • SaaS API could have changed in the meantime (should be detected automatically)
  • SaaS production vs. live system potentially can have subtle differences in the json API description (for api generation the production system is used)
  • The version of python used changed
  • The version of the generator openapi-python-client changed

In any of those cases, generating the api might give different results than in previous commits. These changes in the generated api need to be commited to your GitHub branch for the check to pass in the CI. This should be done automatically by the Pre-Commit Hooks (check if they are installed correctly), but can also be done manually by calling the nox task api:generate, and commiting the results. Before commiting, you might want to run the nox task api:check-outdated locally to see if it passed or if there are further problems:

poetry run -- nox -s api:check-outdated

another cause for the check failing might be a python-toolbox update changing the linting/code formating. This can result in formatting tools like black or isort can modifying the generated code and causing artificial changes.

Change the Source URL of the API Model JSON Definition

If you want to retrieve the JSON definition for the API model from a different source then just edit file noxfile.py.

Read JSON definition From a Local File

Use CLI option --path to read the JSON definition from a local file instead of a URL:

"--path", "/path/to/openapi.json",

Generate file pyproject.toml

openapi-python-client reads the JSON specification of the SaaS API and generates a python client. The generated client code requires transitive dependencies, though, which need to be added to file pyproject.toml to make them available for dependents of SAPIPY.

The easiest way is to make openapi-python-client create a dedicated file pyproject.toml and copy the transitive dependencies from there to SAPIPY's file pyproject.toml.

In order to create file pyproject.toml

  • In file noxfile.py, function generate_api you need to replace mode update by generate.
  • Additionally, in file openapi_config.yml you need to specify a non-existing top-level directory as project_name_override and a package that does not contain slashes, e.g.
project_name_override: "generate"
package_name_override: saas.client.openapi
post_hooks: []

After generating the API,

  • Copy the dependencies from file generate/pyproject.toml and
  • Remove directory generate.

Run Tests

Integration Tests

Executing the integration tests requires the following environment variables to be set:

Variable Description
SAAS_HOST Host to use for requests to REST API
SAAS_ACCOUNT_ID ID of the Exasol SAAS account to be used by the tests
SAAS_PAT Personal access token to access the SAAS API

Slow Tests

Some of the test cases verify connecting to a SaaS database instance and execution will take about 20 minutes.

The regular CI build will ask for a confirmation (aka. "review) before executing these tests.

Creating a Release

Prepare the Release

There are two scenarios for preparing a release:

In both scenarios the SAPIPY relies on Exasol's python-toolbox for preparing a release.

The invocation depends on your setup:

  • When working in a poetry shell, you need to add one double-dash -- argument to separate arguments to the nox-session prepare-release.
  • When calling poetry directly for one-time usage, then you need to add two double-dashes -- -- to terminate arguments to poetry and nox before arguments to the nox-session.
poetry run -- nox -s release:prepare -- <version>

Scenario a) Prepare a Release from Branch main

Note that this scenario requires all your changes to be merged to branch main and no uncommited changes to be present in your local file tree.

Nox session prepare-release will

  • Create a branch, e.g. prepare-release/1.2.3 starting from main
  • Checkout this new branch
  • Update the version in files pyproject.toml and version.py
  • Update changes documentation
    • Rename file doc/unreleased.md to doc/changes_<version>.md and add the current date as date of the release
    • Create a new file doc/unreleased.md
    • Update the file doc/changelog.md
  • Commit and push the changes
  • Create a pull request on GitHub

Please note that creating a pull request on GitHub requires

  • Executable gh to be installed and in your $PATH variable
  • You must be authenticated towards GitHub via gh, use gh auth for that
  • In case you are using a GitHub token, the token must have permission org:read
Manually Create a Pull Request

If you prefer to create the pull request manually or cannot provide one of the prerequisites, you can add command line option --no-pr:

poetry run -- nox -s release:prepare -- <version> --no-pr

Scenario b) Prepare a Release from Another Branch

In case you currently are already working on a branch other than main, please ensure to have all changes commited and add command line option --no-branch:

poetry run -- nox -s release:prepare -- <version> --no-pr --no-branch

Finalize and Publish the Release

When all workflows triggered by merging the pull request to main have succeeded, you can create a new release by

  • Switching to branch main
  • Creating a git tag and
  • Pushing it to origin
TAG="${1}"
git tag "${TAG}"
git push origin "${TAG}"

This will trigger additional GitHub workflows