Skip to main content

Create a temporary file, take care of removing it if needed

[Home | GitLab | PyPI | ReadTheDocs]

Overview

The with-tempfile library is designed to help handle files that should be modified atomically, so that there is no chance that at any time, another program reading the file would get its incomplete contents, or that an error halfway through writing the updated contents will leave the file incomplete on disk.

It currently provides two functions, write_text and append_text.

Binary file handing is planned.

A command-line tool to overwrite or append to a file atomically is planned.

API

Update or create files atomically

write_text

The write_text function creates a temporary file in the same directory as the target (so that an atomic rename will succeed), writes out the supplied contents, and then atomically renames the temporary file to the target one.

LOCAL_CONFIG: Final = pathlib.Path("/etc/sample/config.toml")

with_tempfile.write_text(LOCAL_CONFIG, toml.dumps(cfg))

append_text

The append_text function creates a temporary file in the same directory as the target (so that an atomic rename will succeed), copies the current contents of the target file if it exists, appends the supplied text, and then atomically renames the temporary file to the target one.

ENC_SINGLE: Final = "ISO-8859-15"
"""A fallback single-byte encoding that has all 256 codepoints as valid."""

ENCODINGS: Final = ("UTF-8", ENC_SINGLE)
"""The names of the encodings to try to decode a file's contents with."""

MARKER_TEXT: Final = f"""
# Autogenerated by sampletool; modifications may be lost!
"""

if CFG_SECTION_NAME not in cfg:
    new_section: Final = f"{MARKER_TEXT}{toml.dumps({CFG_SECTION_NAME: cfg_section})}"
    with_tempfile.append_text(LOCAL_CONFIG, new_section, encoding=ENCODINGS)

Note that this function may be dropped in a future version of the with-tempfile library, since in most cases the desired contents of the new file can be fully constructed and write_text may be used instead.

Path manipulation helpers

The with_tempfile.pathutil module provides the PathLike union type that also includes str, and the as_path function that will convert an object into a pathlike.Path object if it is not already one.

def create_default(path: pathutil.PathLike) -> None:
    """Write the default text to the specified file."""
    with_tempfile.write_text(pathutil.as_path(path), DEFAULT_CONTENTS)

The read_text function is similar to the Path.read_text method from the Python standard pathlib library, but it allows more than one encoding to be tried in order. This may be useful for files that may or may not be valid UTF-8 and a reader that might want to fall back to a single-byte encoding.

contents, encoding = pathutil.read_text(path, encoding=ENCODINGS)
with_tempfile.write_text(path, rot13(contents), encoding=encoding)

Temporary file handling

The with_tempfile.temputil module provides the NamedTemporaryTextFile function that returns a TemporaryTextFile object. It is quite similar to NamedTemporaryFile in Python's standard tempfile library, but the object has the new path and resolved_path properties: both pathllib.Path objects. It also has an unset_delete method that prevents the object destructor from trying to delete the temporary file if the program has already e.g. renamed it.

with temputil.NamedTemporaryTextFile(prefix="info-", suffix=".txt", encoding="UTF-8") as tempf:
    print("this is a test", file=tempf, flush=True)
    tempf.path.rename_to("/etc/sample/info.txt")
    tempf.unset_delete()

There is also a TemporaryDirectory class that is similar to the one in the tempfile library, but also has the path and resolved_path properties. An important difference with the system's TemporaryDirectory class is that the __enter__() method returns a pathlib.Path object instead of a string.

with temputil.TemporaryDirectory(prefix="test-") as tempd:
    tempcfg: Final = tempd / "config.txt"
    ...

Maildir-style directory handling

The MaildirSpool dataclass provides a safecat method that creates a file in the specified temporary directory, writes the provided text to it, and then renames it to a guaranteed unique name in the specified spool directory. This is an implementation of Prof. D. J. Bernstein's Maildir concept, although the naming of the files is left to the caller, they do not necessarily follow the original Maildir specification.

base: Final = pathlib.Path("/path/to/maildir")
maildir: Final = temputil.MaildirSpool(tmpdir=base / "tmp", spooldir=base / "new")
new_file: Final = maildir.safecat(
    prefix="616.42.",
    suffix=".txt",
    contents="This is a test\n",
    encoding="UTF-8",
)
assert new_file.parent == base / "new"

There is also a from_maildir() constructor that uses the tmp and new subdirectory names:

base: Final = pathlib.Path("/path/to/maildir")
maildir: Final = temputil.MaildirSpool.from_maildir(base)
new_file: Final = maildir.safecat(
    prefix="616.42.",
    suffix=".txt",
    contents="This is a test\n",
    encoding="UTF-8",
)
assert new_file.parent == base / "new"

The safecat() top-level function provides a shortcut, specifying all of the parameters at once.

Contact

The with-tempfile library was written by Peter Pentchev. It is developed in a GitLab repository. This documentation is hosted at Ringlet with a copy at ReadTheDocs.

Metadata

Release files for with-tempfile 0.1.3

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

Source distribution (sdist)

Source distribution for with-tempfile 0.1.3
File Size Uploaded Provenance Actions
with_tempfile-0.1.3.tar.gz 45.9 kB Without provenance Details for with_tempfile-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for with-tempfile 0.1.3
File Interpreter ABI Platform Actions
with_tempfile-0.1.3-py3-none-any.whl Python 3 none any Details for with_tempfile-0.1.3-py3-none-any.whl

Total release size: 55.6 kB

Release files / with_tempfile-0.1.3.tar.gz

Download URL with_tempfile-0.1.3.tar.gz
Size 45.9 kB
Tags Source
SHA-256 checksum
How to use checksums
aa2e97e6c9af6b49a689cd367a4b2ecbea38c1f323ee22f0989bf59ff1e431c4
BLAKE2b-256 checksum
How to use checksums
cc6e3e8247f92ce9c1847509b315f308e69093a63f121e8f39460e4632f46436
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Release files / with_tempfile-0.1.3-py3-none-any.whl

Download URL with_tempfile-0.1.3-py3-none-any.whl
Size 9.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3dd476fc4bd9ee219f9878d801d42bb93140ffeadc390d150ac6daf9ad9ace03
BLAKE2b-256 checksum
How to use checksums
bcb95398a1c44e1cb158902ab448150f4cc178dc73d08621e96c03ba9905d8c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for with-tempfile 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page