pybasemkit 0.0.1__py3-none-any.whl

basemkit/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

basemkit/base_cmd.py

@@ -0,0 +1,215 @@
+"""
+Created on 2025-06-16
+
+Minimal reusable command line base class with standard options.
+
+@author: wf
+"""
+
+import sys
+import traceback
+import webbrowser
+from argparse import ArgumentParser, Namespace, RawDescriptionHelpFormatter
+
+
+class BaseCmd:
+    """
+    Minimal reusable command line base class with standard options:
+    --about, --debug, --force, --quiet, --verbose, --version.
+
+    Intended to be subclassed by tools requiring consistent CLI behavior.
+    """
+
+    def __init__(self, version, description: str = None):
+        """
+        Initialize the BaseCmd instance.
+
+        Args:
+            version: An object with .name, .version, .description, and .doc_url attributes.
+            description (str): Optional CLI description. Defaults to version.description.
+        """
+        self.version = version
+        self.description = description or self.version.description
+        self.program_version_message = f"{self.version.name} {self.version.version}"
+        self.debug = False
+        self.quiet = False
+        self.verbose = False
+        self.force = False
+        self.parser = None
+        self.args = None
+
+    def add_arguments(self, parser: ArgumentParser):
+        """
+        Add standard CLI arguments to the parser, sorted by long option name.
+
+        Args:
+            parser (ArgumentParser): The parser to add arguments to.
+        """
+        parser.add_argument(
+            "-a", "--about",
+            action="store_true",
+            help="show version info and open documentation"
+        )
+        parser.add_argument(
+            "-d", "--debug",
+            action="store_true",
+            help="enable debug output"
+        )
+        parser.add_argument(
+            "--debugLocalPath",
+            help="remote debug Server path mapping - localPath - path on machine where python runs"
+        )
+        parser.add_argument(
+            "--debugPort",
+            type=int,
+            default=5678,
+            help="remote debug Port [default: %(default)s]"
+        )
+        parser.add_argument(
+            "--debugRemotePath",
+            help="remote debug Server path mapping - remotePath - path on debug server"
+        )
+        parser.add_argument(
+            "--debugServer",
+            help="remote debug Server"
+        )
+        parser.add_argument(
+            "-f", "--force",
+            action="store_true",
+            help="force overwrite or unsafe actions"
+        )
+        parser.add_argument(
+            "-q", "--quiet",
+            action="store_true",
+            help="suppress all output"
+        )
+        parser.add_argument(
+            "-v", "--verbose",
+            action="store_true",
+            help="increase output verbosity"
+        )
+        parser.add_argument(
+            "-V", "--version",
+            action="version",
+            version=self.program_version_message
+        )
+
+
+    def get_arg_parser(self) -> ArgumentParser:
+        """
+        Create and configure the argument parser.
+
+        Returns:
+            ArgumentParser: The configured argument parser.
+        """
+        parser = ArgumentParser(description=self.description, formatter_class=RawDescriptionHelpFormatter)
+        self.add_arguments(parser)
+        return parser
+
+    def parse_args(self, argv=None) -> Namespace:
+        """
+        Parse command line arguments.
+
+        Args:
+            argv (list): Optional list of command line arguments. Defaults to sys.argv.
+
+        Returns:
+            Namespace: Parsed argument values.
+        """
+        if self.parser is None:
+            self.parser = self.get_arg_parser()
+        self.args = self.parser.parse_args(argv)
+        return self.args
+
+    def optional_debug(self, args: Namespace):
+        """
+        Optionally start remote debugging if debugServer is specified.
+
+        Args:
+            args (Namespace): Parsed CLI arguments
+        """
+        if args.debugServer:
+            import pydevd
+            import pydevd_file_utils
+
+            remote_path = args.debugRemotePath
+            local_path  = args.debugLocalPath
+
+            if remote_path and local_path:
+                pydevd_file_utils.setup_client_server_paths([(remote_path, local_path)])
+
+            pydevd.settrace(
+                args.debugServer,
+                port=args.debugPort,
+                stdoutToServer=True,
+                stderrToServer=True,
+            )
+            print("Remote debugger attached.")
+
+
+    def handle_args(self, args: Namespace) -> bool:
+        """
+        Handle parsed arguments. Intended to be overridden in subclasses.
+
+        Args:
+            args (Namespace): Parsed argument namespace.
+
+        Returns:
+            bool: True if argument was handled and no further processing is required.
+        """
+        self.args = args
+        self.debug = args.debug
+        self.quiet = args.quiet
+        self.verbose = args.verbose
+        self.force = args.force
+        self.optional_debug(args)
+        if args.about:
+            print(self.program_version_message)
+            print(f"see {self.version.doc_url}")
+            webbrowser.open(self.version.doc_url)
+            return True
+
+        return False
+
+    def run(self, argv=None) -> int:
+        """
+        Execute the command line logic.
+
+        Args:
+            argv (list): Optional command line arguments.
+
+        Returns:
+            int: Exit code: 0 = OK, 1 = KeyboardInterrupt, 2 = Exception.
+        """
+        try:
+            args = self.parse_args(argv)
+            handled = self.handle_args(args)
+            exit_code = 0
+            if not handled:
+                exit_code = 0
+        except KeyboardInterrupt:
+            exit_code = 1
+        except Exception as e:
+            if self.debug:
+                raise
+            sys.stderr.write(f"{self.version.name}: {e}\n")
+            if getattr(self, "args", None) and self.args.debug:
+                sys.stderr.write(traceback.format_exc())
+            exit_code = 2
+        return exit_code
+
+    @classmethod
+    def main(cls, version, argv=None) -> int:
+        """
+        Entry point for scripts using this command line interface.
+
+        Args:
+            version: Version metadata object passed to constructor.
+            argv (list): Optional command line arguments.
+
+        Returns:
+            int: Exit code from `run()`.
+        """
+        instance = cls(version)
+        exit_code = instance.run(argv)
+        return exit_code

