Sync from upstream

Author: barneygale

CHANGES.rst

@@ -4,7 +4,13 @@ Version History
 Unreleased
 ----------
 
-- Nothing yet
+- Add ``vfspath()``, which returns the virtual filesystem path as a string.
+- Replace ``JoinablePath.__str__()`` abstract method with ``__vfspath__()``.
+- Rename ``magic_open()`` to ``vfsopen()``.
+- Replace ``ReadablePath.__open_rb__()`` abstract method with
+  ``__open_reader__()``, and remove *buffering* argument.
+- Replace ``WritablePath.__open_wb__()`` abstract method with
+  ``__open_writer__()``, and remove *buffering* and add *mode* arguments.
 
 v0.4.3
 ------

docs/api.rst

@@ -10,14 +10,20 @@ Functions
 
 This package offers the following functions:
 
-.. function:: magic_open(path, mode='r' buffering=-1, \
-                         encoding=None, errors=None, newline=None)
+.. function:: vfspath(obj)
 
-    Open the path and return a file object. Unlike the built-in ``open()``
-    function, this function tries to call :meth:`!__open_r__`,
-    :meth:`~ReadablePath.__open_rb__`, :meth:`!__open_w__`, and
-    :meth:`~WritablePath.__open_wb__` methods on the given path object as
-    appropriate for the given mode.
+    Return the virtual filesystem path (a string) of the given object. Unlike
+    the ``os.fspath()`` function, this function calls the object's
+    :meth:`~JoinablePath.__vfspath__` method.
+
+.. function:: vfsopen(obj, mode='r' buffering=-1, \
+                      encoding=None, errors=None, newline=None)
+
+    Open the given object and return a file object. Unlike the built-in
+    ``open()`` function, this function calls the object's
+    :meth:`~ReadablePath.__open_reader__`,
+    :meth:`~WritablePath.__open_writer__` or :meth:`!__open_updater__` method,
+    as appropriate for the given mode.
 
 
 Protocols
@@ -136,7 +142,7 @@ This package offers the following abstract base classes:
      *
      * :attr:`~JoinablePath.parser`
 
-       :meth:`~JoinablePath.__str__`
+       :meth:`~JoinablePath.__vfspath__`
 
        :meth:`~JoinablePath.with_segments`
      * :attr:`~JoinablePath.parts`
@@ -164,7 +170,7 @@ This package offers the following abstract base classes:
      * :class:`JoinablePath`
      * :attr:`~ReadablePath.info`
 
-       :meth:`~ReadablePath.__open_rb__`
+       :meth:`~ReadablePath.__open_reader__`
 
        :meth:`~ReadablePath.iterdir`
 
@@ -181,7 +187,7 @@ This package offers the following abstract base classes:
 
    - * :class:`WritablePath`
      * :class:`JoinablePath`
-     * :meth:`~WritablePath.__open_wb__`
+     * :meth:`~WritablePath.__open_writer__`
 
        :meth:`~WritablePath.mkdir`
 
@@ -201,7 +207,7 @@ This package offers the following abstract base classes:
       (**Abstract attribute**.) Implementation of :class:`PathParser` used for
       low-level splitting and joining.
 
-   .. method:: __str__()
+   .. method:: __vfspath__()
 
       (**Abstract method**.) Return a string representation of the path,
       suitable for passing to methods of the :attr:`parser`.
@@ -302,7 +308,7 @@ This package offers the following abstract base classes:
       (**Abstract attribute**.) Implementation of :class:`PathInfo` that
       supports querying the file type.
 
-   .. method:: __open_rb__(buffering=-1)
+   .. method:: __open_reader__()
 
       (**Abstract method.**) Open the path for reading in binary mode, and
       return a file object.
@@ -318,12 +324,12 @@ This package offers the following abstract base classes:
    .. method:: read_bytes()
 
       Return the binary contents of the path. The default implementation
-      calls :meth:`__open_rb__`.
+      calls :func:`vfsopen`.
 
    .. method:: read_text(encoding=None, errors=None, newline=None)
 
-      Return the text contents of the path. The default implementation calls
-      :meth:`!__open_r__` if it exists, falling back to :meth:`__open_rb__`.
+      Return the text contents of the path. The default implementation
+      calls :func:`vfsopen`.
 
    .. method:: copy(target, **kwargs)
 
@@ -364,10 +370,10 @@ This package offers the following abstract base classes:
    Abstract base class for path objects with support for writing data. This
    is a subclass of :class:`JoinablePath`
 
-   .. method:: __open_wb__(buffering=-1)
+   .. method:: __open_writer__(mode)
 
       (**Abstract method**.) Open the path for writing in binary mode, and
