Add `pathlib.Path.metadata()` and soft-deprecate `info`

[barneygale]

Feature or enhancement

Proposal:

I propose we add a pathlib.Path.metadata() method that requires a keyword-only cached argument, e.g.:

>>> m = pathlib.Path('README.txt').metadata(cached=True)
>>> m
Metadata('README.txt')
>>> m.is_file()
True

If cached is True, the method may return a Metadata object that was previously fetched and cached. If False, the return value is always up-to-date.

pathlib.Path.info should be soft-deprecated; its implementation should call self.metadata(cached=True)

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721/70

[barneygale]

An alternative name for the "cached" argument might be "sync", with the opposite meaning.

[cmaloney]

Is the metadata object required to be filled in at return or could it be more lazily fetched? Recently there is work ongoing to add statx and that has a lot more flags for selecting specific desired subsets of information. If the Metadata object needs to be complete up front then would need a way to say "At least this information is required" (otherwise might end up with multiple statx calls required)