basemkit/basetest.py

@@ -0,0 +1,97 @@
+"""
+Created on 2021-08-19
+
+@author: wf
+"""
+
+import getpass
+import os
+import threading
+import unittest
+from functools import wraps
+from typing import Callable
+
+from basemkit.profiler import Profiler
+
+
+class Basetest(unittest.TestCase):
+    """
+    base test case
+    """
+
+    def setUp(self, debug=False, profile=True):
+        """
+        setUp test environment
+        """
+        unittest.TestCase.setUp(self)
+        self.debug = debug
+        self.profile = profile
+        msg = f"test {self._testMethodName}, debug={self.debug}"
+        self.profiler = Profiler(msg, profile=self.profile)
+
+    def tearDown(self):
+        unittest.TestCase.tearDown(self)
+        self.profiler.time()
+
+    @staticmethod
+    def inPublicCI():
+        """
+        are we running in a public Continuous Integration Environment?
+        """
+        publicCI = getpass.getuser() in ["travis", "runner"]
+        jenkins = "JENKINS_HOME" in os.environ
+        return publicCI or jenkins
+
+    @staticmethod
+    def isUser(name: str):
+        """Checks if the system has the given name"""
+        return getpass.getuser() == name
+
+    @staticmethod
+    def timeout(seconds: float) -> Callable:
+        """
+        Decorator to enforce a timeout on test methods.
+
+        Args:
+            seconds (float): Timeout duration in seconds.
+
+        Returns:
+            Callable: A decorator that wraps a function and raises TimeoutError
+                      if it exceeds the allowed execution time.
+
+        Raises:
+            TimeoutError: If the wrapped function exceeds the timeout.
+            Exception: If the wrapped function raises any other exception.
+        """
+
+        def decorator(func):
+            @wraps(func)
+            def wrapper(*args, **kwargs):
+                result = [None]
+                exception = [None]
+
+                def target():
+                    try:
+                        result[0] = func(*args, **kwargs)
+                    except Exception as e:
+                        exception[0] = e
+
+                thread = threading.Thread(target=target)
+                thread.start()
+                thread.join(seconds)
+
+                if thread.is_alive():
+                    raise TimeoutError(f"Test timed out after {seconds} seconds")
+
+                if exception[0] is not None:
+                    raise exception[0]
+
+                return result[0]
+
+            return wrapper
+
+        return decorator
+
+
+if __name__ == "__main__":
+    unittest.main()

basemkit/persistent_log.py