-      return a file object.
+      return a file object. The mode is either ``'w'`` or ``'a'``.
 
    .. method:: mkdir()
 
@@ -381,20 +387,19 @@ This package offers the following abstract base classes:
    .. method:: write_bytes(data)
 
       Write the given binary data to the path, and return the number of bytes
-      written. The default implementation calls :meth:`__open_wb__`.
+      written. The default implementation calls :func:`vfsopen`.
 
    .. method:: write_text(data, encoding=None, errors=None, newline=None)
 
       Write the given text data to the path, and return the number of bytes
-      written. The default implementation calls :meth:`!__open_w__` if it
-      exists, falling back to :meth:`__open_wb__`.
+      written. The default implementation calls :func:`vfsopen`.
 
    .. method:: _copy_from(source, *, follow_symlinks=True)
 
       Copy the path from the given source, which should be an instance of
       :class:`ReadablePath`. The default implementation uses
       :attr:`ReadablePath.info` to establish the type of the source path. It
-      uses :meth:`~ReadablePath.__open_rb__` and :meth:`__open_wb__` to copy
-      regular files; :meth:`~ReadablePath.iterdir` and :meth:`mkdir` to copy
-      directories; and :meth:`~ReadablePath.readlink` and :meth:`symlink_to`
-      to copy symlinks when *follow_symlinks* is false.
+      uses :func:`vfsopen` to copy regular files;
+      :meth:`~ReadablePath.iterdir` and :meth:`mkdir` to copy directories; and
+      :meth:`~ReadablePath.readlink` and :meth:`symlink_to` to copy symlinks
+      when *follow_symlinks* is false.

pathlib_abc/__init__.py

@@ -11,8 +11,10 @@
 
 
 from abc import ABC, abstractmethod
-from pathlib_abc._glob import _PathGlobber
-from pathlib_abc._os import magic_open, ensure_distinct_paths, ensure_different_files, copyfileobj
+from pathlib_abc._glob import _GlobberBase
+from pathlib_abc._os import (
+    copyfileobj, ensure_different_files,
+    ensure_distinct_paths, vfsopen, vfspath)
 from typing import Optional, Protocol, runtime_checkable
 try:
     from io import text_encoding
@@ -66,6 +68,25 @@ def is_file(self, *, follow_symlinks: bool = True) -> bool: ...
     def is_symlink(self) -> bool: ...
 
 
+class _PathGlobber(_GlobberBase):
+    """Provides shell-style pattern matching and globbing for ReadablePath.
+    """
+
+    @staticmethod
+    def lexists(path):
+        return path.info.exists(follow_symlinks=False)
+
+    @staticmethod
+    def scandir(path):
+        return ((child.info, child.name, child) for child in path.iterdir())
+
+    @staticmethod
+    def concat_path(path, text):
+        return path.with_segments(vfspath(path) + text)
+
+    stringify_path = staticmethod(vfspath)
+
+
 class JoinablePath(ABC):
     """Abstract base class for pure path objects.
 
@@ -92,20 +113,19 @@ def with_segments(self, *pathsegments):
         raise NotImplementedError
 
     @abstractmethod
-    def __str__(self):
-        """Return the string representation of the path, suitable for
-        passing to system calls."""
+    def __vfspath__(self):
+        """Return the string representation of the path."""
         raise NotImplementedError
 
     @property
     def anchor(self):
         """The concatenation of the drive and root, or ''."""
-        return _explode_path(str(self), self.parser.split)[0]
+        return _explode_path(vfspath(self), self.parser.split)[0]
 
     @property
     def name(self):
         """The final path component, if any."""
-        return self.parser.split(str(self))[1]
+        return self.parser.split(vfspath(self))[1]
 
     @property
     def suffix(self):
@@ -141,7 +161,7 @@ def with_name(self, name):
         split = self.parser.split
         if split(name)[0]:
             raise ValueError(f"Invalid name {name!r}")
-        path = str(self)
+        path = vfspath(self)
         path = path.removesuffix(split(path)[1]) + name
         return self.with_segments(path)
 
@@ -174,7 +194,7 @@ def with_suffix(self, suffix):
     def parts(self):
         """An object providing sequence-like access to the
         components in the filesystem path."""
-        anchor, parts = _explode_path(str(self), self.parser.split)
+        anchor, parts = _explode_path(vfspath(self), self.parser.split)
         if anchor:
             parts.append(anchor)
         return tuple(reversed(parts))
@@ -185,24 +205,24 @@ def joinpath(self, *pathsegments):
         paths) or a totally different path (if one of the arguments is
         anchored).
         """
