Private Elements

Command Line Arguments

Module: _ptcsvp.cmdline

This pytest plugin requires command line arguments that are parsed from the pytest framework. This module contains code to instruct pytest to deliver the required values.

_ptcsvp.cmdline.HELP_TEXT_BASE_DIR = 'set base dir for getting CSV data files from'

This is the help text for the base dir command line argument that is added by pytest_addoption().

_ptcsvp.cmdline.HELP_TEXT_SKIP_EMPTY = 'skip tests when csv source is empty'

This is the help text for the skip empty command line argument that is added by pytest_addoption().

_ptcsvp.cmdline.HELP_TEXT_SKIP_MISSING = 'skip tests when csv source is missing'

This is the help text for the skip missing command line argument that is added by pytest_addoption().

_ptcsvp.cmdline.pytest_addoption(parser, plugin_name='csv-params')

Entrypoint for pytest to extend the own Parser with the things we need extra.

Parameters:

  • parser (Parser) – The pytest command line argument parser

  • plugin_name (str) – The name of our plugin, with default value

Return type:

None

Plugin Configuration

Module: _ptcsvp.configure

The pytest plugin needs a setup (pytest_configure()) and a teardown (pytest_unconfigure()) method registered. This module contains the required methods for that.

_ptcsvp.configure.pytest_configure(config, plugin_name='csv_params')

Register our Plugin

Parameters:

  • config (Config) – Pytets configuration class

  • plugin_name (str) – The name of the pytest plugin, with default value

Return type:

None

_ptcsvp.configure.pytest_unconfigure(config, plugin_name='csv_params')

Remove our Plugin

Parameters:

  • config (Config) – Pytest configuration class

  • plugin_name (str) – The name of the pytest plgin, with default value

Return type:

None

The Parametrization

Module: _ptcsvp.parametrize

Parametrize a test function by CSV file

class _ptcsvp.parametrize.TestCaseParameters

Type for a single test case. Contains the optional test_id and the test data.

data: list[Any]
test_id: str | None
_ptcsvp.parametrize.add_parametrization(data_file, base_dir=None, id_col=None, data_casts=None, dialect=CsvParamsDefaultDialect, header_renames=None, reuse_id_col=False, skip_when_missing_csv_file=None, skip_when_empty_csv_file=None, parameters_as_dictionary=None, parameters_as_object=None)

Parametrize a test function with data from a CSV file.

For the public decorator, see pytest_csv_params.decorator.csv_params().

Parameters:

  • data_file (str) – The CSV file to read the data from

  • base_dir (Optional[str]) – Optional base directory to look for non-absolute data_file in

  • id_col (Optional[str]) – Optional name of a column that shall be used to make the test IDs from

  • data_casts (Optional[dict[str, Callable[[str], Any]]]) – Methods to cast a column’s data into a format that is required for the test

  • dialect (type[Dialect]) – The CSV file dialect (CSV file format) to use

  • header_renames (Optional[dict[str, str]]) – A dictonary mapping the header names from the CSV file to usable names for the tests

  • reuse_id_col (bool) – Allows re-using the ID col as test data column; defaults to False for backwards compatibility

  • skip_when_missing_csv_file (Optional[bool]) – Let tests automatically skip when CSV source is missing (since 2.1.0)

  • skip_when_empty_csv_file (Optional[bool]) – Let tests automatically skip when CSV source does not contain any test data (since 2.1.0)

  • parameters_as_dictionary (Optional[str]) – Instead of using one argument per field, all arguments are passed as a dictionary with the given name (since 2.2.0)

  • parameters_as_object (UnionType[str, tuple[str, Callable[[], TestCaseDataElementType]], None]) – Instead of using one argument per field, all arguments are passed as an object with the given name, or with the given name and created by the given factory (since 2.5.0)

Raises:

ParametersObjectConfiguration – When parameters_as_dictionary and parameters_as_object are used at the same time

Return type:

MarkDecorator

Returns:

pytest.mark.parametrize() mark decorator, filled with all the data from the CSV.

