# NewTec Coding Guidelines for Python

## Coding Style

For code formating, and naming conventions [PEP8](https://www.python.org/dev/peps/pep-0008/) is applicable.

The following rule is defined as deviating:

| No   | Rule                               | .pylintrc           |
| :----| -----------------------------------| --------------------|
| E501 | line too long (82 > 79 characters) | max-line-length=120 |

### Static Code Analysis

For static code analysis and to check the code style, [pylint](https://pypi.org/project/pylint/) shall be used.

Ohther common tools that can be used optionally in addition:

- [flake8](https://flake8.pycqa.org/en/latest/index.html) with more focus on style check and support for plugins, e.g.:
  - [flake8-docstrings](https://github.com/pycqa/flake8-docstrings)
  - [flake8-bugbear](https://github.com/PyCQA/flake8-bugbear) finding likly bugs and design problems
  - an Overview of additional plugins can be found in [flake8 plugin list](https://github.com/DmytroLitvinov/awesome-flake8-extensions?tab=readme-ov-file#docstrings)
- [mypy](https://github.com/python/mypy) static typing check for python
- [bandits](https://bandit.readthedocs.io/en/latest/) find common security issues in python

### Naming examples from PEP8

Some examples from PEP8 for naming conventions:

- Packages: "package","example_package",...
- Modules: "module","example_module",...
- Classes: "Class","ExampleClass",...
- Functions: "function","example_function",...
- Variables: "variable","example_variable",...

### Auto formating

[autopep8](https://pypi.org/project/autopep8/) is used for the automatic formatting of the source code

## Python Version

A Python version to be used by all developers, should be defined in projects.
Versions of component packages are defined in requirements.txt

## Documentation

For documentation [python docstring](https://peps.python.org/pep-0257/). There are different options for formating the docstring in detail. There the [Google styleguide](https://google.github.io/styleguide/pyguide.html) applies.

Based on docstrings, Source Code documentation can be generated by sphinx.

### Installation

Install dependencies:

``` shell
pip install sphinx, sphinxcontrib-napoleon
```

Optional:

``` shell
pip install sphinx_rtd_theme
pip install sphinx-favicon
```

[ReadTheDocs](https://sphinx-rtd-theme.readthedocs.io/en/stable/) is a popular theme, used wiht spingx

A sphinx template is already prepared in the [doc/detailed-design](./doc/detailed-design/) folder

The file index.rst is the first pate of the documentation and needs to be adapted to project needs.

The file conf.py is the main configuration file, there project name, author, ... needs to be filled in.

To generate html documentation call `make.bat html`, that can be found under `/doc/detailed-design`. The output will be located in `detailed-design/_build/html`

## Logging

For error-logging it is recommended to use the `log_error()` function of `src\pyTRLCConverter\log_verbose.py`. 
The function accepts two parameters:

1. message (string): The message to be displayed.
2. show_timestamp (boolean, optional): A flag indicating whether to include a timestamp with the message. Defaults to false if not provided.

When invoked, the function outputs the message to standard error (stderr). If showTimestamp is set to true, the current timestamp will be prefixed to the message.