-        return self.with_segments(str(self), *pathsegments)
+        return self.with_segments(vfspath(self), *pathsegments)
 
     def __truediv__(self, key):
         try:
-            return self.with_segments(str(self), key)
+            return self.with_segments(vfspath(self), key)
         except TypeError:
             return NotImplemented
 
     def __rtruediv__(self, key):
         try:
-            return self.with_segments(key, str(self))
+            return self.with_segments(key, vfspath(self))
         except TypeError:
             return NotImplemented
 
     @property
     def parent(self):
         """The logical parent of the path."""
-        path = str(self)
+        path = vfspath(self)
         parent = self.parser.split(path)[0]
         if path != parent:
             return self.with_segments(parent)
@@ -212,7 +232,7 @@ def parent(self):
     def parents(self):
         """A sequence of this path's logical parents."""
         split = self.parser.split
-        path = str(self)
+        path = vfspath(self)
         parent = split(path)[0]
         parents = []
         while path != parent:
@@ -229,7 +249,7 @@ def full_match(self, pattern):
         case_sensitive = self.parser.normcase('Aa') == 'Aa'
         globber = _PathGlobber(self.parser.sep, case_sensitive, recursive=True)
         match = globber.compile(pattern, altsep=self.parser.altsep)
-        return match(str(self)) is not None
+        return match(vfspath(self)) is not None
 
 
 class ReadablePath(JoinablePath):
@@ -251,18 +271,18 @@ def info(self):
         raise NotImplementedError
 
     @abstractmethod
-    def __open_rb__(self, buffering=-1):
+    def __open_reader__(self):
         """
         Open the file pointed to by this path for reading in binary mode and
-        return a file object, like open(mode='rb').
+        return a file object.
         """
         raise NotImplementedError
 
     def read_bytes(self):
         """
         Open the file in bytes mode, read it, and close the file.
         """
-        with magic_open(self, mode='rb', buffering=0) as f:
+        with vfsopen(self, mode='rb') as f:
             return f.read()
 
     def read_text(self, encoding=None, errors=None, newline=None):
@@ -272,7 +292,7 @@ def read_text(self, encoding=None, errors=None, newline=None):
         # Call io.text_encoding() here to ensure any warning is raised at an
         # appropriate stack level.
         encoding = text_encoding(encoding)
-        with magic_open(self, mode='r', encoding=encoding, errors=errors, newline=newline) as f:
+        with vfsopen(self, mode='r', encoding=encoding, errors=errors, newline=newline) as f:
             return f.read()
 
     @abstractmethod
@@ -381,10 +401,10 @@ def mkdir(self):
         raise NotImplementedError
 
     @abstractmethod
-    def __open_wb__(self, buffering=-1):
+    def __open_writer__(self, mode):
         """
         Open the file pointed to by this path for writing in binary mode and
-        return a file object, like open(mode='wb').
+        return a file object.
         """
         raise NotImplementedError
 
@@ -394,7 +414,7 @@ def write_bytes(self, data):
         """
         # type-check for the buffer interface before truncating the file
         view = memoryview(data)
-        with magic_open(self, mode='wb') as f:
+        with vfsopen(self, mode='wb') as f:
             return f.write(view)
 
     def write_text(self, data, encoding=None, errors=None, newline=None):
@@ -407,7 +427,7 @@ def write_text(self, data, encoding=None, errors=None, newline=None):
         if not isinstance(data, str):
             raise TypeError('data must be str, not %s' %
                             data.__class__.__name__)
-        with magic_open(self, mode='w', encoding=encoding, errors=errors, newline=newline) as f:
+        with vfsopen(self, mode='w', encoding=encoding, errors=errors, newline=newline) as f:
             return f.write(data)
 
     def _copy_from(self, source, follow_symlinks=True):
@@ -418,16 +438,16 @@ def _copy_from(self, source, follow_symlinks=True):
         while stack:
             src, dst = stack.pop()
             if not follow_symlinks and src.info.is_symlink():
-                dst.symlink_to(str(src.readlink()), src.info.is_dir())
+                dst.symlink_to(vfspath(src.readlink()), src.info.is_dir())
             elif src.info.is_dir():
                 children = src.iterdir()
                 dst.mkdir()
                 for child in children:
                     stack.append((child, dst.joinpath(child.name)))
             else:
                 ensure_different_files(src, dst)
-                with magic_open(src, 'rb') as source_f:
-                    with magic_open(dst, 'wb') as target_f:
+                with vfsopen(src, 'rb') as source_f:
+                    with vfsopen(dst, 'wb') as target_f:
                         copyfileobj(source_f, target_f)