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

[MRAB]

On 06/05/2013 09:30, Pieter Nagel wrote:
[snip]
> Specification
> =============
>
>
> Added methods on ``stat_result``
> --------------------------------
>
> is_dir()
>      Equivalent to ``bool(stat.S_ISDIR(self.st_mode))``.
>
> is_character_device()
>      Equivalent to ``bool(stat.S_ISCHR(self.st_mode))``.
>
> is_block_device()
>      Equivalent to ``bool(stat.S_ISBLK(self.st_mode))``.
>
> is_file()
>      Equivalent to ``bool(stat.S_ISREG(self.st_mode))``.
>
> is_fifo()
>      Equivalent to ``bool(stat.S_ISFIFO(self.st_mode))``.
>
> is_symbolic_link()
>      Equivalent to ``bool(stat.S_ISLNK(self.st_mode))``.
>
> is_socket()
>      Equivalent to ``bool(stat.S_ISSOCK(self.st_mode)``.
>
> same_stat(other)
>      Equivalent to ``os.path.samestat(self, other)``.
>
> file_mode()
>      This shall return ``stat.filemode(stat.S_IMODE(self.st_mode))``, i.e. a
>      string of the form ‘-rwxrwxrwx’.
>
> permission_bits()
>      This shall return ``stat.S_IMODE(self.st_mode)``.
>
> format()
>      This shall return ``stat.S_IFMT(self.st_mode)``.
>
Some of the names seem too long for me.

>
> Added functions in ``os.path``
> ------------------------------
>
> is_dir(f)
>      This shall be an alias for the existing isdir(f).
>
Do we really need 2 names for the same thing? No.

> is_character_device(f)
>      This shall return ``os.stat(f).is_character_device()``, or ``False`` if
>      ``f`` does not exist.
>
> is_block_device(f)
>      This shall return ``os.stat(f).is_block_device()``, or ``False`` if
>      ``f`` does not exist.
>
> is_file()
>      This shall be an alias for the existing isfile(f).
>
> is_fifo()
>      This shall return ``os.stat(f).is_fifo()``, or ``False`` if
>      ``f`` does not exist.
>
> is_symbolic_link()
>      This shall return ``os.stat(f).is_symbolic_link()``, or ``False`` if
>      ``f`` does not exist.
>
> is_socket()
>      This shall return ``os.stat(f).is_socket()``, or ``False`` if
>      ``f`` does not exist.
>
Some of the names seem too long for me.

>
> Rationale
> =========
>
> The PEP is strongly motivated by a desire for symmetry between functions in
> ``os.path`` and methods on ``stat_result``.
>
> Therefore, for each predicate function in ``os.path`` that is essentially
> just an interrogation of ``os.*stat()``, given an existing path, the
> similarly-named predicate method on ``stat_result`` should have the exact
> same semantics.
>
> This definition does not cover the case where the path being interrogated
> does not exist.  In those cases, predicate functions in ``os.path``, such
> as ``os.path.isfile()``, will return ``False``, whereas ``os.*stat()`` will
> raise FileNotFoundError even before any ``stat_result`` is returned that
> could have been interrogated.  This renders considerations of how the
> proposed new predicates on ``stat_result`` could have been symmetrical with
> functions in ``os.path``, if their ``stat_result`` had existed, moot, and
> this PEP does not propose doing anything about the situation (but see `Open
> Issues`_ below).
>
> Secondly, this definition refers to ‘similarly-named’ predicates instead of
> ‘identically-named’ predicates, because the names in ``os.path`` pre-date
> PEP 8 [#PEP-8]_, and are not compliant with it.  This PEP takes the
> position that it is better that the new predicate methods on
> ``stat_result`` be named in compliance with PEP 8 [#PEP-8]_ (i.e.
> ``is_file()``), than that they be precisely identical to the names in
> ``os.path`` (i.e ``isfile()``).  Note also that PEP 428 [#PEP-428]_ also
> specifies PEP-8 compliant names such as ``is_file()`` for the exact same
> concepts, and if PEP 428 [#PEP-428]_ should be accepted, the issue would be
> even more pertinent.
>
> Lastly, this PEP takes the notion of symmetry as far as adding methods and
> aliases to the existing ``os.path`` in order to be symmetrical with the
> added behaviour on ``stat_result``.  But the author is least strongly
> convicted of this latter point, and may be convinced to abandon it.
>
>
> Backwards Compatibility
> =======================
>
> This PEP neither removes current behavior of ``stat_result``, nor changes
> the semantics of any current behavior.  Likewise, it adds functions and
> aliases for functions to ``os.path``, but does not remove or change any
> existing ones.
>
> Therefore, this PEP should not cause any backwards incompatibilities,
> except in the rare and esoteric cases where code is dependent on the
> *nonexistence* of the proposed new names.  It is not deemed important
> remain compatible with code that mistakenly holds the Python Standard
> Library to be closed for new additions.
>
>
> Open Issues
> ===========
>
> Whether it is more desirable for the proposed added methods’ names to
> follow PEP 8 [#PEP-8]_ (i.e.  ``is_file()`` etc.), or to mirror the
> pre-existing names in ``os.path`` (i.e.  ``isfile()`` etc.) is still open
> for debate.
>
I think is best to follow PEP 8, except when there's an established
pattern, as there is for 'isfile', etc.

> The existing attributes on ``stat_result`` follow the pattern ``st_*`` in
> conformance to the relevant POSIX names for the fields of the C-level
> ``stat`` structure.  The new names for the behaviours proposed here do not
> contain such an ``st_`` prefix (nor could they, for that would suggest a
> conformance with ``stat`` structure names which do not exist in POSIX).
> But the resulting asymmetry of names is annoying.  Should aliases for the
> existing ``st_*`` names be added that omit the ``st_`` prefix?
>
Do we really need 2 names for the same thing? No.

> This PEP does not address a higher-lever mechanism for exposing the
> owner/group/other read/write/execute permissions.  Is there a need for
> this?
>
> This PEP does not address a higher-lever mechanism for exposing the of the
> underlying ``st_flags`` field.  Is there a need for this?
>
> This PEP proposes aliases and methods to make ``os.path`` conform more to
> the added ``stat_result`` methods proposed here.  But is the impedance
> mismatch between ``isfile`` and ``is_file`` really that much of an issue to
> warrant this?
>
> As it stands, this PEP does not address the asymmetry between the existing
> ``os.path.isfile()`` etc.  functions and the new proposed mechanism in the
> case where the underlying file does not exist.  There is a way to handle
> this, though: an optional flag could be added to ``os.*stat()`` that would
> return a null object implementation of ``stat_result`` whenever the file
> does not exist.  Then that null object could return ``False`` to
> ``is_file()`` etc., That means that the following code would behave
> identically, even when the file ``f`` does not exist::
>
>      if os.path.isfile(f) or os.path.isdir(f):
>          # do something
>
>      st = os.stat(f, null_if_missing=True)
>      if st.is_file() or st.is_dir():
>          # do something
>
> Would this be a useful mechanism?
>
I can see that it could be useful, but also possibly confusing (how can
you get the 'stat' of something that doesn't exist?).