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:

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].

No new or changed code without test

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.

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¶

Warning

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¶

Poetry configuration for publishing

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

1. Configuration for production PyPI

  • Get your token from 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

  • 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

  • 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 Building / Docs. You find the compiled docs under dist/docs/html.