# Developer Guide If you want to develop for / with the Pytest CSV Params Plugin, consider to clone the repository: ```bash 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](https://python-poetry.org/) to install `poetry` on your system. Install all the dependencies, including the development dependencies: ```bash 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`](https://github.com/psf/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`](https://github.com/PyCQA/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`](https://github.com/PyCQA/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`](https://github.com/PyCQA/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`](https://mypy.readthedocs.io/en/stable/) 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`](https://github.com/nedbat/coveragepy). 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: ```bash 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`](https://github.com/pyenv/pyenv). To execute them all, run: ```bash poetry run tox ``` If you experience strange `tox` errors, try to recreate the `tox` environments: ```bash poetry run tox -r ``` `tox` is configured in the `pyproject.toml`, section `[tool.tox]`. ```{admonition} 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. (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`](https://www.sphinx-doc.org/). 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 ```{admonition} 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](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](https://test.pypi.org/) first. ```bash poetry publish --build -r test ``` You can omit the `--build` param when you already built the package. #### Publish to production pypi.org ```bash poetry publish --build ``` #### Publish to git.codebau.dev Package Repository ```bash 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 `. You find the compiled docs under `dist/docs/html`.