encommon 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

encommon/types/notate.py

@@ -0,0 +1,319 @@
+"""
+Functions and routines associated with Enasis Network Common Library.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from contextlib import suppress
+from re import compile
+from re import match as re_match
+from typing import Any
+from typing import Optional
+from typing import Union
+
+from .empty import Empty
+
+
+
+_INTEGER = compile(r'^\d+$')
+_INDICES = (list, tuple, dict)
+_RECURSE = dict
+
+
+
+_SETABLE = Union[
+    dict[str, Any],
+    list[Any]]
+
+_GETABLE = Union[
+    tuple[Any, ...],
+    _SETABLE]
+
+
+
+def getate(
+    source: _GETABLE,
+    path: str,
+    default: Optional[Any] = None,
+    delim: str = '/',
+) -> Any:  # noqa: ANN401
+    """
+    Collect the value within the dictionary using notation.
+
+    Example
+    -------
+    >>> source = {'foo': {'bar': 'baz'}}
+    >>> getate(source, 'foo/bar')
+    'baz'
+
+    Example
+    -------
+    >>> source = {'foo': ['bar', 'baz']}
+    >>> getate(source, 'foo/1')
+    'baz'
+
+    :param source: Dictionary object processed in notation.
+    :param path: Path to the value within the source object.
+    :param default: Value to use if none is found in source.
+    :param delim: Override default delimiter between parts.
+    :returns: Value that was located within provided source.
+    """
+
+    sourze: Any = source
+
+    split = path.split(delim)
+
+    length = len(split)
+
+
+    items = enumerate(split)
+
+    for index, base in items:
+
+        if sourze is Empty:
+            return default
+
+
+        indices = isinstance(
+            sourze, _INDICES)
+
+        if (indices is False
+                and index < length):
+            return default
+
+
+        recurse = isinstance(
+            sourze, _RECURSE)
+
+        if recurse is False:
+
+            with suppress(IndexError):
+                sourze = sourze[int(base)]
+                continue
+
+
+        if base not in sourze:
+            sourze = Empty
+            continue
+
+        sourze = sourze[base]
+
+
+    return (
+        default if sourze is Empty
+        else sourze)
+
+
+
+def setate(
+    source: _SETABLE,
+    path: str,
+    value: Any,  # noqa: ANN401
+    delim: str = '/',
+) -> None:
+    """
+    Define the value within the dictionary using notation.
+
+    Example
+    -------
+    >>> source = {'foo': {'bar': 'baz'}}
+    >>> source['foo']['bar']
+    'baz'
+    >>> setate(source, 'foo/bar', 'bop')
+    >>> source['foo']['bar']
+    'bop'
+
+    :param source: Dictionary object processed in notation.
+    :param path: Path to the value within the source object.
+    :param value: Value which will be defined at noted point.
+    :param delim: Override default delimiter between parts.
+    """
+
+    _setvalue(source, path, value, delim)
+
+
+
+def delate(
+    source: _SETABLE,
+    path: str,
+    delim: str = '/',
+) -> None:
+    """
+    Delete the value within the dictionary using notation.
+
+    Example
+    -------
+    >>> source = {'foo': {'bar': 'baz'}}
+    >>> delate(source, 'foo/bar')
+    >>> source
+    {'foo': {}}
+
+    :param source: Dictionary object processed in notation.
+    :param path: Path to the value within the source object.
+    :param delim: Override default delimiter between parts.
+    """
+
+    split = path.split(delim)
+
+    with suppress(KeyError, IndexError):
+
+
+        for part in split[:-1]:
+
+            setable = isinstance(
+                source, dict | list)
+
+            if setable is False:
+                raise ValueError('source')
+
+            if isinstance(source, list):
+                source = source[int(part)]
+
+            elif isinstance(source, dict):
+                source = source[part]
+
+
+        part = split[-1]
+
+        setable = isinstance(
+            source, dict | list)
+
+        if setable is False:
+            raise ValueError('source')
+
+        if isinstance(source, dict):
+            del source[part]
+
+        if isinstance(source, list):
+            del source[int(part)]
+
+
+
+def _setpath(
+    source: _SETABLE,
+    path: str,
+    value: Any,  # noqa: ANN401
+    delim: str = '/',
+) -> None:
+    """
+    Define the value within the dictionary using notation.
+
+    .. note::
+       This is a private helper function that could change.
+
+    :param source: Dictionary object processed in notation.
+    :param path: Path to the value within the source object.
+    :param value: Value which will be defined at noted point.
+    :param delim: Override default delimiter between parts.
+    """
+
+
+    setable = isinstance(
+        source, dict | list)
+
+    assert setable is True
+
+
+    base, path = (
+        path.split(delim, 1))
+
+    next = (
+        path.split(delim, 1)[0])
+
+
+    default: _SETABLE = {}
+
+    if re_match(_INTEGER, next):
+        default = []
+
+    update: Any
+
+
+    if isinstance(source, list):
+
+        length = len(source)
+        index = int(base)
+
+        update = default
+
+        with suppress(IndexError):
+            update = source[index]
+
+        _setvalue(
+            update, path,
+            value, delim)
+
+        if length == index:
+            source.append(update)
+
+        elif length > index:
+            source[index] = update
+
+
+    elif isinstance(source, dict):
+
+        update = default
+
+        with suppress(KeyError):
+            update = source[base]
+
+        _setvalue(
+            update, path,
+            value, delim)
+
+        source[base] = update
+
+
+
+def _setvalue(
+    source: _SETABLE,
+    path: str,
+    value: Any,  # noqa: ANN401
+    delim: str = '/',
+) -> None:
+    """
+    Define the value within the dictionary using notation.
+
+    .. note::
+       This is a private helper function that could change.
+
+    :param source: Dictionary object processed in notation.
+    :param path: Path to the value within the source object.
+    :param value: Value which will be defined at noted point.
+    :param delim: Override default delimiter between parts.
+    """
+
+
+    setable = isinstance(
+        source, dict | list)
+
+    if setable is False:
+        raise ValueError('source')
+
+
+    if delim in path:
+        return _setpath(
+            source, path,
+            value, delim)
+
+
+    if isinstance(source, list):
+
+        length = len(source)
+        index = int(path)
+
+        if index > length:
+            raise IndexError(index)
+
+        if length == index:
+            source.append(value)
+
+        elif length > index:
+            source[index] = value
+
+
+    if isinstance(source, dict):
+        source[path] = value

encommon/types/test/__init__.py

@@ -4,3 +4,40 @@ Functions and routines associated with Enasis Network Common Library.
 This file is part of Enasis Network software eco-system. Distribution
 is permitted, for more information consult the project license file.
 """
