fix: make uproot.recreate physically truncate an existing file

[ariostas]

🤖 AI text below 🤖

Addresses finding 3 of "PR 1" in #1688. This is a regression, with a clear origin.

Before the fsspec migration, uproot.recreate truncated the path itself:

if isinstance(file_path, str):
    with open(file_path, "w"):
        pass
    sink = uproot.sink.file.FileSink(file_path)

#1016 / #1034 moved that into FileSink.__init__, which only truncates when the file does not already exist:

https://github.com/scikit-hep/uproot5/blob/main/src/uproot/sink/file.py#L52-L58

so recreating over an existing file opens it "r+b" and leaves every byte past the new fEND in place. Recreating a 100 kB path as an empty ROOT file left the physical size at 100 kB with fEND at 1658.

Changes

• FileSink takes a mode: "create", "recreate", or "update" (default, so existing callers are unchanged), mirroring ROOT's TFile options. The truncate/create decision lives only there.
  • "recreate" truncates an existing path, and now also a file-like object, which previously kept its stale trailing bytes too. truncate is not required of file-like objects, so ones without it are written as before.
    An existing path is truncated through the file opened "r+b", not with fs.touch beforehand. Filesystems that can write whole files but not open them "r+b" (S3, XRootD) still fail as on main, but with the file intact: truncating first would have emptied the file and then failed.
  • "create" creates the file with exclusive mode "xb", so a file that appears between the existence check and the creation is never overwritten (atomic on local filesystems). Filesystems that don't support "xb" fall back to an existence check. A file-like object has no path to check, so it is written into as is (not truncated), as on main.
  • "update" keeps its "r+b" behavior.
• uproot.create and uproot.recreate share one implementation, and unrecognized options are rejected before the sink is opened. Otherwise uproot.recreate(path, compresion=...) would truncate the existing file and only then raise TypeError. uproot.update validates first as well.
• Each call resolves the URL once (url_to_fs) instead of up to three times with repeated exists checks.

Out of scope, but noticed along the way: extra keyword arguments meant as fsspec storage_options are never popped from options, so create/recreate/update always raise TypeError for them (e.g. uproot.recreate(p, auto_mkdir=True)). I left that unchanged here; see #1729.

[codecov]

Codecov Report

❌ Patch coverage is 85.71429% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.21%. Comparing base (4f2f340) to head (df2ee9c).

Files with missing lines	Patch %	Lines
src/uproot/sink/file.py	83.78%	5 Missing and 1 partial ⚠️

❌ Your patch check has failed because the patch coverage (85.71%) is below the target coverage (98.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

Files with missing lines	Coverage Δ
src/uproot/writing/writable.py	84.83% <100.00%> (+0.31%)	⬆️
src/uproot/sink/file.py	83.18% <83.78%> (-0.91%)	⬇️

... and 1 file with indirect coverage changes

[Copilot]

Copilot review overview

🟡 Changes recommended

create can destructively truncate existing file-like objects; restrict truncation to recreate or reject that combination.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Prevent create mode from truncating existing file-like objects · New

What changed in this PR

Fixes uproot.recreate so existing files are physically truncated while preserving create/update behavior.

Changes:

• Adds create, recreate, and update sink modes.
• Validates options before opening or truncating files.
• Adds regression coverage for truncation and mode behavior.

File	Summary
tests/​test_1697_recreate_truncates.py	Tests truncation and mode behavior.
src/​uproot/​writing/​writable.py	Shares create/recreate setup and validates options early.
src/​uproot/​sink/​file.py	Implements mode-specific creation, truncation, and update behavior; create currently truncates file-like objects.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.