🗃 tdir - create and fill a temporary directory 🗃

Run code inside a temporary directory filled with zero or more files.

Very convenient for writing tests: you can decorate individual tests or a whole test suite.

tdir() runs code in a temporary directory pre-filled with files: it can either be used as a context manager, or a decorator for functions or classes.

tdir.fill() is a tiny function that recursively fills a directory.

Example: as a context manager

from pathlib import Path
import tdir

cwd = Path.cwd()

# Simplest invocation.

with tdir():
   # Do a lot of things in a temporary directory

# Everything is gone!

# With a single file
with tdir('hello') as td:
    # The file `hello` is there
    assert Path('hello').read_text() == 'hello\n'

    # We're in a temporary directory
    assert td == Path.cwd()
    assert td != cwd

    # Write some other file
    Path('junk.txt').write_text('hello, world\n')

# The temporary directory and the files are gone
assert not td.exists()
assert cwd == Path.cwd()

# A more complex example:
#
with tdir(
    'one.txt',
    three='some information',
    four=Path('existing/file'),  # Copy a file into the tempdir
    sub1={
        'file.txt': 'blank lines\n\n\n\n',
        'sub2': [
            'a', 'b', 'c'
        ]
    },
):
    assert Path('one.txt').exists()
    assert Path('four').read_text() == Path('/existing/file').read_text()
    assert Path('sub1/sub2/a').exists()

# All files gone!

Example: as a decorator

from pathlib import Path
import tdir
import unittest

@tdir
def my_function():
    pass  # my_function() always operates in a temporary directory


# Decorate a TestCase so each test runs in a new temporary directory
# with two files
@tdir('a', foo='bar')
class MyTest(unittest.TestCase):
    def test_something(self):
        assert Path('a').read_text() == 'a\n'

    def test_something_else(self):
        assert Path('foo').read_text() == 'bar\n'


class MyTest2(unittest.TestCase):
    # Decorate just one test in unittest
    @tdir(foo='bar', baz=bytes(range(4)))  # binary files are possible
    def test_something(self):
        assert Path('foo').read_text() == 'bar\n'
        assert Path('baz').read_bytes() == bytes(range(4))

    # Run test in an empty temporary directory
    @tdir
    def test_something_else(self):
        assert not Path('a').exists()
        assert Path().absolute() != self.ORIGINAL_PATH

    ORIGINAL_PATH = Path().absolute()

A note on AI use

Version 2.0 has exactly the same API as before, and the great majority of the code is still the handwritten code from before, but I recently used a coding assistant to find a lot of possible errors and edge cases and fix them.

I believe it should do exactly what it did before, but not fail in some unusual but certainly not impossible cases. Please let me know with an issue report if any problems crop up.

Concurrency and file boundaries

chdir=True contexts are serialized across threads because the current directory is process-wide. Nested contexts in one thread remain supported. Fixture names must be relative and remain beneath the requested root; absolute names and .. path components are rejected.

Text fixtures

Text fixtures retain the platform-default encoding unless text_encoding is provided. For portable fixture bytes, pass text_encoding='utf-8'; use text_errors to choose a decoding error policy.

API Documentation

Metadata

Release files for tdir 2.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tdir 2.0.1
File	Size	Uploaded
tdir-2.0.1.tar.gz	31.4 kB	Sep 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tdir 2.0.1
File	Interpreter	ABI	Platform	Reset
tdir-2.0.1-py3-none-any.whl 6.8 kB Sep 19, 2026	Python 3	none	any	Details

Total release size: 38.3 kB

Release files / tdir-2.0.1.tar.gz

Download URL	tdir-2.0.1.tar.gz
Size	31.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`c032c1cbafc1580e7e41cbc8d0769ca22ed9d50fa3933a2332717a783c0806e3`
BLAKE2b-256 checksum How to use checksums	`ebfc0a90b4faff7017e5e61eb6c930af1757c14614f42bc88d6eb361ac80935f`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / tdir-2.0.1-py3-none-any.whl

Download URL	tdir-2.0.1-py3-none-any.whl
Size	6.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`187271b51edd7f8b7c28037fbd4a20d75d5dea2c436ca5256a1ee7383bd9882b`
BLAKE2b-256 checksum How to use checksums	`0dafa01e7f438396a667006c4e79c537f1205e3eedfaee8ee103ce5a1ee6657c`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.10.12 {"installer":{"name":"uv","version":"0.10.12","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`