PrEditor 2.1.0__py3-none-any.whl

preditor/config.py

@@ -0,0 +1,318 @@
+from __future__ import absolute_import
+
+import logging
+from functools import wraps
+
+logger = logging.getLogger(__name__)
+
+
+def set_if_unlocked(track_state=False):
+    def _set_if_unlocked(func):
+        """Decorate property setter functions to prevent editing after locking."""
+
+        @wraps(func)
+        def wrapper(self, value):
+            if not self.is_locked(func.__name__, track_state=track_state):
+                # logger.debug(f'"{func.__name__}" is unlocked and can be set: {value}')
+                return func(self, value)
+            # logger.info(
+            #     f'"{func.__name__}" is locked and can no-longer be set: {value}'
+            # )
+
+        return wrapper
+
+    return _set_if_unlocked
+
+
+class PreditorConfig:
+    """Global configuration of PrEditor's instance.
+
+    When creating the main PrEditor instance it will use `preditor.config` to
+    control how its initialized. That stores an instance of this class.
+
+    Once `preditor.instance(create=True)` the properties on this class will then
+    silently ignore any attempts to set most of its properties. Where noted in
+    the property doc-strings, some properties are used to install a setting that
+    can't be automatically undone, so they will stop responding after the first
+    setting.
+
+    While this class does not force a singleton pattern, it is expected in normal
+    operation that there will only ever be a single instance made and it is stored
+    on `preditor.config` when first imported. Things like excepthook and streams
+    modify python's state which could lead to duplicate outputs, multiple error
+    prompts or other undesirable behavior.
+    """
+
+    def __init__(self):
+        self._locks = {}
+        self._name = None
+        self._logging = False
+        self._headless_callback = None
+        self._on_create_callback = None
+        self._parent_callback = None
+        self._error_dialog_class = True
+        self._excepthooks = []
+
+    def dump(self, indent=0):
+        """A convenient way to inspect the current configuration."""
+        ret = [
+            f"{' ' * indent}name: {self.name}",
+            f"{' ' * indent}streams: {self.streams}",
+            f"{' ' * indent}excepthook: {self.excepthook!r}",
+            f"{' ' * indent}excepthooks: {self.excepthooks!r}",
+            f"{' ' * indent}error_dialog_class: {self.error_dialog_class!r}",
+            f"{' ' * indent}logging: {self.logging}",
+            f"{' ' * indent}headless_callback: {self.headless_callback!r}",
+            f"{' ' * indent}parent_callback: {self.parent_callback!r}",
+            f"{' ' * indent}on_create_callback: {self.on_create_callback!r}",
+        ]
+        return '\n'.join(ret)
+
+    def is_locked(self, value, track_state=False):
+        """Returns if value is locked and can not be updated.
+
+        Once `preditor.instance` returns a value this will always return False.
+        The config settings should not be modified once the instance is created.
+
+        Args:
+            value (str): The name of the value to check. Should match a property
+                name on this class.
+            track_state (bool, optional): If True then also check if value has
+                been flagged as locked. This indicates that it was already set
+                by a previous call and can no longer be modified even if instance
+                is False.
+        """
+        if self.instance(create=False):
+            # if the instance is created all items are locked
+            return True
+        if track_state:
+            return self._locks.get(value, False)
+        return False
+
+    @property
+    def error_dialog_class(self):
+        """Dialog class shown if PrEditor isn't visible and a error happens.
+
+        This dialog is used to prompt the user to show PrEditor and can be
+        sub-classed to add extra functionality. This is called by
+        `PreditorExceptHook.ask_to_show_logger` method when added to
+        `preditor.config.excepthooks`.
+
+        If set to `True` then `blurdev.gui.errordialog.ErrorDialog` is used. When
+        replacing this, it should be a sub-class of that class or re-implement
+        its api.
+
+        You can use an EntryPoint string like `preditor.gui.errordialog:ErrorDialog`
+        instead of passing the actual class object. This lets you delay the import
+        until actually needed.
+        """
+        return self._error_dialog_class
+
+    @error_dialog_class.setter
+    def error_dialog_class(self, cls):
+        self._error_dialog_class = cls
+
+    @property
+    def excepthook(self):
+        """Installs a `sys.excepthook` handler when first set to True.
+
+        Replaces `sys.excepthook` with a interactive exception handler that
+        prompts the user to show PrEditor when an python exception is raised.
+        It is recommended that you only add the excepthook once the Qt UI is
+        initialized. See: :py:class:`preditor.excepthooks.PreditorExceptHook`.
+        """
+        return self._locks.get("excepthook", False)
+
+    @excepthook.setter
+    @set_if_unlocked(track_state=True)
+    def excepthook(self, value):
+        if not value:
+            return
+
+        # Install the excepthook:
+        import preditor.excepthooks
+
+        # Note: install checks if the current excepthook is a instance of this
+        # class and prevents installing a second time.
+        preditor.excepthooks.PreditorExceptHook.install()
+
+        # Disable future setting via `set_if_unlocked`, the `PreditorExceptHook`
+        # is a chaining except hook that calls the previous excepthook when called.
+        # We don't want to install multiple automatically, the user can define that
+        # logic if required.
+        self._locks["excepthook"] = True
+
+    @property
+    def excepthooks(self):
+        """A list of callables that are called when an exception is handled.
+
+        If `excepthook` is enabled installing `PreditorExceptHook` then it will
+        call each item in this list. The signature of the function should be
+        `callable(*args)`. If not configured it will automatically install default
+        callables. You can add `None` to disable this.
+        """
+        return self._excepthooks
+
+    @property
+    def headless_callback(self):
+        """A pointer to a method that is called by `is_headless`.
+
+        This callback returns a bool indicating if PrEditor should attempt to
+        create GUI elements. Application integrations can set this callback to
+        give them control over what PrEditor gets parent to.
+        """
+        return self._headless_callback
+
+    @headless_callback.setter
+    @set_if_unlocked()
+    def headless_callback(self, cb):
+        self._headless_callback = cb
+
+    @classmethod
+    def instance(cls, parent=None, run_workbox=False, create=True):
+        """Returns the existing instance of the PrEditor gui creating it on first call.
+
+        Args:
+            parent (QWidget, optional): If the instance hasn't been created yet, create
+                it and parent it to this object.
+            run_workbox (bool, optional): If the instance hasn't been created yet, this
+                will execute the active workbox's code once fully initialized.
+            create (bool, optional): Returns None if the instance has not been created.
+
+        Returns:
+            Returns a fully initialized instance of the PrEditor gui. If called more
+            than once, the same instance will be returned. If create is False, it may
+            return None.
+        """
+        from .gui.loggerwindow import LoggerWindow
+
+        return LoggerWindow.instance(
+            parent=parent, run_workbox=run_workbox, create=create
+        )
+
+    def is_headless(self):
+        """Returns True if PrEditor should not create GUI items.
+
+        Returns None if the `headless_callback` has not been configured. Otherwise
+        returns the result of calling `headless_callback()` which should return a bool.
+        """
+        if not self.headless_callback:
+            return None
+        return self.headless_callback()
+
+    @property
+    def logging(self):
+        """Restore the python logging configuration settings that were recorded
+        the last time PrEditor prefs were saved.
+
+        If called multiple times with different name's before the instance is
+        created, this will reset the logging configuration from the previous
+        name if logging prefs exist.
+        """
+        return self._logging
+
+    @logging.setter
+    def logging(self, state):
+        self._logging = state
+        self.update_logging()
+
+    @property
+    def name(self):
+        """The name to use for the global instance of PrEditor.
+
+        Once this has been set, you can call `preditor.launch` without passing
+        name to access the main instance. The name controls what preferences
+        are loaded and used by PrEditor including the workbox tabs."""
+        return self._name
+
+    @name.setter
+    @set_if_unlocked()
+    def name(self, name):
+        changed = self.name != name
+        self._name = name
+
+        if changed:
+            # If the core name was changed attempt to update the logging config.
+            self.update_logging()
+
+    @property
+    def on_create_callback(self):
+        """A pointer to a method that is called on LoggerWindow instance create.
+
+        This callback accepts the instance and can be used to customize the
+        LoggerWindow instance when it is first created.
+        """
+        return self._on_create_callback
+
+    @on_create_callback.setter
+    @set_if_unlocked()
+    def on_create_callback(self, cb):
+        self._on_create_callback = cb
+
+    @property
+    def parent_callback(self):
+        """A pointer to a method that is called by `self.root_window`.
+
+        This callback returns a QWidget to use as the parent of the LoggerWindow
+        when the instance is first created. This can be used by DCC's to set the
+        parent to their main window."""
+        return self._parent_callback
+
+    @parent_callback.setter
+    @set_if_unlocked()
+    def parent_callback(self, cb):
+        self._parent_callback = cb
+
+    def root_window(self):
+        """The QWidget to use as the parent of PrEditor widgets."""
+        # If a parent widget callback was configured, use it
+        if self.parent_callback is not None:
+            return self.parent_callback()
+
+        # Otherwise, attempt to find the top level widget from Qt
+        from .gui.app import App
+
+        return App.root_window()
+
+    @property
+    def streams(self):
+        """Installs the stream managers when first set to True.
+
+        Install the stream manager to capture any stdout/stderr text written.
+        Later when calling launch, the LoggerWindow will show all of the captured
+        text. This lets you only create the LoggerWindow IF you need to show it,
+        but when you do it will have all of the std stream text written after
+        this is enabled."""
+        return self._locks.get("streams", False)
+
+    @streams.setter
+    @set_if_unlocked(track_state=True)
+    def streams(self, value):
+        if not value:
+            return
+
+        # Install the stream manager to capture output
+        from .stream import install_to_std
+
+        install_to_std()
+
+        # Disable re-installing streams.
+        self._locks["streams"] = True
+
+    def update_logging(self):
+        """Install/replace the logging config.
+
+        This does nothing unless `logging` is set to True and `name` is set.
+
+        Note: When called repeatedly, this won't remove old logger's added by
+        previous calls so you may see some loggers added that were never
+        actually added by code other than the LoggingConfig.
+        """
+
+        if not (self.logging and self.name):
+            return
+
+        from .logging_config import LoggingConfig
+
+        cfg = LoggingConfig(core_name=self.name)
+        cfg.load()

