API: Test Support

test_support

This package includes helper code that is only used for testing setuptools-pyproject-migration itself. The code is made available when testing by a pytest configuration option that extends sys.path.

class test_support.Project(root: Path)

Bases: object

A Python project on which setup.py pyproject can be run. Test code should not normally construct instances of Project() directly; instead, they can get one through a fixture or some helper function.

Once you have the Project object, create any files you need underneath the root by calling write() or one of its convenience wrappers like setup_py() or setup_cfg(). If you need to do anything other than creating files or if there is some reason not to use the write() method, you can work directly on root, but don’t change anything outside of root. Finally, when all necessary files have been created, call one of run(), run_cli(), or generate() to run setup.py pyproject (or an equivalent) on the project.

Parameters:

root – The root directory in which to create the project. It should already exist. Typically this might be a temporary directory created by pytest’s tmp_path fixture.

distribution(*, extra_args: Iterable[str] | None = None) → Distribution

Run setup.py but stop before actually executing any commands, and instead return the Distribution object.

generate(*, extra_args: Iterable[str] | None = None) → Pyproject

Run the equivalent of setup.py pyproject but return the generated data structure that would go into pyproject.toml instead of writing it out.

root: Path

The directory in which the project is to be created

run(runner: ProjectRunner, *, extra_args: Iterable[str] | None = None) → ProjectRunResult

Run setup.py pyproject on the created project and return the output.

If the project doesn’t already have a setup.py file, a simple one will be automatically created by calling setup_py() with no arguments before running it.

Parameters:

runner – The callable to use to run the script

run_cli(runner: ProjectRunner, *, extra_args: Iterable[str] | None = None) → ProjectRunResult

Run the console script setuptools-pyproject-migration on the created project and return the output.

In contrast to run(), if setup.py doesn’t exist, it will not be created, because the script is supposed to work without it. If you want to test the script’s behavior with a setup.py file, create it “manually” with a call to setup_py().

Parameters:

runner – The callable to use to run the script

setup_cfg(content: str) → None

Write a setup.cfg file in the project root directory.

Parameters:

content – Text content to write to the file.

setup_py(content: str | None = None) → None

Write a setup.py file in the project root directory.

Parameters:

content – Text content to write to the file.

write(filename: Path | str, content: str) → None

Write a file with the given content and the given filename relative to the project root. If the file already exists, it will be overwritten after issuing a warning.

Parameters:

  • filename – A filename or pathlib.Path representing the file to write. This should be a relative path, which will be interpreted relative to the project root directory. If the referenced file is not inside the project root, a warning will be issued.

  • content – Text content to write to the file.

class test_support.ProjectRunResult(*args, **kwargs)

Bases: Protocol

returncode: int
stderr: str
stdout: str
success: bool
class test_support.ProjectRunner(*args, **kwargs)

Bases: Protocol

A runner for an external command. This is basically an abstraction of ScriptRunner.run() from pytest-console-scripts, or at least the subset of its behavior which we use in this project.

class test_support.WritePyprojectFactory

Bases: object

DEFAULT_NAME = 'TestProject'
DEFAULT_VERSION = '1.2.3'
test_support.is_at_least(distribution_name: str, required_version: Version | str) → bool

test_support.distribution