API Reference
=============


.. module:: pathlib_abc


Functions
---------

This package offers the following functions:

.. function:: vfspath(obj)

    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 additionally calls the object's
    :meth:`~ReadablePath.__open_reader__`,
    :meth:`~WritablePath.__open_writer__` or :meth:`!__open_updater__` method,
    as appropriate for the given mode.


Protocols
---------

This package offers the following protocols:

.. class:: PathParser

   Protocol for path parser objects, which split and join string paths.

   Subclasses of :class:`JoinablePath` should provide a path parser object as
   an attribute named :attr:`~JoinablePath.parser`.

   Path parsers provide a subset of the ``os.path`` API. Python itself
   provides the ``posixpath`` and ``ntpath`` modules, which can be assigned
   to :attr:`~JoinablePath.parser` to implement path objects with POSIX or
   Windows syntax.

   .. attribute:: sep

      Character used to separate path components.

   .. attribute:: altsep

      Alternative path separator character, or ``None``.

   .. method:: split(path)

      Split the path into a pair ``(head, tail)``, where *head* is
      everything before the final path separator, and *tail* is everything
      after. Either part may be empty.

      .. note::

         Trailing slashes are meaningful in ``posixpath`` and ``ntpath``, so
         ``P('foo/').parent`` is ``P('foo')``, and its
         :attr:`~JoinablePath.name` is the empty string.

   .. method:: splitext(name)

      Split the filename into a pair ``(stem, ext)``, where *ext* is a file
      extension beginning with a dot and containing at most one dot, and
      *stem* is everything before the extension.

   .. method:: normcase(path)

      Return the path with its case normalized.

      .. note::

         This method is used to detect case sensitivity in
         :meth:`JoinablePath.full_match` and :meth:`ReadablePath.glob`, where
         it's called with the string containing a mix of upper and lowercase
         letters. Case-sensitive filesystems should return the string
         unchanged, whereas case-insensitive filesystems should return the
         string with its case modified (e.g. with ``upper()`` or ``lower()``.)


.. class:: PathInfo

   Protocol for path information objects, which provide file type info.

   Subclasses of :class:`ReadablePath` should provide a path information
   object as an attribute named :attr:`~ReadablePath.info`.

   .. method:: exists(*, follow_symlinks=True)

      Return ``True`` if the path is an existing file or directory, or any
      other kind of file; return ``False`` if the path doesn't exist.

      If *follow_symlinks* is ``False``, return ``True`` for symlinks without
      checking if their targets exist.

   .. method:: is_dir(*, follow_symlinks=True)

      Return ``True`` if the path is a directory, or a symbolic link pointing
      to a directory; return ``False`` if the path is (or points to) any other
      kind of file, or if it doesn't exist.

      If *follow_symlinks* is ``False``, return ``True`` only if the path
      is a directory (without following symlinks); return ``False`` if the
      path is any other kind of file, or if it doesn't exist.

   .. method:: is_file(*, follow_symlinks=True)

      Return ``True`` if the path is a file, or a symbolic link pointing to
      a file; return ``False`` if the path is (or points to) a directory or
      other non-file, or if it doesn't exist.

      If *follow_symlinks* is ``False``, return ``True`` only if the path
      is a file (without following symlinks); return ``False`` if the path
      is a directory or other other non-file, or if it doesn't exist.

   .. method:: is_symlink()

      Return ``True`` if the path is a symbolic link (even if broken); return
      ``False`` if the path is a directory or any kind of file, or if it
      doesn't exist.


Abstract base classes
---------------------

This package offers the following abstract base classes:

