esta-python-template/template

> ***Note:*** **This repository was generated by the [🖨️ ESTA Python Template](https://code.sbb.ch/projects/KD_ESTA_BLUEPRINTS/repos/esta-python-template/).**

# {{ project_name }}

This is a blueprint for Python based projects. It exemplifies a setup and project structure including neat things such as pre-commit-hooks, automated testing, type checking, CI/CD using Tekton, etc. It is intended to be tailored to project needs.

## Getting Started

- Create a new project on [SonarQube](https://codequality.sbb.ch/projects/create) with the "Project key" `{{ name }}` and "Display name" `{{ project_name }}`.
- Configure pylint profile for sonarproject by making [a pull-request at the sonarqube-config repo](https://code.sbb.ch/projects/KD_WZU/repos/sonarqube-config/browse/QualityProfiles/pylint) and adding the `sonar.projectKey` into the files.

## Setup

### Install Pyenv and Poetry

- If not already installed, install [pyenv](https://github.com/pyenv/pyenv).
- If not already installed, get Poetry according to <https://python-poetry.org/docs/#installation>. If your are new to Poetry, you may find <https://python-poetry.org/docs/basic-usage/> interesting.

### Create Environment

Execute the following in a terminal:

```shell
# Create virtualenv, install all dependencies and pre-commit hooks in one command:
make
```

### Set Environment Variables for Local Developement

Environment Variables defined in the `.env`-File are automatically loaded. To get started:

- make a copy of `env.template` and rename it to `.env`
- fill out any missig values (e.g. for passwords)
- close and re-open the terminal

See the Environment Variables section below for a list of all variables used by this application.

{%- if use_ggshield %}

### Setup GGShield (GitGuardian)

The ggshield secret scanner requires an API-token to access the GitGuardian server. This token needs to be set both on your local machine and in tour tekton build environment. The `make` command will warn you if the token is not set:

> Makefile:24: No API-Key for GitGuardian was set!

1. Go to the [GitGuardian](https://gitguardian.sbb.ch/workspace/1/settings/api/personal-access-tokens) and create a new *Personal Access Token* with the *Scan* permission.
2. Set API-token locally
    Add the environment variable GITGUARDIAN_API_KEY to the `.env`-file and reopen your terminal.
    ```.env
    GITGUARDIAN_API_KEY="YourTokenGoesHere"
    ```
3. Set API-token in tekton

    1. On your tekton-instance navigate to "pipeline secrets"
    2. Edit the secret "esta-tekton-pipeline-env"
    3. Add a new entry with the key `GITGUARDIAN_API_KEY` and as value the previously generated access token

You can run `poetry run ggshield api-status` locally to check your setup. Consult the [guide on confluence](https://confluence.sbb.ch/x/0QSFlw) if you have any problems.
{% endif %}

{%- if pypi_repository or docker_repository %}
## Usage

{% endif %}
{%- if pypi_repository -%}

### As Shared Library

Available versions can be seen in artifactory: <https://bin.sbb.ch/ui/repos/tree/General/{{ pypi_repository }}/{{ name }}>

Execute the following command to install the latest package:

```shell
pip install {{ name }} --no-cache-dir --index-url https://bin.sbb.ch/artifactory/api/pypi/{{ pypi_repository }}/simple/ --trusted-host bin.sbb.ch
```

{% endif %}

{%- if docker_repository -%}

### As Docker Container

If you take the docker image as is it will enable you to use defined entrypoints directly. The command's name defined in the `[tool.poetry.scripts]` section of pyproject.toml can be passed to the docker run command like this:

```shell
# docker run <path_to_image> <poetry command>
docker run docker.bin.sbb.ch/{{ docker_repository|replace('.docker', '') }}/{{ name }}:<tag> entrypoint
```

Here, 'entrypoint' is the command name.
{% endif %}

## Contents and Concepts

At first glance one may be overwhelmed by the amount of files and folders present in this directory. This is mainly due to the fact, that each tool uses its own configuration file. The situation has improved with more and more tools adding support for pyproject.toml. The following two tables describe the main structure of the project:

| Folder        | Purpose |
|---------------|-----|
| `.venv`       | This is where the Poetry-managed venv lives. |
| `.vscode`     | This is where settings for vscode live. Some useful defaults are added in case you use vscode in your project. If not, this can savely be deleted.|
{%- if helm_repository %}
| `charts`      | This directory contains the Helm charts of the project. Helm is used to deploy this application to OpenShift. |
{%- endif %}
| `src`         | Main directory for the python code. Most of the times this will contain one subfolder with the main module of the project. `{{ package_name }}` in our case. Replace this with your own module-name. |
| `tests`       | Directory containing all tests. This directory will be scanned by the test-infrastructure to find testcases. |

| File                                  | Purpose |
|---------------------------------------|---------|
{%- if docker_repository %}
| `.dockerignore`                       | Files and directories to ignore when building a Docker image. |
{%- endif %}
| `.gitattributes`                      | Attributes for git are defined in this file, such as automatic line-ending conversion. |
| `.gitignore`                          | This file contains a list of path patterns that you want to ignore for git (they will never appear in commits). |
| `.pre-commit-config.yaml`             | This file contains configuration for the pre-commit hook, which is run whenever you `git commit`, you can configure running code quality tools and tests here. |
{%- if docker_repository %}
| `Dockerfile`                          | Instructions for Docker on how to package this app into a Docker image. |
{%- endif %}
| `dependency-check-suppressions.xml`   | Configuration file for the [OWASP Dependency Check](https://jeremylong.github.io/DependencyCheck/general/suppression.html). Can be used to specify vulnerabilities that should be suppressed by the check (because they aren't applicable to your project). |
| `estaTektonPipeline.yaml`             | Configuration file for Continuous Integration on the ESTA Tekton Pipeline infrastructure. Refer to [ESTA Tekton Parameters - estaTektonPipeline.json](https://confluence.sbb.ch/display/CLEW/ESTA+Tekton+Parameters+-+estaTektonPipeline.json) for more information. |
| `poetry.toml`                         | Configuration for Poetry. |
| `pyproject.toml`                      | This file contains meta information for your project, as well as a high-level specification of the dependencies of your project, from which Poetry will do its dependency resolution and generate the `poetry.lock`. Also, it contains some customization for code-quality tools. Check [PEP 621](https://peps.python.org/pep-0621/) for details.|
| `README.md`                           | This file. Document how to develop and use your application in here. |
| `renovate.json`                       | Configuration file for [Renovate](https://confluence.sbb.ch/spaces/CLEW/pages/2212995011/Renovate). Allows you to set how and when renovate is run. See the [official documentation](https://docs.renovatebot.com/configuration-options/). |
| `sonar-project.properties`            | Configuration for the Sonar check. |

## Environment Variable

The following environment variables may be used to configure `{{ package_name }}`:

| Environment Variable | Purpose | Default Value | Allowed Values |
|----------------------|-|-|-|
| LOG_LEVEL            | Sets the default log level [here](src/{{ package_name }}/common/logging_configuration.py). | "INFO" | See [Python Standard Library API-Reference](https://docs.python.org/3/library/logging.html#logging-levels) |