# Configuration Reference

The **`nmk-python`** plugin handles the configuration items listed in this page.

All of them are initiliazed with convenient default values, so that you don't need to setup them for a default working behavior. You can anyway override them in your project if you need to fine tune the plugin behavior. [Some items](extend.md) are specifically designed to be extended by **`nmk`** projects and plugins.

## Files

(pythonSrcFolders)=

### **`pythonSrcFolders`** -- Python source code folders

| Type      | Default value                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------------- |
| list[str] | [ [${sourceDir}](https://nmk-base.readthedocs.io/en/stable/config.html#sourcedir-source-base-directory) ] |

These are the paths **nmk** will browse to find source files.

(pythonGeneratedSrcFiles)=

### **`pythonGeneratedSrcFiles`** -- Python generated source files

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

This is a list of generated source files, which shall be contributed by any source code generation logic (out of scope of this plugin).

(pythonFoundSrcFiles)=

### **`pythonFoundSrcFiles`** -- Python found source files

| Type      | Default value                                               |
| --------- | ----------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_python.files.PythonFilesFinder` |

This is the list of source files for this python project (excluding test and generated ones; found in **{ref}`${pythonSrcFolders}<pythonSrcFolders>`**).

(pythonTestPackage)=

### **`pythonTestPackage`** -- Python tests package name

| Type | Default value |
| ---- | ------------- |
| str  | tests         |

This is the name of the python module containing tests.

(pythonTestSources)=

### **`pythonTestSources`** -- Python tests source code root folder

| Type | Default value                                                                                                                                            |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| str  | [${sourceDir}](https://nmk-base.readthedocs.io/en/stable/config.html#sourcedir-source-base-directory)/**{ref}`${pythonTestPackage}<pythonTestPackage>`** |

This is the root folder for python tests source code.

(pythonTestSrcFiles)=

### **`pythonTestSrcFiles`** -- Python tests found source files

| Type      | Default value                                                   |
| --------- | --------------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_python.files.PythonTestFilesFinder` |

This is the list of python tests files for this project (found in **{ref}`${pythonTestSources}<pythonTestSources>`** folder).

(pythonSrcFiles)=

### **`pythonSrcFiles`** -- All python source files

| Type      | Default value                                                                                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[str] | [ **{ref}`${pythonFoundSrcFiles}<pythonFoundSrcFiles>`**, **{ref}`${pythonTestSrcFiles}<pythonTestSrcFiles>`**, **{ref}`${pythonGeneratedSrcFiles}<pythonGeneratedSrcFiles>`** ] |

This is a concatenation of all python source code files for this project.

## Version

(pythonVersion)=

### **`pythonVersion`** -- Python version

| Type | Default value                                                     |
| ---- | ----------------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_python.version.PythonVersionResolver` |

This is the current project version (respecting [PyPa version specifiers](https://packaging.python.org/en/latest/specifications/version-specifiers/#version-specifiers)), derived from [${gitVersion}](https://nmk-base.readthedocs.io/en/stable/config.html#gitversion-git-version)

(pythonVersionStamp)=

### **`pythonVersionStamp`** -- Python version stamp file

| Type | Default value                                                                                                        |
| ---- | -------------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.pythonversion |

This is the python version stamp file, updated each time the version is modified.

(pythonMinVersion)=

### **`pythonMinVersion`** -- Minimum supported python version

| Type | Default value                                                                   |
| ---- | ------------------------------------------------------------------------------- |
| str  | "3.10"<br> <br>_<span style="color:orange">Last update in version 1.6.0</span>_ |

This is the minimum python version supported by this project.

(pythonMaxVersion)=

### **`pythonMaxVersion`** -- Maximum supported python version

| Type | Default value                                                                   |
| ---- | ------------------------------------------------------------------------------- |
| str  | "3.14"<br> <br>_<span style="color:orange">Last update in version 1.6.0</span>_ |

This is the maximum python version supported by this project.

(pythonSupportedVersions)=

### **`pythonSupportedVersions`** -- List of all supported python version

| Type      | Default value                                                               |
| --------- | --------------------------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_python.version.PythonSupportedVersionsResolver` |

This is the list of all supported python versions for this project.

## Project

(pythonProjectFile)=

### **`pythonProjectFile`** -- Python project file

| Type | Default value                |
| ---- | ---------------------------- |
| str  | ${PROJECTDIR}/pyproject.toml |

This is python project file, holding settings for python package generation and various python tools.

(pythonProjectFileFragments)=

### **`pythonProjectFileFragments`** -- Python project contributed fragment files

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

List of project fragment files to be merged in generated **{ref}`${pythonProjectFile}<pythonProjectFile>`** file.

(pythonProjectFileItems)=

### **`pythonProjectFileItems`** -- Python project file contributed items

| Type | Default value |
| ---- | ------------- |
| Dict | {}            |

Dictionary of items to be contributed in generated **{ref}`${pythonProjectFile}<pythonProjectFile>`** file.

## Code format/analysis

(pythonLineLength)=

### **`pythonLineLength`** -- Max python source line length

| Type | Default value |
| ---- | ------------- |
| int  | 160           |

This is the maximum line length when formatting code with [ruff](https://astral.sh/ruff).

(pythonIgnoredRules)=

### **`pythonIgnoredRules`** -- List of ignored rules

| Type      | Default value   |
| --------- | --------------- |
| list[str] | ["E203","E501"] |

This is the list of [rules](https://docs.astral.sh/ruff/rules/) that need to be ignored when analyzing code with [ruff](https://astral.sh/ruff).

(pythonAutoFixRules)=

### **`pythonAutoFixRules`** -- List of auto-fixed rules (list version)

| Type      | Default value |
| --------- | ------------- |
| list[str] | ["I"]         |

This is the list of [rules categories](https://docs.astral.sh/ruff/rules/) for which ruff will be invoked with [fix](https://docs.astral.sh/ruff/linter/#fixes) option, helping the developer to quickly fix common mistakes.

_<span style="color:green">Added in version 1.2</span>_

(pythonAutoFixJoinedRules)=

### **`pythonAutoFixJoinedRules`** -- List of auto-fixed rules (string version)

| Type | Default value                                                |
| ---- | ------------------------------------------------------------ |
| str  | Generated by {py:class}`nmk_python.ruff.JoinedRulesResolver` |

This is a comma seperated string version of {ref}`${pythonAutoFixRules}<pythonAutoFixRules>`

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffCommonExtraArgs)=

### **`pythonRuffCommonExtraArgs`** -- Extra args for all ruff commands

| Type | Default value |
| ---- | ------------- |
| str  | ""            |

Extra arguments to be added to all ruff commands executed by **{ref}`py.format<py.format>`**, **{ref}`py.fix<py.fix>`** and **{ref}`py.analyze<py.analyze>`** tasks.

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffFormatExtraArgs)=

### **`pythonRuffFormatExtraArgs`** -- Extra args for ruff format command

| Type | Default value |
| ---- | ------------- |
| str  | ""            |

Extra arguments to be added to ruff command executed by **{ref}`py.format<py.format>`** task.

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffFixExtraArgs)=

### **`pythonRuffFixExtraArgs`** -- Extra args for ruff fix command

| Type | Default value |
| ---- | ------------- |
| str  | ""            |

Extra arguments to be added to ruff command executed by **{ref}`py.fix<py.fix>`** task.

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffCheckExtraArgs)=

### **`pythonRuffCheckExtraArgs`** -- Extra args for ruff check command

| Type | Default value |
| ---- | ------------- |
| str  | ""            |

Extra arguments to be added to ruff command executed by **{ref}`py.analyze<py.analyze>`** task.

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffFormatStamp)=

