encommon 0.7.6__py3-none-any.whl → 0.8.1__py3-none-any.whl

encommon/utils/common.py

@@ -12,16 +12,61 @@ from typing import Union
 
 
 
-JOINABLE = (
-    list  # type: ignore
-    | tuple  # type: ignore
-    | set)  # type: ignore
+JOINABLE = (list, tuple, set)
 
 
 
 PATHABLE = Union[
-    str,
-    Path,
+    str, Path,
     list[str | Path],
     tuple[str | Path],
     set[str]]
+
+
+
+REPLACE = Union[
+    dict[str, str],
+    dict[str, str | Path],
+    dict[str, Path],
+    dict[str, str],
+    dict[str | Path, str],
+    dict[Path, str]]
+
+
+
+def read_text(
+    path: str | Path,
+) -> str:
+    """
+    Read the text content from within the provided file path.
+
+    :param path: Complete or relative path to the text file.
+    :returns: Text content that was read from the file path.
+    """
+
+    path = Path(path).resolve()
+
+    return path.read_text(
+        encoding='utf-8')
+
+
+
+def save_text(
+    path: str | Path,
+    content: str,
+) -> str:
+    """
+    Save the provided text content to the provided file path.
+
+    :param path: Complete or relative path to the text file.
+    :param content: Content that will be written to the file.
+    :returns: Text content that was read from the file path.
+    """
+
+    path = Path(path).resolve()
+
+    path.write_text(
+        data=content,
+        encoding='utf-8')
+
+    return read_text(path)

encommon/utils/match.py