@@ -0,0 +1,127 @@
+"""
+Created on 2024-10-04
+
+@author: wf
+"""
+
+import logging
+from collections import Counter
+from dataclasses import field
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+from basemkit.yamlable import lod_storable
+
+# ANSI colors
+BLUE = "\033[0;34m"
+RED = "\033[0;31m"
+GREEN = "\033[0;32m"
+END_COLOR = "\033[0m"
+
+
+@lod_storable
+class LogEntry:
+    """
+    Represents a log entry with a message, kind, and log level name.
+    """
+
+    msg: str
+    kind: str
+    level_name: str
+    timestamp: Optional[str] = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.now().isoformat()
+
+
+@lod_storable
+class Log:
+    """
+    Wrapper for persistent logging.
+    """
+
+    entries: List[LogEntry] = field(default_factory=list)
+
+    def color_msg(self, color, msg):
+        """Display a colored message"""
+        print(f"{color}{msg}{END_COLOR}")
+
+    def __post_init__(self):
+        """
+        Initializes the log with level mappings and updates the level counts.
+        """
+        self.do_log = True
+        self.do_print = False
+        self.levels = {"❌": logging.ERROR, "⚠️": logging.WARNING, "✅": logging.INFO}
+        self.level_names = {
+            logging.ERROR: "error",
+            logging.WARNING: "warn",
+            logging.INFO: "info",
+        }
+        self.update_level_counts()
+
+    def clear(self):
+        """
+        Clears all log entries.
+        """
+        self.entries = []
+        self.update_level_counts()
+
+    def update_level_counts(self):
+        """
+        Updates the counts for each log level based on the existing entries.
+        """
+        self.level_counts = {"error": Counter(), "warn": Counter(), "info": Counter()}
+        for entry in self.entries:
+            counter = self.get_counter(entry.level_name)
+            if counter is not None:
+                counter[entry.kind] += 1
+
+    def get_counter(self, level: str) -> Counter:
+        """
+        Returns the counter for the specified log level.
+        """
+        return self.level_counts.get(level)
+
+    def get_level_summary(self, level: str, limit: int = 7) -> Tuple[int, str]:
+        """
+        Get a summary of the most common counts for the specified log level.
+
+        Args:
+            level (str): The log level name ('error', 'warn', 'info').
+            limit (int): The maximum number of most common entries to include in the summary (default is 7).
+
+        Returns:
+            Tuple[int, str]: A tuple containing the count of log entries and a summary message.
+        """
+        counter = self.get_counter(level)
+        if counter:
+            count = sum(counter.values())
+            most_common_entries = dict(counter.most_common(limit))  # Get the top 'limit' entries
+            summary_msg = f"{level.capitalize()} entries: {most_common_entries}"
+            return count, summary_msg
+        return 0, f"No entries found for level: {level}"
+
+    def log(self, icon: str, kind: str, msg: str):
+        """
+        Log a message with the specified icon and kind.
+
+        Args:
+            icon (str): The icon representing the log level ('❌', '⚠️', '✅').
+            kind (str): The category or type of the log message.
+            msg (str): The log message to record.
+        """
+        level = self.levels.get(icon, logging.INFO)
+        level_name = self.level_names[level]
+        icon_msg = f"{icon}:{msg}"
+        log_entry = LogEntry(msg=icon_msg, level_name=level_name, kind=kind)
+        self.entries.append(log_entry)
+
+        # Update level counts
+        self.level_counts[level_name][kind] += 1
+
+        if self.do_log:
+            logging.log(level, icon_msg)
+        if self.do_print:
+            print(icon_msg)

basemkit/profiler.py

@@ -0,0 +1,44 @@
+"""
+Created on 2022-11-18
+
+@author: wf
+"""
+
+import time
+
+
+class Profiler:
+    """
+    simple profiler
+    """
+
+    def __init__(self, msg: str, profile=True, with_start: bool = True):
+        """
+        Construct the profiler with the given message and flags.
+
+        Args:
+            msg (str): The message to show if profiling is active.
+            profile (bool): True if profiling messages should be shown.
+            with_start (bool): If True, show start message immediately.
+        """
+        self.msg = msg
+        self.profile = profile
+        if with_start:
+            self.start()
+
+    def start(self):
+        """
+        start profiling
+        """
+        self.starttime = time.time()
+        if self.profile:
+            print(f"Starting {self.msg} ...")
+
+    def time(self, extraMsg: str = ""):
+        """
+        time the action and print if profile is active
+        """
+        elapsed = time.time() - self.starttime
+        if self.profile:
+            print(f"{self.msg}{extraMsg} took {elapsed:5.1f} s")
+        return elapsed

basemkit/shell.py

