For the newly added preserve_time parameter, reserved atime and ctime guarantees.

As it turns out, there are platforms which do not allow changing either atime or ctime to custom values. Thus, the proposed behavior was impossible to implement. `preserve_time` now only makes guarantees about mtime.

Author: atollk

CHANGELOG.md

@@ -18,6 +18,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Better documentation of the `writable` parameter of `fs.open_fs`, and
   hint about using `fs.wrap.read_only` when a read-only filesystem is
   required. Closes [#441](https://github.com/PyFilesystem/pyfilesystem2/issues/441).
+- Copy and move operations now provide a parameter `preserve_time` that, when
+  passed as `True`, makes sure the "mtime" of the destination file will be
+  the same as that of the source file.
 
 ### Changed
 

fs/base.py

@@ -409,8 +409,8 @@ def copy(
             dst_path (str): Path to destination file.
             overwrite (bool): If `True`, overwrite the destination file
                 if it exists (defaults to `False`).
-            preserve_time (bool): If `True`, try to preserve atime, ctime,
-                and mtime of the resource (defaults to `False`).
+            preserve_time (bool): If `True`, try to preserve mtime of the
+                resource (defaults to `False`).
 
         Raises:
             fs.errors.DestinationExists: If ``dst_path`` exists,
@@ -443,8 +443,8 @@ def copydir(
             dst_path (str): Path to destination directory.
             create (bool): If `True`, then ``dst_path`` will be created
                 if it doesn't exist already (defaults to `False`).
-            preserve_time (bool): If `True`, try to preserve atime, ctime,
-                and mtime of the resource (defaults to `False`).
+            preserve_time (bool): If `True`, try to preserve mtime of the
+                resource (defaults to `False`).
 
         Raises:
             fs.errors.ResourceNotFound: If the ``dst_path``
@@ -1054,8 +1054,8 @@ def movedir(self, src_path, dst_path, create=False, preserve_time=False):
             dst_path (str): Path to destination directory.
             create (bool): If `True`, then ``dst_path`` will be created
                 if it doesn't exist already (defaults to `False`).
-            preserve_time (bool): If `True`, try to preserve atime, ctime,
-                and mtime of the resources (defaults to `False`).
+            preserve_time (bool): If `True`, try to preserve mtime of the
+                resources (defaults to `False`).
 
         Raises:
             fs.errors.ResourceNotFound: if ``dst_path`` does not exist,
@@ -1122,8 +1122,8 @@ def move(self, src_path, dst_path, overwrite=False, preserve_time=False):
                 file will be written to.
             overwrite (bool): If `True`, destination path will be
                 overwritten if it exists.
-            preserve_time (bool): If `True`, try to preserve atime, ctime,
-                and mtime of the resources (defaults to `False`).
+            preserve_time (bool): If `True`, try to preserve mtime of the
+                resources (defaults to `False`).
 
         Raises:
             fs.errors.FileExpected: If ``src_path`` maps to a

fs/copy.py

@@ -40,8 +40,8 @@ def copy_fs(
             dst_path)``.
         workers (int): Use `worker` threads to copy data, or ``0`` (default) for
             a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     return copy_dir(
@@ -76,8 +76,8 @@ def copy_fs_if_newer(
             dst_path)``.
         workers (int): Use ``worker`` threads to copy data, or ``0`` (default) for
             a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     return copy_dir_if_newer(
@@ -138,8 +138,8 @@ def copy_file(
         src_path (str): Path to a file on the source filesystem.
         dst_fs (FS or str): Destination filesystem (instance or URL).
         dst_path (str): Path to a file on the destination filesystem.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resource (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resource (defaults to `False`).
 
     """
     with manage_fs(src_fs, writeable=False) as _src_fs:
@@ -182,8 +182,8 @@ def copy_file_internal(
         src_path (str): Path to a file on the source filesystem.
         dst_fs (FS): Destination filesystem.
         dst_path (str): Path to a file on the destination filesystem.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resource (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resource (defaults to `False`).
 
     """
     if src_fs is dst_fs:
@@ -223,8 +223,8 @@ def copy_file_if_newer(
         src_path (str): Path to a file on the source filesystem.
         dst_fs (FS or str): Destination filesystem (instance or URL).
         dst_path (str): Path to a file on the destination filesystem.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resource (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resource (defaults to `False`).
 
     Returns:
         bool: `True` if the file copy was executed, `False` otherwise.
@@ -273,8 +273,8 @@ def copy_structure(
         walker (~fs.walk.Walker, optional): A walker object that will be
             used to scan for files in ``src_fs``. Set this if you only
             want to consider a sub-set of the resources in ``src_fs``.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resource (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resource (defaults to `False`).
 
     """
     walker = walker or Walker()
@@ -311,8 +311,8 @@ def copy_dir(
             ``(src_fs, src_path, dst_fs, dst_path)``.
         workers (int): Use ``worker`` threads to copy data, or ``0`` (default) for
             a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     on_copy = on_copy or (lambda *args: None)
@@ -383,8 +383,8 @@ def copy_dir_if_newer(
             ``(src_fs, src_path, dst_fs, dst_path)``.
         workers (int): Use ``worker`` threads to copy data, or ``0`` (default) for
             a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     on_copy = on_copy or (lambda *args: None)

fs/mirror.py

@@ -74,8 +74,8 @@ def mirror(
         workers (int): Number of worker threads used
             (0 for single threaded). Set to a relatively low number
             for network filesystems, 4 would be a good start.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
 

fs/move.py

@@ -29,8 +29,8 @@ def move_fs(
         dst_fs (FS or str): Destination filesystem (instance or URL).
         workers (int): Use `worker` threads to copy data, or ``0`` (default) for
             a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     move_dir(src_fs, "/", dst_fs, "/", workers=workers, preserve_time=preserve_time)
@@ -51,8 +51,8 @@ def move_file(
         src_path (str): Path to a file on ``src_fs``.
         dst_fs (FS or str): Destination filesystem (instance or URL).
         dst_path (str): Path to a file on ``dst_fs``.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
     with manage_fs(src_fs) as _src_fs:
@@ -93,8 +93,8 @@ def move_dir(
         dst_path (str): Path to a directory on ``dst_fs``.
         workers (int): Use ``worker`` threads to copy data, or ``0``
             (default) for a single-threaded copy.
-        preserve_time (bool): If `True`, try to preserve atime, ctime,
-            and mtime of the resources (defaults to `False`).
+        preserve_time (bool): If `True`, try to preserve mtime of the
+            resources (defaults to `False`).
 
     """
 

tests/test_copy.py

@@ -17,7 +17,7 @@
 class TestCopy(unittest.TestCase):
     @parameterized.expand([(0,), (1,), (2,), (4,)])
     def test_copy_fs(self, workers):
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
 
         src_fs = open_fs("mem://")
         src_fs.makedirs("foo/bar")
@@ -37,13 +37,7 @@ def test_copy_fs(self, workers):
         dst_file1_info = dst_fs.getinfo("test.txt", namespaces)
         dst_file2_info = dst_fs.getinfo("foo/bar/baz.txt", namespaces)
         self.assertEqual(dst_file1_info.modified, src_file1_info.modified)
-        self.assertEqual(
-            dst_file1_info.metadata_changed, src_file1_info.metadata_changed
-        )
         self.assertEqual(dst_file2_info.modified, src_file2_info.modified)
-        self.assertEqual(
-            dst_file2_info.metadata_changed, src_file2_info.metadata_changed
-        )
 
     def test_copy_value_error(self):
         src_fs = open_fs("mem://")
@@ -52,7 +46,7 @@ def test_copy_value_error(self):
             fs.copy.copy_fs(src_fs, dst_fs, workers=-1)
 
     def test_copy_dir0(self):
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
 
         src_fs = open_fs("mem://")
         src_fs.makedirs("foo/bar")
@@ -69,13 +63,10 @@ def test_copy_dir0(self):
 
             dst_file2_info = dst_fs.getinfo("bar/baz.txt", namespaces)
             self.assertEqual(dst_file2_info.modified, src_file2_info.modified)
-            self.assertEqual(
-                dst_file2_info.metadata_changed, src_file2_info.metadata_changed
-            )
 
     @parameterized.expand([(0,), (1,), (2,), (4,)])
     def test_copy_dir(self, workers):
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
 
         src_fs = open_fs("mem://")
         src_fs.makedirs("foo/bar")
@@ -94,9 +85,6 @@ def test_copy_dir(self, workers):
 
             dst_file2_info = dst_fs.getinfo("bar/baz.txt", namespaces)
             self.assertEqual(dst_file2_info.modified, src_file2_info.modified)
-            self.assertEqual(
-                dst_file2_info.metadata_changed, src_file2_info.metadata_changed
-            )
 
     def test_copy_large(self):
         data1 = b"foo" * 512 * 1024

tests/test_memoryfs.py

@@ -72,19 +72,17 @@ def test_copy_preserve_time(self):
         self.fs.makedir("bar")
         self.fs.touch("foo/file.txt")
 
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
         src_info = self.fs.getinfo("foo/file.txt", namespaces)
 
         self.fs.copy("foo/file.txt", "bar/file.txt", preserve_time=True)
         self.assertTrue(self.fs.exists("bar/file.txt"))
 
         dst_info = self.fs.getinfo("bar/file.txt", namespaces)
         self.assertEqual(dst_info.modified, src_info.modified)
-        self.assertEqual(dst_info.metadata_changed, src_info.metadata_changed)
 
-        
-class TestMemoryFile(unittest.TestCase):
 
+class TestMemoryFile(unittest.TestCase):
     def setUp(self):
         self.fs = memoryfs.MemoryFS()
 

tests/test_move.py

@@ -11,7 +11,7 @@
 @parameterized_class(("preserve_time",), [(True,), (False,)])
 class TestMove(unittest.TestCase):
     def test_move_fs(self):
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
 
         src_fs = open_fs("mem://")
         src_fs.makedirs("foo/bar")
@@ -32,16 +32,10 @@ def test_move_fs(self):
             dst_file1_info = dst_fs.getinfo("test.txt", namespaces)
             dst_file2_info = dst_fs.getinfo("foo/bar/baz.txt", namespaces)
             self.assertEqual(dst_file1_info.modified, src_file1_info.modified)
-            self.assertEqual(
-                dst_file1_info.metadata_changed, src_file1_info.metadata_changed
-            )
             self.assertEqual(dst_file2_info.modified, src_file2_info.modified)
-            self.assertEqual(
-                dst_file2_info.metadata_changed, src_file2_info.metadata_changed
-            )
 
     def test_move_dir(self):
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
 
         src_fs = open_fs("mem://")
         src_fs.makedirs("foo/bar")
@@ -60,6 +54,3 @@ def test_move_dir(self):
         if self.preserve_time:
             dst_file2_info = dst_fs.getinfo("bar/baz.txt", namespaces)
             self.assertEqual(dst_file2_info.modified, src_file2_info.modified)
-            self.assertEqual(
-                dst_file2_info.metadata_changed, src_file2_info.metadata_changed
-            )

tests/test_osfs.py

@@ -105,15 +105,14 @@ def test_copy_preserve_time(self):
             raw_info = {"details": {"accessed": now, "modified": now}}
             self.fs.setinfo("foo/file.txt", raw_info)
 
-        namespaces = ("details", "accessed", "metadata_changed", "modified")
+        namespaces = ("details", "modified")
         src_info = self.fs.getinfo("foo/file.txt", namespaces)
 
         self.fs.copy("foo/file.txt", "bar/file.txt", preserve_time=True)
         self.assertTrue(self.fs.exists("bar/file.txt"))
 
         dst_info = self.fs.getinfo("bar/file.txt", namespaces)
         self.assertEqual(dst_info.modified, src_info.modified)
-        self.assertEqual(dst_info.metadata_changed, src_info.metadata_changed)
 
     @unittest.skipUnless(osfs.sendfile, "sendfile not supported")
     @unittest.skipIf(

tests/test_wrap.py

@@ -177,7 +177,7 @@ def test_scandir(self):
         ]
         with mock.patch.object(self.fs, "scandir", wraps=self.fs.scandir) as scandir:
             self.assertEqual(sorted(self.cached.scandir("/"), key=key), expected)
-            scandir.assert_has_calls([mock.call('/', namespaces=None, page=None)])
+            scandir.assert_has_calls([mock.call("/", namespaces=None, page=None)])
         with mock.patch.object(self.fs, "scandir", wraps=self.fs.scandir) as scandir:
             self.assertEqual(sorted(self.cached.scandir("/"), key=key), expected)
             scandir.assert_not_called()
@@ -187,7 +187,7 @@ def test_isdir(self):
             self.assertTrue(self.cached.isdir("foo"))
             self.assertFalse(self.cached.isdir("egg"))  # is file
             self.assertFalse(self.cached.isdir("spam"))  # doesn't exist
-            scandir.assert_has_calls([mock.call('/', namespaces=None, page=None)])
+            scandir.assert_has_calls([mock.call("/", namespaces=None, page=None)])
         with mock.patch.object(self.fs, "scandir", wraps=self.fs.scandir) as scandir:
             self.assertTrue(self.cached.isdir("foo"))
             self.assertFalse(self.cached.isdir("egg"))
@@ -199,7 +199,7 @@ def test_isfile(self):
             self.assertTrue(self.cached.isfile("egg"))
             self.assertFalse(self.cached.isfile("foo"))  # is dir
             self.assertFalse(self.cached.isfile("spam"))  # doesn't exist
-            scandir.assert_has_calls([mock.call('/', namespaces=None, page=None)])
+            scandir.assert_has_calls([mock.call("/", namespaces=None, page=None)])
         with mock.patch.object(self.fs, "scandir", wraps=self.fs.scandir) as scandir:
             self.assertTrue(self.cached.isfile("egg"))
             self.assertFalse(self.cached.isfile("foo"))
@@ -211,7 +211,7 @@ def test_getinfo(self):
             self.assertEqual(self.cached.getinfo("foo"), self.fs.getinfo("foo"))
             self.assertEqual(self.cached.getinfo("/"), self.fs.getinfo("/"))
             self.assertNotFound(self.cached.getinfo, "spam")
-            scandir.assert_has_calls([mock.call('/', namespaces=None, page=None)])
+            scandir.assert_has_calls([mock.call("/", namespaces=None, page=None)])
         with mock.patch.object(self.fs, "scandir", wraps=self.fs.scandir) as scandir:
             self.assertEqual(self.cached.getinfo("foo"), self.fs.getinfo("foo"))
             self.assertEqual(self.cached.getinfo("/"), self.fs.getinfo("/"))