Merge branch 'develop'v0.23.03

5 files changed, 66 insertions, 29 deletions

diff --git a/bsfs/utils/__init__.py b/bsfs/utils/__init__.py
index 94680ee..d497645 100644
--- a/bsfs/utils/__init__.py
+++ b/bsfs/utils/__init__.py
@@ -1,15 +1,10 @@
-"""
 
-Part of the BlackStar filesystem (bsfs) module.
-A copy of the license is provided with the project.
-Author: Matthias Baumgartner, 2022
-"""
 # imports
 import typing
 
 # inner-module imports
 from . import errors
-from .commons import typename
+from .commons import typename, normalize_args
 from .uri import URI
 from .uuid import UUID, UCID
 
@@ -19,6 +14,7 @@ __all__ : typing.Sequence[str] = (
     'URI',
     'UUID',
     'errors',
+    'normalize_args',
     'typename',
     )
 
diff --git a/bsfs/utils/commons.py b/bsfs/utils/commons.py
index bad2fe0..a7092ae 100644
--- a/bsfs/utils/commons.py
+++ b/bsfs/utils/commons.py
@@ -1,14 +1,11 @@
-"""
 
-Part of the BlackStar filesystem (bsfs) module.
-A copy of the license is provided with the project.
-Author: Matthias Baumgartner, 2022
-"""
 # imports
+from collections import abc
 import typing
 
 # exports
 __all__: typing.Sequence[str] = (
+    'normalize_args',
     'typename',
     )
 
@@ -19,5 +16,37 @@ def typename(obj) -> str:
     """Return the type name of *obj*."""
     return type(obj).__name__
 
+# argument type in `normalize_args`.
+ArgType = typing.TypeVar('ArgType') # pylint: disable=invalid-name # type vars don't follow the usual convention
+
+def normalize_args(
+        *args: typing.Union[ArgType, typing.Iterable[ArgType], typing.Iterator[ArgType]]
+        ) -> typing.Tuple[ArgType, ...]:
+    """Arguments to a function can be passed as individual arguments, list-like
+    structures, or iterables. This function processes any of these styles and
+    returns a tuple of the respective items. Typically used within a function
+    provide a flexible interface but sill have parameters in a normalized form.
+
+    Examples:
+
+    >>> normalize_args(0,1,2)
+    (1,2,3)
+    >>> normalize_args([0,1,2])
+    (1,2,3)
+    >>> normalize_args(range(3))
+    (1,2,3)
+
+    """
+    if len(args) == 0: # foo()
+        return tuple()
+    if len(args) > 1: # foo(0, 1, 2)
+        return tuple(args) # type: ignore [arg-type] # we assume that argument styles (arg vs. iterable) are not mixed.
+    if isinstance(args[0], abc.Iterator): # foo(iter([0,1,2]))
+        return tuple(args[0])
+    if isinstance(args[0], abc.Iterable) and not isinstance(args[0], str): # foo([0, 1, 2])
+        return tuple(args[0])
+    # foo(0)
+    return (args[0], ) # type: ignore [return-value] # if args[0] is a str, we assume that ArgType was str.
+
 
 ## EOF ##
diff --git a/bsfs/utils/errors.py b/bsfs/utils/errors.py
index c5e8e16..b82e6e2 100644
--- a/bsfs/utils/errors.py
+++ b/bsfs/utils/errors.py
@@ -1,9 +1,4 @@
-"""
 
-Part of the BlackStar filesystem (bsfs) module.
-A copy of the license is provided with the project.
-Author: Matthias Baumgartner, 2022
-"""
 # imports
 import typing
 
@@ -38,4 +33,10 @@ class UnreachableError(ProgrammingError):
 class ConfigError(_BSFSError):
     """User config issue."""
 
+class BackendError(_BSFSError):
+    """Could not parse an AST structure."""
+
+class UnsupportedError(_BSFSError):
+    """Some requested functionality is not supported by an implementation."""
+
 ## EOF ##
diff --git a/bsfs/utils/uri.py b/bsfs/utils/uri.py
index 84854a4..5755a6e 100644
--- a/bsfs/utils/uri.py
+++ b/bsfs/utils/uri.py
@@ -1,14 +1,11 @@
-"""
 
-Part of the BlackStar filesystem (bsfs) module.
-A copy of the license is provided with the project.
-Author: Matthias Baumgartner, 2022
-"""
 # imports
 import re
 import typing
 
 # constants
+RX_CHARS = re.compile(r'[<>" {}|\\^]')
+
 RX_URI = re.compile(r'''
     ^
     (?:(?P<scheme>[^:/?#]+):)?      # scheme, ://-delimited
@@ -82,6 +79,9 @@ class URI(str):
         no claim about the validity of an URI!
 
         """
+        # check characters
+        if RX_CHARS.search(query) is not None:
+            return False
         # check uri
         parts = RX_URI.match(query)
         if parts is not None:
@@ -232,9 +232,6 @@ class URI(str):
 
     # overload formatting methods
 
-    def format(self, *args, **kwargs) -> 'URI':
-        return URI(super().format(*args, **kwargs))
-
     def __mod__(self, *args) -> 'URI':
         return URI(super().__mod__(*args))
 
diff --git a/bsfs/utils/uuid.py b/bsfs/utils/uuid.py
index 6366b18..ad7fc1c 100644
--- a/bsfs/utils/uuid.py
+++ b/bsfs/utils/uuid.py
@@ -1,12 +1,9 @@
-"""
 
-Part of the BlackStar filesystem (bsfs) module.
-A copy of the license is provided with the project.
-Author: Matthias Baumgartner, 2022
-"""
 # imports
 from collections import abc
 import hashlib
+import io
+import json
 import os
 import platform
 import random
@@ -105,4 +102,21 @@ class UCID():
         with open(path, 'rb') as ifile:
             return HASH(ifile.read()).hexdigest()
 
+    @staticmethod
+    def from_buffer(buffer: io.IOBase) -> str:
+        """Read the content from a buffer."""
+        if isinstance(buffer, io.TextIOBase):
+            return HASH(buffer.read().encode('utf-8', errors='ignore')).hexdigest()
+        return HASH(buffer.read()).hexdigest()
+
+    @staticmethod
+    def from_bytes(content: bytes) -> str:
+        """Get the content from as bytes."""
+        return HASH(content).hexdigest()
+
+    @staticmethod
+    def from_dict(content: dict) -> str:
+        """Get the content from a dict."""
+        return HASH(json.dumps(content).encode('ascii', 'ignore')).hexdigest()
+
 ## EOF ##