Practical Python

Timestamps, Hashes, and Provenance in Python Reports

Use timestamps to explain when, hashes to check file bytes, and provenance notes to record where each input came from.

Use a timestamp for when something happened, a hash for whether file bytes match, and provenance notes for where those bytes came from. A useful technical report carries all three when a later reader needs to audit the result. A matching hash can confirm that a file stayed the same since it was recorded. The source history tells you how that file was acquired.

Record event time and collection time separately

A publisher's date, your retrieval time, and the date of the event described are not automatically the same. Store the supplied timestamp alongside a normalized value when conversion is justified. If the original has no timezone, preserve that uncertainty instead of silently using the collector machine's local setting.

For elapsed duration, a monotonic clock is useful because it is designed for measuring intervals rather than representing civil time. Record UTC for a report's wall-clock context and use the appropriate duration clock for how long an operation took.

Hash the bytes you actually saved

JSON formatting, encoding, line endings, and trailing newlines can change a file's bytes. Compute a digest over the saved representation you intend to identify. Reformatting a report later can be a legitimate edit, but it produces a different artifact.

Keep the original when preservation matters, and analyze a copy. A matching SHA-256 digest supports a statement that the compared byte sequences match the recorded baseline. It does not establish that the baseline was independently trusted.

Preserve context outside the digest

Record the source URL, collection command, software version, interpreter, operating system, and relevant input identifiers. Explain which fields came directly from a source and which were derived by your program.

A sidecar beside a writable report can be changed together with that report. Store important baselines under an appropriate independent preservation procedure. The right procedure depends on the professional context; a teaching example does not create a custody system retroactively.

Avoid turning metadata into conclusions

Two sources pointing to one URL may be repeating the same publication. A new retrieval timestamp does not necessarily mean a new event. A corrected headline may deserve a metadata revision even when the underlying URL remains unchanged.

These distinctions are practical. They help a reviewer ask the next useful question instead of accepting a plausible-looking timeline at face value.

Practice with a tiny artifact

Write a text file, record its hash, and make a copy. Compare the copy before and after changing one character. Then add a short record describing the command and time context. Explain exactly what the comparison established and what it did not. That explanation is part of the exercise, not an optional disclaimer.

To preserve a source offset and compare events across systems, handle timezones in Python timestamps.

Sources and further reading

Related reading

Browse Practical Python · Explore project tutorials

Search PythonProjects.org