@@ -23,12 +23,12 @@ def rgxp_match(
 
     Example
     -------
-    >>> rgxp_match('one', ['one', 'two'])
+    >>> rgxp_match('one', ['on*', 'two'])
     True
 
     Example
     -------
-    >>> rgxp_match('uno', ['one', 'two'])
+    >>> rgxp_match('uno', ['on*', 'two'])
     False
 
     :param values: Value or values to enumerate for matching.
@@ -51,6 +51,7 @@ def rgxp_match(
 
 
     def _matches() -> bool:
+
         return bool(
             function(pattern, value))
 
@@ -85,12 +86,12 @@ def fuzz_match(
 
     Example
     -------
-    >>> rgxp_match('one', ['one', 'two'])
+    >>> rgxp_match('one', ['on[a-z]', 'two'])
     True
 
     Example
     -------
-    >>> rgxp_match('uno', ['one', 'two'])
+    >>> rgxp_match('uno', ['on[a-z]', 'two'])
     False
 
     :param values: Value or values to enumerate for matching.

encommon/utils/paths.py

@@ -10,22 +10,27 @@ is permitted, for more information consult the project license file.
 from os import stat_result
 from pathlib import Path
 from typing import Optional
+from typing import TYPE_CHECKING
 
-from .common import PATHABLE
 from .match import rgxp_match
+from ..types import sort_dict
 
+if TYPE_CHECKING:
+    from .common import PATHABLE
+    from .common import REPLACE
 
 
-_REPLACE = dict[str, str]
+
+STATS_PATH = dict[str, stat_result]
 
 
 
 def resolve_path(
     path: str | Path,
-    replace: Optional[_REPLACE] = None,
+    replace: Optional['REPLACE'] = None,
 ) -> Path:
     """
-    Resolve the provided path and replace the magic keywords.
+    Resolve the provided path replacing the magic keywords.
 
     Example
     -------
@@ -33,14 +38,24 @@ def resolve_path(
     PosixPath('/foo/bar')
 
     :param path: Complete or relative path for processing.
-    :param replace: Optional string values to replace in path.
+    :param replace: Optional values to replace in the path.
     :returns: New resolved filesystem path object instance.
     """
 
     path = str(path).strip()
 
     if replace is not None:
-        for old, new in replace.items():
+
+        items = replace.items()
+
+        for old, new in items:
+
+            if isinstance(old, Path):
+                old = str(old)
+
+            if isinstance(new, Path):
+                new = str(new)
+
             path = path.replace(old, new)
 
     return Path(path).resolve()
@@ -48,11 +63,11 @@ def resolve_path(
 
 
 def resolve_paths(
-    paths: PATHABLE,
-    replace: Optional[_REPLACE] = None,
+    paths: 'PATHABLE',
+    replace: Optional['REPLACE'] = None,
 ) -> tuple[Path, ...]:
     """
-    Resolve the provided paths and replace the magic keywords.
+    Resolve the provided paths replacing the magic keywords.
 
     .. note::
        This will remove duplicative paths from the returned.
@@ -63,7 +78,7 @@ def resolve_paths(
     (PosixPath('/foo/bar'),)
 
     :param paths: Complete or relative paths for processing.
-    :param replace: Optional string values to replace in path.
+    :param replace: Optional values to replace in the path.
     :returns: New resolved filesystem path object instances.
     """
 
@@ -74,13 +89,13 @@ def resolve_paths(
 
     for path in paths:
 
-        _path = resolve_path(
-            str(path), replace)
+        resolved = resolve_path(
+            path, replace)
 
-        if _path in returned:
+        if resolved in returned:
             continue
 
-        returned.append(_path)
+        returned.append(resolved)
 
     return tuple(returned)
 
@@ -88,17 +103,18 @@ def resolve_paths(
 
 def stats_path(
     path: str | Path,
-    replace: Optional[_REPLACE] = None,
+    replace: Optional['REPLACE'] = None,
     ignore: Optional[list[str]] = None,
-) -> dict[str, stat_result]:
+) -> STATS_PATH:
     """
     Collect stats object for the complete or relative path.
 
     .. testsetup::
+       >>> from . import save_text
        >>> path = Path(getfixture('tmpdir'))
        >>> file = path.joinpath('hello.txt')
-       >>> file.write_text('Hello world!')
-       12
+       >>> save_text(file, 'Hello world!')
+       'Hello world!'
 
     Example
     -------
@@ -108,18 +124,20 @@ def stats_path(
     12
 
     :param path: Complete or relative path for enumeration.
-    :param replace: Optional string values to replace in path.
+    :param replace: Optional values to replace in the path.
     :param ignore: Paths matching these patterns are ignored.
     :returns: Metadata for files recursively found in path.
     """
 
     path = Path(path).resolve()
 
-    returned: dict[str, stat_result] = {}
+    returned: STATS_PATH = {}
 
 
     def _ignore() -> bool:
+
         assert ignore is not None
+
         return rgxp_match(
             str(item), ignore)
 
@@ -141,8 +159,9 @@ def stats_path(
             key = resolve_path(
                 item, replace)
 
-            returned[str(key)] = (
-                item.stat())
+            stat = item.stat()
+
+            returned[str(key)] = stat
 
 
-    return dict(sorted(returned.items()))
+    return sort_dict(returned)

encommon/utils/sample.py

@@ -13,17 +13,13 @@ from pathlib import Path
 from typing import Any
 from typing import Callable
 from typing import Optional
-from typing import Union
+from typing import TYPE_CHECKING
 
-from .. import PROJECT
-from .. import WORKSPACE
+from . import read_text
+from . import save_text
 
-
-
-_REPLACE = Union[
-    dict[str, str],
-    dict[str, str | Path],
-    dict[str, Path]]
+if TYPE_CHECKING:
+    from .common import REPLACE
 
 
 
@@ -31,7 +27,7 @@ def prep_sample(
     content: Any,
     *,
     default: Callable[[Any], str] = str,
-    replace: Optional[_REPLACE] = None,
+    replace: Optional['REPLACE'] = None,
 ) -> Any:
     """
     Return the content after processing using JSON functions.
@@ -49,9 +45,9 @@ def prep_sample(
     >>> prep_sample({'one': Empty})
     {'one': 'Empty'}
 
-    :param content: Content which will be processed for JSON.
+    :param content: Content that will be processed as JSON.
     :param default: Callable used when stringifying values.
-    :param replace: Optional string values to replace in path.
+    :param replace: Optional values to replace in the file.
     :returns: Content after processing using JSON functions.
     """
 
@@ -60,13 +56,14 @@ def prep_sample(
 
     prefix = 'encommon_sample'
 
-    replace = dict(replace or {})
+    replace = replace or {}
+
+    items = replace.items()
 
-    replace |= {
-        'PROJECT': PROJECT,
-        'WORKSPACE': WORKSPACE}
+    for old, new in items:
 
-    for old, new in replace.items():
+        if isinstance(old, Path):
+            old = str(old)
 
         if isinstance(new, Path):
             new = str(new)
@@ -79,12 +76,12 @@ def prep_sample(
 
 
 def load_sample(
-    path: Path,
+    path: str | Path,
     content: Optional[Any] = None,
     update: bool = False,
     *,
     default: Callable[[Any], str] = str,
-    replace: Optional[_REPLACE] = None,
+    replace: Optional['REPLACE'] = None,
 ) -> Any:
     """
     Load the sample file and compare using provided content.
@@ -106,16 +103,19 @@ def load_sample(
     >>> load_sample(sample)
     {'one': 'two'}
 
-    :param path: Complete or relative path to the sample file.
+    :param path: Complete or relative path for the sample.
     :param update: Determine whether the sample is updated.
-    :param content: Content which will be processed for JSON.
+    :param content: Content that will be processed as JSON.
     :param default: Callable used when stringifying values.
-    :param replace: Optional string values to replace in file.
+    :param replace: Optional values to replace in the file.
     :returns: Content after processing using JSON functions.
     """
 
+    path = Path(path).resolve()
+
     loaded: Optional[Any] = None
 
+
     content = prep_sample(
         content=content,
         default=default,
@@ -123,14 +123,18 @@ def load_sample(
 
 
     def _save_sample() -> None:
-        path.write_text(
-            dumps(content, indent=2))
+
+        dumped = dumps(
+            content, indent=2)
+
+        save_text(path, dumped)
 
 
     def _load_sample() -> Any:
-        return loads(
-            path.read_text(
-                encoding='utf-8'))
+
+        loaded = read_text(path)
+
+        return loads(loaded)
 
 
     if path.exists():

encommon/utils/stdout.py

@@ -16,11 +16,13 @@ from typing import Literal
 from typing import Optional
 from typing import Union
 
-from encommon.times import Duration
-from encommon.times import Times
-from encommon.types import Empty
-
 from .common import JOINABLE
+from ..times import Duration
+from ..times import Times
+from ..types import Empty
+from ..types.strings import COMMAD
+from ..types.strings import NEWLINE
+from ..types.strings import SEMPTY
 
 
 
@@ -40,6 +42,10 @@ ANSIARRAY = Union[
 
 
 
+_REPEAT = (list, tuple, dict)
+
+
+
 @dataclass(frozen=True)
 class ArrayColors:
     """
@@ -49,6 +55,9 @@ class ArrayColors:
     label: int = 37
     key: int = 97
 
+    colon: int = 37
+    hyphen: int = 37
+
     bool: int = 93
     none: int = 33
     str: int = 92
@@ -58,13 +67,10 @@ class ArrayColors:
     empty: int = 36
     other: int = 91
 
-    colon: int = 37
-    hyphen: int = 37
-
 
 
 def print_ansi(
-    string: str = '',
+    string: str = SEMPTY,
     method: Literal['stdout', 'print'] = 'stdout',
     output: bool = True,
 ) -> str:
@@ -133,8 +139,8 @@ def kvpair_ansi(
     :returns: ANSI colorized string using inline directives.
     """  # noqa: D301 LIT102
 
-    if isinstance(value, JOINABLE):  # type: ignore
-        value = ','.join([
+    if isinstance(value, JOINABLE):
+        value = COMMAD.join([
             str(x) for x in value])
 
     elif not isinstance(value, str):
@@ -161,7 +167,7 @@ def strip_ansi(
     :returns: Provided string with the ANSI codes removed.
     """  # noqa: D301 LIT102
 
-    return re_sub(ANSICODE, '', string)
+    return re_sub(ANSICODE, SEMPTY, string)
 
 
 
@@ -206,25 +212,28 @@ def array_ansi(  # noqa: CFQ001, CFQ004
                 f'{prefix} {repeat}')
 
 
-        if isinstance(value, list | tuple | dict):
+        if isinstance(value, _REPEAT):
             refers.add(id(value))
 
 
-        types = {
+        typing = {
             'list': list,
             'tuple': tuple,
             'dict': dict,
             'frozenset': frozenset,
             'set': set}
 
-        for name, _type in types.items():
+        items = typing.items()
+
+        for name, _type in items:
 
             if not isinstance(value, _type):
                 continue
 
             output.append(
                 f'{prefix} '
-                f'<c{colors.label}>{name}<c0>')
+                f'<c{colors.label}>'
+                f'{name}<c0>')
 
             return _process(
                 source=value,
@@ -281,7 +290,9 @@ def array_ansi(  # noqa: CFQ001, CFQ004
 
         assert isinstance(source, dict)
 
-        for key, value in source.items():
+        items = source.items()
+
+        for key, value in items:
 
             prefix = (
                 f'{" " * indent}'
@@ -340,4 +351,4 @@ def array_ansi(  # noqa: CFQ001, CFQ004
     _output = [
         make_ansi(x) for x in output]
 
-    return '\n'.join(_output)
+    return NEWLINE.join(_output)

encommon/utils/test/test_common.py

@@ -0,0 +1,35 @@
+"""
+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 pathlib import Path
+
+from ..common import read_text
+from ..common import save_text
+
+
+
+def test_readsave_text(
+    tmp_path: Path,
+) -> None:
+    """
+    Perform various tests associated with relevant routines.
+
+    :param tmp_path: pytest object for temporal filesystem.
+    """
+
+    content = 'pytest'
+
+    save_text(
+        f'{tmp_path}/test.txt',
+        content)
+
+    loaded = read_text(
+        f'{tmp_path}/test.txt')
+
+    assert loaded == content

encommon/utils/test/test_paths.py

@@ -13,7 +13,7 @@ from ..paths import resolve_path
 from ..paths import resolve_paths
 from ..paths import stats_path
 from ... import PROJECT
-from ...times.times import Times
+from ...times import Times
 
 
 
@@ -61,7 +61,7 @@ def test_stats_path() -> None:
 
     stats = stats_path(
         f'{PROJECT}/utils',
-        replace={str(PROJECT): '/'},
+        replace={PROJECT: '/'},
         ignore=[r'\S+\.pyc'])
 
     stat = stats['/utils/paths.py']
@@ -81,6 +81,7 @@ def test_stats_path() -> None:
         '/utils/sample.py',
         '/utils/stdout.py',
         '/utils/test/__init__.py',
+        '/utils/test/test_common.py',
         '/utils/test/test_match.py',
         '/utils/test/test_paths.py',
         '/utils/test/test_sample.py',

encommon/utils/test/test_sample.py

@@ -34,34 +34,50 @@ def test_load_sample(
     :param tmp_path: pytest object for temporal filesystem.
     """
 
-    path = (
-        Path(tmp_path)
-        .joinpath('samples.json'))
+    prefix = 'encommon_sample'
 
     source = {
         'list': ['bar', 'baz'],
         'tuple': (1, 2),
         'project': PROJECT,
-        'other': '/path/to/other'}
+        'other': '/pat/h',
+        'devnull': '/dev/null'}
 
     expect = {
         'list': ['bar', 'baz'],
         'tuple': [1, 2],
-        'project': '_/encommon_sample/PROJECT/_',
-        'other': '_/encommon_sample/tmp_path/_'}
+        'project': f'_/{prefix}/PROJECT/_',
+        'other': f'_/{prefix}/pytemp/_',
+        'devnull': '/dev/null'}
+
+
+    devnull = Path('/dev/null')
+
+    replaces = {
+        devnull: 'nothing here',
+        'PROJECT': str(PROJECT),
+        'pytemp': '/pat/h'}
+
+
+    sample_path = (
+        f'{tmp_path}/samples.json')
 
     sample = load_sample(
-        path=path,
+        path=sample_path,
         update=ENPYRWS,
         content=source,
-        replace={'tmp_path': '/path/to/other'})
+        replace=replaces)  # type: ignore
 
     assert sample == expect
 
+
+    source |= {'list': [1, 3, 2]}
+    expect |= {'list': [1, 3, 2]}
+
     sample = load_sample(
-        path=path,
-        content=source | {'list': [1]},
+        path=sample_path,
+        content=source,
         update=True,
-        replace={'tmp_path': '/path/to/other'})
+        replace=replaces)  # type: ignore
 
-    assert sample == expect | {'list': [1]}
+    assert sample == expect

encommon/version.txt

@@ -1 +1 @@
-0.7.6
+0.8.1

{encommon-0.7.6.dist-info → encommon-0.8.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: encommon
-Version: 0.7.6
+Version: 0.8.1
 Summary: Enasis Network Common Library
 License: MIT
 Classifier: Programming Language :: Python :: 3