### **`pythonRuffFormatStamp`** -- Python format stamp file

| Type | Default value                                                                                                      |
| ---- | ------------------------------------------------------------------------------------------------------------------ |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.ruff-format |

This is the stamp file updated each time the **{ref}`py.format<py.format>`** task is executed.

(pythonRuffFixStamp)=

### **`pythonRuffFixStamp`** -- Python fix stamp file

| Type | Default value                                                                                                   |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.ruff-fix |

This is the stamp file updated each time the **{ref}`py.fix<py.fix>`** task is executed.

_<span style="color:green">Added in version 1.2</span>_

(pythonRuffCheckStamp)=

### **`pythonRuffCheckStamp`** -- Python check stamp file

| Type | Default value                                                                                                     |
| ---- | ----------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.ruff-check |

This is the stamp file updated each time the **{ref}`py.analyze<py.analyze>`** task is executed.

(pythonTypeCheckingMode)=

### **`pythonTypeCheckingMode`** -- Pyright type checking mode

| Type | Default value |
| ---- | ------------- |
| str  | "strict"      |

This is the rule set to use with [pyright](https://microsoft.github.io/pyright/#/) type checking tool (executed from VSCode extension).

_<span style="color:green">Added in version 1.4</span>_

## Build

(pythonPackage)=

### **`pythonPackage`** -- Python package name

| Type | Default value                                                                       |
| ---- | ----------------------------------------------------------------------------------- |
| str  | [${projectName}](https://nmk-base.readthedocs.io/en/stable/config.html#projectname) |

This is the name of the python package (wheel) to be generated.

(pythonModule)=

### **`pythonModule`** -- Python module name

| Type | Default value                                                  |
| ---- | -------------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_python.build.PythonModuleResolver` |

This is the name of the python module (typically the same than the wheel name, with "\_" instead of "-").

(pythonPackagePlatform)=

### **`pythonPackagePlatform`** -- Python package platform tag

| Type | Default value |
| ---- | ------------- |
| str  | any           |

This is the platform tag for the current python project.

(pythonArtifacts)=

### **`pythonArtifacts`** -- Python artifacts folder

| Type | Default value                                                                                                   |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/artifacts |

This is the output folder where the python wheel is generated.

(pythonBuildDir)=

### **`pythonBuildDir`** -- Python build folder

| Type | Default value                                                                                                |
| ---- | ------------------------------------------------------------------------------------------------------------ |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/python |

This is the output path where the wheel build is performed.

(pythonWheel)=

### **`pythonWheel`** -- Python generated wheel file

| Type | Default value                                                                                                                                                                              |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| str  | {ref}`${pythonArtifacts}<pythonArtifacts>`/{ref}`${pythonModule}<pythonModule>`-{ref}`${pythonVersion}<pythonVersion>`-py3-none-{ref}`${pythonPackagePlatform}<pythonPackagePlatform>`.whl |

This is the generated python wheel file.

(pythonPackageRequirements)=

### **`pythonPackageRequirements`** -- Python package dependencies

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

This is the list of python package dependencies for the built wheel (i.e. list of packages to be installed when the wheel itself is installed).

(pythonPackageOptionalRequirements)=

### **`pythonPackageOptionalRequirements`** -- Python package optional dependencies

| Type                | Default value |
| ------------------- | ------------- |
| dict[str,list[str]] | {}            |

This is the list of python package **optional** dependencies for the built wheel. This is a map of extra dependencies to be installed when the wheel itself is
installed with an extra specifier.

E.g. when a **sample** wheel is built with this configuration:

```yaml
pythonPackageOptionalRequirements:
  my-option:
    - numpy
```

... the extra **numpy** dependency will be installed only if the `sample[my-option]` syntax is used in requirements.

_<span style="color:green">Added in version 1.3</span>_

(pythonExtraResources)=

### **`pythonExtraResources`** -- Python extra bundled resources

| Type          | Default value |
| ------------- | ------------- |
| dict[str,str] | {}            |

This is a dictionary specifying extra resources to be bundled in the built python wheel, that are not part of the source tree:

- keys are existing resource files or folders
- values are expected paths in the source tree

Paths may be absolute or relative; non-absolute paths are considered to be relative to the project root folder.

```{note}
Resources won't actually be copied in the source tree. Destination path should be considered as the location where resource *would* exist in the source tree.
```

(pythonEditableStamp)=

### **`pythonEditableStamp`** -- Python editable install stamp file

| Type | Default value                                                                                                     |
| ---- | ----------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.pyeditable |

This is the python editable install stamp file, updated each time the project is installed in editable mode.

(pythonEditablePipInstallArgs)=

### **`pythonEditablePipInstallArgs`** -- pip arguments for editable mode install

| Type      | Default value                         |
| --------- | ------------------------------------- |
| list[str] | ["--no-deps", "--no-build-isolation"] |

This is the list of **`pip install`** options to be used when installing project in editable mode with **{ref}`py.editable<py.editable>`** task, with pip build backend.

_<span style="color:red">Renamed in version 1.7.0</span>_ -- was previously named `${pythonEditableInstallArgs}`

(pythonWheelPipInstallArgs)=

### **`pythonWheelPipInstallArgs`** -- pip arguments for wheel install

| Type      | Default value                      |
| --------- | ---------------------------------- |
| list[str] | ["--force-reinstall", "--no-deps"] |

This is the list of **`pip install`** options to be used when installing project built wheel with **{ref}`py.install<py.install>`** task, with pip build backend.

_<span style="color:red">Renamed in version 1.7.0</span>_ -- was previously named `${pythonWheelInstallArgs}`

(pythonEditableUvInstallArgs)=

### **`pythonEditableUvInstallArgs`** -- uv arguments for editable mode install

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

This is the list of **`uv sync`** options to be used when installing project in editable mode with **{ref}`py.editable<py.editable>`** task, with uv build backend.

_<span style="color:green">Added in version 1.7.0</span>_

(pythonWheelUvInstallArgs)=

### **`pythonWheelUvInstallArgs`** -- uv arguments for wheel install

| Type      | Default value |
| --------- | ------------- |
| list[str] | []            |

This is the list of **`uv pip install`** options to be used when installing project built wheel with **{ref}`py.install<py.install>`** task, with uv build backend.

_<span style="color:green">Added in version 1.7.0</span>_ -- was previously named `${pythonWheelInstallArgs}`

(pythonBuildExcludedModules)=

### **`pythonBuildExcludedModules`** -- Excluded modules from wheel build

| Type      | Default value                                       |
| --------- | --------------------------------------------------- |
| list[str] | ["{ref}`${pythonTestPackage}<pythonTestPackage>`*"] |

This is the list of python modules to be excluded (relatively to source directories) when building the python wheel.
Default behavior is to exclude the tests modules (i.e. {ref}`${pythonTestPackage}<pythonTestPackage>` module and sub-modules).

_<span style="color:green">Added in version 1.5</span>_

(pythonDevRequirements)=

### **`pythonDevRequirements`** -- Python development dependencies

| Type      | Default value                                                   |
| --------- | --------------------------------------------------------------- |
| list[str] | Generated by {py:class}`nmk_python.build.PythonDevDepsResolver` |

This is the generated list of python packages which are not direct dependencies of the current package.
It's mainly used for **dev** dependency group generation in {ref}`${pythonProjectFile}<pythonProjectFile>` file.

_<span style="color:green">Added in version 1.7.0</span>_

(pythonArchiveRequirements)=

### **`pythonArchiveRequirements`** -- Python archive dependencies

| Type          | Default value                                                       |
| ------------- | ------------------------------------------------------------------- |
| dict[str,str] | Generated by {py:class}`nmk_python.build.PythonArchiveDepsResolver` |

This is the generated dict of referenced python local wheels (see [${venvArchiveDeps}](https://nmk-base.readthedocs.io/en/stable/config.html#venvarchivedeps-venv-archives-dependencies-list)), indexed by package names.
It's mainly used for **dev** dependency group generation in {ref}`${pythonProjectFile}<pythonProjectFile>` file.

_<span style="color:green">Added in version 1.7.0</span>_

## Tests

(pythonTestOutput)=

### **`pythonTestOutput`** -- Python tests output folder

| Type | Default value                                                                                               |
| ---- | ----------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/tests |

This is the output folder where tests results are generated.

(pythonCoverageHtmlReport)=

### **`pythonCoverageHtmlReport`** -- Python code coverage HTML report folder

| Type | Default value                                                                                                         |
| ---- | --------------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/coverage-report |

This is the output folder where python code coverage HTML report is generated.

(pythonCoverageXmlReport)=

### **`pythonCoverageXmlReport`** -- Python code coverage XML report file

| Type | Default value                                                                                                      |
| ---- | ------------------------------------------------------------------------------------------------------------------ |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/coverage.xml |

This is the output file for python code coverage XML report.

(pythonCoverageFile)=

### **`pythonCoverageFile`** -- Python code coverage data file

| Type | Default value                                                                                                   |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| str  | [${outputDir}](https://nmk-base.readthedocs.io/en/stable/config.html#outputdir-output-base-directory)/.coverage |

This is the cumulative data file for python code coverage.

(pytestExtraArgs)=

### **`pytestExtraArgs`** -- Extra pytest arguments

| Type           | Default value |
| -------------- | ------------- |
| dict[str, str] | see below     |

This is a name/value dictionary of [pytest](https://docs.pytest.org/) options used on the command line when launching tests. Name/value pairs are converted to command-line options using the `--name=value` syntax.

```{warning}
Because of YAML "feature" to consider some values as valid booleans (e.g. unquoted `no` value is parsed as a boolean `false`), please pay attention to these options syntax.
```

Default options are:

- `"numprocesses": "auto"`: automatically use all available cores to parallelize tests (see [pytest-xdist documentation](https://pytest-xdist.readthedocs.io/en/stable/distribution.html))
- `"cov-fail-under": 100`: fails if code coverage falls under 100% (see [pytest-cov documentation](https://pytest-cov.readthedocs.io/en/latest/config.html))
- `"dist": "loadgroup"`: load together tests marked with the same group (see [pytest-xdist documentation](https://pytest-xdist.readthedocs.io/en/stable/distribution.html))
- `"show-capture": "no"`: don't show captured logs on test failure (see [pytest documentation](https://docs.pytest.org/en/stable/reference/reference.html#cmdoption-show-capture))<br> <br>_<span style="color:green">Added in version 1.6.0</span>_