+
+
+
+from copy import deepcopy
+
+
+
+_DICT1 = {
+    'dict1': 'dict1',
+    'str': 'd1string',
+    'list': ['d1list'],
+    'tuple': (1, 2),
+    'dict': {'key': 'd1dict'},
+    'bool': False}
+
+_DICT2 = {
+    'dict2': 'dict2',
+    'str': 'd2string',
+    'list': ['d2list'],
+    'tuple': (3, 4),
+    'dict': {'key': 'd2dict'},
+    'bool': True}
+
+_DICT1R = deepcopy(_DICT1)
+_DICT2R = deepcopy(_DICT2)
+
+_DICT1R['recurse'] = (
+    deepcopy(_DICT1))
+
+_DICT2R['recurse'] = (
+    deepcopy(_DICT2))
+
+_DICT1R['nested'] = [
+    deepcopy(_DICT1)]
+
+_DICT2R['nested'] = [
+    deepcopy(_DICT2)]

encommon/types/test/test_dicts.py

@@ -9,37 +9,22 @@ is permitted, for more information consult the project license file.
 
 from copy import deepcopy
 
+from . import _DICT1
+from . import _DICT1R
+from . import _DICT2
+from . import _DICT2R
 from ..dicts import merge_dicts
 from ..dicts import sort_dict
 
 
 
