[Python-ideas] PEP: Extended stat_result (First Draft)

[Jim Jewett]

On Mon, May 6, 2013 at 4:30 AM, Pieter Nagel <pieter at nagel.co.za> wrote:

> This PEP proposes extending the result of ``os.stat()``, ``os.fstat()`` and
> ``os.lstat()`` calls with added methods such as ``is_file()``.  These added
> methods will obviate the need to use the ``stat`` module to interpret the
> result of these calls.

Another alternative would be to modify os.path.isfile, os.path.isdir,
etc so that they can accept a stat_result in place of a filename (or
open-file handle).

Yet another (albeit more complicated, with questionable
backwards-compatibility) alternative would be to have the os.path.*
functions maintain a very short-duration cache, so that if the same
file is queried multiple times within a second or so, the stat_result
could be reused.

> Whereas in contrast, similar code that wishes to avoid the penalty of two
> potential calls to ``os.stat()``, will look radically different::

>     st = os.stat(f)
>     if stat.S_ISREG(st.st_mode) or stat.S_ISDIR(st.st_mode):
>         # do something

Out of curiosity, is it common to call more than function, except in
the following cases:

(1) stat.S_ISREG(st.st_mode) or stat.S_ISDIR(st.st_mode)
(2) try all the type functions until successful

If those are the only real use cases, it might make sense to just add
a pair of functions for those two specific cases.

    > if os.path.isfile_or_dir(filename)

Or maybe just for the latter, with the first spelled either

    > from os.path import filekind
    > if filekind(filename) in (filekind.REGULAR, filekind.DIR) #symlinks?

or

    > from os.path import filekind
    > if filekind(filename) isinstance (filekind.REGULAR, filekind.DIR)



> This PEP proposes ameliorating the situation by adding higher-level
> predicates such as ``is_file()`` and ``is_dir()`` directly to the
> ``stat_result`` object, so that (assuming the file ``f`` exists) the second
> code example can become::

>     st = os.stat(f)
>     if st.is_file() or st.is_dir():
>         # do something

Even assuming these are added individually (as opposed to a single
filekind), is there a reason not to make them properties?  I
understand that a property normally shouldn't hide something as
expensive as a system call, but in this case the system call is
already complete before the caller has a stat_return with attributes.


> Added methods on ``stat_result``

> same_stat(other)
>     Equivalent to ``os.path.samestat(self, other)``.

Why is this not just an equality test?

Is there just too much  of a backward-compatibility problem for
stat_result objects that refer to the same device/inode, but have
differences in the way other attributes are set?

> format()
>     This shall return ``stat.S_IFMT(self.st_mode)``.

I don't think this is important enough to justify the confusion with "".format


> Rejected Proposals
> ==================

> It has been proposed [#filetype]_ that a mechanism be added whereby
> ``stat_result`` could return some sort of type code identifying the file
> type.  Originally these type codes were proposed as strings such as 'reg',
> 'dir', and the like, but others suggested enumerations instead.  The author
> rejected that proposal to keep the current PEP focused on ameliorating
> existing asymmetries rather than adding new behavior, but is not opposed to
> the notion in principle (assuming enums are used instead of strings).
> Experience with creating the reference implementation for this PEP may yet
> change the author's mind.

I don't think an Enum is quite the right fit, because of

Symbolic links -- if the original filename was to a link, that can be
important, but asking everyone to check for both regular and
link_to_regular is ugly.

Special Types (anything other than File and Directory) may vary by
system, and may have a subclass relationship.

On the other hand, using instance on marker classes might lose the
efficiency you were concerned about.

Maybe the answer is to use marker classes plus convenience methods for
the special case methods of is_file and is_dir?

-jJ