PrEditor 2.1.0__py3-none-any.whl

preditor/utils/__init__.py

@@ -0,0 +1,191 @@
+import errno
+import json
+import os
+import sys
+import traceback
+from pathlib import Path
+
+
+class Json:
+    """Load a json file with a better tracebacks if something goes wrong.
+
+    Args:
+        filename (pathlib.Path): The path to the file being loaded/parsed. Unless
+            `json_str` is also provided load will use `json.load` to parse the
+            contents of this json file.
+        json_str (str, optional): If provided then uses `json.loads` to parse
+            this value. `filename` must be provided and will be included in any
+            exceptions that are raised parsing this text.
+    """
+
+    def __init__(self, filename, json_str=None):
+        if isinstance(filename, str):
+            filename = Path(filename)
+        self.filename = filename
+        self.json_str = json_str
+
+    @classmethod
+    def _load_json(cls, source, load_funct, *args, **kwargs):
+        """Work function that parses json and ensures any errors report the source.
+
+        Args:
+            source (os.PathLike or str): The source of the json data. This is
+                reported in any raised exceptions.
+            load_funct (callable): A function called to parse the json data.
+                Normally this is `json.load` or `json.loads`.
+            *args: Arguments passed to `load_funct`.
+            *kwargs: Keyword arguments passed to `load_funct`.
+
+        Raises:
+            FileNotFoundError: If filename is not pointing to a file that
+                actually exists.
+            ValueError: The error raised due to invalid json.
+        """
+        try:
+            return load_funct(*args, **kwargs)
+        except ValueError as e:
+            # Using python's native json parser
+            msg = f'{e} Source("{source}")'
+            raise type(e)(msg, e.doc, e.pos).with_traceback(sys.exc_info()[2]) from None
+
+    def load(self):
+        """Parse and return self.json_str if defined otherwise self.filename."""
+        if self.json_str:
+            return self.loads_json(self.json_str, self.filename)
+        return self.load_json_file(self.filename)
+
+    @classmethod
+    def load_json_file(cls, filename):
+        """Open and parse a json file. If a parsing error happens the file path
+        is added to the exception to allow for easier debugging.
+
+        Args:
+            filename (pathlib.Path): A existing file path.
+
+        Returns:
+            The data stored in the json file.
+
+        Raises:
+            FileNotFoundError: If filename is not pointing to a file that
+                actually exists.
+            ValueError: The error raised due to invalid json.
+        """
+        if not filename.is_file():
+            raise FileNotFoundError(
+                errno.ENOENT, os.strerror(errno.ENOENT), str(filename)
+            )
+
+        with filename.open() as fle:
+            data = cls._load_json(filename, json.load, fle)
+        return data
+
+    @classmethod
+    def loads_json(cls, json_str, source):
+        """Open and parse a json string. If a parsing error happens the source
+        file path is added to the exception to allow for easier debugging.
+
+        Args:
+            json_str (str): The json data to parse.
+            source (pathlib.Path): The location json_str was pulled from.
+                This is reported if any parsing errors happen.
+
+        Returns:
+            The data stored in the json file.
+
+        Raises:
+            FileNotFoundError: If filename is not pointing to a file that
+                actually exists.
+            ValueError: The error raised due to invalid json.
+        """
+        return cls._load_json(source, json.loads, json_str)
+
+
+class ShellPrint:
+    """Utilities to print to sys.__stdout__/__stderr__ bypassing the PrEditor streams.
+
+    This allows you to write to the host console instead of PrEditor's interface.
+    This helps when developing for the stream or console classes if you cause an
+    exception you might get no traceback printed to debug otherwise.
+
+    On windows if using gui mode app(pythonw.exe) that doesn't have a console
+    the methods will not print anything and just return False. If possible switch
+    to using python.exe or install another file stream like `preditor.debug.FileLogger`,
+    but they will need to be installed on `sys.__stdout__/__stderr__`.
+    """
+
+    def __init__(self, error=False):
+        self.error = error
+
+    def print(self, *args, **kwargs):
+        """Prints to the shell."""
+        if "file" in kwargs:
+            raise KeyError(
+                "file can not be passed to `ShellPrint.print`. Instead use error."
+            )
+        # Check for pythonw.exe's lack of streams and exit
+        kwargs["file"] = self.stream
+        if kwargs["file"] is None:
+            """Note: This protects against errors like this when using pythonw
+              File "preditor/stream/director.py", line 124, in write
+                super().write(msg)
+            RuntimeError: reentrant call inside <_io.BufferedWriter name='nul'>
+            """
+            return False
+
+        # Print to the host stream
+        print(*args, **kwargs)
+        return True
+
+    def print_exc(self, msg, limit=None, chain=True, width=79):
+        """Prints a header line, the current exception and a footer line to shell.
+
+        This must be called from inside of a try/except statement.
+        """
+        stream = self.stream
+        if stream is None:
+            return False
+
+        print(f" {msg} ".center(width, "-"), file=sys.__stderr__)
+        traceback.print_exc(limit=limit, file=stream, chain=chain)
+        print(f" {msg} ".center(width, "-"), file=sys.__stderr__)
+        return True
+
+    @property
+    def stream(self):
+        if self.error:
+            return sys.__stderr__
+        return sys.__stdout__
+
+
+class Truncate:
+    def __init__(self, text, sep='...'):
+        self.text = text
+        self.sep = sep
+        self.sep_spaces = f' {sep} '
+
+    def middle(self, n=100):
+        """Truncates the provided text to a fixed length, putting the sep in the middle.
+        https://www.xormedia.com/string-truncate-middle-with-ellipsis/
+        """
+        if len(self.text) <= n:
+            # string is already short-enough
+            return self.text
+        # half of the size, minus the seperator
+        n_2 = int(n) // 2 - len(self.sep_spaces)
+        # whatever's left
+        n_1 = n - n_2 - len(self.sep_spaces)
+        return '{0}{1}{2}'.format(self.text[:n_1], self.sep_spaces, self.text[-n_2:])
+
+    def lines(self, max_lines=20):
+        """Truncates the provided text to a maximum number of lines with a separator
+        at the end if required.
+        """
+        lines = self.text.split("\n")
+        orig_len = len(lines)
+        lines = lines[:max_lines]
+        trim_len = len(lines)
+        if orig_len != trim_len:
+            lines.append("...")
+        truncated = "\n".join(lines)
+
+        return truncated