@@ -0,0 +1,255 @@
+"""
+Created on 2025-05-14
+
+@author: wf
+"""
+
+import io
+import os
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Dict, List
+
+class ShellResult:
+    """
+    result of a command line call
+    """
+
+    def __init__(self, proc, success: bool):
+        self.proc = proc
+        self.success = success
+
+    def __str__(self):
+        text = self.as_text()
+        return text
+
+    def as_text(self, debug: bool = False):
+        if debug:
+            text = f"{self.proc.args} → rc={self.proc.returncode}, success={self.success}"
+        else:
+            text = "✅" if self.success else f"❌ → rc={self.proc.returncode}"
+        return text
+
+
+class StreamTee:
+    """
+    Tees a single input stream to both a mirror and a capture buffer.
+    """
+
+    def __init__(self, source, mirror, buffer, tee=True):
+        self.source = source
+        self.mirror = mirror
+        self.buffer = buffer
+        self.tee = tee
+        self.thread = threading.Thread(target=self._run, daemon=True)
+
+    def _run(self):
+        for line in iter(self.source.readline, ""):
+            if self.tee:
+                self.mirror.write(line)
+                self.mirror.flush()
+            self.buffer.write(line)
+        self.source.close()
+
+    def start(self):
+        self.thread.start()
+
+    def join(self):
+        self.thread.join()
+
+
+class SysTee:
+    """
+    Tee sys.stdout and sys.stderr to a logfile while preserving original output.
+    """
+
+    def __init__(self, log_path: str):
+        self.logfile = open(log_path, "a")
+        self.original_stdout = sys.stdout
+        self.original_stderr = sys.stderr
+        sys.stdout = self
+        sys.stderr = self
+
+    def write(self, data):
+        self.original_stdout.write(data)
+        self.logfile.write(data)
+
+    def flush(self):
+        self.original_stdout.flush()
+        self.logfile.flush()
+
+    def close(self):
+        sys.stdout = self.original_stdout
+        sys.stderr = self.original_stderr
+        self.logfile.close()
+
+
+class StdTee:
+    """
+    Manages teeing for both stdout and stderr using StreamTee instances.
+    Captures output in instance variables.
+    """
+
+    def __init__(self, process, tee=True):
+        self.stdout_buffer = io.StringIO()
+        self.stderr_buffer = io.StringIO()
+        self.out_tee = StreamTee(process.stdout, sys.stdout, self.stdout_buffer, tee)
+        self.err_tee = StreamTee(process.stderr, sys.stderr, self.stderr_buffer, tee)
+
+    def start(self):
+        self.out_tee.start()
+        self.err_tee.start()
+
+    def join(self):
+        self.out_tee.join()
+        self.err_tee.join()
+
+    @classmethod
+    def run(cls, process, tee=True):
+        """
+        Run teeing and capture for the given process.
+        Returns a StdTee instance with stdout/stderr captured.
+        """
+        std_tee = cls(process, tee=tee)
+        std_tee.start()
+        std_tee.join()
+        return std_tee
+
+
+class Shell:
+    """
+    Runs commands with environment from profile
+    """
+
+    def __init__(self, profile=None, shell_path: str = None):
+        """
+        Initialize shell with optional profile
+
+        Args:
+            profile: Path to profile file to source e.g. ~/.zprofile
+            shell_path: the shell_path e.g. /bin/zsh
+        """
+        self.profile = profile
+        self.shell_path = shell_path
+        if self.shell_path is None:
+            self.shell_path = os.environ.get("SHELL", "/bin/bash")
+        self.shell_name = os.path.basename(self.shell_path)
+        if self.profile is None:
+            self.profile = self.find_profile()
+
+    def find_profile(self) -> str:
+        """
+        Find the appropriate profile file for the current shell
+
+        Searches for the profile file corresponding to the shell_name
+        in the user's home directory.
+
+        Returns:
+            str: Path to the profile file or None if not found
+        """
+        profile = None
+        home = os.path.expanduser("~")
+        # Try common profile files
+        profiles = {"zsh": ".zprofile", "bash": ".bash_profile", "sh": ".profile"}
+        if self.shell_name in profiles:
+            profile_name = profiles[self.shell_name]
+            path = os.path.join(home, profile_name)
+            if os.path.exists(path):
+                profile = path
+        return profile
+
+    @classmethod
+    def ofArgs(cls, args):
+        """
+        Create Shell from command line args
+
+        Args:
+            args: Arguments with optional profile
+
+        Returns:
+            Shell: Configured Shell
+        """
+        # Use explicit profile or detect
+        profile = getattr(args, "profile", None)
+        shell = cls(profile=profile)
+        return shell
+
+    def run(self, cmd, text=True, debug=False, tee=False) -> subprocess.CompletedProcess:
+        """
+        Run command with profile, always capturing output and optionally teeing it.
+
+        Args:
+            cmd: Command to run
+            text: Text mode for subprocess I/O
+            debug: Print the command to be run
+            tee: If True, also print output live while capturing
+
+        Returns:
+            subprocess.CompletedProcess
+        """
+        shell_cmd = f"source {self.profile} && {cmd}" if self.profile else cmd
+
+        if debug:
+            print(f"Running: {shell_cmd}")
+
+        popen_process = subprocess.Popen(
+            [self.shell_path, "-c", shell_cmd],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=text,
+        )
+
+        std_tee = StdTee.run(popen_process, tee=tee)
+        returncode = popen_process.wait()
+
+        process = subprocess.CompletedProcess(
+            args=popen_process.args,
+            returncode=returncode,
+            stdout=std_tee.stdout_buffer.getvalue(),
+            stderr=std_tee.stderr_buffer.getvalue(),
+        )
+
+        if process.returncode != 0:
+            if debug:
+                msg = f"""{process.args} failed:
+  returncode: {process.returncode}
+  stdout    : {process.stdout.strip()}
+  stderr    : {process.stderr.strip()}
+"""
+                print(msg, file=sys.stderr)
+            pass
+
+        return process
+
+    def proc_stats(
+        self,
+        title: str,
+        procs: Dict[Path, subprocess.CompletedProcess],
+        ignores: List[str] = [],
+    ):
+        """
+        Show process statistics with checkmark/crossmark and success/failure summary.
+
+        Args:
+            title (str): A short title to label the output section.
+            procs (Dict[Path, subprocess.CompletedProcess]): Mapping of input files to their process results.
+            ignores (List[str], optional): List of substrings. If any is found in stderr, the error is ignored.
+        """
+        total = len(procs)
+        failures = 0
+        print(f"\n{total} {title}:")
+        for idx, (path, result) in enumerate(procs.items(), start=1):
+            stderr = result.stderr or ""
+            stdout = result.stdout or ""
+            ignored = any(ignore in stderr for ignore in ignores)
+            has_error = (stderr and not ignored) or ("Error" in stdout)
+            if has_error:
+                symbol = "❌"
+                failures += 1
+            else:
+                symbol = "✅"
+            print(f"{symbol} {idx}/{total}: {path.name}")
+        percent_ok = ((total - failures) / total) * 100 if total > 0 else 0
+        print(f"\n✅ {total - failures}/{total} ({percent_ok:.1f}%), ❌ {failures}/{total} ({100 - percent_ok:.1f}%)")

