Implement regular expression support for key searching

[ric-plt/sdlpy.git] / ricsdl-package / ricsdl / syncstorage_abc.py

diff --git a/ricsdl-package/ricsdl/syncstorage_abc.py b/ricsdl-package/ricsdl/syncstorage_abc.py
index ff5eea9..9ccd99d 100644 (file)
--- a/ricsdl-package/ricsdl/syncstorage_abc.py
+++ b/ricsdl-package/ricsdl/syncstorage_abc.py
@@ -290,6 +290,7 @@ class SyncStorageAbc(ABC):
 
         Returns:
             (dict of str: bytes): A dictionary mapping of a key to the read data from the storage.
+                                  Dictionary is sorted by key values in alphabetical order.
 
         Raises:
             SdlTypeError: If function's argument is of an inappropriate type.
@@ -300,12 +301,26 @@ class SyncStorageAbc(ABC):
         pass
 
     @abstractmethod
-    def find_keys(self, ns: str, key_prefix: str) -> List[str]:
-        """
+    def find_keys(self, ns: str, key_pattern: str) -> List[str]:
+        r"""
         Find all keys matching search pattern under the namespace.
 
-        No prior knowledge about the keys in the given namespace exists, thus operation is not
-        guaranteed to be atomic or isolated.
+        Supported glob-style patterns:
+            `?` matches any single character. For example `?at` matches Cat, cat, Bat or bat.
+            `*` matches any number of any characters including none. For example `*Law*` matches
+                Law, GrokLaw, or Lawyer.
+            `[abc]` matches one character given in the bracket. For example `[CB]at` matches Cat or
+                    Bat.
+            `[a-z]` matches one character from the range given in the bracket. For example
+                    `Letter[0-9]` matches Letter0 up to Letter9.
+            `[^abc]` matches any single character what is not given in the bracket. For example
+                     `h[^e]llo` matches hallo, hillo but not hello.
+
+        If searched key itself contains a special character, use a backslash (\) character to
+        escape the special character to match it verbatim.
+
+        NOTE: `find_keys` function is not guaranteed to be atomic or isolated.
+
         All the exceptions except SdlTypeError are derived from SdlException base class. Client
         can catch only that exception if separate handling for different SDL error situations is
         not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
@@ -313,8 +328,7 @@ class SyncStorageAbc(ABC):
 
         Args:
             ns (str): Namespace under which this operation is targeted.
-            key_prefix (str): Only keys starting with given keyPrefix are returned. Passing empty
-                              string as keyPrefix will return all the keys.
+            key_pattern (str): Key search pattern.
 
         Returns:
             (list of str): A list of found keys.
@@ -328,13 +342,26 @@ class SyncStorageAbc(ABC):
         pass
 
     @abstractmethod
-    def find_and_get(self, ns: str, key_prefix: str, atomic: bool) -> Dict[str, bytes]:
-        """
+    def find_and_get(self, ns: str, key_pattern: str) -> Dict[str, bytes]:
+        r"""
         Find keys and get their respective data from SDL storage.
 
-        Only those entries that are matching prefix will be returned.
-        NOTE: In atomic action, if the prefix produces huge number of matches, that can have
-        a severe impact on system performance, due to DB is blocked for long time.
+        Supported glob-style patterns:
+            `?` matches any single character. For example `?at` matches Cat, cat, Bat or bat.
+            `*` matches any number of any characters including none. For example `*Law*` matches
+                Law, GrokLaw, or Lawyer.
+            `[abc]` matches one character given in the bracket. For example `[CB]at` matches Cat or
+                    Bat.
+            `[a-z]` matches one character from the range given in the bracket. For example
+                    `Letter[0-9]` matches Letter0 up to Letter9.
+            `[^abc]` matches any single character what is not given in the bracket. For example
+                     `h[^e]llo` matches hallo, hillo but not hello.
+
+        If searched key itself contains a special character, use a backslash (\) character to
+        escape the special character to match it verbatim.
+
+        NOTE: `find_and_get` function is not guaranteed to be atomic or isolated.
+
         All the exceptions except SdlTypeError are derived from SdlException base class. Client
         can catch only that exception if separate handling for different SDL error situations is
         not needed. Exception SdlTypeError is derived from build-in TypeError and it indicates
@@ -342,13 +369,11 @@ class SyncStorageAbc(ABC):
 
         Args:
             ns (str): Namespace under which this operation is targeted.
-            key_prefix (str): Only keys starting with given keyPrefix are returned. Passing empty
-                              string as keyPrefix will return all the keys.
-            atomic (bool): True to find keys and get their respective data in one atomic operation,
-                           false to find keys and get their respective data non-atomically.
+            key_pattern (str): Key search pattern.
 
         Returns:
             (dict of str: bytes): A dictionary mapping of a key to the read data from the storage.
+                                  Dictionary is sorted by key values in alphabetical order.
 
         Raises:
             SdlTypeError: If function's argument is of an inappropriate type.