"pathlib" --- Object-oriented filesystem paths
**********************************************

在 3.4 版新加入.

**原始碼：**Lib/pathlib.py

======================================================================

這個模組提供了涵蓋不同作業系統中語義對等的檔案路徑類別（class）。路徑
類別被分為純路徑及具體路徑兩種，純路徑提供純粹的計算操作而不涉及輸入輸
出（I/O），而具體路徑則繼承自純路徑，同時提供輸入輸出操作。

[圖片]

If you've never used this module before or just aren't sure which
class is right for your task, "Path" is most likely what you need. It
instantiates a concrete path for the platform the code is running on.

Pure paths are useful in some special cases; for example:

1. If you want to manipulate Windows paths on a Unix machine (or vice
   versa). You cannot instantiate a "WindowsPath" when running on
   Unix, but you can instantiate "PureWindowsPath".

2. You want to make sure that your code only manipulates paths without
   actually accessing the OS. In this case, instantiating one of the
   pure classes may be useful since those simply don't have any OS-
   accessing operations.

也參考:

  **PEP 428**: The pathlib module -- object-oriented filesystem paths.

也參考:

  For low-level path manipulation on strings, you can also use the
  "os.path" module.


Basic use
=========

Importing the main class:

   >>> from pathlib import Path

Listing subdirectories:

   >>> p = Path('.')
   >>> [x for x in p.iterdir() if x.is_dir()]
   [PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
    PosixPath('__pycache__'), PosixPath('build')]

Listing Python source files in this directory tree:

   >>> list(p.glob('**/*.py'))
   [PosixPath('test_pathlib.py'), PosixPath('setup.py'),
    PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
    PosixPath('build/lib/pathlib.py')]

Navigating inside a directory tree:

   >>> p = Path('/etc')
   >>> q = p / 'init.d' / 'reboot'
   >>> q
   PosixPath('/etc/init.d/reboot')
   >>> q.resolve()
   PosixPath('/etc/rc.d/init.d/halt')

Querying path properties:

   >>> q.exists()
   True
   >>> q.is_dir()
   False

Opening a file:

   >>> with q.open() as f: f.readline()
   ...
   '#!/bin/bash\n'


純路徑
======

純路徑物件提供處理路徑的操作，實際上不會存取檔案系統。有三種方法可以存
取這些類別 (class)，我們也稱之為*類型*：

class pathlib.PurePath(*pathsegments)

   一個通用的類別，表示系統的路徑類型（實例化時會建立一個
   "PurePosixPath" 或 "PureWindowsPath")：

      >>> PurePath('setup.py')      # Running on a Unix machine
      PurePosixPath('setup.py')

   *pathsegments* 中的每個元素可以是以下三種的其中一種：一個表示路徑片
   段的字串、實作了 "os.PathLike" 介面 (interface) 並回傳字串的物件，
   或者另一個路徑物件：

      >>> PurePath('foo', 'some/path', 'bar')
      PurePosixPath('foo/some/path/bar')
      >>> PurePath(Path('foo'), Path('bar'))
      PurePosixPath('foo/bar')

   當 *pathsegments* 是空的時候，預設使用目前的目錄：

      >>> PurePath()
      PurePosixPath('.')

   如果一個片段是絕對路徑，則所有先前的片段將被忽略（類似於
   "os.path.join()")：

      >>> PurePath('/etc', '/usr', 'lib64')
      PurePosixPath('/usr/lib64')
      >>> PureWindowsPath('c:/Windows', 'd:bar')
      PureWindowsPath('d:bar')

   在 Windows 系統上，當遇到具有根目錄的相對路徑片段（例如 "r'\foo'"）
   時，磁碟機 (drive) 部分不會被重置：

      >>> PureWindowsPath('c:/Windows', '/Program Files')
      PureWindowsPath('c:/Program Files')

   不必要的斜線和單點會被合併，但雙點 ("'..'") 和前置的雙斜線 ("'//'")
   不會被合併，因為這樣會因為各種原因改變路徑的意義（例如符號連結
   (symbolic links)、UNC 路徑）：

      >>> PurePath('foo//bar')
      PurePosixPath('foo/bar')
      >>> PurePath('//foo/bar')
      PurePosixPath('//foo/bar')
      >>> PurePath('foo/./bar')
      PurePosixPath('foo/bar')
      >>> PurePath('foo/../bar')
      PurePosixPath('foo/../bar')

   （一個使得 "PurePosixPath('foo/../bar')" 等同於
   "PurePosixPath('bar')" 的單純方法，但如果 "foo" 是一個目錄的符號連
   結，這是錯誤的。）

   純路徑物件實作了 "os.PathLike" 介面，使得它們可以在任何接受該介面的
   地方使用。

   在 3.6 版的變更: 新增了對於 "os.PathLike" 介面的支援。