_ptcsvp.parametrize.clean_headers(current_headers, replacing)

Clean the CSV file headers

Parameters:

  • current_headers (list[str]) – List of the current headers, as read from the CSV file (without the ID column, as far as it exists)

  • replacing (Optional[dict[str, str]]) – Dictionary of replacements for headers

Return type:

list[str]

Returns:

List of cleaned header names

Raises:

CsvHeaderNameInvalid – When non-unique names appear

_ptcsvp.parametrize.read_csv(base_dir, data_file, dialect)

Get Data from CSV

Parameters:

  • base_dir (Optional[str]) – Optional directory to look up non-absolute CSV files (given as data_file)

  • data_file (str) – The CSV file to read. If this is an absolute path, base_dir will be ignored; if not, the base_dir is prepended.

  • dialect (type[Dialect]) – The CSV file dialect (definition of the format of a CSV file).

Return type:

list[list[str]]

Returns:

A list of rows, each row contains a list of columns; all type str

The Plugin Class

Module: _ptcsvp.plugin

This module contains the main plugin class. By the time of writing, it is quite unspectacular.

_ptcsvp.plugin.BASE_DIR_KEY = '__pytest_csv_params__config__base_dir'

The class attribute key for Plugin to store the base dir command line argument value.

class _ptcsvp.plugin.Plugin(config)

The main plugin class

Currently, this class is nothing more than the keeper of the value of the command line argument (as defined by _ptcsvp.cmdline.pytest_addoption().

_ptcsvp.plugin.SKIP_EMPTY_KEY = '__pytest_csv_params__config__skip_empty'

The class attribute key for Plugin to store the skip empty command line argument value.

_ptcsvp.plugin.SKIP_MISSING_KEY = '__pytest_csv_params__config__skip_missing'

The class attribute key for Plugin to store the skip missing command line argument value.

The Variable Name Validation

Module: _ptcsvp.varname

This module contains code to validate variable/argument/parameter names or to make them valid ones.

_ptcsvp.varname.VALID_CHARS = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'

Valid characters a variable/parameter/argument name can consist of

_ptcsvp.varname.VARIABLE_NAME = re.compile('^[a-zA-Z_][A-Za-z0-9_]{0,1023}$')

Regular expression that defines a valid variable/parameter/argument name

_ptcsvp.varname.is_valid_name(name)

Checks if the variable name is valid

Parameters:

name (str) – The name to be checked

Return type:

bool

Returns:

True, when the name is valid

_ptcsvp.varname.make_name_valid(name, replacement_char='_')

Make a name a valid name by replacing invalid chars with the as replacement_char given char

Parameters:

  • name (str) – The name to make a valid one

  • replacement_char (str) – The char to replace invalid chars with, default is an underscore _

Return type:

str

Returns:

A valid name

Raises:

CsvHeaderNameInvalid – If the fixed name is still an invalid name

The Version Checks

Module: _ptcsvp.version

This module contains two methods to check if the python version is recent enough (check_python_version()) and if the pytest version is recent enough (check_pytest_version()).

During the setup phase of the plugin (see pytest_csv_params.plugin) these methods are called.

_ptcsvp.version.check_pytest_version(min_version=(8, 3), deprecation_below=(9, 0))

Check if the current version is at least 8.3

Parameters:

  • min_version (tuple[int, int]) – The minimum version required, as tuple, default is 8.3

  • deprecation_below (tuple[int, int]) – The version below which a deprecation warning is raised, as tuple, default is 9.0

Raises:

PytestVersionTooOldException – When the pytest version is too old/unsupported

Return type:

None

_ptcsvp.version.check_python_version(min_version=(3, 10), deprecation_below=(3, 11))

Check if the current version is at least 3.10

Parameters:

  • min_version (tuple[int, int]) – The minimum version required, as tuple, default is 3.10

  • deprecation_below (tuple[int, int]) – The version below which a deprecation warning is raised, as tuple, default is 3.11

Raises:

PythonVersionTooOldException – When the python version is too old/unsupported

Return type:

None