[Python-checkins] peps: Rename relative_to() to relative(), removing the old relative() method.

[antoine.pitrou]

http://hg.python.org/peps/rev/3d6a0f00b70e
changeset:   4550:3d6a0f00b70e
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Wed Oct 10 21:01:50 2012 +0200
summary:
  Rename relative_to() to relative(), removing the old relative() method.

files:
  pep-0428.txt |  37 ++++++++++++++++++++-----------------
  1 files changed, 20 insertions(+), 17 deletions(-)


diff --git a/pep-0428.txt b/pep-0428.txt
--- a/pep-0428.txt
+++ b/pep-0428.txt
@@ -383,8 +383,8 @@
     >>> path_factory('bar')
     PurePosixPath('foo/bar')
 
-Changing the path name
-^^^^^^^^^^^^^^^^^^^^^^
+Changing the path's final component
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``with_name()`` method returns a new path, with the name changed::
 
@@ -404,9 +404,6 @@
     >>> p.name
     ''
 
-Changing the path suffix
-^^^^^^^^^^^^^^^^^^^^^^^^
-
 The ``with_suffix()`` method returns a new path with the suffix changed.
 However, if the path has no suffix, the new suffix is added::
 
@@ -417,6 +414,24 @@
     >>> p.with_suffix('.bz2')
     PureNTPath('README.bz2')
 
+Making the path relative
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``relative()`` method computes the relative difference of a path to
+another::
+
+    >>> PurePosixPath('/usr/bin/python').relative('/usr')
+    PurePosixPath('bin/python')
+
+ValueError is raised if the method cannot return a meaningful value::
+
+    >>> PurePosixPath('/usr/bin/python').relative('/etc')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "pathlib.py", line 926, in relative
+        .format(str(self), str(formatted)))
+    ValueError: '/usr/bin/python' does not start with '/etc'
+
 
 Sequence-like access
 --------------------
@@ -481,18 +496,6 @@
     >>> PureNTPath('c:/PATHLIB/setup.py').match('c:*lib/*.PY')
     True
 
-``relative()`` returns a new relative path by stripping the drive and root::
-
-    >>> PurePosixPath('setup.py').relative()
-    PurePosixPath('setup.py')
-    >>> PurePosixPath('/setup.py').relative()
-    PurePosixPath('setup.py')
-
-``relative_to()`` computes the relative difference of a path to another::
-
-    >>> PurePosixPath('/usr/bin/python').relative_to('/usr')
-    PurePosixPath('bin/python')
-
 ``normcase()`` returns a case-folded version of the path for NT paths::
 
     >>> PurePosixPath('CAPS').normcase()

-- 
Repository URL: http://hg.python.org/peps