vt-commons 0.0.1__py3-none-any.whl

vt/utils/commons/commons/op/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to operations.
+"""
+
+from vt.utils.commons.commons.op.base import RootDirOp as RootDirOp
+from vt.utils.commons.commons.op.base import CWDRootDirOp as CWDRootDirOp
+from vt.utils.commons.commons.op.base import RootDirOps as RootDirOps
+from vt.utils.commons.commons.op.base import ReversibleOp as ReversibleOp

vt/utils/commons/commons/op/base.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable interfaces for python projects related to operations.
+"""
+
+from __future__ import annotations
+from abc import abstractmethod
+from pathlib import Path
+from typing import Protocol, override, final
+
+
+class ReversibleOp(Protocol):
+    """
+    Operation that can be reversed or act in the reversed mode.
+    """
+
+    @property
+    @abstractmethod
+    def rev(self) -> bool:
+        """
+        :return: whether current operation is operating in the reverse mode.
+        """
+        ...
+
+
+# region Root dir related operations
+class RootDirOp(Protocol):
+    """
+    Perform operations on the ``root_dir``.
+    """
+
+    @property
+    @abstractmethod
+    def root_dir(self) -> Path:
+        """
+        :return: Path to the ``root_dir`` root directory for this operation.
+        """
+        ...
+
+
+class CWDRootDirOp(RootDirOp):
+    def __init__(self, root_dir=Path.cwd()):
+        """
+        Perform operations on the root_dir.
+
+        :param root_dir: the path to the root directory.
+        """
+        self._root_dir = root_dir
+
+    @override
+    @property
+    def root_dir(self) -> Path:
+        return self._root_dir
+
+
+@final
+class RootDirOps:
+    """
+    A factory-like class for ``RootDirOp``.
+    """
+
+    @staticmethod
+    def strictly_one_required(
+        root_dir: Path | None = None,
+        root_dir_op: RootDirOp | None = None,
+        *,
+        root_dir_str: str = "root_dir",
+        root_dir_op_str: str = "root_dir_op",
+    ):
+        """
+        Convenience method to raise ``ValueError`` when both ``root_dir`` and ``root_dir_op`` are supplied.
+
+        Examples:
+
+          * OK: only root-dir supplied:
+
+            >>> RootDirOps.strictly_one_required(Path.cwd())
+
+          * OK: only root-dir-op supplied:
+
+            >>> RootDirOps.strictly_one_required(root_dir_op=RootDirOps.from_path(Path('tmp')))
+
+          * At least one of ``root_dir`` or ``root_dir_op`` must be provided:
+
+            >>> RootDirOps.strictly_one_required(None, None)
+            Traceback (most recent call last):
+            ValueError: Either root_dir or root_dir_op is required.
+
+          * Both ``root_dir`` or ``root_dir_op`` cannot be provided:
+
+            >>> RootDirOps.strictly_one_required(root_dir=Path.cwd(), root_dir_op=RootDirOps.from_path(Path('tmp')))
+            Traceback (most recent call last):
+            ValueError: root_dir and root_dir_op are not allowed together.
+
+        :param root_dir: path to the root directory.
+        :param root_dir_op: object that has path to the root directory.
+        :param root_dir_str: variable name string for overriding the default ``root_op`` variable name in error
+            messages.
+        :param root_dir_op_str: variable name string for overriding the default ``root_dir_op`` variable name in error
+            messages.
+        :raises ValueError: when both ``root_dir`` and ``root_dir_op`` are supplied.
+        """
+        if root_dir is None and root_dir_op is None:
+            raise ValueError(f"Either {root_dir_str} or {root_dir_op_str} is required.")
+        if root_dir and root_dir_op:
+            raise ValueError(
+                f"{root_dir_str} and {root_dir_op_str} are not allowed together."
+            )
+
+    @staticmethod
+    def from_path(root_dir: Path = Path.cwd()) -> CWDRootDirOp:
+        """
+        :param root_dir: path to root-dir.
+        :return: a root dir operation for the supplied path.
+        """
+        return CWDRootDirOp(root_dir)
+
+
+# endregion