preditor/constants.py

@@ -0,0 +1,13 @@
+import enum
+
+
+class StreamType(enum.Flag):
+    """Different types of streams used by PrEditor."""
+
+    STDERR = enum.auto()
+    STDIN = enum.auto()
+    STDOUT = enum.auto()
+    CONSOLE = enum.auto()
+    """Write directly to the console ignoring STDERR/STDOUT filters."""
+    RESULT = enum.auto()
+    """Write directly to ConsolePrEdit's result output without using  stdout/err."""

preditor/contexts.py

@@ -0,0 +1,210 @@
+from __future__ import absolute_import
+
+import logging
+from contextlib import contextmanager
+from typing import List, Tuple
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class ErrorReport(object):
+    """Allows you to provide additional debug info if a error happens in this context.
+
+    PrEditor can send a error email when any python error is raised.
+    Sometimes just a traceback does not provide enough information to debug the
+    traceback. This class allows you to provide additional information to the error
+    report only if it is generated. For example if your treegrunt environment does not
+    have a email setup, or the current debug level is not set to Disabled.
+
+    ErrorReport can be used as a with context, or as a function decorator.
+
+    Examples:
+        This example shows a class using both the with context and a decorated method.
+
+        from preditor.contexts import ErrorReport
+        class Test(object):
+            def __init__(self):
+                self.value = None
+            def errorInfo(self):
+                # The text returned by this function will be included in the error email
+                return 'Info about the Test class: {}'.format(self.value)
+            def doStuff(self):
+                with ErrorReport(self.errorInfo, 'Test.doStuff'):
+                    self.value = 'doStuff'
+                    raise RuntimeError("BILL")
+            @ErrorReport(errorInfo, 'Test.doMoreStuff')
+            def doMoreStuff(self):
+                self.value = 'doMoreStuff'
+                raise RuntimeError("BOB")
+
+    Using this class does not initialize the Python Logger, so you don't need to worry
+    if your class is running headless and not use this class. However unless you set up
+    your own error reporting system the callbacks will not be called and nothing will be
+    reported.
+
+    If you want to set up your own error reporting system you need to set
+    `ErrorReport.enabled = True`. Then you will need to call ErrorReport.clearReports()
+    any time excepthook is called. This prevents a buildup of all error reports any time
+    a exception occurs. It should always be in place when you set enabled == True to
+    prevent wasting memory. Calling ErrorReport.generateReport() will return the info
+    you should include in your report. Calling generateReport is optional, but must be
+    called before calling clearReports.
+
+    Args:
+        callback (function): If a exception happens this function is called and its
+            returned value is added to the error email if sent. No arguments are passed
+            to this function and it is expected to only return a string.
+        title (str, optional): This short string is added to the title of the
+            ErrorReport.
+    Attributes:
+        enabled (bool): If False(the default), then all callbacks are cleared even if
+            there is a exception. This is used to prevent these functions from leaking
+            memory if there isn't a excepthook calling clearReports.
+    """
+
+    __reports__: List[Tuple[str, str]] = []
+    enabled = False
+
+    def __init__(self, callback, title=''):
+        self._callback = callback
+        self._title = title
+
+    def __call__(self, funct):
+        def wrapper(wrappedSelf, *args, **kwargs):
+            unbound = self._callback
+            self._callback = self._callback.__get__(wrappedSelf)
+            try:
+                with self:
+                    return funct(wrappedSelf, *args, **kwargs)
+            finally:
+                self._callback = unbound
+
+        return wrapper
+
+    def __enter__(self):
+        type(self).__reports__.append((self._title, self._callback))
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # If exc_type is None, then no exception was raised, so we should remove the
+        # callback. If cls.enabled is False, then nothing has set itself up to call
+        # clearReports. We need to remove the callback so it doesn't stay in memory.
+        if exc_type is None or not type(self).enabled:
+            type(self).__reports__.remove((self._title, self._callback))
+
+    @classmethod
+    def clearReports(cls):
+        """Removes all of the currently stored callbacks.
+
+        This should be called after all error reporting is finished, or if a error
+        happened and there is nothing to report it. If you set cls.enabled to True,
+        something in excepthook should call this to prevent keeping refrences to
+        functions from staying in memory.
+        """
+        cls.__reports__ = []
+
+    @classmethod
+    def generateReport(cls, fmt='{result}'):
+        """Executes and returns all of the currently stored callbacks.
+        Args:
+
+            ftm (str, Optional): The results of the callbacks will be inserted into this
+                string using str.format into {results}.
+        Returns:
+            list: A list of tuples for all active ErrorReport classes. The tuples
+                contain two strings; the title string, and result of the passed in
+                callback function.
+        """
+        ret = []
+        for title, callback in cls.__reports__:
+            result = callback()
+            ret.append((title, fmt.format(result=result)))
+        return ret
+
+
+@contextmanager
+def OverrideConsoleStreams(
+    consoles,
+    tracebacks=None,
+    stdout=None,
+    stderr=None,
+    result=None,
+    logging_handlers=None,
+):
+    """Override a Console's stream and logging_handlers settings.
+
+    This is useful if you don't want to show tracebacks or output for un-related code.
+
+    Example:
+
+        console = OutputConsole()
+        with OverrideConsoleStreams(console, tracebacks=True)
+            # A traceback raised here would show in console
+            do_work_you_only_want_to_show_tracebacks_in_console()
+        raise RuntimeError("This traceback will not be shown in console")
+    """
+    # If a single console was passed, convert it into a list
+    try:
+        iter(consoles)
+    except TypeError:
+        consoles = [consoles]
+
+    # Store the current state and apply changes to the consoles
+    current = []
+    for console in consoles:
+        current.append(
+            (
+                console,
+                None if tracebacks is None else console.stream_echo_tracebacks,
+                None if stdout is None else console.stream_echo_stdout,
+                None if stderr is None else console.stream_echo_stderr,
+                None if result is None else console.stream_echo_result,
+                None if logging_handlers is None else console.logging_handlers,
+            )
+        )
+
+        if tracebacks is not None:
+            # Enable/disable traceback display override
+            console.stream_echo_tracebacks = tracebacks
+            if tracebacks:
+                # traceback display is enabled, make it automatically remove
+                # itself if an exception is raised by the sys.excepthook handler.
+                console._write_error_self_destruct = True
+        if stdout is not None:
+            console.stream_echo_stdout = stdout
+        if stderr is not None:
+            console.stream_echo_stderr = stderr
+        if result is not None:
+            console.stream_echo_result = result
+        if logging_handlers is not None:
+            console.logging_handlers = logging_handlers
+
+    # NOTE: This code is a horrible abomination of necessity.
+    try:
+        yield
+    except Exception:
+        # This is syntactically needed, we don't need to capture the exception,
+        # but the else requires it. We need raise any un-handled exceptions
+        # encountered to allow sys.excepthook to process normally.
+        # This prevents the else code from removing the traceback print overriding
+        # because the else/finally are processed before sys.excepthook is.
+        raise
+    else:
+        # Only called when exception was not raised. Restore the original traceback
+        # and disable the self destructing flag its not needed anymore.
+        for item in current:
+            if tracebacks is not None:
+                item[0].stream_echo_tracebacks = item[1]
+                if tracebacks:
+                    item[0]._write_error_self_destruct = False
+    finally:
+        # Always remove non-traceback options. This is handled before excepthook
+        # so we can just use the simplicity of a normal try/finally statement.
+        for item in current:
+            if stdout is not None:
+                item[0].stream_echo_stdout = item[2]
+            if stderr is not None:
+                item[0].stream_echo_stderr = item[3]
+            if result is not None:
+                item[0].stream_echo_result = item[4]
+            if logging_handlers is not None:
+                item[0].logging_handlers = item[5]

