# Ergonomics of new pathlib.Path.scandir()

**URL:** <https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721>\
**Category:** Core Development\
**Created:** [November 19, 2024, 11:58pm UTC](https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721 "2024-11-19T23:58:34Z")\
**Posts on this page:** 1\
**Showing post:** 30

<div class="post-metadata">

**Author:** ![barneygale](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/barneygale/32/1882_2.png) [@barneygale](https://discuss.python.org/u/barneygale)\
**Post date:** [December 6, 2024, 10:42pm UTC](https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721/30 "2024-12-06T22:42:32Z")

</div>

I’ve now reverted the addition of `Path.scandir()`:

> <https://github.com/python/cpython/pull/127377>
>
> Remove documentation for \`pathlib.Path.scandir()\`, and rename the method to \`\_sc…andir()\`. In the private pathlib ABCs, make \`iterdir()\` abstract and call it from \`\_scandir()\`.
> 
> It's not worthwhile to add this method at the moment - see discussion: https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721
> 
> 
> 
> \* Issue: gh-125413
> 
> 
> 
> 
> \----
> 📚 Documentation preview 📚: https://cpython-previews--127377.org.readthedocs.build/

There’s some discussion here about how we might expose the cached file type in pathlib:

> <https://github.com/python/cpython/pull/127494>
>
> Change the default value of \`PurePathBase.parser\` from \`ParserBase()\` to \`posixp…ath\`. As a result, user subclasses of \`PurePathBase\` and \`PathBase\` use POSIX path syntax by default, which is very often desirable.
> 
> Move \`pathlib.\_abc.ParserBase\` to \`pathlib.\_types.Parser\`, and convert it to a runtime-checkable protocol.
> 
> Add \`pathlib.\_types.DirEntry\`, which is a protocol for directory entries. Objects of this type provide a subset of the \`os.DirEntry\` API, specifically those methods and attributes needed to implement \`glob()\` and \`walk()\`.
> 
> Add \`pathlib.\_types.StatResult\`, which is a protocol for stat() results. Objects of this type provide a small subset of the \`os.stat\_result\` API, specifically attributes for the file type, permissions and location/offset.
> 
> No user-facing changes as the pathlib ABCs are still private.
> 
> 
> \* Issue: gh-127456

IIUC the current proposal is as follows: we add a `Path.info` property, which exposes an object with `is_file()`, `is_dir()` and `is_symlink()` methods. Accessing the property doesn’t perform FS access. The property type is either `os.DirEntry` (for paths generated by `Path.iterdir()`) or a new pathlib type (other paths). In both cases, `stat()` results are cached.

I propose that `p = Path(p)` is sufficient for clearing the `p.info` cache, and so we don’t need to provide further methods/property deleters/etc.

If we add something like `Path.info`, then:

- Users will be able to get at the `os.DirEntry` objects internally generated by `Path.iterdir()`, which are otherwise thrown away
- Users writing performance-sensitive code can rely on `path.info` for cached file status _whether or not_ the path object was generated by `iterdir()`
- In the pathlib ABCs, we can replace `PathBase.stat()` with `PathBase.info`. The former is too low-level and awkward to implement for most virtual filesystems.

Here’s a rough example:

```python
>>> from pathlib import Path
>>> p = Path.cwd()
>>> p.info
<pathlib._local._FileInfo object at 0x7f6f357fcf00>
>>> p.info.is_dir()
True
>>> q = next(p.iterdir())
>>> q
PosixPath('Lib')
>>> q.info
<DirEntry 'Lib'>

```

Thoughts?

---

_[View the full topic](https://discuss.python.org/t/ergonomics-of-new-pathlib-path-scandir/71721)._