🐞 Findings when using PTB for new project saas-api-python

[ckunki]

Findings / Proposals for improvement

Linter settings prio :zero:

• linter complains about unused imports in noxfile.py
• missing docstrings for modules, classes, and functions in tests and noxconfig.py
• long line in generated file version.py

As thresholds are tight, these linter problems cause the initial push to fail.

File .github/workflows/checks.yml: missing step prio :one:

After step Run Tests there is another step missing:

      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: .lint.txt
          path: .lint.txt

References to github workflows don't work prio :two:

• affected files: ci, ci-cd, pr-merge
• ACTUAL: exasol/toolbox/.github/workflows/xyz.yml@version
• PROPOSAL: ./.github/workflows/xyz.yml

Wrong reference to file version.py prio :five:

• ACTUAL: run: poetry run version-check exasol/toolbox/version.py
• PROPOSAL: run: poetry run version-check version.py

Should some of the following files be included in file .gitignore? prio :nine:

• .lint.txt
• .lint.json
• .coverage
• metrics.json

Wrong yaml indent in generated workflow .github/workflows/checks.yml prio :nine:

• steps of build-documentation-job: should be indented with 2 additional spaces

Missing files prio :nine:

• doc/conf.py
• doc/index.rst

Missing folders prio :nine:

• test
• artifacts

File .github/workflows/checks.yml, step "Copy Artifacts into Root Folder" could be simplified prio :nine:

• ACTUAL: working directory and cp .coverage/.coverage ../
• PROPOSAL: no working directory (i.e. use .), cp ./artifacts/.coverage/.coverage ./

GH Workflow Job "Generate Status Report" currently fails with

subprocess.CalledProcessError: Command '['coverage', 'json', '--data-file=.coverage', '-o', '/tmp/tmpm01u0nf3/coverage.json']' returned non-zero exit status 2.

Proposals

• report stderr of subprocess to enable analysis
• as the command locally succeeds, maybe the temp dir is not found?

Mark files as generated? prio :nine:

Should we mark the GH-workflow files, initially generated by PTB, as generated in file .gitattributes? See Git docu on using this file, GH docu for marking files as generated and project-keeper containing an example for using the file.

Benefits:

• Eeduce effort in manual code review sessions
• Enable to detect deviations from default (= generated) more easily

[Nicoretti]

Related issue/pr: #153

https://exasol.github.io/python-toolbox/changes/unreleased.html

[Nicoretti]

Partial Duplicate: #87

@Nicoretti consolidate

[Nicoretti]

@ckunki, here's some feedback and context on the issue:

Linter Settings

The settings provided in the documentation are examples. Exclusions can and should be defined by the project.

References to GitHub Workflows

This issue is fixed but not yet released. See pull request #153.

Missing Files

These files could be generated, but if the project includes Sphinx documentation, it needs to have these files as they are a documentation requirement.

File .github/workflows/checks.yml: Missing Step

Uploading statistics/metrics is intended only for releases, as detailed in the CI-CD workflow.

Mark Files as Generated?

Not currently, because the workflow files can still be adjusted and need not exactly match what was generated. Customization based on extension points will be a feature in the future. Until then, workflows should be treated as if they were written manually, with the "generator" serving as a helper.

[ckunki]

The settings provided in the documentation are examples. Exclusions can and should be defined by the project. References

You are right. I was also able to solve these problems by adding to file pyproject.toml, below [tool.pylint.master]:

ignore = [
    "noxfile.py",
    "version.py",
    "noxconfig.py",
]

But I wanted to provide the fix to other users of the PTB, to enable jumping this hurdle quicker. Maybe we could add a sentence to the PTB documentation?

[tkilias]

Maybe we could add a sentence to the PTB documentation?

Yeah, I think, we should mention, that some things need to configured manually per project and best also a list of what this includes

[ckunki]

Here is another hint for excluding generated code from pylint in pyproject.toml.

I propose adding a sentence to the documentation:

Additionally, the following section in file pyproject.toml below [tool.pylint.master] excludes all files below the specified directory to be excluded from linting. This can be necessary when you need to commit generated code.

ignore-paths = [
    ".*/exasol/saas/client/openapi/.*",
]

[Nicoretti]

This issue does not appear to be a bug within the toolbox itself, but rather a configuration and project setup issue. Accordingly, most things will be addressed as part of Issue #166 on our GitHub repository.