class pathlib.PurePosixPath(*pathsegments)

   "PurePath" 的一個子類別 (subclass)，該路徑類型表示非 Windows 檔案系
   統的路徑：

      >>> PurePosixPath('/etc')
      PurePosixPath('/etc')

   *pathsegments* 的指定方式與 "PurePath" 類似。

class pathlib.PureWindowsPath(*pathsegments)

   "PurePath" 的一個子類別，該路徑類型表示 Windows 檔案系統的路徑，包
   括  UNC paths：

      >>> PureWindowsPath('c:/Program Files/')
      PureWindowsPath('c:/Program Files')
      >>> PureWindowsPath('//server/share/file')
      PureWindowsPath('//server/share/file')

   *pathsegments* 的指定方式與 "PurePath" 類似。

不論你使用的是什麼系統，你都可以實例化這些類別，因為它們不提供任何涉及
系統呼叫 (system calls) 的操作。


通用特性
--------

路徑物件是不可變 (immutable) 且 *hashable* （可雜湊）的。相同類型的路
徑物件可以被比較和排序。這些特性遵守該類型的大小寫規則：

   >>> PurePosixPath('foo') == PurePosixPath('FOO')
   False
   >>> PureWindowsPath('foo') == PureWindowsPath('FOO')
   True
   >>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
   True
   >>> PureWindowsPath('C:') < PureWindowsPath('d:')
   True

不同類型的路徑物件在比較時視為不相等且無法被排序：

   >>> PureWindowsPath('foo') == PurePosixPath('foo')
   False
   >>> PureWindowsPath('foo') < PurePosixPath('foo')
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
   TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'


運算子
------

斜線運算子（slash operator）用於建立子路徑，就像是 "os.path.join()" 函
式一樣。如果引數是絕對路徑，則忽略前一個路徑。在 Windows 系統上，當引
數是以根目錄為基礎的相對路徑（例如，"r’\foo’"），磁碟路徑不會被重置：

   >>> p = PurePath('/etc')
   >>> p
   PurePosixPath('/etc')
   >>> p / 'init.d' / 'apache2'
   PurePosixPath('/etc/init.d/apache2')
   >>> q = PurePath('bin')
   >>> '/usr' / q
   PurePosixPath('/usr/bin')
   >>> p / '/an_absolute_path'
   PurePosixPath('/an_absolute_path')
   >>> PureWindowsPath('c:/Windows', '/Program Files')
   PureWindowsPath('c:/Program Files')

路徑物件可以被用在任何可以使用 "os.PathLike" 的地方：

   >>> import os
   >>> p = PurePath('/etc')
   >>> os.fspath(p)
   '/etc'

The string representation of a path is the raw filesystem path itself
(in native form, e.g. with backslashes under Windows), which you can
pass to any function taking a file path as a string:

   >>> p = PurePath('/etc')
   >>> str(p)
   '/etc'
   >>> p = PureWindowsPath('c:/Program Files')
   >>> str(p)
   'c:\\Program Files'

Similarly, calling "bytes" on a path gives the raw filesystem path as
a bytes object, as encoded by "os.fsencode()":

   >>> bytes(p)
   b'/etc'

備註:

  Calling "bytes" is only recommended under Unix.  Under Windows, the
  unicode form is the canonical representation of filesystem paths.


Accessing individual parts
--------------------------

To access the individual "parts" (components) of a path, use the
following property:

PurePath.parts

   A tuple giving access to the path's various components:

      >>> p = PurePath('/usr/bin/python3')
      >>> p.parts
      ('/', 'usr', 'bin', 'python3')

      >>> p = PureWindowsPath('c:/Program Files/PSF')
      >>> p.parts
      ('c:\\', 'Program Files', 'PSF')

   (note how the drive and local root are regrouped in a single part)


Methods and properties
----------------------

Pure paths provide the following methods and properties:

PurePath.drive

   A string representing the drive letter or name, if any:

      >>> PureWindowsPath('c:/Program Files/').drive
      'c:'
      >>> PureWindowsPath('/Program Files/').drive
      ''
      >>> PurePosixPath('/etc').drive
      ''

   UNC shares are also considered drives:

      >>> PureWindowsPath('//host/share/foo.txt').drive
      '\\\\host\\share'

PurePath.root

   A string representing the (local or global) root, if any:

      >>> PureWindowsPath('c:/Program Files/').root
      '\\'
      >>> PureWindowsPath('c:Program Files/').root
      ''
      >>> PurePosixPath('/etc').root
      '/'

   UNC shares always have a root:

      >>> PureWindowsPath('//host/share').root
      '\\'

   If the path starts with more than two successive slashes,
   "PurePosixPath" collapses them:

      >>> PurePosixPath('//etc').root
      '//'
      >>> PurePosixPath('///etc').root
      '/'
      >>> PurePosixPath('////etc').root
      '/'

   備註:

     This behavior conforms to *The Open Group Base Specifications
     Issue 6*, paragraph 4.11 Pathname Resolution:*"A pathname that
     begins with two successive slashes may be interpreted in an
     implementation-defined manner, although more than two leading
     slashes shall be treated as a single slash."*

