Skip to content
Append a sidecar extension without replacing the original suffix

Append a sidecar extension without replacing the original suffix

November 19, 2026

A checksum sidecar often keeps the entire data filename and adds another extension. with_suffix() replaces the last suffix, so it can produce the wrong name for that convention. Change the final name with with_name() when the original extension must remain.

Set up

Tested on Linux with CPython 3.12.14. Use Bash, Python 3.12 or newer, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal open and stop if setup fails. Run without -O so the assertions remain enabled.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as sidecar_path_names.py:

from pathlib import PurePosixPath


def checksum_path(path):
    return path.with_name(path.name + ".sha256")


for name in ("reports/data.csv", "reports/archive.tar.gz", "reports/README"):
    path = PurePosixPath(name)
    replaced = path.with_suffix(".sha256")
    appended = checksum_path(path)
    print(f"{path}: replace={replaced.name}, append={appended.name}")
    assert appended.parent == path.parent
    assert appended.name == path.name + ".sha256"

assert checksum_path(PurePosixPath("data.csv")) == PurePosixPath("data.csv.sha256")
assert checksum_path(PurePosixPath("archive.tar.gz")) == PurePosixPath("archive.tar.gz.sha256")
try:
    checksum_path(PurePosixPath("/"))
except ValueError:
    print("Root path: rejected (no filename)")
else:
    raise AssertionError("expected root path rejection")

Run:

python3 -B sidecar_path_names.py

Observed output:

reports/data.csv: replace=data.sha256, append=data.csv.sha256
reports/archive.tar.gz: replace=archive.tar.sha256, append=archive.tar.gz.sha256
reports/README: replace=README.sha256, append=README.sha256
Root path: rejected (no filename)

Preserve the whole final name

The CSV filename loses its original extension in the replacement column. The compressed archive loses only its last suffix there, leaving the preceding archive suffix. Appending to the complete final name preserves both.

The extensionless filename gives the same result under both methods. That case alone would miss the difference, so the assertions and output include single and compound extensions. The parent directory remains unchanged.

The with_name reference describes replacing the final component; with_suffix replaces the last suffix or appends one when absent. A root path has no final filename, so the helper’s attempted name change raises the caught error.

Separate a path name from file operations

The example uses pure POSIX paths and performs no filesystem I/O. It neither calculates a checksum nor checks whether a source or sidecar exists. The extension is a naming convention, not evidence that any content has been verified.

The helper expects a path intended to name a file. A directory path with a nonempty final name can also be transformed; path text alone does not prove that it is a file. Use the path flavor appropriate to the input, and handle output collisions and write failures separately when adding real file operations. A second call would append the extension again, so apply it to the original data path once.

Clean up

Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.

rm -- sidecar_path_names.py
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on