danielutils 1.1.28__py3-none-any.whl

danielutils/logging_/_impl/logger.py

@@ -0,0 +1,109 @@
+import json
+import logging
+from datetime import datetime
+from typing import Any, Type, Optional, Dict, List
+
+from .log_level import LogLevel
+from .logger_strategy_impl_base import LoggerStrategyImplBase
+from ..utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class _LoggerImpl:
+    def __init__(self, origin: Type):
+        self.origin = origin
+
+    @classmethod
+    def parse_message(
+            cls,
+            origin: Type,
+            logger_id: Optional[str],
+            channel: str,
+            level: LogLevel,
+            message: str,
+            module: Optional[str] = None,
+            cls_name: Optional[str] = None,
+            metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        d = dict(
+            timestamp=str(datetime.now()),
+            origin=origin.__qualname__,
+            logger_id=logger_id,
+            channel=channel,
+            level=level.name,
+            message=message
+        )
+        if module:
+            d.update({'module': module})
+
+        if cls_name:
+            d.update({'cls': cls_name})
+
+        if metadata:
+            d.update({'metadata': metadata})
+        s = json.dumps(d)
+        return f"{s}\n"
+
+    def _log(self, level: LogLevel, message: str, channel: str, **metadata):
+        message = str(message)
+        loggers_count = len(LoggerStrategyImplBase._loggers[channel])
+        
+        for logger_instance in LoggerStrategyImplBase._loggers[channel]:
+            logger_instance(self.parse_message(
+                self.origin,
+                logger_instance.logger_id,
+                channel,
+                level,
+                message,
+                metadata.get("cls", {}).get("__module__", None),
+                metadata.pop("cls", {}).get("__qualname__", None),
+                metadata
+            ))
+
+    def debug(self, message: str, channel: str = "all", **metadata):
+        self._log(LogLevel.DEBUG, message, channel, **metadata)
+
+    def info(self, message: str, channel: str = "all", **metadata):
+        self._log(LogLevel.INFO, message, channel, **metadata)
+
+    def warning(self, message: str, channel: str = "all", **metadata):
+        self._log(LogLevel.WARNING, message, channel, **metadata)
+
+    def error(self, message: str, channel: str = "all", **metadata):
+        self._log(LogLevel.ERROR, message, channel, **metadata)
+
+
+class Logger:
+    @classmethod
+    def __init_subclass__(cls, **kwargs) -> None:
+        logger.info("Initializing Logger subclass: %s", cls.__qualname__)
+        cls._logger = _LoggerImpl(cls)
+        cls._registered_loggers: List[LoggerStrategyImplBase] = []
+        cls.init_subscribers()
+        logger.info("Logger subclass %s initialized successfully", cls.__qualname__)
+
+    @classmethod
+    @property
+    def logger(cls) -> _LoggerImpl:
+        return cls._logger
+
+    @classmethod
+    def init_subscribers(cls):
+        pass
+
+    @classmethod
+    def register_logger(cls, logger_instance: LoggerStrategyImplBase) -> None:
+        logger.info("Registering logger %s for class %s", logger_instance.logger_id, cls.__qualname__)
+        cls._registered_loggers.append(logger_instance)
+        logger.info("Logger registered successfully, total registered: %s", len(cls._registered_loggers))
+
+
+class GlobalLogger(Logger):
+    pass
+
+
+__all__ = [
+    "Logger",
+    "GlobalLogger"
+]

danielutils/logging_/_impl/logger_strategy_impl_base.py

@@ -0,0 +1,37 @@
+import logging
+from collections import defaultdict
+from typing import Dict, List, Callable
+from ..utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class LoggerStrategyImplBase:
+    _loggers: Dict[str, List['LoggerStrategyImplBase']] = defaultdict(list)
+
+    def __init__(self, output_func: Callable[[str], None], logger_id: str, channel: str = "all"):
+        logger.info("Initializing LoggerStrategyImplBase: id=%s, channel=%s", logger_id, channel)
+        self.output_func: Callable[[str], None] = output_func
+        self.channel: str = channel
+        self.logger_id: str = logger_id
+        LoggerStrategyImplBase._loggers[channel].append(self)
+        logger.info("Logger %s added to channel %s, total loggers: %s", logger_id, channel, len(LoggerStrategyImplBase._loggers[channel]))
+
+    def __call__(self, s: str) -> None:
+        self.output_func(s)
+
+    def delete(self) -> None:
+        logger.info("Deleting logger %s from channel %s", self.logger_id, self.channel)
+        LoggerStrategyImplBase._loggers[self.channel].remove(self)
+        logger.info("Logger deleted, remaining loggers in channel: %s", len(LoggerStrategyImplBase._loggers[self.channel]))
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.delete()
+
+
+__all__ = [
+    "LoggerStrategyImplBase"
+]

danielutils/logging_/utils.py

@@ -0,0 +1,199 @@
+import logging
+import sys
+import io
+from typing import Optional, Dict, List
+
+
+class UTF8StreamHandler(logging.StreamHandler):
+    """Custom StreamHandler that ensures UTF-8 encoding."""
+
+    def __init__(self, stream=None) -> None:
+        if stream is None:
+            stream = sys.stdout
+        super().__init__(stream)
+        # Ensure the stream uses UTF-8 encoding
+        if hasattr(stream, 'reconfigure'):
+            try:
+                stream.reconfigure(encoding='utf-8', errors='replace')
+            except (AttributeError, OSError):
+                pass
+
+    def emit(self, record):
+        try:
+            msg = self.format(record)
+            # Ensure the message is properly encoded
+            if isinstance(msg, str):
+                # Write as UTF-8 bytes to handle Unicode properly
+                self.stream.write(msg + self.terminator)
+            else:
+                self.stream.write(str(msg) + self.terminator)
+            self.flush()
+        except UnicodeError:
+            # Fallback for Unicode issues
+            try:
+                self.stream.write(f"Unicode error in log: {record.getMessage()}\n")
+                self.flush()
+            except Exception:
+                # Last resort - write to stderr
+                sys.stderr.write(f"Critical logging error: {record.getMessage()}\n")
+
+
+class ExtraDataFormatter(logging.Formatter):
+    """Custom formatter that includes extra data from log records."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        try:
+            # Get the base formatted message
+            base_message = super().format(record)
+
+            # Check for data in two ways:
+            # 1. Direct 'data' attribute
+            # 2. 'data' key inside 'extra' dict
+            data = getattr(record, 'data', None)
+            if data is None:
+                extra = getattr(record, 'extra', None)
+                if extra and isinstance(extra, dict):
+                    data = extra.get('data')
+
+            if data and isinstance(data, dict):
+                # Format data as key=value pairs, sorted alphabetically by key
+                # Handle Unicode characters safely
+                sorted_items = sorted(data.items())
+                data_pairs = []
+                for k, v in sorted_items:
+                    try:
+                        # Ensure both key and value are properly encoded
+                        k_str = str(k) if k is not None else 'None'
+                        v_str = str(v) if v is not None else 'None'
+                        data_pairs.append(f"{k_str}={v_str}")
+                    except UnicodeError:
+                        # Fallback for problematic Unicode characters
+                        data_pairs.append(f"{repr(k)}={repr(v)}")
+
+                data_str = " | " + " | ".join(data_pairs)
+                return base_message + data_str
+
+            return base_message
+        except UnicodeError as e:
+            # Fallback for any Unicode issues
+            return f"Unicode error in log formatting: {e} | {record.getMessage()}"
+
+
+class DanielUtilsLogFilter(logging.Filter):
+    """Filter to exclude danielutils logs when requested."""
+
+    def __init__(self, exclude_danielutils_logs: bool = True):
+        super().__init__()
+        self.exclude_danielutils_logs = exclude_danielutils_logs
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """
+        Filter log records based on whether danielutils logs should be excluded.
+        
+        Args:
+            record: The log record to filter
+            
+        Returns:
+            True if the record should be logged, False otherwise
+        """
+        if not self.exclude_danielutils_logs:
+            return True
+
+        # Check if the logger name starts with 'danielutils'
+        logger_name = record.name
+        return not logger_name.startswith('danielutils')
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance using Python's builtin logging.getLogger.
+    
+    This function simply delegates to the builtin logger and returns the result.
+
+    Args:
+        name: The name of the logger
+
+    Returns:
+        Logger instance from Python's builtin logging module
+    """
+    return logging.getLogger(name)
+
+
+def setup_stdout_logging_handler(
+        level: int = logging.INFO,
+        format_string: Optional[str] = None,
+        exclude_danielutils_logs: bool = True
+) -> logging.Logger:
+    """
+    Set up stdout logging handler for proper log propagation.
+    
+    This function adds a handler to the root logger so that all child loggers
+    will have their messages handled. This is the recommended approach for
+    logging configuration as it allows proper log propagation without
+    duplicating handlers on every logger.
+
+    Args:
+        level: The logging level (default: INFO)
+        format_string: Custom format string for log messages
+        exclude_danielutils_logs: Whether to exclude logs from danielutils modules (default: True)
+
+    Returns:
+        Root logger instance with the new handler added
+    """
+    if format_string is None:
+        format_string = '%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s'
+
+    # Get root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(level)
+
+    # Create console handler that outputs to stdout with UTF-8 encoding
+    console_handler = UTF8StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+
+    # Add filter to exclude danielutils logs if requested
+    if exclude_danielutils_logs:
+        danielutils_filter = DanielUtilsLogFilter(exclude_danielutils_logs=True)
+        console_handler.addFilter(danielutils_filter)
+
+    # Create formatter
+    formatter = ExtraDataFormatter(format_string)
+    console_handler.setFormatter(formatter)
+
+    # Add handler to root logger
+    root_logger.addHandler(console_handler)
+
+    return root_logger
+
+
+def get_logger_handlers() -> Dict[str, List[logging.Handler]]:
+    """
+    Get all registered loggers and their handlers.
+
+    Returns:
+        Dictionary mapping logger names to lists of their registered handlers
+    """
+    logger_dict = {}
+
+    # Get all existing loggers
+    for name in logging.Logger.manager.loggerDict:
+        logger = logging.getLogger(name)
+        if logger.handlers:
+            logger_dict[name] = logger.handlers.copy()
+
+    # Also include the root logger if it has handlers
+    root_logger = logging.getLogger()
+    if root_logger.handlers:
+        logger_dict['root'] = root_logger.handlers.copy()
+
+    return logger_dict
+
+
+__all__ = [
+    "UTF8StreamHandler",
+    "ExtraDataFormatter",
+    "DanielUtilsLogFilter",
+    "get_logger",
+    "setup_stdout_logging_handler",
+    "get_logger_handlers",
+]

danielutils/lombok/__init__.py

@@ -0,0 +1 @@
+from .builder import *

danielutils/lombok/builder.py

@@ -0,0 +1,68 @@
+import logging
+from typing import Type, Generic, TypeVar
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+T = TypeVar("T", bound=Type)
+
+
+class Builder(Generic[T]):
+    PREFIX: str = "foo"
+
+    def __init__(self, dcls: T):
+        logger.info("Initializing Builder for class: %s", dcls.__qualname__)
+        setattr(self, f"{Builder.PREFIX}_dcls", dcls)
+        setattr(self, f"{Builder.PREFIX}_kwargs", {})
+
+    def __getattribute__(self, item: str):
+        if item.startswith(Builder.PREFIX) or item == "build":
+            return super().__getattribute__(item)
+        
+        cls = super().__getattribute__(f"{Builder.PREFIX}_dcls")
+        
+        if item not in cls.__dataclass_fields__:
+            error_msg = f"'{cls.__qualname__}' object has no attribute '{item}'"
+            logger.error("AttributeError: %s", error_msg)
+            raise AttributeError(error_msg)
+
+        def inner(o) -> Builder:
+            getattr(self, f"{Builder.PREFIX}_kwargs")[item] = o
+            return self
+
+        return inner
+
+    def build(self) -> T:
+        dcls = getattr(self, f"{Builder.PREFIX}_dcls")
+        kwargs = getattr(self, f"{Builder.PREFIX}_kwargs")
+        instance = dcls(**kwargs)
+        logger.info("Successfully built instance of %s", dcls.__qualname__)
+        return instance
+
+
+def builder(dcls: T):
+    logger.info("Applying @builder decorator to class: %s", dcls.__qualname__)
+    
+    if not hasattr(dcls, "__dataclass_fields__"):
+        error_msg = "Can only create builders out of @dataclass classes"
+        logger.error("RuntimeError: %s", error_msg)
+        raise RuntimeError(error_msg)
+    
+    for name in dcls.__dataclass_fields__.keys():
+        if name.startswith("build"):
+            error_msg = f"@builder reserves attributes that has 'build' prefix. Invalid attribute: '{name}'"
+            logger.error("AttributeError: %s", error_msg)
+            raise AttributeError(error_msg)
+    
+    @classmethod  # type: ignore
+    def builder_impl(cls) -> Builder[T]:
+        return Builder[T](cls)
+
+    setattr(dcls, "builder", builder_impl)
+    logger.info("Successfully applied @builder decorator to %s", dcls.__qualname__)
+    return dcls
+
+
+__all__ = [
+    "builder"
+]

danielutils/math_/__init__.py

@@ -0,0 +1,2 @@
+from .constants import *
+from .functions import *

danielutils/math_/constants.py

@@ -0,0 +1,103 @@
+"""mathematical constants that are useful in calculations"""
+PI = 3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
+E = 2.7182818284590452353602874713526624977572470936999595749669676277240766303535475945713821785251664274
+PRIMES_1000 = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31,
+               37, 41, 43, 47, 53, 59, 61, 67, 71, 73,
+               79, 83, 89, 97, 101, 103, 107, 109, 113, 127,
+               131, 137, 139, 149, 151, 157, 163, 167, 173, 179,
+               181, 191, 193, 197, 199, 211, 223, 227, 229, 233,
+               239, 241, 251, 257, 263, 269, 271, 277, 281, 283,
+               293, 307, 311, 313, 317, 331, 337, 347, 349, 353,
+               359, 367, 373, 379, 383, 389, 397, 401, 409, 419,
+               421, 431, 433, 439, 443, 449, 457, 461, 463, 467,
+               479, 487, 491, 499, 503, 509, 521, 523, 541, 547,
+               557, 563, 569, 571, 577, 587, 593, 599, 601, 607,
+               613, 617, 619, 631, 641, 643, 647, 653, 659, 661,
+               673, 677, 683, 691, 701, 709, 719, 727, 733, 739,
+               743, 751, 757, 761, 769, 773, 787, 797, 809, 811,
+               821, 823, 827, 829, 839, 853, 857, 859, 863, 877,
+               881, 883, 887, 907, 911, 919, 929, 937, 941, 947,
+               953, 967, 971, 977, 983, 991, 997, 1009, 1013, 1019,
+               1021, 1031, 1033, 1039, 1049, 1051, 1061, 1063, 1069, 1087,
+               1091, 1093, 1097, 1103, 1109, 1117, 1123, 1129, 1151, 1153,
+               1163, 1171, 1181, 1187, 1193, 1201, 1213, 1217, 1223, 1229,
+               1231, 1237, 1249, 1259, 1277, 1279, 1283, 1289, 1291, 1297,
+               1301, 1303, 1307, 1319, 1321, 1327, 1361, 1367, 1373, 1381,
+               1399, 1409, 1423, 1427, 1429, 1433, 1439, 1447, 1451, 1453,
+               1459, 1471, 1481, 1483, 1487, 1489, 1493, 1499, 1511, 1523,
+               1531, 1543, 1549, 1553, 1559, 1567, 1571, 1579, 1583, 1597,
+               1601, 1607, 1609, 1613, 1619, 1621, 1627, 1637, 1657, 1663,
+               1667, 1669, 1693, 1697, 1699, 1709, 1721, 1723, 1733, 1741,
+               1747, 1753, 1759, 1777, 1783, 1787, 1789, 1801, 1811, 1823,
+               1831, 1847, 1861, 1867, 1871, 1873, 1877, 1879, 1889, 1901,
+               1907, 1913, 1931, 1933, 1949, 1951, 1973, 1979, 1987, 1993,
+               1997, 1999, 2003, 2011, 2017, 2027, 2029, 2039, 2053, 2063,
+               2069, 2081, 2083, 2087, 2089, 2099, 2111, 2113, 2129, 2131,
+               2137, 2141, 2143, 2153, 2161, 2179, 2203, 2207, 2213, 2221,
+               2237, 2239, 2243, 2251, 2267, 2269, 2273, 2281, 2287, 2293,
+               2297, 2309, 2311, 2333, 2339, 2341, 2347, 2351, 2357, 2371,
+               2377, 2381, 2383, 2389, 2393, 2399, 2411, 2417, 2423, 2437,
+               2441, 2447, 2459, 2467, 2473, 2477, 2503, 2521, 2531, 2539,
+               2543, 2549, 2551, 2557, 2579, 2591, 2593, 2609, 2617, 2621,
+               2633, 2647, 2657, 2659, 2663, 2671, 2677, 2683, 2687, 2689,
+               2693, 2699, 2707, 2711, 2713, 2719, 2729, 2731, 2741, 2749,
+               2753, 2767, 2777, 2789, 2791, 2797, 2801, 2803, 2819, 2833,
+               2837, 2843, 2851, 2857, 2861, 2879, 2887, 2897, 2903, 2909,
+               2917, 2927, 2939, 2953, 2957, 2963, 2969, 2971, 2999, 3001,
+               3011, 3019, 3023, 3037, 3041, 3049, 3061, 3067, 3079, 3083,
+               3089, 3109, 3119, 3121, 3137, 3163, 3167, 3169, 3181, 3187,
+               3191, 3203, 3209, 3217, 3221, 3229, 3251, 3253, 3257, 3259,
+               3271, 3299, 3301, 3307, 3313, 3319, 3323, 3329, 3331, 3343,
+               3347, 3359, 3361, 3371, 3373, 3389, 3391, 3407, 3413, 3433,
+               3449, 3457, 3461, 3463, 3467, 3469, 3491, 3499, 3511, 3517,
+               3527, 3529, 3533, 3539, 3541, 3547, 3557, 3559, 3571, 3581,
+               3583, 3593, 3607, 3613, 3617, 3623, 3631, 3637, 3643, 3659,
+               3671, 3673, 3677, 3691, 3697, 3701, 3709, 3719, 3727, 3733,
+               3739, 3761, 3767, 3769, 3779, 3793, 3797, 3803, 3821, 3823,
+               3833, 3847, 3851, 3853, 3863, 3877, 3881, 3889, 3907, 3911,
+               3917, 3919, 3923, 3929, 3931, 3943, 3947, 3967, 3989, 4001,
+               4003, 4007, 4013, 4019, 4021, 4027, 4049, 4051, 4057, 4073,
+               4079, 4091, 4093, 4099, 4111, 4127, 4129, 4133, 4139, 4153,
+               4157, 4159, 4177, 4201, 4211, 4217, 4219, 4229, 4231, 4241,
+               4243, 4253, 4259, 4261, 4271, 4273, 4283, 4289, 4297, 4327,
+               4337, 4339, 4349, 4357, 4363, 4373, 4391, 4397, 4409, 4421,
+               4423, 4441, 4447, 4451, 4457, 4463, 4481, 4483, 4493, 4507,
+               4513, 4517, 4519, 4523, 4547, 4549, 4561, 4567, 4583, 4591,
+               4597, 4603, 4621, 4637, 4639, 4643, 4649, 4651, 4657, 4663,
+               4673, 4679, 4691, 4703, 4721, 4723, 4729, 4733, 4751, 4759,
+               4783, 4787, 4789, 4793, 4799, 4801, 4813, 4817, 4831, 4861,
+               4871, 4877, 4889, 4903, 4909, 4919, 4931, 4933, 4937, 4943,
+               4951, 4957, 4967, 4969, 4973, 4987, 4993, 4999, 5003, 5009,
+               5011, 5021, 5023, 5039, 5051, 5059, 5077, 5081, 5087, 5099,
+               5101, 5107, 5113, 5119, 5147, 5153, 5167, 5171, 5179, 5189,
+               5197, 5209, 5227, 5231, 5233, 5237, 5261, 5273, 5279, 5281,
+               5297, 5303, 5309, 5323, 5333, 5347, 5351, 5381, 5387, 5393,
+               5399, 5407, 5413, 5417, 5419, 5431, 5437, 5441, 5443, 5449,
+               5471, 5477, 5479, 5483, 5501, 5503, 5507, 5519, 5521, 5527,
+               5531, 5557, 5563, 5569, 5573, 5581, 5591, 5623, 5639, 5641,
+               5647, 5651, 5653, 5657, 5659, 5669, 5683, 5689, 5693, 5701,
+               5711, 5717, 5737, 5741, 5743, 5749, 5779, 5783, 5791, 5801,
+               5807, 5813, 5821, 5827, 5839, 5843, 5849, 5851, 5857, 5861,
+               5867, 5869, 5879, 5881, 5897, 5903, 5923, 5927, 5939, 5953,
+               5981, 5987, 6007, 6011, 6029, 6037, 6043, 6047, 6053, 6067,
+               6073, 6079, 6089, 6091, 6101, 6113, 6121, 6131, 6133, 6143,
+               6151, 6163, 6173, 6197, 6199, 6203, 6211, 6217, 6221, 6229,
+               6247, 6257, 6263, 6269, 6271, 6277, 6287, 6299, 6301, 6311,
+               6317, 6323, 6329, 6337, 6343, 6353, 6359, 6361, 6367, 6373,
+               6379, 6389, 6397, 6421, 6427, 6449, 6451, 6469, 6473, 6481,
+               6491, 6521, 6529, 6547, 6551, 6553, 6563, 6569, 6571, 6577,
+               6581, 6599, 6607, 6619, 6637, 6653, 6659, 6661, 6673, 6679,
+               6689, 6691, 6701, 6703, 6709, 6719, 6733, 6737, 6761, 6763,
+               6779, 6781, 6791, 6793, 6803, 6823, 6827, 6829, 6833, 6841,
+               6857, 6863, 6869, 6871, 6883, 6899, 6907, 6911, 6917, 6947,
+               6949, 6959, 6961, 6967, 6971, 6977, 6983, 6991, 6997, 7001,
+               7013, 7019, 7027, 7039, 7043, 7057, 7069, 7079, 7103, 7109,
+               7121, 7127, 7129, 7151, 7159, 7177, 7187, 7193, 7207, 7211,
+               7213, 7219, 7229, 7237, 7243, 7247, 7253, 7283, 7297, 7307,
+               7309, 7321, 7331, 7333, 7349, 7351, 7369, 7393, 7411, 7417,
+               7433, 7451, 7457, 7459, 7477, 7481, 7487, 7489, 7499, 7507,
+               7517, 7523, 7529, 7537, 7541, 7547, 7549, 7559, 7561, 7573,
+               7577, 7583, 7589, 7591, 7603, 7607, 7621, 7639, 7643, 7649,
+               7669, 7673, 7681, 7687, 7691, 7699, 7703, 7717, 7723, 7727,
+               7741, 7753, 7757, 7759, 7789, 7793, 7817, 7823, 7829, 7841,
+               7853, 7867, 7873, 7877, 7879, 7883, 7901, 7907, 7919]