-_DICT1 = {
-    'dict1': 'dict1',
-    'str': 'd1string',
-    'list': ['d1list'],
-    'dict': {'key': 'd1value'},
-    'bool': False}
-
-_DICT2 = {
-    'dict2': 'dict2',
-    'str': 'd2string',
-    'list': ['d2list'],
-    'dict': {'key': 'd2value'},
-    'bool': True}
-
-
-
 def test_merge_dicts() -> None:
     """
     Perform various tests associated with relevant routines.
     """
 
-    dict1 = deepcopy(_DICT1)
-    dict2 = deepcopy(_DICT2)
-
-    dict1['recurse'] = deepcopy(dict1)
-    dict2['recurse'] = deepcopy(dict2)
+    dict1 = deepcopy(_DICT1R)
+    dict2 = deepcopy(_DICT2R)
 
 
     source = deepcopy(dict1)
@@ -52,14 +37,17 @@ def test_merge_dicts() -> None:
         'dict2': 'dict2',
         'str': 'd1string',
         'list': ['d1list', 'd2list'],
-        'dict': {'key': 'd1value'},
+        'dict': {'key': 'd1dict'},
+        'tuple': (1, 2),
         'bool': False,
+        'nested': [_DICT1, _DICT2],
         'recurse': {
             'dict1': 'dict1',
             'dict2': 'dict2',
             'str': 'd1string',
             'list': ['d1list', 'd2list'],
-            'dict': {'key': 'd1value'},
+            'dict': {'key': 'd1dict'},
+            'tuple': (1, 2),
             'bool': False}}
 
 
@@ -73,14 +61,17 @@ def test_merge_dicts() -> None:
         'dict2': 'dict2',
         'str': 'd2string',
         'list': ['d1list', 'd2list'],
-        'dict': {'key': 'd2value'},
+        'dict': {'key': 'd2dict'},
+        'tuple': (3, 4),
         'bool': True,
+        'nested': [_DICT1, _DICT2],
         'recurse': {
             'dict1': 'dict1',
             'dict2': 'dict2',
             'str': 'd2string',
             'list': ['d1list', 'd2list'],
-            'dict': {'key': 'd2value'},
+            'dict': {'key': 'd2dict'},
+            'tuple': (3, 4),
             'bool': True}}
 
 
@@ -98,13 +89,16 @@ def test_merge_dicts() -> None:
         'dict2': 'dict2',
         'str': 'd1string',
         'list': ['d1list'],
-        'dict': {'key': 'd1value'},
+        'dict': {'key': 'd1dict'},
+        'tuple': (1, 2),
         'bool': False,
+        'nested': [_DICT1],
         'recurse': {
             'dict1': 'dict1',
             'str': 'd1string',
             'list': ['d1list'],
-            'dict': {'key': 'd1value'},
+            'dict': {'key': 'd1dict'},
+            'tuple': (1, 2),
             'bool': False}}
 
 
@@ -116,7 +110,8 @@ def test_sort_dict() -> None:
 
     assert sort_dict(_DICT1) == {
         'bool': False,
-        'dict': {'key': 'd1value'},
+        'dict': {'key': 'd1dict'},
+        'tuple': (1, 2),
         'dict1': 'dict1',
         'list': ['d1list'],
         'str': 'd1string'}

encommon/types/test/test_notate.py