basemkit/yamlable.py

@@ -0,0 +1,338 @@
+"""
+Created on 2023-12-08, Extended on 2023-16-12 and 2024-01-25
+
+@author: wf, ChatGPT
+
+Prompts for the development and extension of the 'YamlAble' class within the 'yamable' module:
+
+1. Develop 'YamlAble' class in 'yamable' module. It
+   should convert dataclass instances to/from YAML.
+2. Implement methods for YAML block scalar style and
+   exclude None values in 'YamlAble' class.
+3. Add functionality to remove None values from
+   dataclass instances before YAML conversion.
+4. Ensure 'YamlAble' processes only dataclass instances,
+   with error handling for non-dataclass objects.
+5. Extend 'YamlAble' for JSON serialization and
+   deserialization.
+6. Add methods for saving/loading dataclass instances
+   to/from YAML and JSON files in 'YamlAble'.
+7. Implement loading of dataclass instances from URLs
+   for both YAML and JSON in 'YamlAble'.
+8. Write tests for 'YamlAble' within the pyLodStorage context.
+   Use 'samples 2' example from pyLoDStorage
+   https://github.com/WolfgangFahl/pyLoDStorage/blob/master/lodstorage/sample2.py
+   as a reference.
+9. Ensure tests cover YAML/JSON serialization, deserialization,
+   and file I/O operations, using the sample-based approach..
+10. Use Google-style docstrings, comments, and type hints
+   in 'YamlAble' class and tests.
+11. Adhere to instructions and seek clarification for
+    any uncertainties.
+12. Add @lod_storable annotation support that will automatically
+    YamlAble support and add @dataclass and @dataclass_json
+    prerequisite behavior to a class
+
+"""
+
+import urllib.request
+from collections.abc import Iterable, Mapping
+from dataclasses import asdict, dataclass, is_dataclass
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any, Generic, TextIO, Type, TypeVar, Union
+
+import yaml
+from dacite import from_dict
+from dataclasses_json import dataclass_json
+
+T = TypeVar("T")
+
+
+def lod_storable(cls):
+    """
+    Decorator to make a class LoDStorable by
+    inheriting from YamlAble.
+    This decorator also ensures the class is a
+    dataclass and has JSON serialization/deserialization
+    capabilities.
+    """
+    cls = dataclass(cls)  # Apply the @dataclass decorator
+    cls = dataclass_json(cls)  # Apply the @dataclass_json decorator
+
+    class LoDStorable(YamlAble, cls):
+        """
+        decorator class
+        """
+
+        __qualname__ = cls.__qualname__
+        pass
+
+    LoDStorable.__name__ = cls.__name__
+    LoDStorable.__doc__ = cls.__doc__
+
+    return LoDStorable
+
+
+class DateConvert:
+    """
+    date converter
+    """
+
+    @classmethod
+    def iso_date_to_datetime(cls, iso_date: str) -> date:
+        date = datetime.strptime(iso_date, "%Y-%m-%d").date() if iso_date else None
+        return date
+
+
+class YamlAble(Generic[T]):
+    """
+    An extended YAML handler class for converting dataclass objects to and from YAML format,
+    and handling loading from and saving to files and URLs.
+    """
+
+    def _yaml_setup(self):
+        """
+        Initializes the YamAble handler, setting up custom representers and preparing it for various operations.
+        """
+        if not is_dataclass(self):
+            raise ValueError("I must be a dataclass instance.")
+        if not hasattr(self, "_yaml_dumper"):
+            self._yaml_dumper = yaml.Dumper
+            self._yaml_dumper.ignore_aliases = lambda *_args: True
+            self._yaml_dumper.add_representer(type(None), self.represent_none)
+            self._yaml_dumper.add_representer(str, self.represent_literal)
+
+    def represent_none(self, _, __) -> yaml.Node:
+        """
+        Custom representer for ignoring None values in the YAML output.
+        """
+        return self._yaml_dumper.represent_scalar("tag:yaml.org,2002:null", "")
+
+    def represent_literal(self, dumper: yaml.Dumper, data: str) -> yaml.Node:
+        """
+        Custom representer for block scalar style for strings.
+        """
+        if "\n" in data:
+            return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+        return dumper.represent_scalar("tag:yaml.org,2002:str", data)
+
+    def to_yaml(
+        self,
+        ignore_none: bool = True,
+        ignore_underscore: bool = True,
+        allow_unicode: bool = True,
+        sort_keys: bool = False,
+    ) -> str:
+        """
+        Converts this dataclass object to a YAML string, with options to omit None values and/or underscore-prefixed variables,
+        and using block scalar style for strings.
+
+        Args:
+            ignore_none: Flag to indicate whether None values should be removed from the YAML output.
+            ignore_underscore: Flag to indicate whether attributes starting with an underscore should be excluded from the YAML output.
+            allow_unicode: Flag to indicate whether to allow unicode characters in the output.
+            sort_keys: Flag to indicate whether to sort the dictionary keys in the output.
+
+        Returns:
+            A string representation of the dataclass object in YAML format.
+        """
+        obj_dict = asdict(self)
+        self._yaml_setup()
+        clean_dict = self.remove_ignored_values(obj_dict, ignore_none, ignore_underscore)
+        yaml_str = yaml.dump(
+            clean_dict,
+            Dumper=self._yaml_dumper,
+            default_flow_style=False,
+            allow_unicode=allow_unicode,
+            sort_keys=sort_keys,
+        )
+        return yaml_str
+
+    @classmethod
+    def from_yaml(cls: Type[T], yaml_str: str) -> T:
+        """
+        Deserializes a YAML string to a dataclass instance.
+
+        Args:
+            yaml_str (str): A string containing YAML formatted data.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        data: dict[str, Any] = yaml.safe_load(yaml_str)
+        instance: T = cls.from_dict(data)
+        return instance
+
+    @classmethod
+    def load_from_yaml_stream(cls: Type[T], stream: TextIO) -> T:
+        """
+        Loads a dataclass instance from a YAML stream.
+
+        Args:
+            stream (TextIO): The input stream containing YAML data.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        yaml_str: str = stream.read()
+        instance: T = cls.from_yaml(yaml_str)
+        return instance
+
+    @classmethod
+    def load_from_yaml_file(cls: Type[T], filename: str) -> T:
+        """
+        Loads a dataclass instance from a YAML file.
+
+        Args:
+            filename (str): The path to the YAML file.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        with open(filename, "r") as file:
+            return cls.load_from_yaml_stream(file)
+
+    @classmethod
+    def load_from_yaml_url(cls: Type[T], url: str) -> T:
+        """
+        Loads a dataclass instance from a YAML string obtained from a URL.
+
+        Args:
+            url (str): The URL pointing to the YAML data.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        yaml_str: str = cls.read_from_url(url)
+        instance: T = cls.from_yaml(yaml_str)
+        return instance
+
+    def save_to_yaml_stream(self, file: TextIO):
+        """
+        Saves the current dataclass instance to the given YAML stream.
+
+        Args:
+            file (TextIO): The stream to which YAML content will be saved.
+        """
+        yaml_content: str = self.to_yaml()
+        file.write(yaml_content)
+
+    def save_to_yaml_file(self, filename: str):
+        """
+        Saves the current dataclass instance to a YAML file.
+
+        Args:
+            filename (str): The path where the YAML file will be saved.
+        """
+
+        with open(filename, "w", encoding="utf-8") as file:
+            self.save_to_yaml_stream(file)
+
+    @classmethod
+    def load_from_json_file(cls: Type[T], filename: Union[str, Path]) -> T:
+        """
+        Loads a dataclass instance from a JSON file.
+
+        Args:
+            filename (str): The path to the JSON file.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        with open(filename, "r", encoding="utf-8") as file:
+            json_str: str = file.read()
+        instance: T = cls.from_json(json_str)
+        return instance
+
+    @classmethod
+    def load_from_json_url(cls: Type[T], url: str) -> T:
+        """
+        Loads a dataclass instance from a JSON string obtained from a URL.
+
+        Args:
+            url (str): The URL pointing to the JSON data.
+
+        Returns:
+            T: An instance of the dataclass.
+        """
+        json_str: str = cls.read_from_url(url)
+        instance: T = cls.from_json(json_str)
+        return instance
+
+    def save_to_json_file(self, filename: str, **kwargs: Any):
+        """
+        Saves the current dataclass instance to a JSON file.
+
+        Args:
+            filename (str): The path where the JSON file will be saved.
+            **kwargs: Additional keyword arguments for the `to_json` method.
+        """
+        json_content: str = self.to_json(**kwargs)
+        with open(filename, "w", encoding="utf-8") as file:
+            file.write(json_content)
+
+    @classmethod
+    def read_from_url(cls, url: str) -> str:
+        """
+        Helper method to fetch content from a URL.
+        """
+        with urllib.request.urlopen(url) as response:
+            if response.status == 200:
+                return response.read().decode()
+            else:
+                raise Exception(f"Unable to load data from URL: {url}")
+
+    @classmethod
+    def remove_ignored_values(
+        cls,
+        value: Any,
+        ignore_none: bool = True,
+        ignore_underscore: bool = False,
+        ignore_empty: bool = True,
+    ) -> Any:
+        """
+        Recursively removes specified types of values from a dictionary or list.
+        By default, it removes keys with None values. Optionally, it can also remove keys starting with an underscore.
+
+        Args:
+            value: The value to process (dictionary, list, or other).
+            ignore_none: Flag to indicate whether None values should be removed.
+            ignore_underscore: Flag to indicate whether keys starting with an underscore should be removed.
+            ignore_empty: Flag to indicate whether empty collections should be removed.
+        """
+
+        def is_valid(v):
+            """Check if the value is valid based on the specified flags."""
+            if ignore_none and v is None:
+                return False
+            if ignore_empty:
+                if isinstance(v, Mapping) and not v:
+                    return False  # Empty dictionary
+                if isinstance(v, Iterable) and not isinstance(v, (str, bytes)) and not v:
+                    return False  # Empty list, set, tuple, etc., but not string or bytes
+            return True
+
+        if isinstance(value, Mapping):
+            value = {
+                k: YamlAble.remove_ignored_values(v, ignore_none, ignore_underscore, ignore_empty)
+                for k, v in value.items()
+                if is_valid(v) and (not ignore_underscore or not k.startswith("_"))
+            }
+        elif isinstance(value, Iterable) and not isinstance(value, (str, bytes)):
+            value = [
+                YamlAble.remove_ignored_values(v, ignore_none, ignore_underscore, ignore_empty)
+                for v in value
+                if is_valid(v)
+            ]
+        return value
+
+    @classmethod
+    def from_dict2(cls: Type[T], data: dict) -> T:
+        """
+        Creates an instance of a dataclass from a dictionary, typically used in deserialization.
+        """
+        if not data:
+            return None
+        instance = from_dict(data_class=cls, data=data)
+        return instance

pybasemkit-0.0.1.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: pybasemkit
+Version: 0.0.1
+Summary: Python base module kit: YAML/JSON I/O, structured logging, CLI tooling, shell execution, and pydevd remote debug support.
+Project-URL: Home, https://github.com/WolfgangFahl/pybasemkit
+Project-URL: Documentation, https://wiki.bitplan.com/index.php/pybasemkit
+Project-URL: Source, https://github.com/WolfgangFahl/pybasemkit
+Author-email: Wolfgang Fahl <wf@WolfgangFahl.com>
+Maintainer-email: Wolfgang Fahl <wf@WolfgangFahl.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: cli,dataclass,debug,infrastructure,logging,shell,yaml
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: dacite>=1.9.2
+Requires-Dist: dataclasses-json>=0.6.7
+Requires-Dist: pyyaml>=6.0.2
+Provides-Extra: dev
+Requires-Dist: black>=25.1.0; extra == 'dev'
+Requires-Dist: isort>=6.0.1; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: green>=3.3.0; extra == 'test'
+Requires-Dist: pytest>=8.4.0; extra == 'test'
+Requires-Dist: tox>=4.15.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pybasemkit
+Python base module kit: YAML/JSON I/O, structured logging, CLI tooling, shell execution, and remote pydevd debug support.
+
+[![pypi](https://img.shields.io/pypi/pyversions/pybasemkit)](https://pypi.org/project/pybasemkit/)
+[![Github Actions Build](https://github.com/WolfgangFahl/pybasemkit/actions/workflows/build.yml/badge.svg)](https://github.com/WolfgangFahl/pybasemkit/actions/workflows/build.yml)
+[![PyPI Status](https://img.shields.io/pypi/v/pybasemkit.svg)](https://pypi.python.org/pypi/pybasemkit/)
+[![GitHub issues](https://img.shields.io/github/issues/WolfgangFahl/pybasemkit.svg)](https://github.com/WolfgangFahl/pybasemkit/issues)
+[![GitHub closed issues](https://img.shields.io/github/issues-closed/WolfgangFahl/pybasemkit.svg)](https://github.com/WolfgangFahl/pybasemkit/issues/?q=is%3Aissue+is%3Aclosed)
+[![API Docs](https://img.shields.io/badge/API-Documentation-blue)](https://WolfgangFahl.github.io/pybasemkit/)
+[![License](https://img.shields.io/github/license/WolfgangFahl/pybasemkit.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+## Docs and Tutorials
+[Wiki](https://wiki.bitplan.com/index.php/pybasemkit)

pybasemkit-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+basemkit/__init__.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+basemkit/base_cmd.py,sha256=-m_eEicjg_4B7QLl5yAp3eQEN_mqTv8TmKlOHGMFDKA,6452
+basemkit/basetest.py,sha256=oirMWoUNBIdyf69j1gtYDgvqNyjmQ59e21yciABviOw,2483
+basemkit/persistent_log.py,sha256=8L8VV6iaffC9QqiCYfgUdFQOIsKjYDglsCYX6vdODxM,3749
+basemkit/profiler.py,sha256=h7N3jo43r6VS92UIARZMobNJYnsmpdk1zR4yVsyvhls,1059
+basemkit/shell.py,sha256=BF6IQDNjVY3OuK6pSg_g8LyqfOcA-U_qol25J_ABgxc,7479
+basemkit/yamlable.py,sha256=MSTK2VtRAutogKGiwPxpjXbw3akcwOoOqmf-LCncqEE,11613
+pybasemkit-0.0.1.dist-info/METADATA,sha256=p3wurArE08SBBHtJXKXzJ3qIsT3ndZeHEt_kG5y7bbE,2697
+pybasemkit-0.0.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pybasemkit-0.0.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pybasemkit-0.0.1.dist-info/RECORD,,

pybasemkit-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pybasemkit-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.