danielutils/math_/functions.py

@@ -0,0 +1,34 @@
+from typing import Union
+from ..decorators import validate
+
+
+@validate  # type:ignore
+def sign(v: Union[int, float]) -> int:
+    """return the sign of the number
+
+    Args:
+        v (Union[int, float]): number
+
+    Returns:
+        int: either 1 or -1
+    """
+    if v >= 0:
+        return 1
+    return -1
+
+
+def lp_norm(arr, p: Union[int, float]) -> float:
+    """calculates a norm over the data
+    """
+    return root(sum(abs(v)**p for v in arr), p)
+
+
+def root(value, power: Union[int, float]) -> float:
+    """calculates any root over value
+    """
+    return value**(1/power)
+
+
+__all__ = [
+    "sign"
+]

danielutils/math_/math_print.py

@@ -0,0 +1,52 @@
+import logging
+from .math_symbols import subscript_dict, superscript_dict
+from ..logging_.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def mprint_parse_one(s: str) -> str:
+    """a helper function that parses "mathematically" one string
+
+    Args:
+        s (str): the string to parse with math_ symbols
+
+    Returns:
+        str: the result
+    """
+    logger.info("Parsing mathematical string: %s", s)
+
+    def inner(res: str, index: int, dct: dict):
+        start = index
+        while index < len(s) and s[index] not in {' ', '*', '+', '-', '/', '_', '^'}:
+            index += 1
+        end = index
+        for char in s[start:end]:
+            if char in dct:
+                res += dct[char]
+            else:
+                res += char
+        index -= 1
+        return res, index
+    
+    res: str = ""
+    i = 0
+    while i < len(s):
+        c = s[i]
+        if c == "^":
+            i += 1
+            res, i = inner(res, i, superscript_dict)
+        elif c == "_":
+            i += 1
+            res, i = inner(res, i, subscript_dict)
+        else:
+            res += c
+        i += 1
+    
+    logger.info("Parsing completed, result: %s", res)
+    return res
+
+
+__all__ = [
+    "mprint_parse_one"
+]