vt/utils/commons/commons/os/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to operating systems.
+"""
+
+from vt.utils.commons.commons.os.windows import is_windows as is_windows
+from vt.utils.commons.commons.os.windows import not_windows as not_windows
+
+from vt.utils.commons.commons.os.linux import is_linux as is_linux
+from vt.utils.commons.commons.os.linux import not_linux as not_linux
+
+from vt.utils.commons.commons.os.mac import is_mac as is_mac
+from vt.utils.commons.commons.os.mac import not_mac as not_mac
+
+from vt.utils.commons.commons.os.posix import is_posix as is_posix
+from vt.utils.commons.commons.os.posix import not_posix as not_posix

vt/utils/commons/commons/os/_base_utils.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Internal reusable common utilities, interfaces and implementations for python projects related to operating systems.
+"""
+
+import os
+import platform
+
+
+def _is_platform(platform_name: str) -> bool:
+    return platform.system() == platform_name
+
+
+def _is_os_name(os_name: str) -> bool:
+    return os.name == os_name

vt/utils/commons/commons/os/linux.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to Linux operating system.
+"""
+
+from vt.utils.commons.commons.os._base_utils import _is_platform
+
+LINUX_ID_STR = "Linux"
+"""
+Linux OS determined by python using this string.
+
+https://docs.python.org/3/library/platform.html#platform.system
+"""
+
+
+def not_linux() -> bool:
+    """
+    :return: ``True`` if system is not linux. ``False`` otherwise.
+    """
+    return not is_linux()
+
+
+def is_linux() -> bool:
+    """
+    :return: ``True`` if system is linux. ``False`` otherwise.
+    """
+    return _is_platform(LINUX_ID_STR)

vt/utils/commons/commons/os/mac.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to Mac operating system.
+"""
+
+from vt.utils.commons.commons.os._base_utils import _is_platform
+
+MAC_ID_STR = "Darwin"
+"""
+Mac OS determined by python using this string.
+
+https://docs.python.org/3/library/platform.html#platform.system
+"""
+
+
+def not_mac() -> bool:
+    """
+    :return: ``True`` if system is not mac. ``False`` otherwise.
+    """
+    return not is_mac()
+
+
+def is_mac() -> bool:
+    """
+    :return: ``True`` if system is mac. ``False`` otherwise.
+    """
+    return _is_platform(MAC_ID_STR)

vt/utils/commons/commons/os/posix.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to POSIX operating system
+families.
+"""
+
+from vt.utils.commons.commons.os._base_utils import _is_os_name
+
+POSIX_ID_STR = "posix"
+"""
+POSIX OS families are determined by python using this string.
+
+https://docs.python.org/3/library/os.html#os.name
+"""
+
+
+def not_posix() -> bool:
+    """
+    :return: ``True`` if system is not POSIX. ``False`` otherwise.
+    """
+    return not is_posix()
+
+
+def is_posix() -> bool:
+    """
+    :return: ``True`` if system is POSIX. ``False`` otherwise.
+    """
+    return _is_os_name(POSIX_ID_STR)

vt/utils/commons/commons/os/windows.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to Windows operating system.
+"""
+
+from vt.utils.commons.commons.os._base_utils import _is_platform
+
+WINDOWS_ID_STR = "Windows"
+"""
+Windows OS determined by python using this string.
+
+https://docs.python.org/3/library/platform.html#platform.system
+"""
+
+
+def not_windows() -> bool:
+    """
+    :return: ``True`` if system is not windows. ``False`` otherwise.
+    """
+    return not is_windows()
+
+
+def is_windows() -> bool:
+    """
+    :return: ``True`` if system is windows. ``False`` otherwise.
+    """
+    return _is_platform(WINDOWS_ID_STR)

