Commits

Antoine Pitrou  committed c3d9fb2

Import some doc changes from the stdlib

  • Participants
  • Parent commits bf75f7c
  • Branches pep428

Comments (0)

Files changed (1)

File docs/index.rst

 This module is best used with Python 3.2 or later, but it is also compatible
 with Python 2.7.
 
+.. note::
+   This module has been `included <http://docs.python.org/dev/library/pathlib.html>`_
+   in the Python 3.4 standard library after :pep:`428` acceptance. You only
+   need to install it for Python 3.3 or older.
+
+.. seealso::
+   :pep:`428`: The pathlib module -- object-oriented filesystem paths
+      Rationale for the stabilized pathlib design and API.
 
 Download
 --------
 
-Releases are available on PyPI: http://pypi.python.org/pypi/pathlib/
+Standalone releases are available on PyPI: http://pypi.python.org/pypi/pathlib/
 
-The development repository and issue tracker can be found at BitBucket:
+Main development now takes place in the Python standard library: see
+the `Python developer's guide <http://docs.python.org/devguide/>`_.
+
+The maintenance repository for this standalone backport module can be
+found on BitBucket, but activity is expected to be quite low:
 https://bitbucket.org/pitrou/pathlib/
 
-
 Basic use
 ---------
 
 Methods and properties
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Pure paths provide the following methods an properties:
+Pure paths provide the following methods and properties:
 
 .. data:: PurePath.drive
 
 
 .. method:: PurePath.is_reserved()
 
-   With :class:`PureWindowsPath`, return True if the path is considered
-   reserved under Windows, False otherwise.  With :class:`PurePosixPath`,
-   False is always returned.
+   With :class:`PureWindowsPath`, return ``True`` if the path is considered
+   reserved under Windows, ``False`` otherwise.  With :class:`PurePosixPath`,
+   ``False`` is always returned.
 
       >>> PureWindowsPath('nul').is_reserved()
       True
 
 .. method:: PurePath.joinpath(*other)
 
-   Calling this method is equivalent to indexing the path with each of
+   Calling this method is equivalent to combining the path with each of
    the *other* arguments in turn::
 
       >>> PurePosixPath('/etc').joinpath('passwd')
 
 .. method:: PurePath.match(pattern)
 
-   Match this path against the provided glob-style pattern.  Return True
-   if matching is successful, False otherwise.
+   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::
 
 .. method:: Path.group()
 
-   Return the name of the group owning the file.  :exc:`KeyError` is thrown
+   Return the name of the group owning the file.  :exc:`KeyError` is raised
    if the file's gid isn't found in the system database.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
 .. method:: Path.is_symlink()
 
-   Return True if the path points to a symbolic link, False otherwise.
+   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
+   ``False`` is also returned if the path doesn't exist; other errors (such
    as permission errors) are propagated.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
 .. method:: 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.
+   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;
+   ``False`` is also returned if the path doesn't exist or is a broken symlink;
    other errors (such as permission errors) are propagated.
 
 
    combined with the process' ``umask`` value to determine the file mode
    and access flags.  If the path already exists, :exc:`OSError` is raised.
 
-   If *parents* is True, any missing parents of this path are created
-   as needed.  If *parents* is False (the default), a missing parent raises
+   If *parents* is true, any missing parents of this path are created
+   as needed.  If *parents* is false (the default), a missing parent raises
    :exc:`OSError`.
 
 
 
 .. method:: Path.owner()
 
-   Return the name of the user owning the file.  :exc:`KeyError` is thrown
+   Return the name of the user owning the file.  :exc:`KeyError` is raised
    if the file's uid isn't found in the system database.
 
 
 .. method:: Path.symlink_to(target, target_is_directory=False)
 
    Make this path a symbolic link to *target*.  Under Windows,
-   *target_is_directory* must be True (default False) if the link's target
+   *target_is_directory* must be true (default ``False``) if the link's target
    is a directory.  Under POSIX, *target_is_directory*'s value is ignored.
 
       >>> p = Path('mylink')
 
    Remove this file or symbolic link.  If the path points to a directory,
    use :func:`Path.rmdir` instead.
-