@@ -0,0 +1,217 @@
+"""
+Functions and routines associated with Enasis Network Common Library.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from copy import deepcopy
+
+from _pytest.python_api import RaisesContext
+
+from pytest import raises
+
+from . import _DICT1R
+from ..notate import delate
+from ..notate import getate
+from ..notate import setate
+
+
+
+def test_getate() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    source = deepcopy(_DICT1R)
+
+
+    value = getate(['1', 2], '1')
+    assert value == 2
+
+    value = getate((1, 2), '1')
+    assert value == 2
+
+    value = getate({'1': 2}, '1')
+    assert value == 2
+
+
+    path = 'recurse/dict/key'
+    value = getate(source, path)
+
+    assert value == 'd1dict'
+
+
+    path = 'recurse/list/0'
+    value = getate(source, path)
+
+    assert value == 'd1list'
+
+
+
+def test_getate_cover() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    source = deepcopy(_DICT1R)
+
+
+    assert not getate({}, 'd/n/e')
+    assert not getate([], '0/n/e')
+
+
+    path = 'recurse/str/a'
+    value = getate(source, path)
+
+    assert value is None
+
+
+
+def test_setate() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    source = deepcopy(_DICT1R)
+
+
+    path = 'list/1'
+    before = getate(source, path)
+    setate(source, path, 1)
+    after = getate(source, path)
+    assert after == 1
+    assert before is None
+
+
+    path = 'recurse/dict/key'
+    before = getate(source, path)
+    setate(source, path, 1)
+    after = getate(source, path)
+    assert after == 1
+    assert before == 'd1dict'
+
+
+    path = 'nested/0/dict/key'
+    before = getate(source, path)
+    setate(source, path, 1)
+    after = getate(source, path)
+    assert after == 1
+    assert before == 'd1dict'
+
+
+    path = 'recurse/list/0'
+    before = getate(source, path)
+    setate(source, path, 1)
+    after = getate(source, path)
+    assert after == 1
+    assert before == 'd1list'
+
+
+
+def test_setate_cover() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    source = deepcopy(_DICT1R)
+
+
+    path = 'nested/1/dict/key'
+    before = getate(source, path)
+    setate(source, path, 1)
+    after = getate(source, path)
+    assert after == 1
+    assert before is None
+
+
+
+def test_setate_raises() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    _raises: RaisesContext[
+        ValueError | IndexError]
+
+
+    _raises = raises(ValueError)
+
+    with _raises as reason:
+        setate(1, '1', 1)  # type: ignore
+
+    _reason = str(reason.value)
+
+    assert _reason == 'source'
+
+
+    _raises = raises(IndexError)
+
+    with _raises as reason:
+        setate([], '1', 1)
+
+    _reason = str(reason.value)
+
+    assert _reason == '1'
+
+
+
+def test_delate() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    source = deepcopy(_DICT1R)
+
+
+    path = 'recurse/dict/key'
+    before = getate(source, path)
+    delate(source, path)
+    after = getate(source, path)
+    assert after is None
+    assert before == 'd1dict'
+
+
+    path = 'nested/0/dict/key'
+    before = getate(source, path)
+    delate(source, path)
+    after = getate(source, path)
+    assert after is None
+    assert before == 'd1dict'
+
+
+    path = 'recurse/list/0'
+    before = getate(source, path)
+    delate(source, path)
+    after = getate(source, path)
+    assert after is None
+    assert before == 'd1list'
+
+
+
+def test_delate_raises() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+
+    _raises = raises(ValueError)
+
+    with _raises as reason:
+        delate(1, '1')  # type: ignore
+
+    _reason = str(reason.value)
+
+    assert _reason == 'source'
+
+
+    _raises = raises(ValueError)
+
+    with _raises as reason:
+        delate({'a': 1}, 'a/1/c')
+
+    _reason = str(reason.value)
+
+    assert _reason == 'source'

encommon/utils/__init__.py

@@ -7,8 +7,8 @@ is permitted, for more information consult the project license file.
 
 
 
-from .common import read_text
-from .common import save_text
+from .files import read_text
+from .files import save_text
 from .match import fuzz_match
 from .match import rgxp_match
 from .paths import resolve_path