Add new rename method + support code to move keys around

Author: ntninja

datastore/adapter/directory.py

@@ -158,6 +158,7 @@ class ObjectDatastore(
 	FORWARD_CONTAINS = True
 	FORWARD_GET_ALL  = True
 	FORWARD_PUT_NEW  = True
+	FORWARD_RENAME   = True
 	FORWARD_STAT     = True
 
 
@@ -225,6 +226,22 @@ async def delete(self, key: datastore.Key) -> None:
 		await super().directory_remove(dir_key, key, missing_ok=True)
 
 
+	async def rename(self, key1: datastore.Key, key2: datastore.Key, *,
+	                 replace: bool = True) -> None:
+		"""Renames item *key1* to *key2*
+		
+		DirectoryTreeDatastore removes the previous directory entry and add a new one.
+		"""
+		await super().rename(key1, key2, replace=replace)
+		
+		if key1 != key2:
+			dir_key1 = key1.parent.instance('directory')
+			await super().directory_remove(dir_key1, key1, missing_ok=True)
+			
+			dir_key2 = key2.parent.instance('directory')
+			await super().directory_add(dir_key2, key2, create=True)
+	
+	
 	async def query(self, query: datastore.Query) -> datastore.Cursor:
 		"""Returns objects matching criteria expressed in `query`.
 		DirectoryTreeDatastore uses directory entries.

datastore/adapter/keytransform.py

@@ -51,7 +51,8 @@ class _Adapter(typing.Generic[DS, MD, RT, RV]):
 
 	FORWARD_CONTAINS = True
 	FORWARD_GET_ALL  = True
-	FORWARD_PUT_NEW  = False  # Still not true in all cases
+	FORWARD_PUT_NEW  = False  # Only true if we can also transform the returned name back
+	FORWARD_RENAME   = True
 	FORWARD_STAT     = True
 
 	key_transform_fn: _support.FunctionProperty[KEY_TRANSFORM_T]
@@ -126,6 +127,13 @@ async def contains(self, key: datastore.Key) -> bool:
 		return await super().contains(self._transform_key(key))  # type: ignore[misc, no-any-return]
 
 
+	async def rename(self, key1: datastore.Key, key2: datastore.Key, *,
+	                 replace: bool = True) -> None:
+		"""Renames item *keytransform(key1)* to *keytransform(key2)*"""
+		await super().rename(self._transform_key(key1),  # type: ignore[misc]
+		                     self._transform_key(key2), replace=replace)
+	
+	
 	async def stat(self, key: datastore.Key) -> MD:
 		"""Returns the metadata of the object named by keytransform(key)."""
 		return await super().stat(self._transform_key(key))  # type: ignore[misc, no-any-return]

datastore/adapter/logging.py

@@ -23,6 +23,7 @@ class _Adapter(typing.Generic[DS, MD, RT, RV]):
 	FORWARD_CONTAINS = True
 	FORWARD_GET_ALL  = True
 	FORWARD_PUT_NEW  = True
+	FORWARD_RENAME   = True
 	FORWARD_STAT     = True
 
 	logger: logging.Logger
@@ -106,6 +107,16 @@ async def contains(self, key: datastore.Key) -> bool:
 		return await super().contains(key)  # type: ignore[misc, no-any-return]
 
 
+	async def rename(self, key1: datastore.Key, key2: datastore.Key, *,
+	                 replace: bool = True) -> None:
+		"""Renames item *key1* to *key2*
+		
+		LoggingDatastore logs the change.
+		"""
+		self.logger.info('%s: rename %s → %s', self, key1, key2)
+		await super().rename(key1, key2, replace=replace)  # type: ignore[misc]
+	
+	
 	async def stat(self, key: datastore.Key) -> MD:
 		"""Returns metadata about things stored at name *key*
 		

datastore/adapter/mount.py

@@ -112,6 +112,19 @@ async def contains(self, key: datastore.Key) -> bool:
 		return await ds.contains(subkey)
 
 
+	async def rename(self, key1: datastore.Key, key2: datastore.Key, *,
+	                 replace: bool = True) -> None:
+		ds1, _, subkey1 = self._find_mountpoint(key1)
+		ds2, _, subkey2 = self._find_mountpoint(key2)
+		if ds1 is None:
+			raise KeyError(key1)
+		if ds2 is None:
+			raise RuntimeError(f"Cannot rename to {key2}: No datastore mounted at that path")
+		if ds1 is not ds2:
+			raise RuntimeError(f"Cannot rename {key1} to {key2}: Cross-mount renames are not supported")
+		await ds1.rename(subkey1, subkey2, replace=replace)
+	
+	
 	async def stat(self, key: datastore.Key) -> MD:
 		ds, _, subkey = self._find_mountpoint(key)
 		if ds is None:

datastore/adapter/tiered.py

@@ -206,6 +206,30 @@ async def contains(self, key: datastore.Key) -> bool:
 		return False
 
 
+	async def rename(self, key1: datastore.Key, key2: datastore.Key, *,
+	                 replace: bool = True) -> None:
+		"""Renames item *key1* to *key2*"""
+		renamed: typing.List[DS] = []
+		
+		async def do_rename(store: DS) -> None:  # type: ignore[return]  # mypy bug
+			await store.rename(key1, key2, replace=replace)
+			renamed.append(store)
+		
+		try:
+			async with trio.open_nursery() as nursery:
+				for store in self._stores:
+					nursery.start_soon(do_rename, store)
+		except BaseException:
+			# Try to undo our changes
+			with trio.CancelScope(shield=True):
+				for store in reversed(renamed):
+					try:
+						await store.rename(key2, key1, replace=False)
+					except BaseException:
+						pass  # Swallow all exceptions
+			raise
+	
+	
 	async def stat(self, key: datastore.Key) -> MD:
 		"""Returns the metadata of the object named by key. Checks each
 		datastore in order."""

datastore/core/binarystore.py

@@ -256,6 +256,33 @@ async def get_all(self, key: key_.Key) -> bytes:
 		return await (await self.get(key)).collect()
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the data at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		
+		Raises
+		------
+		KeyError
+			There was no data by name *key1* in the datastore
+		KeyError
+			There was already some data at name *key2* in the datastore,
+			but *replace* was not ``True``
+		RuntimeError
+			An internal error occurred
+		NotImplementedError
+			This datastore does not support this operation
+		"""
+		raise NotImplementedError()
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.StreamMetadata:
 		"""Returns any metadata associated with the data stream named by `key`
 		or raises `KeyError` otherwise
@@ -481,6 +508,31 @@ async def contains(self, key: key_.Key) -> bool:
 		return key in self._collection(key)
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the data at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		"""
+		if key1 == key2:
+			return
+		
+		collection1 = self._collection(key1)
+		collection2 = self._collection(key2)
+		if key1 not in collection1:
+			raise KeyError(key1)
+		if not replace and key2 in collection2:
+			raise KeyError(key2)
+		collection2[key2] = collection1[key1]
+		del collection1[key1]
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.StreamMetadata:
 		"""Returns the length of the byte sequence named by `key` if it exists.
 		
@@ -533,6 +585,7 @@ class Adapter(Datastore):
 	FORWARD_PUT_NEW:   bool = False  # Not always true
 	FORWARD_PUT_NEW_D: typing.Optional[bool] = None  # Defaults to the value of `FORWARD_PUT_NEW`
 	FORWARD_PUT_NEW_I: typing.Optional[bool] = None  # Defaults to the value of `FORWARD_PUT_NEW`
+	FORWARD_RENAME:    bool = False
 	FORWARD_STAT:      bool = False
 
 	child_datastore: Datastore
@@ -704,6 +757,36 @@ async def contains(self, key: key_.Key) -> bool:
 			return await Datastore.contains(self, key)
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the data at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		
+		Raises
+		------
+		KeyError
+			Key *key1* did not exist in the child datastore
+		KeyError
+			Key *key2* already exists in the child datastore, but *replace* was not ``True``
+		RuntimeError
+			An internal error occurred in the child datastore
+		NotImplementedError
+			``FORWARD_RENAME`` is not ``True`` or the child datastore does not
+			support this operation
+		"""
+		if self.FORWARD_RENAME:
+			return await self.child_datastore.rename(key1, key2, replace=replace)
+		else:
+			return await Datastore.rename(self, key1, key2, replace=replace)  # Will raise
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.StreamMetadata:
 		"""Returns the metadata of the stream named by `key` if it exists
 		

datastore/core/objectstore.py

@@ -286,6 +286,33 @@ async def get_all(self, key: key_.Key) -> typing.List[T_co]:
 		return await (await self.get(key)).collect()
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves content at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		
+		Raises
+		------
+		KeyError
+			There was no content at name *key1* in the datastore
+		KeyError
+			There was already some content at name *key2* in the datastore,
+			but *replace* was not ``True``
+		RuntimeError
+			An internal error occurred
+		NotImplementedError
+			This datastore does not support this operation
+		"""
+		raise NotImplementedError()
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.ChannelMetadata:
 		"""Returns any metadata associated with the objects named by `key` or
 		raises `KeyError` otherwise
@@ -517,6 +544,31 @@ async def contains(self, key: key_.Key) -> bool:
 		return key in self._collection(key)
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the objects at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		"""
+		if key1 == key2:
+			return
+		
+		collection1 = self._collection(key1)
+		collection2 = self._collection(key2)
+		if key1 not in collection1:
+			raise KeyError(key1)
+		if not replace and key2 in collection2:
+			raise KeyError(key2)
+		collection2[key2] = collection1[key1]
+		del collection1[key1]
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.ChannelMetadata:
 		"""Returns the length of the object list named by `key` if it exists.
 		
@@ -574,6 +626,7 @@ class Adapter(Datastore[T_co], typing.Generic[T_co, U_co]):
 	FORWARD_PUT_NEW:   bool = False  # Not always true
 	FORWARD_PUT_NEW_D: typing.Optional[bool] = None  # Defaults to the value of `FORWARD_PUT_NEW`
 	FORWARD_PUT_NEW_I: typing.Optional[bool] = None  # Defaults to the value of `FORWARD_PUT_NEW`
+	FORWARD_RENAME:    bool = False
 	FORWARD_STAT:      bool = False
 
 	child_datastore: Datastore[U_co]
@@ -771,6 +824,37 @@ async def contains(self, key: key_.Key) -> bool:
 			return await Datastore.contains(self, key)
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the content at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		
+		Raises
+		------
+		KeyError
+			There was no content at name *key1* in the child datastore
+		KeyError
+			There was already some content at name *key2* in the child datastore,
+			but *replace* was not ``True``
+		RuntimeError
+			An internal error occurred in the child datastore
+		NotImplementedError
+			``FORWARD_RENAME`` is not ``True`` or the child datastore does not
+			support this operation
+		"""
+		if self.FORWARD_RENAME:
+			return await self.child_datastore.rename(key1, key2, replace=replace)
+		else:
+			return await Datastore.rename(self, key1, key2, replace=replace)  # Will raise
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.ChannelMetadata:
 		"""Returns the metadata of the object list named by `key` if it exists
 		

datastore/core/serialize.py

@@ -213,6 +213,32 @@ async def contains(self, key: key_.Key) -> bool:
 		return await self.child_datastore.contains(key)
 
 
+	async def rename(self, key1: key_.Key, key2: key_.Key, *, replace: bool = True) -> None:
+		"""Moves the content at name *key1* to *key2*
+		
+		Arguments
+		---------
+		key1
+			The key to rename, must exist
+		key2
+			The new name of the key, if *replace* is ``False`` this must not exist
+		replace
+			Should an existing key at name *key2* be replaced
+		
+		Raises
+		------
+		KeyError
+			Key *key1* does not exist in the child datastore
+		KeyError
+			Key *key2* already exists in the child datastore, but *replace* was not ``True``
+		RuntimeError
+			An internal error occurred in the child datastore
+		NotImplementedError
+			The child datastore does not support this operation
+		"""
+		await self.child_datastore.rename(key1, key2, replace=replace)
+	
+	
 	async def stat(self, key: key_.Key) -> util.metadata.ChannelMetadata:
 		"""Returns whether an object named by `key` exists