Meta

• License Expression: MIT
  SPDX License Expression
• Author: Omar Kohl
• Maintainer: Omar Kohl
• Tags datafiles , pytest , tmp_path
• Requires: Python >=3.8

Classifiers

• Development Status
  • 5 - Production/Stable
• Framework
  • Pytest
• Intended Audience
  • Developers
• License
  • OSI Approved :: MIT License
• Operating System
  • OS Independent
• Programming Language
  • Python :: 3
  • Python :: 3.8
  • Python :: 3.9
  • Python :: 3.10
  • Python :: 3.11
  • Python :: 3.12
  • Python :: 3.13
• Topic
  • Software Development :: Testing

pytest-datafiles

👁 PyPI version
👁 Code Climate

pytest plugin to create a tmp_path containing a preconfigured set of files and/or directories.

Note about maintenance: This project is maintained and bug reports or pull requests will be addressed. There is little activity because it simply works and no changes are required.

Features

This plugin allows you to specify one or several files/directories that are copied to a temporary directory (tmp_path) before the execution of the test. This means the original files are not modified and every test runs on its own version of the same files.

Files/directories can be specified either as strings or as pathlib.Path objects.

To take advantage of the datafiles fixture in a test function, add datafiles as one of the test function parameters (per usual with pytest fixtures) and decorate the test function with @pytest.mark.datafiles(file1, file2, dir1, dir2, ...). See the examples below.

The datafiles variable in your test function is a pathlib.Path object (tmp_path) where the copied files are located. Under Linux systems this will most likely be some subdirectory of /tmp/.

Options

The following options can be specified as keyword arguments (kwargs) to the @pytest.mark.datafiles decorator function:

• keep_top_dir: For all parameters that represent directories, keep that directory instead of only (recursively) copying its content. Possible values are True or False. False is the default value.
• on_duplicate: Specify the action to take when duplicate files/directories are found. Possible values are: exception, ignore and replace. The default value is exception.
  • exception: An exception is raised instead of copying the duplicate file/directory.
  • ignore: The second (or subsequent) files/directories with the same name as the first one are simply ignored (i.e., the first file/directory with the duplicate name is kept).
  • replace: The second (or subsequent) files/directories with the same name replace the previous ones (i.e., the last file/directory with the duplicate name is kept).

See below for some examples.

Installation

pipinstallpytest-datafiles

Upgrade to 3.0

Version 3 now uses tmp_path, resulting in pathlib.Path objects instead of py.path.

Your tests may need to be adjusted. In examples/example_upgradev3.py you see some possible variations.

Usage

The full code with more details for the examples can be found in examples/.

Example 1

One possible use case is when you are running tests on very big files that are not included or packaged with your tests. For example, your test files are large video files stored under /opt/big_files/. You don't want your tests modifying the original files, but the files are required by the tests. You can reference these data files in your test method as follows:

# more details in `examples/example_1.py`

@pytest.mark.datafiles('/opt/big_files/film1.mp4')
deftest_fast_forward(datafiles):
 # ...

Example 2

Now for another use case: let's say in the directory where your tests are located, you place a directory named test_files. Here you have a lot of images you want to run tests on. By using this plugin, you make sure the original files under test_files are not modified by every test.

# more details in `examples/example_2.py`

@pytest.mark.datafiles(
 FIXTURE_DIR / 'img1.jpg',
 FIXTURE_DIR / 'img2.jpg',
 FIXTURE_DIR / 'img3.jpg',
)
deftest_find_borders(datafiles):
 # ...

Example 3

If all (or many) of your tests rely on the same files it can be easier to define one decorator beforehand and apply it to every test like this example:

# more details in `examples/example_3.py`

ALL_IMGS = pytest.mark.datafiles(
 FIXTURE_DIR / 'img1.jpg',
 FIXTURE_DIR / 'img2.jpg',
 FIXTURE_DIR / 'img3.jpg',
)

@ALL_IMGS
deftest_something1(datafiles):
 # ...

Example 4

Imagine you have 3 directories (dir1, dir2, dir3) each containing the files (fileA and fileB).

This example clarifies the options on_duplicate and keep_top_dir.

Example 5

You can also use a str paths.

# more details in `examples/example_5.py`

@pytest.mark.datafiles(
 os.path.join(FIXTURE_DIR, 'img1.jpg'),
 os.path.join(FIXTURE_DIR, 'img2.jpg'),
 os.path.join(FIXTURE_DIR, 'img3.jpg'),
)
deftest_str(datafiles):
 # ...

Contributing

Contributions are very welcome. Tests can be run with make test. Please ensure the coverage stays at least the same before you submit a pull request.

Releasing

To create and upload a new package, update the version number in pyproject.toml and CHANGELOG.md, then:

# Run tests and linting
maketest
makelint

# Build the distribution
makeclean
makedist

# Optional: Test on TestPyPI first
uvpublish--publish-urlhttps://test.pypi.org/legacy/

# Verify the package is usable
uvvenvtest-venv--python3.11
sourcetest-venv/bin/activate
uvpipinstall--index-urlhttps://test.pypi.org/simple/--extra-index-urlhttps://pypi.org/simple/pytest-datafiles
pytestexamples/example_2.py
deactivate

# Create git tag (using jj)
jjtagset3.0.1-r@-
jjgitpush
gitpush--tags

# Upload to PyPI
uvpublish

# Create GitHub release
ghreleasecreate3.0.1\
--title"pytest-datafiles 3.0.1"\
--notes-from-tag\
dist/*

Authentication: Set the UV_PUBLISH_TOKEN environment variable with your PyPI API token, or uv publish will prompt for credentials.

Of course this will only work if you have the necessary PyPI credentials for this package.

License

Distributed under the terms of the MIT license, "pytest-datafiles" is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Acknowledgements

Thanks to @flub for the idea to use pytest marks to solve the problem this plugin is trying to solve.

Some ideas to improve this project were taken from the Cookiecutter templates cookiecutter-pypackage and cookiecutter-pytest-plugin.

Verified details

These details have been verified by PyPI

Maintainers

👁 Avatar for omarkohl from gravatar.com
omarkohl

Unverified details

These details have not been verified by PyPI

Project links

• Homepage
• Issues
• Repository

• Download URL: pytest_datafiles-3.0.1.tar.gz
• Upload date: Jan 4, 2026
• Size: 222.2 kB
• Tags: Source
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.9.16 {"installer":{"name":"uv","version":"0.9.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Hashes for pytest_datafiles-3.0.1.tar.gz

Algorithm	Hash digest
SHA256	05fc3eef2429fe26ae42283cccb1f3831b53b12d4bd8b4734bf42973d4af6e16
MD5	75dfb343ebfc833559353b4dba0e21b4
BLAKE2b-256	fc8d081ba12c1ea4eb1b899eb61b4501136c233492280fdb70343edcdfdf26ce

See more details on using hashes here.

• Download URL: pytest_datafiles-3.0.1-py3-none-any.whl
• Upload date: Jan 4, 2026
• Size: 6.4 kB
• Tags: Python 3
• Uploaded using Trusted Publishing? No
• Uploaded via: uv/0.9.16 {"installer":{"name":"uv","version":"0.9.16","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Hashes for pytest_datafiles-3.0.1-py3-none-any.whl

Algorithm	Hash digest
SHA256	c48f27a8afec03a482a10587ab5f5ab930ced4cbdeb2e3a2cbcc0323a51d22c7
MD5	ed167139c49220799da5bf3cb7d23edf
BLAKE2b-256	4b2388880d5dc36eac9696ad40823e37c1fdbfa81a67b9cfd0ed445b3ed7ec54

See more details on using hashes here.