agapsys-utils 0.0.0__tar.gz

agapsys_utils-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leandro José Britto de Oliveira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agapsys_utils-0.0.0/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: agapsys-utils
+Version: 0.0.0
+Summary: Common utilities
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# agapsys-utils
+
+This project provides general purpose utiltities that individually thet do not fit in a dedicated library.
+
+## License
+
+m-conf is distributed under MIT License. Please see the [LICENSE](LICENSE) file for details on copying and distribution.
+
+## Basic usage
+
+  ```py
+  import agapsys.utils as utils
+
+  # That's it... use the available modules
+  ```

agapsys_utils-0.0.0/README.md

@@ -0,0 +1,15 @@
+# agapsys-utils
+
+This project provides general purpose utiltities that individually thet do not fit in a dedicated library.
+
+## License
+
+m-conf is distributed under MIT License. Please see the [LICENSE](LICENSE) file for details on copying and distribution.
+
+## Basic usage
+
+  ```py
+  import agapsys.utils as utils
+
+  # That's it... use the available modules
+  ```

agapsys_utils-0.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires      = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name            = "agapsys-utils"
+version         = "0.0.0"
+description     = "Common utilities"
+readme          = "README.md"
+license         = "MIT"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "twine",
+    "pytest>=7.0",
+    "pytest-cov"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest]
+addopts    = []
+testpaths  = ["tests"]
+pythonpath = ["src"]

agapsys_utils-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agapsys_utils-0.0.0/src/agapsys/utils/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Leandro José Britto de Oliveira
+# Licensed under the MIT License.

agapsys_utils-0.0.0/src/agapsys/utils/assertions.py

@@ -0,0 +1,104 @@
+# Copyright (c) 2026 Leandro José Britto de Oliveira
+# Licensed under the MIT License.
+
+from typing import Any, Type
+
+import builtins
+
+def check(condition: bool, exc_type: Type[BaseException], err_msg: str | None = None) -> bool:
+    """
+    Asserts a given condition is `True`.
+
+    Args:
+        condition (bool): Condition which must evaluate to `True`.
+        exc_type (Type[BaseException]): Type of the exception to be raised if condition is `False`.
+        err_msg (str | None, optional): Custom error message used if assertion fails.
+
+    Raises:
+        exc_type: If condition is `False`.
+
+    Returns:
+        bool: If function returns, it will always return `True`.
+    """
+    assert builtins.isinstance(condition, bool)
+    assert builtins.issubclass(exc_type, BaseException)
+    assert builtins.isinstance(err_msg, (str, type(None)))
+
+    if not condition:
+        if err_msg is None:
+            err_msg = "Condition is False"
+
+        raise exc_type(err_msg)
+
+    return True
+
+def isinstance(obj: Any, class_or_tuple: Type | tuple[Type, ...], err_msg: str | None = None) -> bool:
+    """
+    Standardized assert for isinstance checks.
+
+    Args:
+        obj (Any):
+            Inspected object.
+
+        class_or_tuple (type | tuple[type, ...]):
+            A type or a list of types.
+
+        err_msg (str | None, optional):
+            Custom error message used if assertion fails.
+
+    Raises:
+        TypeError: If `obj` is not an instance of expected types.
+
+    Returns:
+        bool: If function returns, it will always return `True`.
+    """
+    return check(
+        builtins.isinstance(obj, class_or_tuple),
+        TypeError,
+        f"Invalid type: {'None' if type(obj) == type(None) else type(obj).__name__}" if err_msg is None else err_msg
+    )
+
+def issubclass(cls: Type, class_or_tuple: Type | tuple[Type, ...], err_msg: str | None = None) -> bool:
+    """
+    Standardized assert for issubclass checks.
+
+    Args:
+        cls (Type):
+            Inspected given type.
+
+        class_or_tuple (type | tuple[type, ...]):
+            Accepted parent classes.
+
+        err_msg (str | None, optional):
+            Custom error message used if assertion fails.
+
+    Raises:
+        TypeError: If `cls` is not a subclass of any of provided types.
+
+    Returns:
+        bool: If function returns, it will always return `True`.
+    """
+    return check(
+        builtins.issubclass(cls, class_or_tuple),
+        TypeError,
+        f"{cls.__name__} is not a valid type" if err_msg is None else err_msg
+    )
+
+def check_value(condition: bool, err_msg: str | None = None) -> bool:
+    """
+    Standardized way of check if a value meets a certain criteria.
+
+    Args:
+        condition (bool):
+            Tested condition.
+
+        var_name (str, optional):
+            Variable name (used upon error).
+
+        err_msg (str | None, optional):
+            Custom error message used if assertion fails.
+
+    Raises:
+        ValueError: If `condition` is `False`.
+    """
+    return check(condition, ValueError, err_msg)

