Skip to content

API Reference

Update or create files atomically

with_tempfile.write_text(fpath, contents, *, encoding=None)

Atomically write the specified text to the specified file.

Source code in python/src/with_tempfile/impl.py 
17
18
19
20
21
22
23
24
25
def write_text(fpath: pathutil.PathLike, contents: str, *, encoding: str | None = None) -> None:
    """Atomically write the specified text to the specified file."""
    with temputil.NamedTemporaryTextFile(
        dir=str(pathutil.as_path(fpath).parent),
        encoding=encoding,
    ) as tempf:
        print(contents, end="", file=tempf, flush=True)
        tempf.path.rename(fpath)
        tempf.unset_delete()

with_tempfile.append_text(fpath, contents, *, encoding=None)

If the file exists, atomically append text, otherwise write the new contents.

Source code in python/src/with_tempfile/impl.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
def append_text(
    fpath: pathutil.PathLike,
    contents: str,
    *,
    encoding: str | Iterable[str] | None = None,
) -> None:
    """If the file exists, atomically append text, otherwise write the new contents."""
    try:
        current, actual_encoding = pathutil.read_text(pathutil.as_path(fpath), encoding=encoding)
    except FileNotFoundError:
        current, actual_encoding = "", pathutil.encoding_tuple(encoding)[0]

    write_text(fpath, f"{current}{contents}", encoding=actual_encoding)

Path manipulation helpers

with_tempfile.pathutil

Helpers for manipulating pathlib.Path objects and strings.

This module's main purpose is to define the PathLike type that may be used for function arguments that may be of any type suitable for passing to the system Python file handling routines. It is somewhat similar to the os.PathLike class, but it has a different set of allowed classes, e.g. it allows strings.

PathLike = pathlib.Path | str module-attribute

Something that may be used as a path.

as_path(path)

Convert a pathlike object to a path as needed.

Source code in python/src/with_tempfile/pathutil.py 
27
28
29
30
31
32
def as_path(path: PathLike) -> pathlib.Path:
    """Convert a pathlike object to a path as needed."""
    if isinstance(path, pathlib.Path):
        return path

    return pathlib.Path(path)

encoding_tuple(encoding)

Split the first of the requested encoding names from the rest.

Source code in python/src/with_tempfile/pathutil.py 
35
36
37
38
39
40
41
42
43
44
45
def encoding_tuple(encoding: str | Iterable[str] | None) -> tuple[str, Iterator[str]]:
    """Split the first of the requested encoding names from the rest."""
    if encoding is None:
        return "UTF-8", iter(())

    if isinstance(encoding, str):
        return encoding, iter(())

    it: Final = iter(encoding)
    first: Final = next(it)
    return first, it

read_text(path, *, encoding)

Read a file's contents, try to decode it using the specified encodings in order.

The return value is a tuple containing the full text read from the file and the name of the encoding used to decode it.

The encoding parameter may be either None, a string, or an iterable of strings. In the latter case the specified encodings are tried in order; the first one that successfully decodes the file's contents is returned.

Source code in python/src/with_tempfile/pathutil.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def read_text(path: pathlib.Path, *, encoding: str | Iterable[str] | None) -> tuple[str, str]:
    """Read a file's contents, try to decode it using the specified encodings in order.

    The return value is a tuple containing the full text read from the file and
    the name of the encoding used to decode it.

    The `encoding` parameter may be either None, a string, or an iterable of strings.
    In the latter case the specified encodings are tried in order; the first one that
    successfully decodes the file's contents is returned.
    """
    first, rest = encoding_tuple(encoding)
    raw: Final = path.read_bytes()
    try:
        return raw.decode(first), first
    except ValueError:
        for enc in rest:
            try:
                return raw.decode(enc), enc
            except ValueError:
                pass

        # None of the encodings worked, return the error from the first attempt
        raise

Temporary file handling

with_tempfile.temputil

Helpers that combine temporary files and pathlib routines.

This module defines the NamedTemporaryTextFile function and the TemporaryDirectory class that parallel the corresponding classes from the system tempfile module, but also have the additional path and resolved_path fields. The goal is to make it easier to use pathlib.Path objects everywhere, while still using the system temporary file routines.

TemporaryDirectory

Bases: TempDir

A temporary directory with a ready-made pathlib.Path path.

Note that the __enter__() method (and consequently with TemporaryDirectory(...) as tempd:) returns a pathlib.Path object instead of a string!