vt/utils/commons/commons/state/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to states and state variables.
+"""
+
+from vt.utils.commons.commons.state.done import DoneEnquirer as DoneEnquirer
+from vt.utils.commons.commons.state.done import DoneMarker as DoneMarker
+from vt.utils.commons.commons.state.done import DoneVisitor as DoneVisitor
+from vt.utils.commons.commons.state.done import (
+    DelegatingDoneVisitor as DelegatingDoneVisitor,
+)

vt/utils/commons/commons/state/done.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# coding=utf-8
+
+"""
+Reusable common utilities, interfaces and implementations for python projects related to states and state variables
+marking and enquiring ``done`` state.
+"""
+
+from abc import abstractmethod
+from collections.abc import Sequence
+from typing import Protocol, override
+
+from vt.utils.commons.commons.collections import get_first_true, get_last_true
+
+
+class DoneMarker[T](Protocol):
+    """
+    Interface to facilitate marking as operation as ``done``.
+    """
+
+    @abstractmethod
+    def mark_done(self, _id: T) -> bool:
+        """
+        Mark an ``_id`` as ``done`` in the system. Returns ``True`` when ``_id`` is marked ``done`` to represent a
+        logical truthy and done state.
+
+        :param _id: any id.
+        :return: ``True`` if marking is done, ``False`` if marking is not to be done for a dry-run or if ``_id``
+            is already marked done.
+        :raise Exception: on underlying system error.
+        """
+        ...
+
+
+class DoneEnquirer[T](Protocol):
+    """
+    Interface to facilitate checkin whether an operation is marked as ``done``.
+    """
+
+    @abstractmethod
+    def is_done(self, _id: T) -> bool:
+        """
+        Check whether the supplied ``_id`` is marked ``done`` in the system. Returns ``True`` when ``_id`` is marked
+        ``done`` to represent a logical truthy and done state.
+
+        :param _id: any id.
+        :return: ``True`` if marking is done, ``False`` if marking is not done.
+        :raise Exception: on underlying system error.
+        """
+        ...
+
+    def get_first_done(self, ids: Sequence[T], default_val: T) -> T:
+        """
+        Get the first id which is marked as ``done`` else get the ``default_val``.
+
+        Examples:
+
+          * Doctest setup:
+            >>> from typing import Any
+            >>> class AlwaysDone(DoneEnquirer[Any]):
+            ...     def __init__(self, marking: bool):
+            ...         self.marking = marking
+            ...
+            ...     def is_done(self, _id: Any) -> bool:
+            ...         return self.marking
+
+        * First id is returned if all are marked done::
+
+            >>> AlwaysDone(True).get_first_done([1, 2, 3], -1)
+            1
+
+        * Default id is returned if none are marked done::
+
+            >>> AlwaysDone(False).get_first_done([1, 2, 3], -1)
+            -1
+
+        :param ids: sequence of id(s) from which the first ever ``done`` id is to be found.
+        :param default_val: value returned if no id is marked as ``done`` from the ``ids`` list.
+        :return: the first id from the list of ``ids`` which is marked ``done`` by the ``done_enquirer`` or
+            ``default_val`` if no id was identified as ``done``.
+        """
+        return get_first_true(ids, default_val, self.is_done)
+
+    def get_last_done(self, ids: Sequence[T], default_val: T) -> T:
+        """
+        Get the last id which is marked as ``done`` else get the ``default_val``.
+
+        Examples:
+
+          * Doctest setup:
+
+            >>> from typing import Any
+            >>> class AlwaysDone(DoneEnquirer[Any]):
+            ...     def __init__(self, marking: bool):
+            ...         self.marking = marking
+            ...
+            ...     def is_done(self, _id: Any) -> bool:
+            ...         return self.marking
+
+        * Last id is returned if all are marked done::
+
+            >>> AlwaysDone(True).get_last_done([1, 2, 3], -1)
+            3
+
+        * Default id is returned if none are marked done::
+
+            >>> AlwaysDone(False).get_last_done([1, 2, 3], -1)
+            -1
+
+        :param ids: sequence of id(s) from which the last ``done`` id is to be found.
+        :param default_val: value returned if no id is marked as ``done`` from the ``ids`` list.
+        :return: the last id from the list of ``ids`` which is marked ``done`` by the ``done_enquirer`` or
+            ``default_val`` if no id was identified as ``done``.
+        """
+        return get_last_true(ids, default_val, self.is_done)
+
+
+class DoneVisitor[T](DoneMarker[T], DoneEnquirer[T], Protocol):
+    """
+    Interface for:
+
+    * Marking the operation as done. Supplied by ``DoneMarker``.
+    * Checking whether an operation is marked as done. Supplied by ``DoneEnquirer``.
+    """
+
+    pass
+
+
+class DelegatingDoneVisitor[T](DoneVisitor[T], Protocol):
+    """
+    A ``DoneVisitor`` that stores references to the supplied ``DoneMarker`` and ``DoneEnquirer``.
+
+    Created to facilitate composition over inheritance and hence each of its components, i.e.:
+
+    * ``done_marker``
+    * ``done_enquirer``
+
+    Can be initialised at runtime.
+    """
+
+    @property
+    @abstractmethod
+    def done_marker(self) -> DoneMarker[T]:
+        """
+        :return: stored ``DoneMarker``.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def done_enquirer(self) -> DoneEnquirer[T]:
+        """
+        :return: stored ``DoneEnquirer``.
+        """
+        ...
+
+    @override
+    def mark_done(self, _id: T) -> bool:
+        return self.done_marker.mark_done(_id)
+
+    @override
+    def is_done(self, _id: T) -> bool:
+        return self.done_enquirer.is_done(_id)