PurePath.anchor

   The concatenation of the drive and root:

      >>> PureWindowsPath('c:/Program Files/').anchor
      'c:\\'
      >>> PureWindowsPath('c:Program Files/').anchor
      'c:'
      >>> PurePosixPath('/etc').anchor
      '/'
      >>> PureWindowsPath('//host/share').anchor
      '\\\\host\\share\\'

PurePath.parents

   An immutable sequence providing access to the logical ancestors of
   the path:

      >>> p = PureWindowsPath('c:/foo/bar/setup.py')
      >>> p.parents[0]
      PureWindowsPath('c:/foo/bar')
      >>> p.parents[1]
      PureWindowsPath('c:/foo')
      >>> p.parents[2]
      PureWindowsPath('c:/')

   在 3.10 版的變更: The parents sequence now supports *slices* and
   negative index values.

PurePath.parent

   The logical parent of the path:

      >>> p = PurePosixPath('/a/b/c/d')
      >>> p.parent
      PurePosixPath('/a/b/c')

   You cannot go past an anchor, or empty path:

      >>> p = PurePosixPath('/')
      >>> p.parent
      PurePosixPath('/')
      >>> p = PurePosixPath('.')
      >>> p.parent
      PurePosixPath('.')

   備註:

     This is a purely lexical operation, hence the following
     behaviour:

        >>> p = PurePosixPath('foo/..')
        >>> p.parent
        PurePosixPath('foo')

     If you want to walk an arbitrary filesystem path upwards, it is
     recommended to first call "Path.resolve()" so as to resolve
     symlinks and eliminate "".."" components.

PurePath.name

   A string representing the final path component, excluding the drive
   and root, if any:

      >>> PurePosixPath('my/library/setup.py').name
      'setup.py'

   UNC drive names are not considered:

      >>> PureWindowsPath('//some/share/setup.py').name
      'setup.py'
      >>> PureWindowsPath('//some/share').name
      ''

PurePath.suffix

   The file extension of the final component, if any:

      >>> PurePosixPath('my/library/setup.py').suffix
      '.py'
      >>> PurePosixPath('my/library.tar.gz').suffix
      '.gz'
      >>> PurePosixPath('my/library').suffix
      ''

PurePath.suffixes

   A list of the path's file extensions:

      >>> PurePosixPath('my/library.tar.gar').suffixes
      ['.tar', '.gar']
      >>> PurePosixPath('my/library.tar.gz').suffixes
      ['.tar', '.gz']
      >>> PurePosixPath('my/library').suffixes
      []

PurePath.stem

   The final path component, without its suffix:

      >>> PurePosixPath('my/library.tar.gz').stem
      'library.tar'
      >>> PurePosixPath('my/library.tar').stem
      'library'
      >>> PurePosixPath('my/library').stem
      'library'

PurePath.as_posix()

   Return a string representation of the path with forward slashes
   ("/"):

      >>> p = PureWindowsPath('c:\\windows')
      >>> str(p)
      'c:\\windows'
      >>> p.as_posix()
      'c:/windows'

PurePath.as_uri()

   Represent the path as a "file" URI.  "ValueError" is raised if the
   path isn't absolute.

   >>> p = PurePosixPath('/etc/passwd')
   >>> p.as_uri()
   'file:///etc/passwd'
   >>> p = PureWindowsPath('c:/Windows')
   >>> p.as_uri()
   'file:///c:/Windows'

PurePath.is_absolute()

   Return whether the path is absolute or not.  A path is considered
   absolute if it has both a root and (if the flavour allows) a drive:

      >>> PurePosixPath('/a/b').is_absolute()
      True
      >>> PurePosixPath('a/b').is_absolute()
      False

      >>> PureWindowsPath('c:/a/b').is_absolute()
      True
      >>> PureWindowsPath('/a/b').is_absolute()
      False
      >>> PureWindowsPath('c:').is_absolute()
      False
      >>> PureWindowsPath('//some/share').is_absolute()
      True

PurePath.is_relative_to(*other)

   Return whether or not this path is relative to the *other* path.

   >>> p = PurePath('/etc/passwd')
   >>> p.is_relative_to('/etc')
   True
   >>> p.is_relative_to('/usr')
   False

   If multiple arguments are supplied, they are joined together.

   This method is string-based; it neither accesses the filesystem nor
   treats "".."" segments specially. The following code is equivalent:

   >>> u = PurePath('/usr')
   >>> u == p or u in p.parents
   False

   在 3.9 版新加入.

PurePath.is_reserved()

   With "PureWindowsPath", return "True" if the path is considered
   reserved under Windows, "False" otherwise.  With "PurePosixPath",
   "False" is always returned.

   >>> PureWindowsPath('nul').is_reserved()
   True
   >>> PurePosixPath('nul').is_reserved()
   False

   File system calls on reserved paths can fail mysteriously or have
   unintended effects.