.. list-table::
   :header-rows: 1

   - * ABC
     * Inherits from
     * Abstract methods
     * Mixin methods

   - * :class:`JoinablePath`
     *
     * :attr:`~JoinablePath.parser`

       :meth:`~JoinablePath.__vfspath__`

       :meth:`~JoinablePath.with_segments`
     * :attr:`~JoinablePath.parts`
       :attr:`~JoinablePath.anchor`

       :attr:`~JoinablePath.parent`
       :attr:`~JoinablePath.parents`

       :attr:`~JoinablePath.name`
       :attr:`~JoinablePath.stem`
       :attr:`~JoinablePath.suffix`
       :attr:`~JoinablePath.suffixes`

       :meth:`~JoinablePath.with_name`
       :meth:`~JoinablePath.with_stem`
       :meth:`~JoinablePath.with_suffix`

       :meth:`~JoinablePath.joinpath`
       :meth:`~JoinablePath.__truediv__`
       :meth:`~JoinablePath.__rtruediv__`

       :meth:`~JoinablePath.relative_to`
       :meth:`~JoinablePath.is_relative_to`

       :meth:`~JoinablePath.full_match`

   - * :class:`ReadablePath`
     * :class:`JoinablePath`
     * :attr:`~ReadablePath.info`

       :meth:`~ReadablePath.__open_reader__`

       :meth:`~ReadablePath.iterdir`

       :meth:`~ReadablePath.readlink`
     * :meth:`~ReadablePath.read_bytes`
       :meth:`~ReadablePath.read_text`

       :meth:`~ReadablePath.copy`
       :meth:`~ReadablePath.copy_into`

       :meth:`~ReadablePath.glob`

       :meth:`~ReadablePath.walk`

   - * :class:`WritablePath`
     * :class:`JoinablePath`
     * :meth:`~WritablePath.__open_writer__`

       :meth:`~WritablePath.mkdir`

       :meth:`~WritablePath.symlink_to`
     * :meth:`~WritablePath.write_bytes`
       :meth:`~WritablePath.write_text`

       :meth:`~WritablePath._copy_from`


.. class:: JoinablePath

   Abstract base class for path objects without I/O support.

   .. attribute:: parser

      (**Abstract attribute**.) Implementation of :class:`PathParser` used for
      low-level splitting and joining.

   .. method:: __vfspath__()

      (**Abstract method**.) Return a string representation of the path,
      suitable for passing to methods of the :attr:`parser`.

   .. method:: with_segments(*pathsegments)

      (**Abstract method**.) Create a new path object of the same type by
      combining the given *pathsegments*. This method is called whenever a
      derivative path is created, such as from :attr:`parent` and
      :meth:`with_name`.

   .. attribute:: parts

      Tuple of path components. The default implementation repeatedly calls
      :meth:`PathParser.split` to decompose the path.

   .. attribute:: anchor

      The path's irreducible prefix. The default implementation repeatedly
      calls :meth:`PathParser.split` until the directory name stops changing.

   .. attribute:: parent

      The path's lexical parent. The default implementation calls
      :meth:`PathParser.split` once.

   .. attribute:: parents

      Sequence of the path's lexical parents, beginning with the immediate
      parent. The default implementation repeatedly calls
      :meth:`PathParser.split`.

   .. attribute:: name

      The path's base name. The name is empty if the path has only an anchor,
      or ends with a slash. The default implementation calls
      :meth:`PathParser.split` once.

   .. attribute:: stem

      The path's base name with the file extension omitted. The default
      implementation calls :meth:`PathParser.splitext` on :attr:`name`.

   .. attribute:: suffix

      The path's file extension. The default implementation calls
      :meth:`PathParser.splitext` on :attr:`name`.

   .. attribute:: suffixes

      Sequence of the path's file extensions. The default implementation
      repeatedly calls :meth:`PathParser.splitext` on :attr:`name`.

   .. method:: with_name(name)

      Return a new path with a different :attr:`name`. The name may be empty.
      The default implementation calls :meth:`PathParser.split` to remove the
      old name, and :meth:`with_segments` to create the new path object.

   .. method:: with_stem(stem)

      Return a new path with a different :attr:`stem`, similarly to
      :meth:`with_name`.

   .. method:: with_suffix(suffix)

      Return a new path with a different :attr:`suffix`, similarly to
      :meth:`with_name`.

   .. method:: joinpath(*pathsegments)

      Return a new path with the given path segments joined onto the end. The
      default implementation calls :meth:`with_segments` with the combined
      segments.

   .. method:: __truediv__(pathsegment)

      Return a new path with the given path segment joined on the end.

   .. method:: __rtruediv__(pathsegment)

      Return a new path with the given path segment joined on the beginning.

   .. method:: relative_to(other, *, walk_up=False)

      Return a new relative path from *other* to this path. The default
      implementation compares this path and the parents of *other*;
      ``__eq__()`` must be implemented for this to work correctly.

   .. method:: is_relative_to(other)

      Returns ``True`` is this path is relative to *other*, ``False``
      otherwise. The default implementation compares this path and the parents
      of *other*; ``__eq__()`` must be implemented for this to work correctly.

   .. method:: full_match(pattern)

      Return true if the path matches the given glob-style pattern, false
      otherwise. The default implementation uses :meth:`PathParser.normcase`
      to establish case sensitivity.