Source code in python/src/with_tempfile/temputil.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
class TemporaryDirectory(TempDir):
    """A temporary directory with a ready-made `pathlib.Path` path.

    Note that the `__enter__()` method (and consequently `with TemporaryDirectory(...) as tempd:`)
    returns a `pathlib.Path` object instead of a string!
    """

    path: pathlib.Path
    """The path to the tempfile as a `pathlib.Path` object."""

    resolved_path: pathlib.Path
    """The resolved path to the tempfile as a `pathlib.Path` object."""

    if sys.version_info >= (3, 12):

        def __init__(
            self,
            suffix: str | None = None,
            prefix: str | None = None,
            dir: pathutil.PathLike | None = None,  # noqa: A002  # tempfile API
            ignore_cleanup_errors: bool = False,  # noqa: FBT001,FBT002  # tempfile API
            *,
            delete: bool = True,
        ) -> None:
            """Create the temporary directory, initialize our new fields."""
            super().__init__(
                suffix=suffix,
                prefix=prefix,
                dir=dir,
                ignore_cleanup_errors=ignore_cleanup_errors,
                delete=delete,
            )
            self._setup_paths()

    else:

        def __init__(
            self,
            suffix: str | None = None,
            prefix: str | None = None,
            dir: pathutil.PathLike | None = None,  # noqa: A002  # tempfile API
            ignore_cleanup_errors: bool = False,  # noqa: FBT001,FBT002  # tempfile API
        ) -> None:
            """Create the temporary directory, initialize our new fields."""
            super().__init__(
                suffix=suffix,
                prefix=prefix,
                dir=dir,
                ignore_cleanup_errors=ignore_cleanup_errors,
            )
            self._setup_paths()

    def _setup_paths(self) -> None:
        """Initialize our new fields."""
        self.path = pathlib.Path(self.name)
        self.resolved_path = self.path.resolve()

    def __enter__(self) -> pathlib.Path:  # type: ignore[override]
        """Enter a context, return the path to the directory.

        Note that this method returns a `pathlib.Path` object instead of a string!
        """
        return self.path
path instance-attribute

The path to the tempfile as a pathlib.Path object.

resolved_path instance-attribute

The resolved path to the tempfile as a pathlib.Path object.

__enter__()

Enter a context, return the path to the directory.

Note that this method returns a pathlib.Path object instead of a string!

Source code in python/src/with_tempfile/temputil.py 
183
184
185
186
187
188
def __enter__(self) -> pathlib.Path:  # type: ignore[override]
    """Enter a context, return the path to the directory.

    Note that this method returns a `pathlib.Path` object instead of a string!
    """
    return self.path
__init__(suffix=None, prefix=None, dir=None, ignore_cleanup_errors=False)

Create the temporary directory, initialize our new fields.

Source code in python/src/with_tempfile/temputil.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
def __init__(
    self,
    suffix: str | None = None,
    prefix: str | None = None,
    dir: pathutil.PathLike | None = None,  # noqa: A002  # tempfile API
    ignore_cleanup_errors: bool = False,  # noqa: FBT001,FBT002  # tempfile API
) -> None:
    """Create the temporary directory, initialize our new fields."""
    super().__init__(
        suffix=suffix,
        prefix=prefix,
        dir=dir,
        ignore_cleanup_errors=ignore_cleanup_errors,
    )
    self._setup_paths()

TemporaryTextFile

Bases: TempTextWrap

A named temporary file with a ready-made pathlib.Path path.

