[Docutils-checkins] SF.net SVN: docutils:[9420] trunk/docutils

[<mi...@us...>]

Revision: 9420
          http://sourceforge.net/p/docutils/code/9420
Author:   milde
Date:     2023-06-29 13:49:53 +0000 (Thu, 29 Jun 2023)
Log Message:
-----------
Documentation and test update to utils.relative_path().

Modified Paths:
--------------
    trunk/docutils/docutils/utils/__init__.py
    trunk/docutils/test/test_utils.py

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2023-06-29 13:49:42 UTC (rev 9419)
+++ trunk/docutils/docutils/utils/__init__.py	2023-06-29 13:49:53 UTC (rev 9420)
@@ -479,15 +479,27 @@
     """
     Build and return a path to `target`, relative to `source` (both files).
 
-    Differences to `os.relpath()`:
+    The return value is a `str` suitable to be included in `source`
+    as a reference to `target`.
 
+    :Parameters:
+        `source` : path-like object or None
+            Path of a file in the start directory for the relative path
+            (the file does not need to exist).
+            The value ``None`` is replaced with "<cwd>/dummy_file".
+        `target` : path-like object
+            End point of the returned relative path.
+
+    Differences to `os.path.relpath()`:
+
     * Inverse argument order.
-    * `source` expects path to a FILE (while os.relpath expects a dir)!
-      (Add a "dummy" file name if `source` points to a directory.)
+    * `source` expects path to a FILE
+      while `start` in `os.path.relpath()` expects a DIRECTORY.
+      (You must add a "dummy" file name if the `source` is a directory.)
     * Always use Posix path separator ("/") for the output.
-    * Use `os.sep` for parsing the input (ignored by `os.relpath()`).
+    * Use `os.sep` for parsing the input
+      (changing the value of `os.sep` is ignored by `os.relpath()`).
     * If there is no common prefix, return the absolute path to `target`.
-
     """
     source_parts = os.path.abspath(source or type(target)('dummy_file')
                                    ).split(os.sep)

Modified: trunk/docutils/test/test_utils.py
===================================================================
--- trunk/docutils/test/test_utils.py	2023-06-29 13:49:42 UTC (rev 9419)
+++ trunk/docutils/test/test_utils.py	2023-06-29 13:49:53 UTC (rev 9420)
@@ -324,16 +324,22 @@
         source = os.path.join('häm', 'spam', 'fileA')
         target = os.path.join('häm', 'fileB')
         self.assertEqual(utils.relative_path(source, target), '../fileB')
+        source = os.path.join('häm', 'fileA')
+        target = os.path.join('..', 'spam', 'fileB')
+        self.assertEqual(utils.relative_path(source, target),
+                         '../../spam/fileB')
         # if source is None, default to the cwd:
         target = os.path.join('eggs', 'fileB')
         self.assertEqual(utils.relative_path(None, target), 'eggs/fileB')
         # If there is no common prefix, return the absolute path to `target`:
-        # source = '/foo/bar/fileA' # POSIX
-        #   TODO: how to specify an absolute path independent of the OS?
-        # target = os.path.join('eggs', 'fileB')
-        # self.assertEqual(utils.relative_path(source, target),
-        #                  os.path.abspath('fileB'))
-        # Correctly process unicode instances:
+        if os.sep == '/':
+            source = '/foo/bar/fileA'
+        else:
+            source = r'C:\foo\bar\fileA'
+        target = os.path.join('eggs', 'fileB')
+        self.assertEqual(utils.relative_path(source, target),
+                         os.path.abspath('eggs/fileB'))
+        # Correctly process characters outside the ASCII range:
         self.assertEqual(utils.relative_path('spam', 'spam'), '')
         source = os.path.join('häm', 'spam', 'fileA')
         target = os.path.join('häm', 'spam', 'fileB')

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.