preditor/utils/call_stack.py

@@ -0,0 +1,86 @@
+import functools
+import inspect
+import logging
+import threading
+
+_logger = logging.getLogger(__name__)
+
+
+class CallStack:
+    """Decorator that logs the inputs and return of the decorated function.
+
+    For most cases use `@preditor.utils.call_stack.log_calls`, but if you want
+    to create a custom configured version you can create your own instance of
+    `CallStack` to customize the output.
+
+    Parameters:
+        logger: A python logging instance to write log messages to.
+        level: Write to logger using this debug level.
+        print: If set to True use the print function instead of python logging.
+        input_prefix: Text shown before the function name.
+        return_prefix: Text shown before the return data.
+    """
+
+    def __init__(self, logger=None, level=logging.DEBUG, print=True):
+        self._call_depth = threading.local()
+        self.logger = _logger if logger is None else logger
+        self.level = level
+        self.print = print
+        self.input_prefix = "\u2192"
+        self.return_prefix = "\u2190"
+
+    @property
+    def indent(self):
+        return getattr(self._call_depth, "indent", 0)
+
+    @indent.setter
+    def indent(self, indent):
+        self._call_depth.indent = indent
+
+    def log(self, msg):
+        if self.print:
+            print(msg)
+        else:
+            self.logger.log(self.level, msg, stacklevel=2)
+
+    def log_calls(self, func):
+        """Decorator that writes function input and return value.
+        If another decorated function call is made during the first call it's
+        output will be indented to reflect that.
+        """
+        # Check for and remove self and cls arguments once during decoration
+        sig = inspect.signature(func)
+        params = list(sig.parameters.values())
+        slice_index = 1 if params and params[0].name in ("self", "cls") else 0
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # remove 'self' or 'cls' from positional display (but do NOT remove kwargs)
+            # display_args = args[1:] if slice_index and args else args
+            display_args = args[slice_index:]
+
+            # Generate repr of the calling arguments
+            parts = [repr(a) for a in display_args]
+            parts += [f"{k}={v!r}" for k, v in kwargs.items()]
+            arg_str = ", ".join(parts)
+
+            indent = "  " * self.indent
+            self.log(f"{indent}{self.input_prefix} {func.__qualname__}({arg_str})")
+
+            self.indent += 1
+            try:
+                result = func(*args, **kwargs)
+            finally:
+                self.indent -= 1
+
+            self.log(f"{indent}{self.return_prefix} {result!r}")
+            return result
+
+        return wrapper
+
+
+call_stack = CallStack()
+"""An shared instance for ease of use and configuration"""
+
+log_calls = call_stack.log_calls
+"""Use `from preditor.utils.call_stack import log_calls` as a shared decorator."""

preditor/utils/cute.py