preditor/cores/core.py

@@ -0,0 +1,20 @@
+from __future__ import absolute_import, print_function
+
+from Qt.QtCore import QObject
+
+
+class Core(QObject):
+    """
+    The Core class provides all the main shared functionality and signals that need to
+    be distributed between different pacakges.
+    """
+
+    def __init__(self, objectName=None):
+        super(Core, self).__init__()
+        if objectName is None:
+            objectName = 'PrEditor'
+        self.setObjectName(objectName)
+
+        # Paths in this variable will be removed in
+        # preditor.osystem.subprocessEnvironment
+        self._removeFromPATHEnv = set()

preditor/dccs/.hab.json

@@ -0,0 +1,10 @@
+{
+    "name": "preditor",
+    "version": "0.0.dev0",
+    "environment": {
+        "append": {
+            "MAYA_MODULE_PATH": "{relative_root}/maya",
+            "ADSK_APPLICATION_PLUGINS": "{relative_root}/studiomax"
+        }
+    }
+}

preditor/dccs/maya/PrEditor_maya.mod

@@ -0,0 +1 @@
++ PrEditor DEVELOPMENT .

preditor/dccs/maya/README.md

@@ -0,0 +1,22 @@
+# Maya Integration
+
+This is an example of using an Maya module to add PrEditor into Maya. This adds
+a PrEditor menu with a PrEditor action in Maya's menu bar letting you open PrEditor. It
+adds the excepthook so if a python exception is raised it will prompt the user
+to show PrEditor. PrEditor will show all python stdout/stderr output generated
+after the plugin is loaded.
+
+# Setup
+
+Make sure to follow these [setup instructions](/preditor/README.md#Setup) first to create the virtualenv.
+
+Alternatively you can use [myapy's](https://help.autodesk.com/view/MAYAUL/2026/ENU/?guid=GUID-72A245EC-CDB4-46AB-BEE0-4BBBF9791627) pip to install the requirements, but a
+separate virtualenv is recommended. This method should not require setting the
+`PREDITOR_SITE` environment variable even if you use an editable install.
+
+# Use
+
+The [preditor/dccs/maya](/preditor/dccs/maya) directory is setup as a Maya Module. To load it in
+maya add the full path to that directory to the `MAYA_MODULE_PATH` environment
+variable. You can use `;` on windows and `:` on linux to join multiple paths together.
+You will need to enable auto load for the `PrEditor_maya.py` plugin.