pytest-csv-params/docs/pages/developer.md

Developer Guide

If you want to develop for / with the Pytest CSV Params Plugin, consider to clone the repository:

git clone https://git.codebau.dev/pytest-plugins/pytest-csv-params.git

You need Python 3.8 or newer.

The project's dependencies and building are managed by poetry. Please follow the instructions from python-poetry.org to install poetry on your system.

Install all the dependencies, including the development dependencies:

poetry install

Commit Signing

Commit signing is mandatory for all commits for the main branch. Please make sure, your public key is set up and registered with git.codebau.dev.

Testing

Tests are implemented with pytest. You find them in the tests folder. Besides unit and integration tests, some other checks are executed by pytest plugins:

• pytest-black: This plugin checks code formatting with black. If tests fail, try poetry run black . from the project root to fix formatting issues. Configuration: pyproject.toml, section [tool.black].
• pytest-isort: This plugin checks import sorting with isort. If tests fail, try poetry run isort . from the project root to fix import sorting issues. Configuration: pyproject.toml, section [tool.isort].
• pytest-pylint: This plugin does a static code analysis with pylint. The test configuration can be found in .pylintrc in the project root.
• pytest-bandit: This plugin performs a static security analysis of the code with bandit. The configuration is part of the [tool.pytest.ini_options] section in the pyproject.toml, config keys bandit_*.
• pytest-mypy: This plugin uses mypy to perform typing checks against the code. The configuration can be found in the pyproject.toml, section [tool.mypy].

Most plugins are enabled by the addopts switches, configured in the pyproject.toml, section [tool.pytest.ini_options]. Some plugins have extra configuration switches even there.

Additionally, the code coverage is measured by pytest-cov using coverage.py. A high coverage alone is not a very good metric, but it helps to find and fix coverage weaknesses. The configuration for coverage measurement is in the pyproject.toml, sections [tool.coverage], [tool.coverage.run] and [tool.coverage.report].

There are some other pytest plugins installed and used for tests:

• pytest-mock: Simplified mocking
• pytest-clarity: Better output of assertion errors
• pytest-order: Execute tests in a given order (used in {mod}tests.poc.test_parametrize_with_generator).

Test runs with pytest

Just run all the tests with:

poetry run pytest

Test runs with tox

tox is used to execute all tests under the different supported Python versions. Make sure you installed all relevant versions on your system, for example with pyenv.

To execute them all, run:

poetry run tox

If you experience strange tox errors, try to recreate the tox environments:

poetry run tox -r

tox is configured in the pyproject.toml, section [tool.tox].

If you add or change code, please make sure your changes are covered by meaningful tests.

Building

There are two different things to build from the source code: The Wheel distribution package from the Python code and the documentation.

Code

The building and deployment is managed by poetry. The complete build and deploy configuration takes place in the pyproject.toml. Besides the standard configuration in section [tool.poetry], additional URLs are defined in section [tool.poetry.urls]. As a speciality for this plugin, an entry point is defined in section [tool.poetry.plugins."pytest11"].

To build the packages, just run poetry build from the project root.

(build-docs)=

Docs

The docs are in the docs folder. There is a conf.py that contains all the settings. Documentation is managed by sphinx. There is a make file (Makefile) as well as a make.bat, they contain some configuration also.

The serve.py scripts starts a live reload server to preview the documentation.

To build the documentation, run poetry run make html (respectively poetry run make.bat html on Windows) from the docs directory.

Publishing

The following section is more a reference for project members. If you not belong to the project, you'll not be able to
publish or update packages.

Maybe you find it helpful as a boiler plate for your own projects.

Increase Version

If not already done, increase the version in the pyproject.toml. This can be done manually, but poetry offers a helper for that:

poetry command	Effect
poetry version patch	increase patch
poetry version minor	increase minor
poetry version major	increase major

Complete Changelog

Update the docs/pages/changelog.md file with all relevant things happened since the last release. Set a compare link and a link to the release page. You can set them up even if the release does not exist at the moment.

Don't forget to commit now!

Tag the release

Set a git tag in the format vX.Y.Z (with the leading v). Push all your commits and the tag now.

PyPI

If not already done, you need to setup `poetry` for publishing.

**1. Configuration for production PyPI**

- Get your token from [pypi.org](https://pypi.org/)
- Set your token with `poetry config pypi-token.pypi pypi-YOUR_PROD_TOKEN`

**2. Configuration for test PyPI**

- Get your token from [test.pypi.org](https://test.pypi.org/)
- Setup the test repo: `poetry config repositories.test.url https://test.pypi.org/legacy/`
- Set your token with `poetry config pypi-token.test pypi-YOUR_TEST_TOKEN`

**3. Configuration for Codebau Package Repository**

- Get your token from [git.codebau.dev](https://git.codebau.dev/)
- Setup the codebau repo:
  `poetry config repositories.codebau.url https://git.codebau.dev/api/packages/pytest-plugins/pypi`
- Setup your token with `poetry config pypi-token.codebau YOUR_CODEBAU_TOKEN`

Publish to test.pypi.org

It's a good practice to publish a new package to test.pypi.org first.

poetry publish --build -r test

You can omit the --build param when you already built the package.

Publish to production pypi.org

poetry publish --build

Publish to git.codebau.dev Package Repository

poetry publish --build -r codebau

Documentation

The documentation is automatically build from the main branch and published to docs.codebau.dev. If you want to build by yourself, see {ref}Building / Docs <build-docs>. You find the compiled docs under dist/docs/html.