PurePath.joinpath(*other)

   Calling this method is equivalent to combining the path with each
   of the *other* arguments in turn:

      >>> PurePosixPath('/etc').joinpath('passwd')
      PurePosixPath('/etc/passwd')
      >>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
      PurePosixPath('/etc/passwd')
      >>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
      PurePosixPath('/etc/init.d/apache2')
      >>> PureWindowsPath('c:').joinpath('/Program Files')
      PureWindowsPath('c:/Program Files')

PurePath.match(pattern)

   Match this path against the provided glob-style pattern.  Return
   "True" if matching is successful, "False" otherwise.

   If *pattern* is relative, the path can be either relative or
   absolute, and matching is done from the right:

      >>> PurePath('a/b.py').match('*.py')
      True
      >>> PurePath('/a/b/c.py').match('b/*.py')
      True
      >>> PurePath('/a/b/c.py').match('a/*.py')
      False

   If *pattern* is absolute, the path must be absolute, and the whole
   path must match:

      >>> PurePath('/a.py').match('/*.py')
      True
      >>> PurePath('a/b.py').match('/*.py')
      False

   As with other methods, case-sensitivity follows platform defaults:

      >>> PurePosixPath('b.py').match('*.PY')
      False
      >>> PureWindowsPath('b.py').match('*.PY')
      True

PurePath.relative_to(*other)

   Compute a version of this path relative to the path represented by
   *other*.  If it's impossible, ValueError is raised:

      >>> p = PurePosixPath('/etc/passwd')
      >>> p.relative_to('/')
      PurePosixPath('etc/passwd')
      >>> p.relative_to('/etc')
      PurePosixPath('passwd')
      >>> p.relative_to('/usr')
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        File "pathlib.py", line 694, in relative_to
          .format(str(self), str(formatted)))
      ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other absolute.

   If multiple arguments are supplied, they are joined together.

   NOTE: This function is part of "PurePath" and works with strings.
   It does not check or access the underlying file structure.

PurePath.with_name(name)

   Return a new path with the "name" changed.  If the original path
   doesn't have a name, ValueError is raised:

      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
      >>> p.with_name('setup.py')
      PureWindowsPath('c:/Downloads/setup.py')
      >>> p = PureWindowsPath('c:/')
      >>> p.with_name('setup.py')
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
          raise ValueError("%r has an empty name" % (self,))
      ValueError: PureWindowsPath('c:/') has an empty name

PurePath.with_stem(stem)

   Return a new path with the "stem" changed.  If the original path
   doesn't have a name, ValueError is raised:

      >>> p = PureWindowsPath('c:/Downloads/draft.txt')
      >>> p.with_stem('final')
      PureWindowsPath('c:/Downloads/final.txt')
      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
      >>> p.with_stem('lib')
      PureWindowsPath('c:/Downloads/lib.gz')
      >>> p = PureWindowsPath('c:/')
      >>> p.with_stem('')
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
        File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
          return self.with_name(stem + self.suffix)
        File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
          raise ValueError("%r has an empty name" % (self,))
      ValueError: PureWindowsPath('c:/') has an empty name

   在 3.9 版新加入.

PurePath.with_suffix(suffix)

   Return a new path with the "suffix" changed.  If the original path
   doesn't have a suffix, the new *suffix* is appended instead.  If
   the *suffix* is an empty string, the original suffix is removed:

      >>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
      >>> p.with_suffix('.bz2')
      PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
      >>> p = PureWindowsPath('README')
      >>> p.with_suffix('.txt')
      PureWindowsPath('README.txt')
      >>> p = PureWindowsPath('README.txt')
      >>> p.with_suffix('')
      PureWindowsPath('README')


Concrete paths
==============

Concrete paths are subclasses of the pure path classes.  In addition
to operations provided by the latter, they also provide methods to do
system calls on path objects.  There are three ways to instantiate
concrete paths:

class pathlib.Path(*pathsegments)

   A subclass of "PurePath", this class represents concrete paths of
   the system's path flavour (instantiating it creates either a
   "PosixPath" or a "WindowsPath"):

      >>> Path('setup.py')
      PosixPath('setup.py')

   *pathsegments* 的指定方式與 "PurePath" 類似。

class pathlib.PosixPath(*pathsegments)

   A subclass of "Path" and "PurePosixPath", this class represents
   concrete non-Windows filesystem paths:

      >>> PosixPath('/etc')
      PosixPath('/etc')

   *pathsegments* 的指定方式與 "PurePath" 類似。

class pathlib.WindowsPath(*pathsegments)

   A subclass of "Path" and "PureWindowsPath", this class represents
   concrete Windows filesystem paths:

      >>> WindowsPath('c:/Program Files/')
      WindowsPath('c:/Program Files')

   *pathsegments* 的指定方式與 "PurePath" 類似。

