homepage

timespec is just a structure of two integers, so we should expose it as a simple and efficient Python tuple: (int, int). We can simply expose this type in os.stat, or we can do better by providing an optional callback to convert this tuple to a high level object. It looks like everybodys wants something different at high level (decimal, datetime, float128, ...), so giving the choice of the type to the caller looks to be a good idea :-)
os.stat(fn) => timestamps stored as int
os.stat(fn, lambda x: x) => timestamps stored as (int, int)
Callbacks for other data types:
def to_decimal(sec, nsec):
 return decimal.Decimal(sec) + decimal.Decimal(nsec).scaleb(-9)
def to_datetime(sec, nsec):
 # naive, we can do better
 t = sec + nsec*1e-9
 return datetime.datetime.fromtimestamp(t)
def to_float128(sec, nsec):
 return float128(sec) + float128(nsec)*float128(1e-9)
etc.
Using a callback removes also the bootstrap issue: we don't have to prodive to_datetime() in the posix module or in directly in the os module. The datetime module may provide its own callback, or we can write it as a recipe in os.stat documentation.
I don't know how to call this new argument: decode_timestamp? timestamp_callback? ...?
If it is too slow to use a callback, we can take the first option: expose the timestamp as (int, int). For example: os.stat(path, tuple_timestamp=True).