.. class:: ReadablePath

   Abstract base class for path objects with support for reading data. This
   is a subclass of :class:`JoinablePath`

   .. attribute:: info

      (**Abstract attribute**.) Implementation of :class:`PathInfo` that
      supports querying the file type.

   .. method:: __open_reader__()

      (**Abstract method.**) Open the path for reading in binary mode, and
      return a file object.

   .. method:: iterdir()

      (**Abstract method**.) Yield path objects for the directory contents.

   .. method:: readlink()

      (**Abstract method**.) Return the symlink target as a new path object.

   .. method:: read_bytes()

      Return the binary contents of the path. The default implementation
      calls :func:`vfsopen`.

   .. method:: read_text(encoding=None, errors=None, newline=None)

      Return the text contents of the path. The default implementation
      calls :func:`vfsopen`.

   .. method:: copy(target, **kwargs)

      Copy the path to the given target, which should be an instance of
      :class:`WritablePath`. The default implementation calls
      :meth:`WritablePath._copy_from`, passing along keyword arguments.

   .. method:: copy_into(target_dir, **kwargs)

      Copy the path *into* the given target directory, which should be an
      instance of :class:`WritablePath`. See :meth:`copy`.

   .. method:: glob(pattern, *, recurse_symlinks=True)

      Yield path objects in the file tree that match the given glob-style
      pattern. The default implementation uses :attr:`info` and
      :meth:`iterdir`.

      .. warning::

         For performance reasons, the default value for *recurse_symlinks* is
         ``True`` in this base class, but for historical reasons, the default
         is ``False`` in ``pathlib.Path``. Furthermore, ``True`` is the *only*
         acceptable value for *recurse_symlinks* in this base class.

         For maximum compatibility, users should supply
         ``recurse_symlinks=True`` explicitly when globbing recursively.

   .. method:: walk(top_down=True, on_error=None, follow_symlinks=False)

      Yield a ``(dirpath, dirnames, filenames)`` triplet for each directory
      in the file tree, like ``os.walk()``. The default implementation uses
      :attr:`info` and :meth:`iterdir`.


.. class:: WritablePath

   Abstract base class for path objects with support for writing data. This
   is a subclass of :class:`JoinablePath`

   .. method:: __open_writer__(mode)

      (**Abstract method**.) Open the path for writing in binary mode, and
      return a file object. The *mode* argument is either ``'w'``, ``'a'``,
      or ``'x'``.

   .. method:: mkdir()

      (**Abstract method**.) Create this path as a directory.

   .. method:: symlink_to(target, target_is_directory=False)

      (**Abstract method**.) Create this path as a symlink to the given
      target.

   .. method:: write_bytes(data)

      Write the given binary data to the path, and return the number of bytes
      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 :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 :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.