You can only instantiate the class flavour that corresponds to your
system (allowing system calls on non-compatible path flavours could
lead to bugs or failures in your application):

   >>> import os
   >>> os.name
   'posix'
   >>> Path('setup.py')
   PosixPath('setup.py')
   >>> PosixPath('setup.py')
   PosixPath('setup.py')
   >>> WindowsPath('setup.py')
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File "pathlib.py", line 798, in __new__
       % (cls.__name__,))
   NotImplementedError: cannot instantiate 'WindowsPath' on your system


Methods
-------

Concrete paths provide the following methods in addition to pure paths
methods.  Many of these methods can raise an "OSError" if a system
call fails (for example because the path doesn't exist).

在 3.8 版的變更: "exists()", "is_dir()", "is_file()", "is_mount()",
"is_symlink()", "is_block_device()", "is_char_device()", "is_fifo()",
"is_socket()" now return "False" instead of raising an exception for
paths that contain characters unrepresentable at the OS level.

classmethod Path.cwd()

   Return a new path object representing the current directory (as
   returned by "os.getcwd()"):

      >>> Path.cwd()
      PosixPath('/home/antoine/pathlib')

classmethod Path.home()

   Return a new path object representing the user's home directory (as
   returned by "os.path.expanduser()" with "~" construct). If the home
   directory can't be resolved, "RuntimeError" is raised.

      >>> Path.home()
      PosixPath('/home/antoine')

   在 3.5 版新加入.

Path.stat(*, follow_symlinks=True)

   Return a "os.stat_result" object containing information about this
   path, like "os.stat()". The result is looked up at each call to
   this method.

   This method normally follows symlinks; to stat a symlink add the
   argument "follow_symlinks=False", or use "lstat()".

      >>> p = Path('setup.py')
      >>> p.stat().st_size
      956
      >>> p.stat().st_mtime
      1327883547.852554

   在 3.10 版的變更: 新增 *follow_symlinks* 參數。

Path.chmod(mode, *, follow_symlinks=True)

   Change the file mode and permissions, like "os.chmod()".

   This method normally follows symlinks. Some Unix flavours support
   changing permissions on the symlink itself; on these platforms you
   may add the argument "follow_symlinks=False", or use "lchmod()".

      >>> p = Path('setup.py')
      >>> p.stat().st_mode
      33277
      >>> p.chmod(0o444)
      >>> p.stat().st_mode
      33060

   在 3.10 版的變更: 新增 *follow_symlinks* 參數。

Path.exists()

   Whether the path points to an existing file or directory:

      >>> Path('.').exists()
      True
      >>> Path('setup.py').exists()
      True
      >>> Path('/etc').exists()
      True
      >>> Path('nonexistentfile').exists()
      False

   備註:

     If the path points to a symlink, "exists()" returns whether the
     symlink *points to* an existing file or directory.

Path.expanduser()

   Return a new path with expanded "~" and "~user" constructs, as
   returned by "os.path.expanduser()". If a home directory can't be
   resolved, "RuntimeError" is raised.

      >>> p = PosixPath('~/films/Monty Python')
      >>> p.expanduser()
      PosixPath('/home/eric/films/Monty Python')

   在 3.5 版新加入.

