Getting Started

Your usage of the exasol-toolbox will likely fall into one of two scenarios:

  1. Integrating Exasol-Toolbox into your Project

  2. Creating a New Project with Exasol-Toolbox Support

Creating a New Project with Exasol-Toolbox Support

Important

To establish a new project with toolbox support, you need to have Cookiecutter installed:

pip install cookiecutter

1. Create a new project

Cookiecutter will create the project within the current directory. So if you usually checkout all your GitHub repos in ~/git you could use cd ~/git before calling cookiecutter.

Use the following command to create a new project:

cookiecutter https://github.com/exasol/python-toolbox.git \
 --checkout <latest-tag> --directory project-template

Note

Without option --checkout cookiecutter will use the main branch of the PTB. In order to get reliable and reproducible results, we recommend using the tag of PTB’s latest released version instead.

2. Follow the interactive project setup prompt

3. Bootstrap the development environment

Navigate to the directory of the newly created project:

cd <your-project-name>

Generate a poetry environment for the project:

# An example python_version value is python3.10
poetry env use <python_version>

Install all necessary project and development dependencies for the project:

poetry install

4. Start using your project

List all available nox sessions:

nox -l

Integrating Exasol-Toolbox into your Project

1. Add the toolbox as a dependency

poetry add --group dev exasol-toolbox

2. Provide a project configuration

Make sure you provide the required configuration. Configuration for the exasol-toolbox gets provided by creating a noxconfig.py file in the workspace root. This file should be similar to the example shown below.

Note

For further details on plugins, see the customization section.

noxconfig.py
from __future__ import annotations

from pathlib import Path
from typing import Iterable

from exasol.toolbox.config import BaseConfig


class Config(BaseConfig):
    root: Path = Path(__file__).parent
    doc: Path = Path(__file__).parent / "doc"
    source: Path = Path("exasol/{{cookiecutter.package_name}}")
    version_file: Path = (
            Path(__file__).parent
            / "exasol"
            / "{{cookiecutter.package_name}}"
            / "version.py"
    )
    path_filters: Iterable[str] = ()
    pyupgrade_args: Iterable[str] = (
    "--py{{cookiecutter.python_version_min | replace('.', '')}}-plus",)
    plugins: Iterable[object] = ()

PROJECT_CONFIG = Config()

3. Configure the tooling

Configuration values for the tooling should be defined in the pyproject.toml. Copy the example below & adapt it for your project’s specific needs.

pyproject.toml (tool specific configuration)
[tool.coverage.run]
relative_files = true
source = [
    "exasol",
]

[tool.coverage.report]
fail_under = 15

[tool.black]
line-length = 88
verbose = false
include = "\\.pyi?$"

[tool.isort]
profile = "black"
force_grid_wrap = 2

[tool.pylint.master]
fail-under = 5.0
ignore = []

[tool.pylint.format]
max-line-length = 88
max-module-lines = 800

[[tool.mypy.overrides]]
module = [
    "test.*",
]
ignore_errors = true

[tool.sonar]
projectKey = "com.exasol:{{cookiecutter.repo_name}}"
hostUrl = "https://sonarcloud.io"
organization = "exasol"
exclusions = "exasol/{{cookiecutter.package_name}}/version.py"

For further reference, see the formatting code configuration section.

4. Make the toolbox sessions available

To use the standard toolbox session via nox, just import them in your noxfile.py. If you only need the standard sessions provided by the toolbox, your noxfile.py is straightforward, and you just can use the example noxfile.py below.

noxfile.py
import nox

# imports all nox task provided by the toolbox
from exasol.toolbox.nox.tasks import *

# default actions to be run if nothing is explicitly specified with the -s option
nox.options.sessions = ["project:fix"]

5. Set up the GitHub pre-commit hooks [optional]

See the pre-commit configuration section for the required steps.

6. Set up deploying documentation (optional)

See the documentation configuration section for the required steps.

7. Set up Sonar

Look at the configuration of Sonar for a:

8. Go 🥜

You are ready to use the toolbox. With nox -l you can list all available sessions.