Source code in python/src/with_tempfile/temputil.py 
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
class TemporaryTextFile(TempTextWrap):
    """A named temporary file with a ready-made `pathlib.Path` path."""

    path: pathlib.Path
    """The path to the tempfile as a `pathlib.Path` object."""

    resolved_path: pathlib.Path
    """The resolved path to the tempfile as a `pathlib.Path` object."""

    if sys.version_info >= (3, 12):

        def __init__(
            self: Self,
            file: IO[str],
            name: str,
            delete: bool = True,  # noqa: FBT001,FBT002  # tempfile API
            delete_on_close: bool = True,  # noqa: FBT001,FBT002  # tempfile API
        ) -> None:
            """Create the temporary file, initialize our new fields."""
            super().__init__(file, name=name, delete=delete, delete_on_close=delete_on_close)
            self._setup_paths()
    else:

        def __init__(
            self: Self,
            file: IO[str],
            name: str,
            delete: bool = True,  # noqa: FBT001,FBT002  # tempfile API
        ) -> None:
            """Create the temporary file, initialize our new fields."""
            super().__init__(file, name=name, delete=delete)
            self._setup_paths()

    def __repr__(self) -> str:
        """Provide a Python-esque representation."""
        # Python 3.14 may evaluate `f"{self!r}"` in the constructor...
        if not hasattr(self, "path"):
            self._setup_paths()

        return (
            f"{type(self).__name__}(file={self.file!r}, name={self.name!r}, "
            f"path={self.path!r}, resolved_path={self.resolved_path!r}"
        )

    def _setup_paths(self) -> None:
        """Initialize our new fields."""
        self.path = pathlib.Path(self.name)
        self.resolved_path = self.path.resolve()

    def unset_delete(self, *, also_on_close: bool = True) -> None:
        """Unset the "delete on drop" and also possibly the "delete on close" flag.

        The caller took care of the file, e.g. renamed it, removed it, or passed it to
        another consumer to use as-is.
        """

        def handle(obj: Any) -> None:  # noqa: ANN401  # we can handle anything
            """Unset the `delete` and maybe the `delete_on_close` flags if they are there."""
            if hasattr(obj, "delete"):
                obj.delete = False
            if also_on_close and hasattr(obj, "delete_on_close"):
                obj.delete_on_close = False

        handle(self)

        match getattr(self, "_closer", None):
            case None:
                pass

            case closer:
                handle(closer)
path instance-attribute

The path to the tempfile as a pathlib.Path object.

resolved_path instance-attribute

The resolved path to the tempfile as a pathlib.Path object.

__init__(file, name, delete=True)

Create the temporary file, initialize our new fields.

Source code in python/src/with_tempfile/temputil.py 
56
57
58
59
60
61
62
63
64
def __init__(
    self: Self,
    file: IO[str],
    name: str,
    delete: bool = True,  # noqa: FBT001,FBT002  # tempfile API
) -> None:
    """Create the temporary file, initialize our new fields."""
    super().__init__(file, name=name, delete=delete)
    self._setup_paths()
__repr__()

Provide a Python-esque representation.

Source code in python/src/with_tempfile/temputil.py 
66
67
68
69
70
71
72
73
74
75
def __repr__(self) -> str:
    """Provide a Python-esque representation."""
    # Python 3.14 may evaluate `f"{self!r}"` in the constructor...
    if not hasattr(self, "path"):
        self._setup_paths()

    return (
        f"{type(self).__name__}(file={self.file!r}, name={self.name!r}, "
        f"path={self.path!r}, resolved_path={self.resolved_path!r}"
    )
unset_delete(*, also_on_close=True)

Unset the "delete on drop" and also possibly the "delete on close" flag.

The caller took care of the file, e.g. renamed it, removed it, or passed it to another consumer to use as-is.

Source code in python/src/with_tempfile/temputil.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def unset_delete(self, *, also_on_close: bool = True) -> None:
    """Unset the "delete on drop" and also possibly the "delete on close" flag.

    The caller took care of the file, e.g. renamed it, removed it, or passed it to
    another consumer to use as-is.
    """

    def handle(obj: Any) -> None:  # noqa: ANN401  # we can handle anything
        """Unset the `delete` and maybe the `delete_on_close` flags if they are there."""
        if hasattr(obj, "delete"):
            obj.delete = False
        if also_on_close and hasattr(obj, "delete_on_close"):
            obj.delete_on_close = False

    handle(self)

    match getattr(self, "_closer", None):
        case None:
            pass

        case closer:
            handle(closer)

NamedTemporaryTextFile(*, buffering=-1, dir=None, encoding=None, prefix=None, suffix=None, delete=True)

Create a temporary file that holds its path.

Source code in python/src/with_tempfile/temputil.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def NamedTemporaryTextFile(  # noqa: N802,PLR0913  # tempfile-like API
    *,
    buffering: int = -1,
    dir: str | None = None,  # noqa: A002  # tempfile API
    encoding: str | None = None,
    prefix: str | None = None,
    suffix: str | None = None,
    delete: bool = True,
) -> TemporaryTextFile:
    """Create a temporary file that holds its path."""
    fd, name = tempfile.mkstemp(dir=dir, prefix=prefix, suffix=suffix, text=True)
    tempf: Final = open(  # noqa: PTH123,SIM115  # low-level; also, a file descriptor
        fd,
        mode="w+",
        buffering=buffering,
        encoding=encoding,
    )
    return TemporaryTextFile(tempf, name, delete=delete)