pyutilities 2.4.0.dev1__tar.gz → 2.4.2__tar.gz

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyutilities
-Version: 2.4.0.dev1
+Version: 2.4.2
 Summary: PyUtilities :: Useful python 3+ utilities library for various use cases.
 License-Expression: MIT
 License-File: LICENSE
@@ -26,11 +26,23 @@ Requires-Dist: click (>=8.3,<9.0)
 Requires-Dist: fake-useragent (>=2.0,<3.0)
 Requires-Dist: loguru (==0.7.3)
 Requires-Dist: markdown (>=3.7,<4.0)
+Requires-Dist: marshmallow (>=4.1,<5.0)
 Requires-Dist: openpyxl (==3.1.5)
 Requires-Dist: paramiko (==4.*)
+Requires-Dist: pendulum (>=3.2,<4.0)
 Requires-Dist: prettytable (>=3.14,<4.0)
+Requires-Dist: prettytable (>=3.17,<4.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pydantic-settings (==2.*)
+Requires-Dist: pydantic-yaml (==1.*)
+Requires-Dist: pyfiglet (>=1.0,<2.0)
+Requires-Dist: python-dateutil (>=2.9,<3.0)
+Requires-Dist: python-dotenv (>=1.2,<2.0)
+Requires-Dist: pytz (==2026.*)
 Requires-Dist: pyyaml (==6.*)
 Requires-Dist: requests (>=2.32,<3.0)
+Requires-Dist: rich-pyfiglet (>=1.0,<2.0)
+Requires-Dist: ruamel.yaml (==0.*)
 Requires-Dist: urllib3 (>=2.6,<3.0)
 Requires-Dist: xlrd (>=2.0.1,<2.1.0)
 Requires-Dist: xlwings (>=0.35,<1.0)
@@ -43,8 +55,8 @@ Description-Content-Type: text/markdown
 
 # Python Utilities Library
 
-Version 2.2.0, 2018 - 2026, Dmitrii Gusev  
-*Last update: XX.XX.2026*
+Version 2.4.2, 2018 - 2026, Dmitrii Gusev  
+*Last update: 15.05.2026*
 
 ## Project Description
 
@@ -52,18 +64,28 @@ Useful utilities functions for various needs for the python 3.10+. Containing 'g
 
 ## Versions history
 
-### 2.2.0
+### 2.4.0/2.4.1/2.4.2
+
+- many refactorings and minor code improvements
+- overall tests coverage now > 50%, working on improvements :)
+- added new date/time function, several decorators
+- added several useful string functions
+- added LoggingManager component for loguru simple configuration
+- v.2.4.1/v.2.4.2 - minor docs fixes
+
+### 2.3.0
 
-Added new functions:
+Intermediate version with improvements/refactorings.
+
+### 2.2.0
 
-- func1()
-- func2()
+Added several new functions - see sources.
 
 ### 2.1.2
 
 Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...
 
-**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and may be installed only for it!**
+**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
 
 ### Versions before 2.x.x
 

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/docs/README-PUB.md

@@ -1,7 +1,7 @@
 # Python Utilities Library
 
-Version 2.2.0, 2018 - 2026, Dmitrii Gusev  
-*Last update: XX.XX.2026*
+Version 2.4.2, 2018 - 2026, Dmitrii Gusev  
+*Last update: 15.05.2026*
 
 ## Project Description
 
@@ -9,18 +9,28 @@ Useful utilities functions for various needs for the python 3.10+. Containing 'g
 
 ## Versions history
 
-### 2.2.0
+### 2.4.0/2.4.1/2.4.2
+
+- many refactorings and minor code improvements
+- overall tests coverage now > 50%, working on improvements :)
+- added new date/time function, several decorators
+- added several useful string functions
+- added LoggingManager component for loguru simple configuration
+- v.2.4.1/v.2.4.2 - minor docs fixes
+
+### 2.3.0
 
-Added new functions:
+Intermediate version with improvements/refactorings.
+
+### 2.2.0
 
-- func1()
-- func2()
+Added several new functions - see sources.
 
 ### 2.1.2
 
 Major release with complete set of useful 'general purpose' functions. Documentation 'is coming'...
 
-**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and may be installed only for it!**
+**Warning! Versions 2.1.0, 2.1.1 are intended only for the python version = 3.10 and can be installed only for it!**
 
 ### Versions before 2.x.x
 

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/pyproject.toml

@@ -8,7 +8,7 @@
 #       - most of modules should be typed (used mypy stubs libraries)
 #
 #   Created:  Dmitrii Gusev, 30.05.2025
-#   Modified: Dmitrii Gusev, 19.04.2026
+#   Modified: Dmitrii Gusev, 15.05.2026
 #
 ####################################################################################################
 
@@ -20,7 +20,7 @@ build-backend = "poetry.core.masonry.api"
 # -- project / poetry utility meta-information
 [project]
 name = "pyutilities"