agapsys_utils-0.0.0/src/agapsys/utils/proc.py

@@ -0,0 +1,420 @@
+# Copyright (c) 2026 Leandro José Britto de Oliveira
+# Licensed under the MIT License.
+
+from .           import assertions
+from abc         import ABC, abstractmethod
+from dataclasses import dataclass
+from io          import IOBase, BytesIO, TextIOWrapper
+from typing      import Any, IO
+
+import locale
+import os
+import selectors
+import shlex
+import subprocess
+import sys
+import time
+
+@dataclass(frozen=True)
+class Result:
+    """
+    Process execution result.
+
+    Args:
+        exit_code (int): Process exit code.
+
+        stdout (str | bytes | None):
+            Data captured from process stdout. It process was open in text mode,
+            it is a string, otherwise it is composed by raw bytes. If capturing
+            was not set during process creation, it is `None`.
+
+        stderr (str | bytes | None):
+            Data captured from process stderr. It process was open in text mode,
+            it is a string, otherwise it is composed by raw bytes. If capturing
+            was not set during process creation, it is `None`.
+    """
+    exit_code: int
+    stdout: str | bytes | None
+    stderr: str | bytes | None
+
+class Error(Exception):
+    """
+    Process execution error.
+    """
+
+    def __init__(self, result: Result) -> None:
+        """
+        Process execution error.
+
+        Args:
+            result (Result): Execution result.
+        """
+        assertions.isinstance(result, Result)
+        assertions.check_value(result.exit_code != 0)
+
+        super().__init__(f"Process exited with code {result.exit_code}")
+        self.__result = result
+
+    @property
+    def result(self) -> Result:
+        """
+        Execution result.
+
+        Returns:
+            Result: Execution result.
+        """
+        return self.__result
+
+class Listener(ABC):
+    """
+    Listener for a process.
+    """
+    @classmethod
+    def decode(cls, data: bytes) -> str:
+        """
+        Decodes raw bytes into a string using system defaults.
+
+        Args:
+            data (bytes): raw bytes.
+
+        Returns:
+            str: Decoded string.
+        """
+
+        if not hasattr(Listener.decode, "encoding"):
+            encoding = locale.getpreferredencoding(False)
+
+        return data.decode(encoding, errors="replace")
+
+    def __init__(self, interactive: bool = True):
+        """
+        Listener for a process.
+
+        Args:
+            interactive (bool, optional):
+                Defines if this listener interacts with the process.
+                Defaults to True.
+        """
+        assertions.isinstance(interactive, bool)
+        self.__interactive = interactive
+        super().__init__()
+
+    @property
+    def interactive(self) -> bool:
+        """_summary_
+
+        Returns:
+            bool: _description_
+        """
+        return self.__interactive
+
+    def on_open(self, stdin: IOBase | None):
+        """
+        Called upon process start.
+
+        Default implementation does nothing.
+
+        Args:
+            stdin (IOBase | None):
+                Process stdin. Use it to send data to the process. If listener
+                is interactive, this will be a valide pipe to communicate
+                with the process. Otherwise, it is `None`.
+        """
+        pass
+
+    @abstractmethod
+    def on_read(
+        self,
+        stdin: IOBase | None,
+        stdout_data: str | bytes | None,
+        stderr_data: str | bytes | None
+    ):
+        """Called upon data is read from the process.
+
+        This is an abstract method.
+
+        Args:
+            stdin (IOBase):
+                Process stdin. Use it to send data to the process. If listener
+                is interactive, this will be a valide pipe to communicate
+                with the process. Otherwise, it is `None`.
+
+            stdout_data (str | bytes | None):
+                Read data. `None` if no data was read from stdout.
+                If process was open in text mode, this argument will be a
+                string. Otherwise it will be raw data.
+
+            stderr_data (str | bytes | None):
+                Read data. `None` if no data was read from stderr.
+                If process was open in text mode, this argument will be a
+                string. Otherwise it will be raw data.
+        """
+        pass
+
+    def on_close(self, exit_code: int):
+        """
+        Called upon process finish.
+
+        Default implementation does nothing.
+
+        Args:
+            exit_code (int):
+                Process exit code.
+        """
+        pass
+
+def open(
+    cmd: str|list[str],
+    text_mode: bool = True,
+    env: dict[str, str] | None = None,
+    stdin: IO[Any] | None = None,
+    stdout: IO[Any] | None = None,
+    stderr: IO[Any] | None = None,
+    capture_output: bool = False,
+    listener: Listener | None = None,
+    check_exit: bool = False,
+    timeout: float | None = None
+) -> Result:
+    """
+    Executes a process and wait for its completion.
+
+    Args:
+        cmd (str | list[str]):
+            Command to be executed.
+
+        text_mode (bool, Optional):
+            Interpret output as text. Defaults to `True`.
+
+        env (dict[str, str] | None, Optional):
+            Custom environment for the process. Passsing `None` means inheriting
+            parent environment. Defaults to `None`.
+
+        stdin (IOBase, Optional):
+            IOBase instance to attach to process stdin. Defaults to `None`.
+
+        stdout (IOBase | None, Optional):
+            IOBase instance to attach to process stdout. Defaults to `None`.
+
+        stderr (IOBase | None, Optional):
+            IOBase instance to attach to process stderr. Defaults to `None`.
+
+        capture_output (bool, Optional):
+            Defines if output shall be captured to be read after process
+            finishes.
+
+        listener (Listener | None, Optional):
+            Listener instance used to monitor/interact with process. Defaults
+            to `None`. NOTE: It is not possible to pass an interactive
+            listener along with `stdin`.
+
+        check_exit (bool, Optional):
+            If `True`, raises an _Error_ if exit code is not zero.
+
+        timeout (int | None):
+            Timeout (in seconds) waiting for process to terminate. Passing
+            `None` means waiting until ti finishes. Defaults to `None`
+
+    Raises:
+        Error:
+            If process exited with a non-zero code and `check_exit` is `True`.
+
+        TimeoutError:
+            If a timeout was reached an process did not terminate (it will
+            be killed).
+
+        ValueError:
+            If `stdin` was given along with an interactive `listener`.
+
+    Returns:
+        Result: Result of process execution (note that function does not return
+        if process exited with a non-zero value and `check_exit` was `True`. For
+        this case use raised exception to get details about execution result).
+    """
+    assertions.check_value(assertions.isinstance(cmd, (str, list)) and bool(cmd))
+    assertions.isinstance(text_mode, bool)
+    assertions.isinstance(env, (dict, type(None)))
+    assertions.isinstance(stdin, (type(None), IOBase))
+    assertions.isinstance(stdout, (type(None), IOBase))
+    assertions.isinstance(stderr, (type(None), IOBase))
+    assertions.isinstance(capture_output, bool)
+    assertions.isinstance(check_exit, bool)
+    assertions.isinstance(listener, (type(None), Listener))
+    assertions.isinstance(timeout, (float, int, type(None)))
+
+    if timeout is not None:
+        if isinstance(timeout, int):
+            timeout = float(timeout)
+
+        assert timeout > 0.0
+
+    if isinstance(cmd, str):
+        cmd = shlex.split(cmd)
+
+    if stdin is None:
+        proc_stdin = subprocess.DEVNULL # proc.stdin is None
+    else:
+        if listener is not None and listener.interactive:
+            raise ValueError("Cannot pass an interactive listener along with stdin")
+
+        if stdin is sys.stdin:
+            proc_stdin = None # proc.stdin is None (process inherits parent)
+        else:
+            proc_stdin = stdin # proc.stdin is NOT None and it will be provided one
+
+    if listener is not None and listener.interactive:
+        proc_stdin = subprocess.PIPE # Listener will communicate with the process
+
+    proc = subprocess.Popen(
+        cmd,
+        stdin=proc_stdin,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=text_mode,
+        env=env
+    )
+
+    assert proc.stdout is not None
+    assert proc.stderr is not None
+
+    sel = selectors.DefaultSelector()
+
+    sel.register(proc.stdout, selectors.EVENT_READ)
+    sel.register(proc.stderr, selectors.EVENT_READ)
+
+    stdout_buffer = None if not capture_output else BytesIO()
+    stderr_buffer = None if not capture_output else BytesIO()
+
+    def decode(data: bytes) -> bytes | str:
+        """
+        Returns either given data or decoded version if `text_mode` is `True`.
+
+        Args:
+            data (bytes): raw bytes.
+
+        Returns:
+            bytes | str: `data` if `text_mode` is `False`. Otherwise, returns
+            string resulting from decoding given data.
+        """
+        if not text_mode:
+            return data
+        else:
+            return Listener.decode(data)
+
+    def read(stream: IOBase) -> bytes:
+        """
+        Read all data (raw bytes) currently available from an IO
+
+        Args:
+            stream (IOBase): IO object to read from.
+
+        Returns:
+            bytes: Read data (raw bytes).
+        """
+        chunks = []
+        while True:
+            try:
+                if isinstance(stream, TextIOWrapper):
+                    chunk = stream.buffer.read()
+                else:
+                    chunk = stream.read()
+
+                if not chunk:
+                    break
+
+                chunks.append(chunk)
+            except BlockingIOError:
+                # No more data available right now
+                break
+
+        return b"".join(chunks)
+
+        #if isinstance(stream, TextIOWrapper):
+        #    return stream.buffer.read1(chunk_size)
+        #else:
+        #    return stream.read1(chunk_size)
+
+    def write(data: bytes, stream: IO[Any]):
+        """
+        Writes raw bytes into an IO object.
+
+        Args:
+            data (bytes): Raw data to be written.
+            stream (IO[Any]): IO object.
+        """
+        if isinstance(stream, TextIOWrapper):
+            stream.buffer.write(data)
+            stream.buffer.flush()
+        else:
+            stream.write(data)
+            stream.flush()
+
+    # Make pipes non-block so it is possible to read all data available
+    # upon selector events (Works on all platforms, including Windows)
+    os.set_blocking(proc.stdout.fileno(), False)
+    os.set_blocking(proc.stderr.fileno(), False)
+
+    listener_stdin = None
+    if stdin is None and listener is not None:
+        # Pass the pipe to the listener so it can communicate with the process.
+        listener_stdin = proc.stdin
+
+    if proc.poll() is None and listener is not None:
+        listener.on_open(listener_stdin)
+
+    mark = time.perf_counter()
+    remaining: float | None = timeout
+
+    while remaining is None or remaining >= 0:
+        events = sel.select(remaining)
+        for key, _ in events:
+            while True:
+                data = read(key.fileobj)
+                decoded_data = decode(data)
+
+                if not data:
+                    break
+
+                if key.fileobj is proc.stdout:
+                    # process stdout
+                    if capture_output:
+                        stdout_buffer.write(data)
+
+                    if stdout is not None:
+                        write(data, stdout)
+
+                    if listener is not None:
+                        listener.on_read(listener_stdin, decoded_data, None)
+
+                elif key.fileobj is proc.stderr:
+                    # process stderr
+                    if capture_output:
+                        stderr_buffer.write(data)
+
+                    if stderr:
+                        write(data, stderr)
+
+                    if listener is not None:
+                        listener.on_read(listener_stdin, None, decoded_data)
+
+        # If process exited, break
+        if proc.poll() is not None:
+            exit_code = proc.wait()
+
+            if listener is not None:
+                listener.on_close(exit_code)
+
+            stdout_data = None if not capture_output else decode(stdout_buffer.getvalue())
+            stderr_data = None if not capture_output else decode(stderr_buffer.getvalue())
+
+            result = Result(exit_code, stdout_data, stderr_data)
+
+            if exit_code != 0 and check_exit:
+                raise Error(result)
+
+            return result
+
+        elapsed = time.perf_counter() - mark
+        remaining = None if remaining is None else remaining - elapsed
+
+    proc.kill()
+    raise TimeoutError()