@@ -0,0 +1,106 @@
+__all__ = ["ensureWindowIsVisible"]
+from functools import partial
+
+# NOTE: Only import QtWidgets and QtGui inside functions not at the module level
+# to preserve headless environment support.
+from Qt.QtCore import Property
+
+
+def ensureWindowIsVisible(widget):
+    """
+    Checks the widget's geometry against all of the system's screens. If it does
+    not intersect, it will reposition it to the top left corner of the highest
+    numbered screen. Returns a boolean indicating if it had to move the widget.
+    """
+    from Qt.QtWidgets import QApplication
+
+    screens = QApplication.screens()
+    geo = widget.geometry()
+
+    for screen in screens:
+        if screen.geometry().intersects(geo):
+            break
+    else:
+        monGeo = screens[-1].geometry()  # Use the last screen available
+        geo.moveTo(monGeo.x() + 7, monGeo.y() + 30)
+
+        # Setting the geometry may trigger a second check if setGeometry is overridden
+        disable = hasattr(widget, 'checkScreenGeo') and widget.checkScreenGeo
+        if disable:
+            widget.checkScreenGeo = False
+        widget.setGeometry(geo)
+        if disable:
+            widget.checkScreenGeo = True
+        return True
+    return False
+
+
+def QtPropertyInit(name, default, callback=None, typ=None):
+    """Initializes a default Property value with a usable getter and setter.
+
+    You can optionally pass a function that will get called any time the property
+    is set. If using the same callback for multiple properties, you may want to
+    use the preditor.decorators.singleShot decorator to prevent your function getting
+    called multiple times at once. This callback must accept the attribute name and
+    value being set.
+
+    Example:
+        class TestClass(QWidget):
+            def __init__(self, *args, **kwargs):
+                super(TestClass, self).__init__(*args, **kwargs)
+
+            stdoutColor = QtPropertyInit('_stdoutColor', QColor(0, 0, 255))
+            pyForegroundColor = QtPropertyInit('_pyForegroundColor', QColor(0, 0, 255))
+
+    Args:
+        name(str): The name of internal attribute to store to and lookup from.
+        default: The property's default value.  This will also define the Property type
+            if typ is not set. To define a property containing a list, dict or set,
+            pass the list, dict, or set class not an instance of the class. Ie pass
+            `list` not `[]`. See flake8-bugbear rule B006 for more info.
+        callback(callable): If provided this function is called when the property is
+            set.
+        typ (class, optional): If not None this value is used to specify the type of
+            the Property. This is useful when you need to specify a property as python's
+            object but pass a default value of a given class.
+
+    Returns:
+        Property
+    """
+
+    # Prevent all instances of class sharing a mutable data structure. If the
+    # default is one of these classes and not a instance of them, replace them
+    # with an instance of the default class.
+    # See flake8-bugbear B006: Do not use mutable data structures for argument
+    # defaults. They are created during function definition time. All calls to
+    # the function reuse this one instance of that data structure, persisting
+    # changes between them.
+    is_mutable = default in (list, dict, set)
+
+    def _getattrDefault(default, is_mutable, self, attrName):
+        try:
+            value = getattr(self, attrName)
+        except AttributeError:
+            # Create a unique instance of the default mutable class for self.
+            if is_mutable:
+                default = default()
+
+            setattr(self, attrName, default)
+            return default
+        return value
+
+    def _setattrCallback(callback, attrName, self, value):
+        setattr(self, attrName, value)
+        if callback:
+            callback(self, attrName, value)
+
+    ga = partial(_getattrDefault, default, is_mutable)
+    sa = partial(_setattrCallback, callback, name)
+    # Use the default value's class if typ is not provided.
+    if typ is None:
+        if is_mutable:
+            # In this case the type is the same as the default
+            typ = default
+        else:
+            typ = default.__class__
+    return Property(typ, fget=(lambda s: ga(s, name)), fset=(lambda s, v: sa(s, v)))

preditor/utils/stylesheets.py

@@ -0,0 +1,54 @@
+from __future__ import absolute_import
+
+import glob
+import os
+
+
+def read_stylesheet(stylesheet='', path=None):
+    """Returns the contents of the requested stylesheet.
+
+    Args:
+
+        stylesheet (str): the name of the stylesheet. Attempt to load stylesheet.css
+            shipped with preditor. Ignored if path is provided.
+
+        path (str): Return the contents of this file path.
+
+    Returns:
+        str: The contents of stylesheet or blank if stylesheet was not found.
+        valid: A stylesheet was found and loaded.
+    """
+    if path is None:
+        path = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+            'resource',
+            'stylesheet',
+            '{}.css'.format(stylesheet),
+        )
+    if os.path.isfile(path):
+        with open(path) as f:
+            return f.read(), True
+    return '', False
+
+
+def stylesheets(subFolder=None):
+    """Returns a list of installed stylesheet names.
+
+    Args:
+        subFolder (str or None, optional): Use this to access sub-folders of
+            the stylesheet resource directory.
+
+    Returns:
+        list: A list .css file paths in the target directory.
+    """
+    components = [
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        'resource',
+        'stylesheet',
+    ]
+    if subFolder is not None:
+        components.append(subFolder)
+    cssdir = os.path.join(*components)
+    cssfiles = sorted(glob.glob(os.path.join(cssdir, '*.css')))
+    # Only return the filename without the .css extension
+    return [os.path.splitext(os.path.basename(fp))[0] for fp in cssfiles]