-version = "2.4.0dev1"
+version = "2.4.2"
 description = "PyUtilities :: Useful python 3+ utilities library for various use cases."
 authors     = [
     {name = "Dmitrii Gusev", email = "dmitry.ed.gusev@gmail.com"},
@@ -52,19 +52,42 @@ classifiers = [
 # - project runtime dependencies
 dependencies = [
 
+    # -- loguru
+    "loguru==0.7.3",
+
+    # -- ms word / ms excel libraries
     "xlrd~=2.0.1",  # - allowed: >=2.0.1 <2.1.0
     "xlwt==1.3.0",
     "xlwings~=0.35",
-    "loguru==0.7.3",
-    "pyyaml==6.*",
     "openpyxl==3.1.5",
+
+    # -- data validation and marshalling (JSON/YAML) --
+    "pydantic (>=2.12.5,<3.0.0)",
+    "pydantic-yaml ==1.*",
+    "pydantic-settings ==2.*",
+    "marshmallow ~=4.1",
+    "pyyaml ==6.*",
+    "ruamel.yaml ==0.*",
+
+    # -- technical libraries
     "urllib3~=2.6",  # - allowed: >=2.3.0 <3.0.0
     "paramiko==4.*",
     "requests~=2.32",  # - allowed: >=2.32.0 <3.0.0
     "markdown~=3.7",  # - allowed: >=3.7.0 <4.0.0
     "prettytable~=3.14",  # - allowed: >=3.14.0 <4.0.0
     "fake-useragent~=2.0",  # - allowed: >=2.0.0 <3.0.0
-    "click~=8.3"
+    "click~=8.3",
+    "python-dotenv ~=1.2", # - loading various .env configs
+
+    # -- terminal pseudo-graphics / pretty output
+    "prettytable ~=3.17", # - terminal tables
+    "pyfiglet ~=1.0", # - ASCII graphics
+    "rich-pyfiglet ~=1.0", # - ASCII graphics addon (colors)
+
+    # -- datetime utilities
+    "pendulum ~=3.2",
+    "python-dateutil ~=2.9",
+    "pytz ==2026.*"
 
 ]
 
@@ -241,7 +264,8 @@ follow_untyped_imports = true
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = """
---cov=./src/pyutilities --verbose --cov-report=html --cov-report=xml --cov-report=json --cov-report=annotate --capture=sys -rx --durations=0 --full-trace --color=auto
+--cov=./src/pyutilities --verbose --cov-report=html --cov-report=xml --cov-report=json --cov-report=annotate --capture=sys -rx --durations=0 --full-trace --color=auto --hypothesis-show-statistics --hypothesis-verbosity=verbose
+
 """
 testpaths = [
     "tests/",

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/cli/pyutils.py

@@ -18,7 +18,7 @@ MSG_VERSION = f"\nPy Utilities, version: {__version__}, (C) Dmitrii Gusev, 2018-
 @click.help_option("-h", "--help")
 @click.version_option(__version__, "-v", "--version", message=MSG_VERSION)
 @click.pass_context
-def pyutils(ctx):
+def pyutils(ctx):  # pylint: disable=unused-argument
     """Module [Py Utilities], (C) Dmitrii Gusev, 2018-2026."""
     click.echo("")
 

pyutilities-2.4.2/src/pyutilities/log/log_manager.py

@@ -0,0 +1,325 @@
+# -*- coding: utf-8 -*-
+
+"""
+Application logging init/managing module. For logging used loguru library. Provides flexible logging
+with console and file output, rotation, retention, and compression.
+
+Created:  Dmitrii Gusev, 06.04.2026
+Modified: Dmitrii Gusev, 15.05.2026
+"""
+
+import logging
+import sys
+from pathlib import Path
+from types import FrameType
+from typing import Optional
+
+from loguru import logger
+
+from pyutilities.utils.string_utils import is_empty
+
+# - Default logger names for Flask (they needs special processing in case we are in Flask app)
+FLASK_LOGGERS: list[str] = ["werkzeug", "flask.app"]
+
+# - Log format and coloring constants (application + intercepted) - for more info see loguru details
+DEFAULT_LOG_FORMAT = (
+    "<b><green>{time:DD-MM-YYYY HH:mm:ss}</green></b> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{extra[name]}</cyan>:<cyan>{function}</cyan>:"
+    "<cyan>{line}</cyan> - <level>{message}</level>\n"
+)
+INTERCEPTED_LOG_FORMAT = (
+    "<b><green>{time:DD-MM-YYYY HH:mm:ss}</green></b> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan>:"
+    "<cyan>{line}</cyan> - <level>{message}</level>\n"
+)
+
+
+class InterceptHandler(logging.Handler):
+    """Intercept standard logging messages and redirect them to loguru. This allows Flask and other
+    libraries using standard logging to use loguru. This class instance should be added to the logger
+    as a handler - and all logging messages will be intercepted by loguru and printed/showed in the
+    loguru output (console, log files).
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+
+        # Get corresponding Loguru level if it exists (for external captured message)
+        try:
+            level = logger.level(record.levelname).name  # matched log level for external message
+        except ValueError:
+            level = str(record.levelno)  # fallback default
+
+        # Find caller from where originated the logged message
+        frame: FrameType | None = logging.currentframe()
+        depth = 6  # in some examples this is set to = 6 (six), originally here was = 2 (two)
+        while frame and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        # emit the external captured log message
+        logger.opt(depth=depth, exception=record.exc_info).log(level, record.getMessage())
+
+
+class LoggerFileAppenderConfig:  # pylint: disable=too-few-public-methods
+    """Logger file appender configuration for the LoggerManager, if we need the file appender/handler.
+    This class is needed only for configuration simplification. By default - the only console appender /
+    handler will be added to the logger, no files logs.
+    """
+
+    def __init__(
+        self,
+        file: str | None = None,
+        rotation: str = "100Mb",
+        retention: str = "7 days",
+        compression: str = "zip",
+    ):
+        """Initialize the logger appenders config, with the necessary arguments/parameters.
+        Args:
+            file: Log file path (None to disable file logging)
+            rotation: Log rotation size (e.g., "10 MB", "100 MB", "1 GB")
+            retention: Log retention period (e.g., "7 days", "1 week", "1 month")
+            compression: Compression format for rotated logs ("zip", "gz", "bz2", "xz")
+        """
+
+        self.file = file
+        self.rotation = rotation
+        self.retention = retention
+        self.compression = compression
+
+
+class LoggerManager:  # pylint: disable=too-few-public-methods, too-many-instance-attributes
+    """Manages application logging using loguru. Some LoggerManager implementation features are:
+    - Console and/or file logging
+    - Logs files rotation (default 100MB) + retention (default 7 days)
+    - Logs compression (zip) + configurable log level
+    - Contextual logging with class/function/line information
+    - Intercepts Flask and standard library logging
+    """
+
+    def __init__(
+        self,
+        level: str = "INFO",
+        console: bool = True,
+        log_file_config: Optional[LoggerFileAppenderConfig] = None,
+        extra_loggers: Optional[dict[str, str]] = None,
+    ) -> None:
+        """Initialize the logger manager class instance.
+        Args:
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL), default = INFO
+            console: Enable/disable console logging (stdout), True/False, default = True
+            log_file_config: LoggerFileAppenderConfig - appenders configuration class
+            extra_loggers: dict[str, str] - <logger_name>: <logging_level> for additional loggers to be
+                configured with the setup, default = None
+        """
+
+        self.file: Optional[str] = None
+        self.rotation: Optional[str] = None
+        self.retention: Optional[str] = None
+        self.compression: Optional[str] = None
+
+        # - internal state initialization - file appender/handler
+        if log_file_config and not is_empty(log_file_config.file):
+            self.file = log_file_config.file
+            self.rotation = log_file_config.rotation
+            self.retention = log_file_config.retention
+            self.compression = log_file_config.compression
+
+        # - internal state initialization - console appender and level
+        self.level = level.upper()
+        self.console = console
+        # - internal state initialization - extra loggers and keys
+        self.extra_loggers: Optional[dict[str, str]] = extra_loggers
+        self.extra_loggers_keys: list[str] = (
+            extra_loggers.keys() if extra_loggers else []  # type: ignore[assignment]
+        )
+
+        logger.remove()  # Remove default logger (in order to avoid duplicate messages)
+        self._configure_logger()  # Configure logger (call internal method)
+        self._intercept_standard_logging()  # Intercept standard logging (call internal method)
+
+    def _configure_logger(self) -> None:
+        """INTERNAL. Configure loguru logger based on settings. Internal method for class LoggerManager.
+        This method configure the records formatting, creating and adding the necessary handlers to the
+        loguru logger, some additional logger setup ().
+        """
+
+        # Custom formatter that handles both application logs (with extra[name]) and intercepted logs.
+        # This method is used as parameter for console appender - see below.
+        def format_record(record) -> str:
+            # Map format based on whether 'name' exists in extra
+            format_map: dict[bool, str] = {
+                True: DEFAULT_LOG_FORMAT,  # Application logs with extra[name]
+                False: INTERCEPTED_LOG_FORMAT,  # Intercepted logs from standard library
+            }
+            return format_map["name" in record["extra"]]
+
+        # ! change some coloring of the log messages
+        logger.level("DEBUG", color="<green>")
+
+        # Define handlers configuration
+        handlers = []  # handlers storage array
+
+        if self.console:  # if console appender/handler enabled - configure and add it
+
+            handlers.append(  # add console handler (write to console)
+                {
+                    "sink": sys.stdout,
+                    "format": format_record,  # use the method above to format log record
+                    "level": self.level,
+                    "colorize": True,
+                }
+            )
+
+        if self.file:  # if file appender/handler enabled - configure and add it
+
+            log_path: Path = Path(self.file)  # Ensure log directory exists (where logs should be stored)
+            log_path.parent.mkdir(parents=True, exist_ok=True)  # create all necessary dirs (intermediate)
+
+            handlers.append(  # add file handler (write to file specified)
+                {
+                    "sink": self.file,
+                    "format": format_record,  # use the method above to format log record
+                    "level": self.level,
+                    "rotation": self.rotation,
+                    "retention": self.retention,
+                    "compression": self.compression,
+                    "enqueue": True,  # Thread-safe logging
+                }
+            )
+
+        # Add all configured handlers to logger
+        for handler_config in handlers:
+            logger.add(**handler_config)  # type: ignore[arg-type]
+
+    def _intercept_standard_logging(self) -> None:
+        """INTERNAL. Intercept standard library logging, used by external libraries and by the flask
+        application itself (flask.app, werkzeug) and redirect to loguru. Also set level for some used
+        libraries - for development/debug purposes. Internal method for class LoggerManager."""
+
+        # Intercept werkzeug (Flask)/system logging (A MUST: level=0, force=True -> intercept ALL!)
+        logging.basicConfig(handlers=[InterceptHandler()], level=0, force=True)
+
+        # Intercept specific loggers (they are using python logging mechanism) - for Flask
+        if self.extra_loggers:  # if there are extra loggers - process them
+            for logger_name in self.extra_loggers_keys:
+                if logger_name in FLASK_LOGGERS:  # special init for Flask loggers
+                    log = logging.getLogger(name=logger_name)
+                    log.handlers = [InterceptHandler()]
+                    log.propagate = False
+                else:  # just set level for other loggers
+                    # ! set the appropriate level for some libraries - it may help to reduce
+                    # !   logging output amount (brevity) or clarify libraries internals (more logging)
+                    logging.getLogger(logger_name).setLevel(self.extra_loggers[logger_name])
+
+    @staticmethod
+    def get_logger(name: str):
+        """CLASS METHOD. Get a logger instance with a specific name (typically class name). Factory method,
+        binds the specific name to the loguru logger and return the loguru logger.
+        Args:
+            name: Logger name (usually __name__ or class name)
+        Returns:
+            Logger instance bound with the name
+        Usage:
+            class MyService:
+                def __init__(self):
+                    self.logger = LoggerManager.get_logger(self.__class__.__name__)
+
+                def my_method(self):
+                    self.logger.info("Processing data")
+        """
+        return logger.bind(name=name)
+
+
+# pylint: disable=too-many-arguments, too-many-positional-arguments
+def setup_logging(
+    level: str = "INFO",
+    console: bool = True,
+    file: str | None = None,
+    rotation: str = "100 MB",
+    retention: str = "7 days",
+    compression: str = "zip",
+    extra_loggers: Optional[dict[str, str]] = None,
+) -> LoggerManager:
+    """MODULE METHOD. Setup application logging. This is the MAIN ENTRY POINT FOR configuring LOGGING
+    in the application. Should be called once at application startup - this method creates and initializes
+    the only  instance of the LoggerManager class.
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        console: Enable console logging (stdout)
+        file: Log file path (None to disable file logging)
+        rotation: Log rotation size (e.g., "10 MB", "100 MB", "1 GB")
+        retention: Log retention period (e.g., "7 days", "1 week", "1 month")
+        compression: Compression format for rotated logs ("zip", "gz", "bz2", "xz")
+        extra_loggers: dict[str, str] - <logger_name>: <logging_level> for additional loggers to be
+            configured with the setup
+    Returns:
+        LoggerManager instance
+    Usage:
+        from app.core.log import setup_logging
+
+        # Console only (default)
+        setup_logging(level="INFO")
+
+        # File only
+        setup_logging(console=False, file="logs/app.log")
+
+        # Both console and file
+        setup_logging(console=True, file="logs/app.log")
+    """
+
+    # create instance of file appender config - if file specified
+    log_file_config: Optional[LoggerFileAppenderConfig] = (
+        LoggerFileAppenderConfig(file=file, rotation=rotation, retention=retention, compression=compression)
+        if not is_empty(file)
+        else None
+    )
+
+    return LoggerManager(
+        level=level, console=console, log_file_config=log_file_config, extra_loggers=extra_loggers
+    )
+
+
+# pylint: disable=too-many-arguments, too-many-positional-arguments
+def setup_logging_flask(
+    level: str = "INFO",
+    console: bool = True,
+    file: str | None = None,
+    rotation: str = "100 MB",
+    retention: str = "7 days",
+    compression: str = "zip",
+    extra_loggers: Optional[dict[str, str]] = None,
+) -> LoggerManager:
+    """MODULE METHOD. Setup application logging for Flask application. This is the MAIN ENTRY POINT
+    FOR configuring LOGGING in the application. Should be called once at application startup - this
+    method creates and initializes the only instance of the LoggerManager class.
+    # ! Difference from the setup_logging() method is that the Flask loggers added to extra_loggers.
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        console: Enable console logging (stdout)
+        file: Log file path (None to disable file logging)
+        rotation: Log rotation size (e.g., "10 MB", "100 MB", "1 GB")
+        retention: Log retention period (e.g., "7 days", "1 week", "1 month")
+        compression: Compression format for rotated logs ("zip", "gz", "bz2", "xz")
+        extra_loggers: dict[str, str] - <logger_name>: <logging_level> for additional loggers to be
+            configured with the setup
+    """
+
+    # create instance of file appender config - if file specified
+    log_file_config: Optional[LoggerFileAppenderConfig] = (
+        LoggerFileAppenderConfig(file=file, rotation=rotation, retention=retention, compression=compression)
+        if not is_empty(file)
+        else None
+    )
+
+    # add Flask loggers to the dictionary of extra_loggers
+    if not extra_loggers:  # init extra loggers in case it is not initialized
+        extra_loggers = {}
+
+    for logger_name in FLASK_LOGGERS:
+        extra_loggers[logger_name] = "INFO"  # by default set the INFO, but this value will be ignored
+
+    return LoggerManager(
+        level=level, console=console, log_file_config=log_file_config, extra_loggers=extra_loggers
+    )

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/sys/sys_utils.py

@@ -4,13 +4,14 @@
 System Utilities module.
 
 Created:  Dmitrii Gusev, 18.07.2025
-Modified: Dmitrii Gusev, 28.07.2025
+Modified: Dmitrii Gusev, 15.05.2026
 """
 
 import logging
 import os
 
-from pyutilities.utils.string_utils import str_2_bool, str_2_float, str_2_int
+from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
+from pyutilities.utils.string_utils import is_empty, str_2_bool, str_2_float, str_2_int
 
 log = logging.getLogger(__name__)
 log.addHandler(logging.NullHandler())
@@ -19,10 +20,7 @@ log.addHandler(logging.NullHandler())
 def get_str_from_env(key: str, default: str = "") -> str:
     """TBD"""
 
-    if not key or not key.strip():
-        return default
-
-    return os.environ.get(key) or default
+    return default if is_empty(key) else (os.environ.get(key) or default)
 
 
 def get_int_from_env(key: str, default: int = 0) -> int:
@@ -53,3 +51,11 @@ def get_bool_from_env(key: str, default: bool = False) -> bool:
 
     env_value = os.environ.get(key)
     return str_2_bool(env_value) if env_value else default
+
+
+# # show all env variables sorted by name:
+# # print('\n'.join(f'{k}={v}' for k, v in sorted(os.environ.items())))
+
+
+if __name__ == "__main__":
+    print(MSG_MODULE_ISNT_RUNNABLE)

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/utils/common_utils.py

@@ -9,15 +9,13 @@ Useful materials:
         how-do-i-convert-this-list-of-dictionaries-to-a-csv-file
 
 Created:  Gusev Dmitrii, 10.10.2022
-Modified: Dmitrii Gusev, 24.11.2025
+Modified: Dmitrii Gusev, 14.05.2026
 """
 
 import csv
 import inspect
 import logging
 import os
-import threading
-import time
 from typing import Any, Dict, List, Tuple
 
 from pyutilities.defaults import DEFAULT_ENCODING, MSG_MODULE_ISNT_RUNNABLE
@@ -36,59 +34,6 @@ NUM_CHARS = "0123456789"
 SPEC_CHARS = "-"
 
 
-def singleton(class_):
-    """Decorator: singleton class decorator. Use it on the class level to make class Singleton."""
-
-    instances = {}  # classes instances storage
-
-    def get_instance(*args, **kwargs):
-        if class_ not in instances:
-            instances[class_] = class_(*args, **kwargs)
-        return instances[class_]
-
-    return get_instance
-
-
-def threadsafe_function(fn):
-    """Decorator: it is making sure that the decorated function is thread safe."""
-
-    lock = threading.Lock()  # acquire lock
-
-    def new(*args, **kwargs):
-        lock.acquire()
-        try:
-            r = fn(*args, **kwargs)
-        finally:
-            lock.release()  # release lock in any case
-        return r
-
-    return new
-
-
-def debug_benchmark(func):
-    """Decorator: logs the given function execution time."""
-
-    def wrapper(*args, **kwargs):
-        t = time.process_time()
-        res = func(*args, **kwargs)
-        log.debug("Function [%s] executed in [%s] second(s).", func.__name__, time.process_time() - t)
-        return res
-
-    return wrapper
-
-
-def debug_function_name(func):
-    """Decorator: logs the name of the decorating function."""
-
-    def wrapper(*args, **kwargs):
-        log.debug("Function [%s] is working.", func.__name__)
-        # print(func.__name__, args, kwargs)
-        res = func(*args, **kwargs)
-        return res
-
-    return wrapper
-
-
 def myself():
     """Handy utility function/lambda for getting name of executing function from inside the function.
     Can be rewritten as lambda: myself = lambda: inspect.stack()[1][3]"""

pyutilities-2.4.2/src/pyutilities/utils/datetime_utils.py

@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+
+"""
+Useful date/time utilities and functions.
+
+Created:  Dmitrii Gusev, 22.03.2026
+Modified: Dmitrii Gusev, 10.05.2026
+"""
+
+from datetime import datetime, timedelta, timezone
+
+import pendulum
+from pendulum import Date
+
+from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
+
+MSK_TIMEZONE: timezone = timezone(timedelta(hours=3), name="Moscow Timezone (Russia)")
+MSK_TIMEZONE_NAME: str = "Europe/Moscow"
+
+
+def get_timestamp(
+    current_timezone: timezone = MSK_TIMEZONE,
+    days: float = 0,
+    hours: float = 0,
+    minutes: float = 0,
+    seconds: float = 0,
+) -> datetime:
+    """Return timestamp: now (in the default timezone) +/- the specified time delta in hours / minutes /
+    seconds. Default timezone can be changed by the function argument."""
+
+    return datetime.now(current_timezone) + timedelta(
+        days=days, hours=hours, minutes=minutes, seconds=seconds
+    )
+
+
+def get_dates_range_before_date(date: datetime) -> tuple[int, int]:
+    """Generates two dates range - date_from/date_to for the time period 'before today' - from the 1st day
+    of the current month till the today - 1 day (current month). In case today is 1st day - range for the
+    whole previous month, if today is 01.01.XXXX - range for 01.12.XXXX-1 - 31.12.XXXX-1.
+    """
+
+    # - local variables
+    local_today: Date = Date(date.year, date.month, date.day)
+    date_from: Date
+    date_to: Date
+
+    # - processing and calculating dates
+    if local_today.day == 1:  # today - 1st day of month, we need report for the previous month
+
+        if local_today.month == 1:  # we are at 01.01.XXXX - we need report for Dec.XXXX - 1
+
+            date_from = pendulum.date(local_today.year - 1, 12, 1)  # from: 01 Dec Year-1
+            date_to = pendulum.date(local_today.year - 1, 12, 31)  # to: 31 Dec Year-1
+
+        else:  # we are at 01.XX.XXXX - we need report for previous month
+
+            # from: 01 Month-1 Year
+            date_from = pendulum.date(local_today.year, local_today.month - 1, 1)
+            # to: Last Day Month-1 Year
+            date_to = pendulum.date(
+                local_today.year, local_today.month - 1, local_today.subtract(months=1).days_in_month
+            )
+
+    else:  # today isn't the 1st, we need report from 1st till yesterday
+
+        date_from = pendulum.date(local_today.year, local_today.month, 1)  # from: 01 Month Year
+        date_to = pendulum.date(local_today.year, local_today.month, date.day - 1)  # to: Day-1 Month Year
+
+    # - generate from/to timestamps
+    tstamp_from = pendulum.datetime(date_from.year, date_from.month, date_from.day)
+    tstamp_to = pendulum.datetime(date_to.year, date_to.month, date_to.day)
+
+    # - return the tuple of values
+    return (tstamp_from.int_timestamp, tstamp_to.int_timestamp)
+
+
+if __name__ == "__main__":
+    print(MSG_MODULE_ISNT_RUNNABLE)

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/utils/decorators.py

@@ -4,11 +4,12 @@
 Decorators module. Contains some useful decorators.
 
 Created:  Gusev Dmitrii, 10.10.2022
-Modified: Dmitrii Gusev, 25.11.2025
+Modified: Dmitrii Gusev, 15.05.2026
 """
 
 import functools
 import logging
+import threading
 import time
 from typing import Any
 
@@ -18,6 +19,78 @@ log = logging.getLogger(__name__)
 log.addHandler(logging.NullHandler())
 
 
+def singleton_v1(clazz):
+    """Decorator: singleton class decorator. Use it on the class level to make class Singleton.
+    Version 1: uses set of instances for storing the one class instance.
+    """
+
+    instances = {}  # classes instances storage
+
+    @functools.wraps(clazz)
+    def get_instance(*args, **kwargs):
+        if clazz not in instances:
+            instances[clazz] = clazz(*args, **kwargs)
+        return instances[clazz]
+
+    return get_instance
+
+
+def singleton_v2(clazz):
+    """Decorator: singleton class decorator. Use it on the class level to make class Singleton.
+    Version 2: uses reference to the singleton instance for storing the lnk to the one class instance.
+    """
+
+    @functools.wraps(clazz)
+    def wrapper_singleton(*args, **kwargs):
+        if wrapper_singleton.instance is None:  # type: ignore[attr-defined]
+            wrapper_singleton.instance = clazz(*args, **kwargs)  # type: ignore[attr-defined]
+        return wrapper_singleton.instance  # type: ignore[attr-defined]
+
+    wrapper_singleton.instance = None  # type: ignore[attr-defined]
+
+    return wrapper_singleton
+
+
+def threadsafe_function(fn):
+    """Decorator: it is making sure that the decorated function is thread safe."""
+
+    lock = threading.Lock()  # acquire lock
+
+    @functools.wraps(fn)
+    def new(*args, **kwargs):
+        with lock:
+            result = fn(*args, **kwargs)
+        return result
+
+    return new
+
+
+def debug_benchmark(func):
+    """Decorator: logs the given function execution time."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        t = time.process_time()
+        res = func(*args, **kwargs)
+        log.debug("Function [%s] executed in [%s] second(s).", func.__name__, time.process_time() - t)
+        return res
+
+    return wrapper
+
+
+def debug_function_name(func):
+    """Decorator: logs the name of the decorating function."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        log.debug("Function [%s] is working.", func.__name__)
+        # print(func.__name__, args, kwargs)
+        res = func(*args, **kwargs)
+        return res
+
+    return wrapper
+
+
 def retry(max_tries=3, delay_seconds=1):
     """Retrying decorator."""
 
@@ -41,7 +114,9 @@ def retry(max_tries=3, delay_seconds=1):
 
 
 def memoize(func):
-    """Decorator - analogue for the functool.lru_cache()."""
+    """Cache decorator - analogue for the functool.lru_cache().
+    WARNING! Unbounded cache!
+    """
 
     cache: dict[Any, Any] = {}
 

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/utils/lambdas.py

@@ -1,13 +1,18 @@
-# # -*- coding: utf-8 -*-
+# -*- coding: utf-8 -*-
 
-# """
-#     Module with useful lambdas functions/one-liners.
+"""
+Lambdas module. Contains useful lambda functions.
 
-#     Created:  Dmitrii Gusev, 29.07.2025
-#     Modified: Dmitrii Gusev, 21.11.2025
-# """
+Created:  Dmitrii Gusev, 15.05.2026
+Modified: Dmitrii Gusev, 15.05.2026
+"""
 
-# from pathlib import Path
+import logging
+
+from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
+
+log = logging.getLogger(__name__)
+log.addHandler(logging.NullHandler())
 
 # # execute shell cmd and return output
 # sh = lambda cmd: __import__('subprocess').run(cmd, shell=True, check=True, capture_output=True) \
@@ -23,22 +28,15 @@
 # # split list into n-sized chunks
 # chunked = lambda lst, n: [lst[i:i+n] for i in range(0, len(lst), n)]
 
-# # convert python object to the human-readable JSON
-# pretty_json = lambda obj: __import__('json').dumps(obj, ensure_ascii=False, indent=2)
-
-# # get all files with the .py extebsion recursively
+# # get all files with the .py extension recursively
 # files = list(Path('.').rglob('*.py'))
 
-# # show all env variables sorted by name:
-# # print('\n'.join(f'{k}={v}' for k, v in sorted(os.environ.items())))
-
 # # read all lines from file, removing wrap line
 # lines = Path('file.txt').read_text().splitlines()
 
 # # get SHA256 code of the string
 # hash = hashlib.sha256(b"your text").hexdigest()
 
-
 # # quickly stop the script execution
 # raise SystemExit("Done")
 
@@ -53,3 +51,7 @@
 
 # # check host liveness without ping
 # ok = socket.create_connection((host, port), timeout=2)
+
+
+if __name__ == "__main__":
+    print(MSG_MODULE_ISNT_RUNNABLE)

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/utils/string_utils.py

@@ -10,14 +10,17 @@ in 'fast' executing code, where logging will just add additional complexity and
 Also most of the functions use LRU feature of the python language.
 
 Created:  Dmitrii Gusev, 15.04.2019
-Modified: Dmitrii Gusev, 17.04.2026
+Modified: Dmitrii Gusev, 14.05.2026
 """
 
+import json
 import logging
 from functools import lru_cache
 from re import match as re_match
 from typing import Any, Dict, Iterable, Tuple
 
+import pyfiglet
+
 from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
 
 # configure logger on module level. it isn't a good practice, but it's convenient.
@@ -26,19 +29,31 @@ log = logging.getLogger(__name__)
 # to avoid errors like 'no handlers' for libraries it's necessary/convenient to add NullHandler
 log.addHandler(logging.NullHandler())
 
-# useful module defaults
+# - Symbols :: useful module defaults
 SPECIAL_SYMBOLS = ".,/-№"
 CYRILLIC_SYMBOLS = "абвгдеёжзийклмнопрстуфхцчшщъыьэюяАБВГДЕЁЖЗИЙКЛМНОПРСТУФХЦЧШЩЪЫЬЭЮЯ"
 LATIN_SYMBOLS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
 ALL_SYMBOLS = SPECIAL_SYMBOLS + CYRILLIC_SYMBOLS + LATIN_SYMBOLS
-
-# set of regex for determining float values
-REGEX_FLOAT_1 = "^\d+?\.\d+?$"  # original regex # pylint: disable=anomalous-backslash-in-string # noqa: W605
-REGEX_FLOAT_2 = "^\\d+?\\.\\d+?$"  # original regex with fixed warnings
+# - Symbols :: password replacement symbols for various output
+REPLACEMENT_SYMBOLS = "**********"
+# - Symbols :: set of regex for determining float values
+# REGEX_FLOAT_1 = "^\d+?\.\d+?$"  # orig regex # pylint: disable=anomalous-backslash-in-string # noqa: W605
+REGEX_FLOAT_2 = "^\\d+?\\.\\d+?$"  # orig regex with fixed warnings
 REGEX_FLOAT_3 = "^[+-]?([0-9]*[.])?[0-9]+$"  # simplified regex, matches: 123/123.456/.456
 REGEX_FLOAT_4 = "^[+-]?([0-9]+([.][0-9]*)?|[.][0-9]+)$"  # matches as previous plus: 123.
-
-# cache setup (size) for cached functions/methods
+# - Symbols :: string True values (for the conversion purpose)
+TRUE_STRINGS_LIST: list[str] = [
+    "true",
+    "1",
+    "t",
+    "y",
+    "yes",
+    "yeah",
+    "yup",
+    "certainly",
+    "uh-huh",
+]
+# - CACHE :: cache setup (size) for cached functions/methods
 LRU_CACHE_SIZE: int = 128
 
 
@@ -110,12 +125,26 @@ def filterc_str(string: str | None, trace: bool = False) -> str | None:
     return filter_str(string, trace)
 
 
+def is_empty(string: str | None) -> bool:
+    """NOT CACHED. Is string  empty - None or contains only spaces. Based on non-cached trim_2_none()."""
+
+    return trim_2_none(string) is None
+
+
+@lru_cache(maxsize=LRU_CACHE_SIZE)
+def is_emptyc(string: str | None) -> bool:
+    """CACHED. Is string empty - equals to None or contains only spaces. Based on cached trim_2_none()."""
+
+    return trimc_2_none(string) is None
+
+
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def process_url(
     url: str, postfix: str = "", format_values: Tuple[str] | None = None, trace: bool = False
 ) -> str:
-    """Process the provided url and update it: add postfix (if provided) and add format values
-    (if provided). In case empty string provided = empty string will be returned as well."""
+    """CACHED. Process the provided url and update it: add postfix (if provided) and add format
+    values (if provided). In case empty string provided = empty string will be returned as well.
+    """
 
     result: str = ""
     if url and url.strip():  # provided url is not empty
@@ -148,7 +177,7 @@ def process_url(
 def process_urls(
     urls: Dict[str, str], postfix: str = "", format_values: Tuple[str] | None = None, trace: bool = False
 ) -> Dict[str, str]:
-    """Process the provided dictionary of urls with the function"""
+    """CACHED. Process the provided dictionary of urls with the function"""
 
     processed: Dict[str, str] = {}
 
@@ -164,8 +193,9 @@ def process_urls(
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def get_str_ending(string: str, symbol: str = "/", trace: bool = False) -> str:
-    """Returns the last right part of the string after the symbol (not including the symbol itself). It is
-    most right part of the string, after the last right symbol (if there are multiple symbols).
+    """CACHED. Returns the last right part of the string after the symbol (not including the symbol
+    itself). It is most right part of the string, after the last right symbol (if there are multiple
+    symbols).
     """
 
     result: str = string
@@ -183,8 +213,9 @@ def get_str_ending(string: str, symbol: str = "/", trace: bool = False) -> str:
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def is_number(value: str, trace: bool = False) -> bool:
-    """Returns True if string is a number. String is checked 'as is' - no trailing/leading spaces cut, no
-    any other transformations."""
+    """CACHED. Returns True if string is a number. String is checked 'as is' - no trailing/leading
+    spaces cut, no any other transformations.
+    """
 
     result: bool = False
 
@@ -199,10 +230,12 @@ def is_number(value: str, trace: bool = False) -> bool:
 
 
 def iter_2_str(values: Iterable[Any], braces: bool = True, trace: bool = False) -> str:  # noqa: C901
-    """Convert number of iterable values to a single string value. If iterable is empty - the result is
-    empty string. If braces == True, the braces will be added around the resulting string. For each value
-    in the iterable trailing/leading spaces will be cut, duplicates will be removed, duplicate numbers
-    will be removed as well."""
+    """NOT CACHED. Despite the function itself doesn't use cache, it uses cached function is_number().
+    Convert number of iterable values to a single string value. If iterable is empty - the result
+    is empty string. If braces == True, the braces will be added around the resulting string. For
+    each value in the iterable trailing/leading spaces will be cut, duplicates will be removed,
+    duplicate numbers will be removed as well.
+    """
 
     # setup for processing
     resulting_value: str = ""
@@ -244,11 +277,47 @@ def iter_2_str(values: Iterable[Any], braces: bool = True, trace: bool = False)
                 resulting_value = resulting_value[:-2]
 
     if trace:
-        log.debug("iter_2_str(): resulting string is [%s].", resulting_value)
+        log.debug("iter_2_str(): result is [%s].", resulting_value)
 
     return resulting_value  # returning result
 
 
+def dict_2_json_str(dictionary: dict[Any, Any]) -> str:
+    """NOT CACHED. Convert dictionary to readable/printable JSON string. If contains entries like
+    'password'/'pass' - such an entries values will be replaced by '**********' values. Non-serializable
+    entries will be replaced by symbols '<not serializable>'.
+    """
+
+    if not dictionary:  # quick check
+        return ""
+
+    # - filter out (mask) passwords in the config
+    filtered_dictionary = {
+        k: (v if "password" not in str(k).lower() and "pass" not in str(k).lower() else REPLACEMENT_SYMBOLS)
+        for k, v in dictionary.items()
+    }
+
+    # - dump JSON and set a lambda for not serializable types
+    json_str: str = json.dumps(filtered_dictionary, indent=4, default=lambda o: "<not serializable>")
+
+    return json_str
+
+
+# # convert python object to the human-readable JSON
+# pretty_json = lambda obj: __import__('json').dumps(obj, ensure_ascii=False, indent=2)
+
+
+def generate_ascii_title(app_title: str, app_subtitle: str) -> str:
+    """NOT CACHED. Generates ASCII title for the application/system, using short/abbreviated name,
+    version, author and dates info. ASCII title returned as string.
+    """
+
+    ascii_title: str = pyfiglet.figlet_format(f"{app_title}", font="doom")
+    ascii_title += f"\n\n{ascii_title}\n{app_subtitle}\n"
+
+    return ascii_title
+
+
 def coalesce(*args, trace: bool = False) -> str:
     """NOT CACHED. Return first not None and not empty value from provided args list."""
 
@@ -280,8 +349,9 @@ def coalescec(*args, trace: bool = False) -> str:
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def one_of_2_str(string1: str | None, string2: str | None, trace: bool = False) -> str | None:
-    """Function returning one of two strings, if other is empty. If both are empty or filled in - method
-    returns None (empty value)."""
+    """CACHED. Function returning one of two strings, if other is empty. If both are empty or
+    filled in - method returns None (empty value).
+    """
 
     result: str | None = None
     if string1 and string1.strip():  # first string check
@@ -299,7 +369,7 @@ def one_of_2_str(string1: str | None, string2: str | None, trace: bool = False)
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def convert_bytes(num: float, trace: bool = False) -> str:
-    """Function will convert bytes to MB.... GB... etc. for readability."""
+    """CACHED. Function will convert bytes to MB.... GB... etc. for readability."""
 
     # processing of the value
     result: str = "unknown"
@@ -316,9 +386,10 @@ def convert_bytes(num: float, trace: bool = False) -> str:
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def str_2_bool(string: str | None, trace: bool = False) -> bool:
-    """Convert string to bool. If empty string - return False. If string is not empty - return if string,
-    converted to lower case, contains in the list: 'true', '1', 't', 'y', 'yes', 'yeah', 'yup', 'certainly',
-    'uh-huh'."""
+    """CACHED. Convert string to bool. If empty string - return False. If string is not empty - return
+    if string, converted to lower case, contains in the list: 'true', '1', 't', 'y', 'yes', 'yeah',
+    'yup', 'certainly', 'uh-huh'.
+    """
 
     result: bool
     if not string or not string.strip():  # empty string - returning False
@@ -344,8 +415,9 @@ def str_2_bool(string: str | None, trace: bool = False) -> bool:
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def str_2_int(string: str | None, trace: bool = False) -> int:
-    """Convert string to integer number. Empty string or string with non-digit symbols will return 0,
-    otherwise will return int(string)."""
+    """CACHED. Convert string to integer number. Empty string or string with non-digit symbols will
+    return 0, otherwise will return int(string).
+    """
 
     result: int
     if not string or not string.strip():  # empty input string
@@ -368,8 +440,9 @@ def str_2_int(string: str | None, trace: bool = False) -> int:
 
 @lru_cache(maxsize=LRU_CACHE_SIZE)
 def str_2_float(string: str | None, trace: bool = False) -> float:
-    """Convert string to float number. Empty string or string with non-digit symbols
-    will return 0, otherwise will return float(string)."""
+    """CACHED. Convert string to float number. Empty string or string with non-digit symbols
+    will return 0, otherwise will return float(string).
+    """
 
     result: float
     if not string or not string.strip():

{pyutilities-2.4.0.dev1 → pyutilities-2.4.2}/src/pyutilities/web/http_client.py

@@ -5,7 +5,7 @@
 HTTP client module, based on requests module.
 
 Created:  Dmitrii Gusev, 01.06.2021
-Modified: Dmitrii Gusev, 24.11.2025
+Modified: Dmitrii Gusev, 15.05.2026
 """
 
 import logging
@@ -17,7 +17,7 @@ from requests import Response
 from requests.adapters import HTTPAdapter, Retry
 
 from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
-from pyutilities.utils.common_utils import threadsafe_function
+from pyutilities.utils.decorators import threadsafe_function
 
 # init module logger
 log = logging.getLogger(__name__)

pyutilities-2.4.0.dev1/src/pyutilities/utils/datetime_utils.py

@@ -1,33 +0,0 @@
-# -*- coding: utf-8 -*-
-
-"""
-Useful date/time utilities and functions.
-
-Created:  Dmitrii Gusev, 22.03.2026
-Modified: Dmitrii Gusev, 22.03.2026
-"""
-
-from datetime import datetime, timedelta, timezone
-
-from pyutilities.defaults import MSG_MODULE_ISNT_RUNNABLE
-
-MSK_TIMEZONE: timezone = timezone(timedelta(hours=3), name="Moscow Timezone (Russia)")
-
-
-def get_timestamp(
-    current_timezone: timezone = MSK_TIMEZONE,
-    days: float = 0,
-    hours: float = 0,
-    minutes: float = 0,
-    seconds: float = 0,
-) -> datetime:
-    """Return timestamp: now (in the default timezone) +/- the specified time delta in hours / minutes /
-    seconds. Default timezone can be changed by the function argument."""
-
-    return datetime.now(current_timezone) + timedelta(
-        days=days, hours=hours, minutes=minutes, seconds=seconds
-    )
-
-
-if __name__ == "__main__":
-    print(MSG_MODULE_ISNT_RUNNABLE)