agapsys_utils-0.0.0/src/agapsys_utils.egg-info/PKG-INFO

@@ -0,0 +1,30 @@
+Metadata-Version: 2.4
+Name: agapsys-utils
+Version: 0.0.0
+Summary: Common utilities
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# agapsys-utils
+
+This project provides general purpose utiltities that individually thet do not fit in a dedicated library.
+
+## License
+
+m-conf is distributed under MIT License. Please see the [LICENSE](LICENSE) file for details on copying and distribution.
+
+## Basic usage
+
+  ```py
+  import agapsys.utils as utils
+
+  # That's it... use the available modules
+  ```

agapsys_utils-0.0.0/src/agapsys_utils.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/agapsys/utils/__init__.py
+src/agapsys/utils/assertions.py
+src/agapsys/utils/proc.py
+src/agapsys_utils.egg-info/PKG-INFO
+src/agapsys_utils.egg-info/SOURCES.txt
+src/agapsys_utils.egg-info/dependency_links.txt
+src/agapsys_utils.egg-info/requires.txt
+src/agapsys_utils.egg-info/top_level.txt

agapsys_utils-0.0.0/src/agapsys_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agapsys_utils-0.0.0/src/agapsys_utils.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+build
+twine
+pytest>=7.0
+pytest-cov

agapsys_utils-0.0.0/src/agapsys_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+agapsys