Path.glob(pattern)

   Glob the given relative *pattern* in the directory represented by
   this path, yielding all matching files (of any kind):

      >>> sorted(Path('.').glob('*.py'))
      [PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
      >>> sorted(Path('.').glob('*/*.py'))
      [PosixPath('docs/conf.py')]

   Patterns are the same as for "fnmatch", with the addition of ""**""
   which means "this directory and all subdirectories, recursively".
   In other words, it enables recursive globbing:

      >>> sorted(Path('.').glob('**/*.py'))
      [PosixPath('build/lib/pathlib.py'),
       PosixPath('docs/conf.py'),
       PosixPath('pathlib.py'),
       PosixPath('setup.py'),
       PosixPath('test_pathlib.py')]

   備註:

     Using the ""**"" pattern in large directory trees may consume an
     inordinate amount of time.

   引發一個附帶引數 "self"、"pattern" 的稽核事件 "pathlib.Path.glob"。

   在 3.11 版的變更: Return only directories if *pattern* ends with a
   pathname components separator ("sep" or "altsep").

Path.group()

   Return the name of the group owning the file.  "KeyError" is raised
   if the file's gid isn't found in the system database.

Path.is_dir()

   Return "True" if the path points to a directory (or a symbolic link
   pointing to a directory), "False" if it points to another kind of
   file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.is_file()

   Return "True" if the path points to a regular file (or a symbolic
   link pointing to a regular file), "False" if it points to another
   kind of file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.is_mount()

   Return "True" if the path is a *mount point*: a point in a file
   system where a different file system has been mounted.  On POSIX,
   the function checks whether *path*'s parent, "path/..", is on a
   different device than *path*, or whether "path/.." and *path* point
   to the same i-node on the same device --- this should detect mount
   points for all Unix and POSIX variants.  Not implemented on
   Windows.

   在 3.7 版新加入.

Path.is_symlink()

   Return "True" if the path points to a symbolic link, "False"
   otherwise.

   "False" is also returned if the path doesn't exist; other errors
   (such as permission errors) are propagated.

Path.is_socket()

   Return "True" if the path points to a Unix socket (or a symbolic
   link pointing to a Unix socket), "False" if it points to another
   kind of file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.is_fifo()

   Return "True" if the path points to a FIFO (or a symbolic link
   pointing to a FIFO), "False" if it points to another kind of file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.is_block_device()

   Return "True" if the path points to a block device (or a symbolic
   link pointing to a block device), "False" if it points to another
   kind of file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.is_char_device()

   Return "True" if the path points to a character device (or a
   symbolic link pointing to a character device), "False" if it points
   to another kind of file.

   "False" is also returned if the path doesn't exist or is a broken
   symlink; other errors (such as permission errors) are propagated.

Path.iterdir()

   When the path points to a directory, yield path objects of the
   directory contents:

      >>> p = Path('docs')
      >>> for child in p.iterdir(): child
      ...
      PosixPath('docs/conf.py')
      PosixPath('docs/_templates')
      PosixPath('docs/make.bat')
      PosixPath('docs/index.rst')
      PosixPath('docs/_build')
      PosixPath('docs/_static')
      PosixPath('docs/Makefile')

   The children are yielded in arbitrary order, and the special
   entries "'.'" and "'..'" are not included.  If a file is removed
   from or added to the directory after creating the iterator, whether
   a path object for that file be included is unspecified.

Path.lchmod(mode)

   Like "Path.chmod()" but, if the path points to a symbolic link, the
   symbolic link's mode is changed rather than its target's.

Path.lstat()

   Like "Path.stat()" but, if the path points to a symbolic link,
   return the symbolic link's information rather than its target's.

Path.mkdir(mode=0o777, parents=False, exist_ok=False)

   Create a new directory at this given path.  If *mode* is given, it
   is combined with the process' "umask" value to determine the file
   mode and access flags.  If the path already exists,
   "FileExistsError" is raised.

   If *parents* is true, any missing parents of this path are created
   as needed; they are created with the default permissions without
   taking *mode* into account (mimicking the POSIX "mkdir -p"
   command).

   If *parents* is false (the default), a missing parent raises
   "FileNotFoundError".

   If *exist_ok* is false (the default), "FileExistsError" is raised
   if the target directory already exists.

   If *exist_ok* is true, "FileExistsError" will not be raised unless
   the given path already exists in the file system and is not a
   directory (same behavior as the POSIX "mkdir -p" command).

   在 3.5 版的變更: 新增 *exist_ok* 參數。

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

   Open the file pointed to by the path, like the built-in "open()"
   function does:

      >>> p = Path('setup.py')
      >>> with p.open() as f:
      ...     f.readline()
      ...
      '#!/usr/bin/env python3\n'

Path.owner()

   回傳擁有該檔案的用戶的名稱。如果在系統資料庫中找不到該檔案的 uid ，
   則會引發 "KeyError"。

Path.read_bytes()

   將指向檔案的二進制內容以一個位元組 (bytes) 物件回傳：

      >>> p = Path('my_binary_file')
      >>> p.write_bytes(b'Binary file contents')
      20
      >>> p.read_bytes()
      b'Binary file contents'

   在 3.5 版新加入.

Path.read_text(encoding=None, errors=None)

   將指向檔案的解碼內容以字串形式回傳：

      >>> p = Path('my_text_file')
      >>> p.write_text('Text file contents')
      18
      >>> p.read_text()
      'Text file contents'

   該檔案被打開並且隨後關閉。選填參數的含義與 "open()" 函數中的相同。

   在 3.5 版新加入.

Path.readlink()

   回傳符號連結指向的路徑（如 "os.readlink()" 的回傳值）：

      >>> p = Path('mylink')
      >>> p.symlink_to('setup.py')
      >>> p.readlink()
      PosixPath('setup.py')

   在 3.9 版新加入.

Path.rename(target)

   將此檔案或目錄重新命名為所提供的 *target* ，並回傳一個新的路徑
   (Path) 物件指向該 *target* 。在 Unix 系統上，若 *target* 存在且為一
   個檔案，若使用者有權限，則會在不顯示訊息的情況下進行取代。在
   Windows 系統上，若 *target* 存在，則會引發 "FileExistsError" 錯誤。
   *target* 可以是字串或另一個路徑物件：

      >>> p = Path('foo')
      >>> p.open('w').write('some text')
      9
      >>> target = Path('bar')
      >>> p.rename(target)
      PosixPath('bar')
      >>> target.open().read()
      'some text'

   目標路徑可以是絕對路徑或相對路徑。相對路徑會相對於當前的工作目錄進
   行解釋，*not* 相對於路徑物件所在的目錄。

   此功能是使用 "os.rename()" 實現的，並提供相同的保證。

   在 3.8 版的變更: 新增了回傳值，回傳新的路徑 (Path) 物件。

Path.replace(target)

   將此檔案或目錄重新命名為給定的 *target* ，並回傳一個指向 *target*
   的新路徑物件。如果 *target* 指向一個現有的檔案或空目錄，它將被無條
   件地取代。

   目標路徑可以是絕對路徑或相對路徑。相對路徑會相對於當前的工作目錄進
   行解釋，*not* 相對於路徑物件所在的目錄。

   在 3.8 版的變更: 新增了回傳值，回傳新的路徑 (Path) 物件。

Path.absolute()

   使路徑成為絕對路徑，不進行標準化或解析符號連結。 回傳一個新的路徑物
   件：

      >>> p = Path('tests')
      >>> p
      PosixPath('tests')
      >>> p.absolute()
      PosixPath('/home/antoine/pathlib/tests')

Path.resolve(strict=False)

   將路徑轉換為絕對路徑，解析所有符號連結。回傳一個新的路徑物件：

      >>> p = Path()
      >>> p
      PosixPath('.')
      >>> p.resolve()
      PosixPath('/home/antoine/pathlib')

   同時也會消除 "".."" 的路徑組件（這是唯一的方法）：

      >>> p = Path('docs/../setup.py')
      >>> p.resolve()
      PosixPath('/home/antoine/pathlib/setup.py')

   如果路徑不存在且 *strict* 為 "True"， 則引發 "FileNotFoundError"。
   如果 *strict* 為 "False"， 則將盡可能解析該路徑，並將任何剩餘部分追
   加到路徑中，而不檢查其是否存在。  如果在解析過程中遇到無窮迴圈，則
   引發 "RuntimeError"。

   在 3.6 版新加入: *strict* 引數（在 3.6 版本之前的行為是嚴格的）。

Path.rglob(pattern)

   這相當於在給定的相對 *pattern* 前面加上 ""**/"" 並呼叫
   "Path.glob()" ：

      >>> sorted(Path().rglob("*.py"))
      [PosixPath('build/lib/pathlib.py'),
       PosixPath('docs/conf.py'),
       PosixPath('pathlib.py'),
       PosixPath('setup.py'),
       PosixPath('test_pathlib.py')]

   引發一個附帶引數 "self"、"pattern" 的稽核事件 "pathlib.Path.rglob"
   。

   在 3.11 版的變更: Return only directories if *pattern* ends with a
   pathname components separator ("sep" or "altsep").

Path.rmdir()

   移除此目錄。該目錄必須為空。

Path.samefile(other_path)

   回傳是否此路徑指向與 *other_path* 相同的檔案，*other_path* 可以是路
   徑 (Path) 物件或字串。其語義類似於 "os.path.samefile()" 和
   "os.path.samestat()"。

   An "OSError" can be raised if either file cannot be accessed for
   some reason.

      >>> p = Path('spam')
      >>> q = Path('eggs')
      >>> p.samefile(q)
      False
      >>> p.samefile('spam')
      True

   在 3.5 版新加入.

Path.symlink_to(target, target_is_directory=False)

   Make this path a symbolic link pointing to *target*.

   On Windows, a symlink represents either a file or a directory, and
   does not morph to the target dynamically.  If the target is
   present, the type of the symlink will be created to match.
   Otherwise, the symlink will be created as a directory if
   *target_is_directory* is "True" or a file symlink (the default)
   otherwise.  On non-Windows platforms, *target_is_directory* is
   ignored.

      >>> p = Path('mylink')
      >>> p.symlink_to('setup.py')
      >>> p.resolve()
      PosixPath('/home/antoine/pathlib/setup.py')
      >>> p.stat().st_size
      956
      >>> p.lstat().st_size
      8

   備註:

     The order of arguments (link, target) is the reverse of
     "os.symlink()"'s.

Path.hardlink_to(target)

   Make this path a hard link to the same file as *target*.

   備註:

     The order of arguments (link, target) is the reverse of
     "os.link()"'s.

   在 3.10 版新加入.

Path.link_to(target)

   Make *target* a hard link to this path.

   警告:

     This function does not make this path a hard link to *target*,
     despite the implication of the function and argument names. The
     argument order (target, link) is the reverse of
     "Path.symlink_to()" and "Path.hardlink_to()", but matches that of
     "os.link()".

   在 3.8 版新加入.

   在 3.10 版之後被棄用: This method is deprecated in favor of
   "Path.hardlink_to()", as the argument order of "Path.link_to()"
   does not match that of "Path.symlink_to()".

Path.touch(mode=0o666, exist_ok=True)

   Create a file at this given path.  If *mode* is given, it is
   combined with the process' "umask" value to determine the file mode
   and access flags.  If the file already exists, the function
   succeeds if *exist_ok* is true (and its modification time is
   updated to the current time), otherwise "FileExistsError" is
   raised.

Path.unlink(missing_ok=False)

   Remove this file or symbolic link.  If the path points to a
   directory, use "Path.rmdir()" instead.

   If *missing_ok* is false (the default), "FileNotFoundError" is
   raised if the path does not exist.

   If *missing_ok* is true, "FileNotFoundError" exceptions will be
   ignored (same behavior as the POSIX "rm -f" command).

   在 3.8 版的變更: 新增 *missing_ok* 參數。

Path.write_bytes(data)

   Open the file pointed to in bytes mode, write *data* to it, and
   close the file:

      >>> p = Path('my_binary_file')
      >>> p.write_bytes(b'Binary file contents')
      20
      >>> p.read_bytes()
      b'Binary file contents'

   An existing file of the same name is overwritten.

   在 3.5 版新加入.

Path.write_text(data, encoding=None, errors=None, newline=None)

   Open the file pointed to in text mode, write *data* to it, and
   close the file:

      >>> p = Path('my_text_file')
      >>> p.write_text('Text file contents')
      18
      >>> p.read_text()
      'Text file contents'

   An existing file of the same name is overwritten. The optional
   parameters have the same meaning as in "open()".

   在 3.5 版新加入.

   在 3.10 版的變更: 新增 *newline* 參數。


Correspondence to tools in the "os" module
==========================================

Below is a table mapping various "os" functions to their corresponding
"PurePath"/"Path" equivalent.

備註:

  Not all pairs of functions/methods below are equivalent. Some of
  them, despite having some overlapping use-cases, have different
  semantics. They include "os.path.abspath()" and "Path.absolute()",
  "os.path.relpath()" and "PurePath.relative_to()".

+--------------------------------------+-----------------------------------+
| "os" 和 "os.path"                    | "pathlib"                         |
|======================================|===================================|
| "os.path.abspath()"                  | "Path.absolute()" [1]             |
+--------------------------------------+-----------------------------------+
| "os.path.realpath()"                 | "Path.resolve()"                  |
+--------------------------------------+-----------------------------------+
| "os.chmod()"                         | "Path.chmod()"                    |
+--------------------------------------+-----------------------------------+
| "os.mkdir()"                         | "Path.mkdir()"                    |
+--------------------------------------+-----------------------------------+
| "os.makedirs()"                      | "Path.mkdir()"                    |
+--------------------------------------+-----------------------------------+
| "os.rename()"                        | "Path.rename()"                   |
+--------------------------------------+-----------------------------------+
| "os.replace()"                       | "Path.replace()"                  |
+--------------------------------------+-----------------------------------+
| "os.rmdir()"                         | "Path.rmdir()"                    |
+--------------------------------------+-----------------------------------+
| "os.remove()", "os.unlink()"         | "Path.unlink()"                   |
+--------------------------------------+-----------------------------------+
| "os.getcwd()"                        | "Path.cwd()"                      |
+--------------------------------------+-----------------------------------+
| "os.path.exists()"                   | "Path.exists()"                   |
+--------------------------------------+-----------------------------------+
| "os.path.expanduser()"               | "Path.expanduser()" 和            |
|                                      | "Path.home()"                     |
+--------------------------------------+-----------------------------------+
| "os.listdir()"                       | "Path.iterdir()"                  |
+--------------------------------------+-----------------------------------+
| "os.path.isdir()"                    | "Path.is_dir()"                   |
+--------------------------------------+-----------------------------------+
| "os.path.isfile()"                   | "Path.is_file()"                  |
+--------------------------------------+-----------------------------------+
| "os.path.islink()"                   | "Path.is_symlink()"               |
+--------------------------------------+-----------------------------------+
| "os.link()"                          | "Path.hardlink_to()"              |
+--------------------------------------+-----------------------------------+
| "os.symlink()"                       | "Path.symlink_to()"               |
+--------------------------------------+-----------------------------------+
| "os.readlink()"                      | "Path.readlink()"                 |
+--------------------------------------+-----------------------------------+
| "os.path.relpath()"                  | "PurePath.relative_to()" [2]      |
+--------------------------------------+-----------------------------------+
| "os.stat()"                          | "Path.stat()", "Path.owner()",    |
|                                      | "Path.group()"                    |
+--------------------------------------+-----------------------------------+
| "os.path.isabs()"                    | "PurePath.is_absolute()"          |
+--------------------------------------+-----------------------------------+
| "os.path.join()"                     | "PurePath.joinpath()"             |
+--------------------------------------+-----------------------------------+
| "os.path.basename()"                 | "PurePath.name"                   |
+--------------------------------------+-----------------------------------+
| "os.path.dirname()"                  | "PurePath.parent"                 |
+--------------------------------------+-----------------------------------+
| "os.path.samefile()"                 | "Path.samefile()"                 |
+--------------------------------------+-----------------------------------+
| "os.path.splitext()"                 | "PurePath.stem" 和                |
|                                      | "PurePath.suffix"                 |
+--------------------------------------+-----------------------------------+

-[ 註解 ]-

[1] "os.path.abspath()" normalizes the resulting path, which may
    change its meaning in the presence of symlinks, while
    "Path.absolute()" does not.

[2] "PurePath.relative_to()" requires "self" to be the subpath of the
    argument, but "os.path.relpath()" does not.
