cdxcore 0.1.5__py3-none-any.whl → 0.1.9__py3-none-any.whl

cdxcore/crman.py

@@ -1,52 +1,91 @@
-"""
-crman
-Managing \r updates
-Hans Buehler 2023
+r"""
+Overview
+--------
+
+A very simple implementation of a tool that tracks the last printed line before a newline was encountered.
+Helps with somewhat consistent progress reporting with "\\r" and "\\n" characters.
+
+*This functionality does not quite work accross all terminal types which were tested. Main focus is to make
+it work for Jupyer for now. Any feedback on
+how to make this more generically operational is welcome.
+
+Used by :class:`cdxcore.verbose.Context`.
+
+Import
+------
+
+.. code-block:: python
+
+    from cdxcore.crman import CRman
+
 """
 
 from collections.abc import Callable
-from .logger import Logger#
-_log = Logger(__file__)
 
 class CRMan(object):
-    """
-    Carraige Return ('\r') manager.    
-    This class is meant to enable efficient per-line updates using '\r' for text output with a focus on making it work with both Jupyter and the command shell.
-    In particular, Jupyter does not support the ANSI \33[2K 'clear line' code.
+    r"""
+    Carriage Return ("\\r") manager.    
     
+    This class is meant to enable efficient per-line updates using "\\r" for text output with a focus on making it work with both Jupyter and the command shell.
+    In particular, Jupyter does not support the ANSI `\\33[2K` 'clear line' code. To simulate clearing
+    lines, ``CRMan`` keeps track of the length of the current line, and clears it by appending spaces to a message
+    following "\\r"
+    accordingly.
+                                                         
+    *This functionality does not quite work accross all terminal types which were tested. Main focus is to make
+    it work for Jupyer for now. Any feedback on
+    how to make this more generically operational is welcome.*
+    
+    .. code-block:: python
+
         crman = CRMan()
         print( crman("\rmessage 111111"), end='' )
         print( crman("\rmessage 2222"), end='' )
         print( crman("\rmessage 33"), end='' )
         print( crman("\rmessage 1\n"), end='' )
+    
+    prints::
         
-        --> message 1     
-        
+        message 1     
+    
+    While
+    
+    .. code-block:: python
+
         print( crman("\rmessage 111111"), end='' )
         print( crman("\rmessage 2222"), end='' )
         print( crman("\rmessage 33"), end='' )
         print( crman("\rmessage 1"), end='' )
-        print( crman("... and more"), end='' )
+        print( crman("... and more.") )
         
-        --> message 1... and more
+    prints
+
+    .. code-block:: python.
+    
+        message 1... and more
     """
     
     def __init__(self):
-        """ See help(CRMan) """
+        """
+        See :class:`cdxcore.crman.CRMan`               
+        :meta private:
+        """
         self._current = ""
         
     def __call__(self, message : str) -> str:
-        """
-        Convert 'message' containing '\r' and '\n' into a printable string which ensures that '\r' string do not lead to printed artifacts.
-        Afterwards, the object will retain any text not terminated by '\n'
+        r"""
+        Convert `message` containing "\\r" and "\\n" into a printable string which ensures
+        that a "\\r" string does not lead to printed artifacts.
+        Afterwards, the object will retain any text not terminated by "\\n".
         
         Parameters
         ----------
-            message : str
-                message containing \r and \n.
-                
+        message : str
+            message containing "\\r" and "\\n".
+            
         Returns
         -------
+        Message: str
             Printable string.
         """
         if message is None:
@@ -56,6 +95,8 @@ class CRMan(object):
         output = ""
         
         # first line
+        # handle any `current` line
+        
         line   = lines[0]
         icr    = line.rfind('\r')
         if icr == -1:
@@ -63,6 +104,7 @@ class CRMan(object):
         else:
             line = line[icr+1:]
         if len(self._current) > 0:
+            # print spaces to clear current line in terminals which do not support \33[2K'
             output    += '\r' + ' '*len(self._current) + '\r' + '\33[2K' + '\r'
         output        += line
         self._current = line
@@ -79,6 +121,7 @@ class CRMan(object):
                 output += line + '\n'
                 
             # final line
+            # keep track of any residuals in `current`
             line      = lines[-1]
             if len(line) > 0:
                 icr           = line.rfind('\r')
@@ -89,13 +132,38 @@ class CRMan(object):
         return output
             
     def reset(self):
-        """ Reset object """
+        """
+        Reset object.
+        """
         self._current = ""
         
-    def write(self, text, end='', flush=True, channel : Callable = None ):
+    @property
+    def current(self) -> str:
         """
-        Write to stdout using \r and \n translations.
-        The 'end' and 'flush' parameters mirror those of print()
+        Return current string.
+        
+        This is the string that ``CRMan``is currently visible to the user
+        since the last time a new line was printed.
+        """
+        return self._current
+        
+    def write(self, text : str, end : str = '', flush : bool = True, channel : Callable = None ):
+        r"""
+        Write to a ``channel``,
+        
+        Writes ``text`` to ``channel`` taking into account any ``current`` lines
+        and any "\\r" and "\\n" contained in ``text``.
+        The ``end`` and ``flush`` parameters mirror those of
+        :func:`print`.
+                                                                 
+        Parameters
+        ----------
+        text : str
+            Text to print, containing "\\r" and "\\n".
+        end, flush : optional
+            ``end`` and ``flush`` parameters mirror those of :func:`print`.
+        channel : Callable
+            Callable to output the residual text. If ``None``, the default, use :func:`print` to write to ``stdout``.
         """
         text = self(text+end)
         if channel is None:
@@ -103,3 +171,5 @@ class CRMan(object):
         else:
             channel( text, flush=flush )
         return self
+
+

cdxcore/err.py

@@ -0,0 +1,371 @@
+# -*- coding: utf-8 -*-
+"""
+Overview
+--------
+
+Basic error handling and reporting functions.
+
+The main use of this module are the functions
+:func:`cdxcore.err.verify` and :func:`cdxcore.err.warn_if`.
+Both test some runtime condition and will either
+raise an ``Exception`` or issue a ``Warning`` if triggered. In both cases, required string formatting is only performed
+if the event is actually triggered.
+
+This way we are able to write neat code which produces robust,
+informative errors and warnings without impeding runtime performance.
+
+Example::
+    
+    from cdxcore.err import verify, warn_if
+    import numpy as np
+    
+    def f( x : np.ndarray ):
+        std = np.std(x,axis=0,keepdims=True)
+        verify( np.all( std>1E-8 ), "Cannot normalize 'x' by standard deviation: standard deviations are {std}", std=std )
+        x /= std        
+        
+    f( np.zeros((10,10)) )
+    
+raises a :class:`RuntimeError`
+
+.. code-block:: python
+
+    Cannot normalize 'x' by standard deviation: standard deviations are [[0. 0. 0. 0. 0. 0. 0. 0. 0. 0.]]
+
+For warnings, we can use ``warn_if``::
+
+    from cdxcore.err import verify, warn_if
+    import numpy as np
+    
+    def f( x : np.ndarray ):
+        std = np.std(x,axis=0,keepdims=True)
+        warn_if( not np.all( std>1E-8 ), lambda : f"Normalizing 'x' by standard deviation: standard deviations are {std}" )
+        x   = np.where( std<1E-8, 0., x/np.where( std<1E-8, 1., std ) )
+        
+    f( np.zeros((10,10)) )
+    
+issues a warning::
+
+    RuntimeWarning: Normalizing 'x' by standard deviation: standard deviations are [[0. 0. 0. 0. 0. 0. 0. 0. 0. 0.]]
+      warn_if( not np.all( std>1E-8 ), "Normalizing 'x' by standard deviation: standard deviations are {std}", std=std )    
+
+Note that though we used two different approaches for message formatting, the the error messages in both cases
+are only formatted if the condition in ``verify`` is not met.
+
+Import
+------
+.. code-block:: python
+
+    from cdxcore.err import verify, warn_if, error, warn
+    
+Documentation
+-------------
+"""
+
+import warnings as warnings
+import os as os
+from collections.abc import Callable
+
+def _fmt( text : str, args = None, kwargs = None, f : Callable =  None ) -> str:
+    """ Utility function. See [cdxcore.err.fmt][]() . 'f' not currently used.':meta private: """
+    args   = None if not args is None and len(args) == 0 else args
+    kwargs = None if not kwargs is None and len(kwargs) == 0 else kwargs
+    
+    # callable
+    if not isinstance(text, str) and callable(text):
+        # handle callable
+        # we pass args and kwargs as provided
+        if not args is None:
+            if not kwargs is None:
+                return text(* args, ** kwargs)
+            else:
+                return text(*args)
+        elif not kwargs is None :
+            return text(**kwargs)
+        return text()
+    text = str(text)
+        
+    # text
+    # C-style positional parameters first
+    if not args is None:
+        # args are only valid for c-style %d, %s
+        if not kwargs is None:
+            raise ValueError("Cannot specify both 'args' and 'kwargs'", text)
+        try:    
+            return text % tuple(args)
+        except TypeError as e:
+            raise TypeError(e, text, args)
+    # text
+    # python 2 and 3 mode
+    kwargs = dict() if kwargs is None else kwargs
+    if text.find("%(") == -1:
+        return text.format(**kwargs)
+    else:
+        return text % kwargs
+    
+def fmt(text : str|Callable, * args, ** kwargs) -> str:
+    """
+    Basic tool for delayed string formatting.
+    
+    The main use case is that formatting is not executed until this function is called,
+    hence potential error messages are not generated until an error actually occurs.
+    See, for example, :func:`cdxcore.err.verify`.
+    
+    The follwing example illustrates all four supported modi operandi::
+        
+        from cdxcore.err import fmt
+        one = 1
+        fmt(lambda : f"one {one:d})   # using a lambda function
+        fmt("one {one:d}", one=one)   # using python 3 string.format()
+        fmt("one %{one}ld", one=one)  # using python 2 style
+        fmt("one %ld", one)           # using c-style
+    
+    As shown, do not use f-strings directly as they are immediately executed in the scope they are typed in
+    but wrap them with a ``lambda`` function.
+    
+    Parameters
+    ----------    
+    text : str | Callable
+        Error text which may contain one of the following string formatting patterns:
+        
+        * Python 3 ```{parameter:d}```, in which case ``message.fmt(kwargs)`` for :meth:`str.format` is used
+          to obtain the output message.
+        
+        * Python 2 ```%(parameter)d``` in which case ``message % kwargs`` is used to obtain the output message.
+        
+        * Classic C-stype ```%d, %s, %f``` in which case ``message % args`` is used to obtain the output message.
+        
+        * If ``message`` is a ``Callable`` such as a ``lambda`` function, then ``message( * args, ** kwargs )``
+          is called to obtain the output message.
+          
+          A common use case is using an f-string wrapped in a ``lambda`` function; see example above.
+        
+    * args, ** kwargs:
+        See above
+
+    Returns
+    -------
+    Text : str
+        The formatted message.
+    """
+    return _fmt(text=text,args=args,kwargs=kwargs,f=fmt)
+
+def error( text : str|Callable, *args, exception : Exception = RuntimeError, **kwargs ):
+    """
+    Raise an exception with string formatting.
+    
+    See also :func:`cdxcore.err.fmt` for formatting comments.
+    The point of this function is to have an interface which is consistent with
+    :func:`cdxcore.err.verify`.
+
+    Examples::
+
+        from cdxcore.err import error
+        one = 1
+        error(lambda : f"one {one:d}")  # wrapped f-string
+        error("one {one:d}", one=one)   # using python 3 string.format()
+        error("one %{one}ld", one=one)  # using python 2 style
+        error("one %ld", one)           # using c-style
+    
+    As shown, do not use f-strings directly as they are immediately executed in the scope they are typed in
+    but wrap them with a ``lambda`` function.
+
+    Parameters
+    ----------
+    text : str | Callable
+        Error text which may contain one of the following string formatting patterns:
+        
+        * Python 3 ```{parameter:d}```, in which case ``message.fmt(kwargs)`` for :meth:`str.format` is used
+          to obtain the output message.
+        
+        * Python 2 ```%(parameter)d``` in which case ``message % kwargs`` is used to obtain the output message.
+        
+        * Classic C-stype ```%d, %s, %f``` in which case ``message % args`` is used to obtain the output message.
+        
+        * If ``message`` is a ``Callable`` such as a ``lambda`` function, then ``message( * args, ** kwargs )``
+          is called to obtain the output message.
+          
+          A common use case is using an f-string wrapped in a ``lambda`` function; see example above.
+        
+    exception : Exception, optional
+        Which type of exception to raise. Defaults to :class:`RuntimeError`.
+
+    * args, ** kwargs:
+        See above
+
+    Raises
+    ------
+    exception : exception
+    """
+    text = _fmt(text=text,args=args,kwargs=kwargs,f=error)
+    raise exception( text )
+    
+def verify( cond : bool, text : str|Callable, *args, exception : Exception = RuntimeError, **kwargs ):
+    """
+    Raise an exception using delayed error string formatting if a condition is not met.
+    
+    The point of this function is to only format an error message if a condition ``cond`` is not met
+    and an error is to be raised.
+
+    Examples::
+        
+        from cdxcore.err import verify
+        one = 1
+        good = False                           # some condition
+        verify(good, lambda : f"one {one:d}")  # wrapped f-string
+        verify(good, "one {one:d}", one=one)   # using python 3 string.format()
+        verify(good, "one %{one}ld", one=one)  # using python 2 style
+        verify(good, "one %ld", one)           # using c-style
+    
+    As shown, do not use f-strings directly as they are immediately executed in the scope they are typed in
+    but wrap them with a ``lambda`` function.
+    
+    Parameters
+    ----------
+    cond : bool
+        Condition to test.
+    
+    text : str | Callable
+        Error text which may contain one of the following string formatting patterns:
+        
+        * Python 3 ```{parameter:d}```, in which case ``message.fmt(kwargs)`` for :meth:`str.format` is used
+          to obtain the output message.
+        
+        * Python 2 ```%(parameter)d``` in which case ``message % kwargs`` is used to obtain the output message.
+        
+        * Classic C-stype ```%d, %s, %f``` in which case ``message % args`` is used to obtain the output message.
+        
+        * If ``message`` is a ``Callable`` such as a ``lambda`` function, then ``message( * args, ** kwargs )``
+          is called to obtain the output message.
+          
+          A common use case is using an f-string wrapped in a ``lambda`` function; see example above.
+        
+    exception : Exception, optiona
+        Which type of exception to raise. Defaults to :class:`RuntimeError`.
+
+    * args, ** kwargs:
+        See above
+
+    Raises
+    ------
+    exception : exception
+    """
+    if not cond:
+        text = _fmt(text=text,args=args,kwargs=kwargs,f=verify)
+        raise exception( fmt(text, * args, ** kwargs) )
+
+_warn_skips = (os.path.dirname(__file__),)
+
+def warn( text : str|Callable, *args, warning = RuntimeWarning, stack_level : int = 1, **kwargs ):
+    """
+    Issue a warning.
+    
+    The point of this function is to have an interface consistent with :func:`cdxcore.err.warn_if`.
+
+    Examples::
+        
+        from cdxcore.err import warn
+        one = 1        
+        warn(lambda : f"one {one:d}")  # wrapped f-string
+        warn("one {one:d}", one=one)   # using python 3 string.format()
+        warn("one %{one}ld", one=one)  # using python 2 style
+        warn("one %ld", one)           # using c-style
+    
+    As shown, do not use f-strings directly as they are immediately executed in the scope they are typed in
+    but wrap them with a ``lambda`` function.
+    
+    Parameters
+    ----------
+    text : str | Callable
+        Error text which may contain one of the following string formatting patterns:
+        
+        * Python 3 ```{parameter:d}```, in which case ``message.fmt(kwargs)`` for :meth:`str.format` is used
+          to obtain the output message.
+        
+        * Python 2 ```%(parameter)d``` in which case ``message % kwargs`` is used to obtain the output message.
+        
+        * Classic C-stype ```%d, %s, %f``` in which case ``message % args`` is used to obtain the output message.
+        
+        * If ``message`` is a ``Callable`` such as a ``lambda`` function, then ``message( * args, ** kwargs )``
+          is called to obtain the output message.
+          
+          A common use case is using an f-string wrapped in a ``lambda`` function; see example above.
+        
+    warning : optional
+        Which type of warning to issue. 
+        This corresponds to the ``category`` parameter for :func:`warnings.warn`.
+        Default is :class:`RuntimeWarning`.
+
+    stack_level : int, optional
+        What stack to report; see :func:`warnings.warn`.
+        Default is 1, which means ``warn`` itself is not reported as part of the stack trace.
+
+    * args, ** kwargs:
+        See above
+    """
+    warnings.warn( message=text,
+                   category=warning,
+                   stacklevel=stack_level,
+                   skip_file_prefixes=_warn_skips )
+
+def warn_if( cond : bool, text : str|Callable, *args, warning = RuntimeWarning, stack_level : int = 1, **kwargs ):    
+    """
+    Issue a warning with delayed string formatting if a condition is met.
+    
+    The point of this function is to only format an error message if a condition ``cond`` is met
+    and a warning is to be issued.
+
+    Examples::
+            
+        from cdxcore.err import warn_if
+        one = 1       
+        bad = True                            # some conditon
+        warn_if(bad,lambda : f"one {one:d}")  # wrapped f-string
+        warn_if(bad,"one {one:d}", one=one)   # using python 3 string.format()
+        warn_if(bad,"one %{one}ld", one=one)  # using python 2 style
+        warn_if(bad,"one %ld", one)           # using c-style
+    
+    As shown, do not use f-strings directly as they are immediately executed in the scope they are typed in
+    but wrap them with a ``lambda`` function.
+    
+    Parameters
+    ----------
+    cond : bool
+        Condition to test.
+        
+    text : str | Callable
+        Error text which may contain one of the following string formatting patterns:
+        
+        * Python 3 ```{parameter:d}```, in which case ``message.fmt(kwargs)`` for :meth:`str.format` is used
+          to obtain the output message.
+        
+        * Python 2 ```%(parameter)d``` in which case ``message % kwargs`` is used to obtain the output message.
+        
+        * Classic C-stype ```%d, %s, %f``` in which case ``message % args`` is used to obtain the output message.
+        
+        * If ``message`` is a ``Callable`` such as a ``lambda`` function, then ``message( * args, ** kwargs )``
+          is called to obtain the output message.
+          
+          A common use case is using an f-string wrapped in a ``lambda`` function; see example above.
+        
+    warning : optional
+        Which type of warning to issue. 
+        This corresponds to the ``category`` parameter for :func:`warnings.warn`.
+        Default is :class:`RuntimeWarning`.
+
+    stack_level : int, optional
+        What stack to report; see :func:`warnings.warn`.
+        Default is 1, which means ``warn`` itself is not reported as part of the stack trace.
+
+    * args, ** kwargs:
+        See above
+    """
+    if cond:
+        text = _fmt(text=text,args=args,kwargs=kwargs,f=warn_if)
+        warnings.warn( message=text,
+                       category=warning,
+                       stacklevel=stack_level,
+                       skip_file_prefixes=_warn_skips )
+        
+
+