vt_commons-0.0.1.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: vt-commons
+Version: 0.0.1
+Summary: Reusable common utilities, interfaces and implementations for python projects.
+Author-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
+Maintainer-email: Suhas Krishna Srivastava <suhas.srivastava@vaastav.tech>
+License-Expression: Apache-2.0
+Project-URL: homepage, https://github.com/Vaastav-Technologies/py-commons
+Project-URL: source, https://github.com/Vaastav-Technologies/py-commons
+Project-URL: issues, https://github.com/Vaastav-Technologies/py-commons/issues
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# vt-commons
+
+[![🔧 test](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/test.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/test.yml)
+[![💡 typecheck](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/typecheck.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/typecheck.yml)
+[![🛠️ lint](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/lint.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/lint.yml)
+[![📊 coverage](https://codecov.io/gh/Vaastav-Technologies/py-commons/branch/main/graph/badge.svg)](https://codecov.io/gh/Vaastav-Technologies/py-commons)
+[![📤 Upload Python Package](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Vaastav-Technologies/py-commons/actions/workflows/python-publish.yml)
+
+---
+Commons methods, utils, interfaces and implementations for python projects.
+
+### Install
+
+```shell
+pip install vt-commons
+```
+
+#### Usage examples
+
+- Check for OS
+    ```python
+    from vt.utils.commons.commons.os import is_windows
+
+    is_windows()
+    ```
+    Check in `vt.utils.commons.commons.os` and documentation for more functions and utilities related to OS.
+- Perform some operation on a root directory
+    ```python
+    from vt.utils.commons.commons.op import RootDirOp, CWDRootDirOp, RootDirOps
+    from pathlib import Path
+
+    class MyRootDirectoryOperation(RootDirOp):
+        ...
+        @property
+        def root_dir(self)-> Path:
+            return Path('path', 'to', 'my', 'root-directory')
+
+    certain_root_dir_operation: CWDRootDirOp = RootDirOps.from_path(Path('path', 'to', 'my', 'root-directory'))
+    ```
+    Check in `vt.utils.commons.commons.op` and documentation for more functions and utilities related to operations.
+- Perform state operations
+    ```python
+    from vt.utils.commons.commons.state import DoneMarker
+
+    # Track state by marking done
+    class MyStateManager(DoneMarker[int]):
+        def __init__(self, *args, **kwargs):
+            self.id_state = {1: False}
+            ...
+
+        def mark_done(self, _id: int)-> bool:
+            # mark done for _id
+            if self.id_state[_id] is True:
+                return False
+            self.id_state[_id] = True
+            return True
+    ```
+    Check in `vt.utils.commons.commons.state` and documentation for more functions and utilities related to tracking state.
+- Check if a value is `MISSING`
+    ```python
+    from vt.utils.commons.commons.core_py import MISSING, Missing, is_missing
+
+    def some_operation(arg: Missing = MISSING):
+        """
+        ``MISSING`` can be used as a default value sentinel when ``None`` is a valid value for arg.
+        """
+        arg = 10 if is_missing(arg) else arg
+        ...
+    ```
+    Check in `vt.utils.commons.commons.core_py` and documentation for more functions and utilities related to function management.
+- Query and operate on iterables
+    ```python
+    from vt.utils.commons.commons.collections import get_first_true
+
+    assert 3 == get_first_true([1, 3, 5, 7, 2, 1], 8, lambda x: x>2)
+    ```
+    Check in `vt.utils.commons.commons.collections` and documentation for more functions and utilities related to collection management.
+
+
+### Contribute
+
+Want to contribute?
+
+Checkout [Guidelines for contributions](CONTRIBUTING.md).

vt_commons-0.0.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+vt/utils/commons/commons/__init__.py,sha256=xHXyqVRavmIrOdLyWUtprNyQSp4QO_kK-_rqS0rg8Nk,126
+vt/utils/commons/commons/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vt/utils/commons/commons/collections/__init__.py,sha256=eg1ur18wdljA6lfttw48z2qJNpKKGWXuqgH_xRMC8Gw,324
+vt/utils/commons/commons/collections/utils.py,sha256=x3uwXOk2MdaASYqbyMpZAGqahR6NV1tZGQtC81bjziw,4152
+vt/utils/commons/commons/core_py/__init__.py,sha256=fCs6ZGwRLH_y2d6Mzvyqd5IA013zY_SLt68AxPEKrTg,1717
+vt/utils/commons/commons/core_py/base.py,sha256=yNwgTgbVqoF8Obx8jR0BdvZE57drXGmsBCed057udRA,799
+vt/utils/commons/commons/core_py/utils.py,sha256=4ru1xvcHFyxNriL8ivELWkiKsDzVFNypMv7t1nB5t90,27512
+vt/utils/commons/commons/op/__init__.py,sha256=UH7ADJcCFHsCfRKzyijmax1UlmcY3FaFTggtZZFX-i0,435
+vt/utils/commons/commons/op/base.py,sha256=Cv5fYOamCG3S_VbpUoTQ-0lZmo9hypy2LOd4LU3QZyQ,3509
+vt/utils/commons/commons/os/__init__.py,sha256=dxmmjYwJxKQ2TbTihWM46kPm7dMCPvVA90tBqQhRWbA,703
+vt/utils/commons/commons/os/_base_utils.py,sha256=HOrGP7Yp7YjgAOvZNpe02KUqH7s_v8f7V_tA_Vm-MyI,356
+vt/utils/commons/commons/os/linux.py,sha256=JRlr2Uy2WMoVIlmiB3oq6sVjFrhOwy8kiv7hcAKfiOc,651
+vt/utils/commons/commons/os/mac.py,sha256=xPDWyWHdgID8SSUUs4Zh997ihNsR-KRvSG5lM6n2XoY,634
+vt/utils/commons/commons/os/posix.py,sha256=V8kij7pGDXj6uJWWf4gUhjzYlBMDMKvWqcVJALNx3ec,657
+vt/utils/commons/commons/os/windows.py,sha256=fJeVn0cdNplzPOiJbeGY8yyriug28Jei1WGKaLBFJFw,671
+vt/utils/commons/commons/state/__init__.py,sha256=sKFo9_VSnv_VyFlnzUnET7_QkKnqXYrj9cEU1u3w83I,494
+vt/utils/commons/commons/state/done.py,sha256=fGs0yNWgwRwm44gzmR6FNX7NKq7-39rEnsri9ztyZ4o,5146
+vt_commons-0.0.1.dist-info/licenses/LICENSE,sha256=pOzr5bMWS6mHi3vro8d5vw0qW1i14rVq2XFrDuystVY,11372
+vt_commons-0.0.1.dist-info/METADATA,sha256=M-_m3IVJCzejea3o2OAm0uOmWMivNE8JXBF1nFIuyHQ,4718
+vt_commons-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+vt_commons-0.0.1.dist-info/top_level.txt,sha256=aN5KWgJq84W0MDifCX3yRJAp04FH7pd5PDh7qa2P8sM,3
+vt_commons-0.0.1.dist-info/RECORD,,

vt_commons-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+