PrEditor 1.0.0__py3-none-any.whl

preditor/weakref.py

@@ -0,0 +1,363 @@
+# coding: utf-8
+# /*##########################################################################
+#
+# Copyright (c) 2016-2018 European Synchrotron Radiation Facility
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# ###########################################################################*/
+# Code pulled from the silx codebase
+# https://github.com/silx-kit/silx/blob/master/src/silx/utils/weakref.py
+"""Weakref utils for compatibility between Python 2 and Python 3 or for
+extended features.
+"""
+from __future__ import absolute_import
+
+__authors__ = ["V. Valls"]
+__license__ = "MIT"
+__date__ = "15/09/2016"
+
+
+import inspect
+import types
+import weakref
+
+
+def ref(object, callback=None):
+    """Returns a weak reference to object. The original object can be retrieved
+    by calling the reference object if the referent is still alive. If the
+    referent is no longer alive, calling the reference object will cause None
+    to be returned.
+
+    The signature is the same as the standard `weakref` library, but it returns
+    `WeakMethod` if the object is a bound method.
+
+    :param object: An object
+    :param func callback: If provided, and the returned weakref object is
+        still alive, the callback will be called when the object is about to
+        be finalized. The weak reference object will be passed as the only
+        parameter to the callback. Then the referent will no longer be
+        available.
+    :return: A weak reference to the object
+    """
+    if inspect.ismethod(object):
+        return WeakMethod(object, callback)
+    else:
+        return weakref.ref(object, callback)
+
+
+def proxy(object, callback=None):
+    """Return a proxy to object which uses a weak reference. This supports use
+    of the proxy in most contexts instead of requiring the explicit
+    dereferencing used with weak reference objects.
+
+    The signature is the same as the standard `weakref` library, but it returns
+    `WeakMethodProxy` if the object is a bound method.
+
+    :param object: An object
+    :param func callback: If provided, and the returned weakref object is
+        still alive, the callback will be called when the object is about to
+        be finalized. The weak reference object will be passed as the only
+        parameter to the callback. Then the referent will no longer be
+        available.
+    :return: A proxy to a weak reference of the object
+    """
+    if inspect.ismethod(object):
+        return WeakMethodProxy(object, callback)
+    else:
+        return weakref.proxy(object, callback)
+
+
+class WeakMethod(object):
+    """Wraps a callable object like a function or a bound method.
+    Feature callback when the object is about to be finalized.
+    Provids the same interface as a normal weak reference.
+    """
+
+    def __init__(self, function, callback=None):
+        """
+        Constructor
+        :param function: Function/method to be called
+        :param callback: If callback is provided and not None,
+            and the returned weakref object is still alive, the
+            callback will be called when the object is about to
+            be finalized; the weak reference object will be passed
+            as the only parameter to the callback; the referent will
+            no longer be available
+        """
+        self.__callback = callback
+
+        if inspect.ismethod(function):
+            # it is a bound method
+            self.__obj = weakref.ref(function.__self__, self.__call_callback)
+            self.__method = weakref.ref(function.__func__, self.__call_callback)
+        else:
+            self.__obj = None
+            self.__method = weakref.ref(function, self.__call_callback)
+
+    def __call_callback(self, ref):
+        """Called when the object is about to be finalized"""
+        if not self.is_alive():
+            return
+        self.__obj = None
+        self.__method = None
+        if self.__callback is not None:
+            self.__callback(self)
+
+    def __call__(self):
+        """Return a callable function or None if the WeakMethod is dead."""
+        if self.__obj is not None:
+            method = self.__method()
+            obj = self.__obj()
+            if method is None or obj is None:
+                return None
+            return types.MethodType(method, obj)
+        elif self.__method is not None:
+            return self.__method()
+        else:
+            return None
+
+    def is_alive(self):
+        """True if the WeakMethod is still alive"""
+        return self.__method is not None
+
+    def __eq__(self, other):
+        """Check it another obect is equal to this.
+
+        :param object other: Object to compare with
+        """
+        if isinstance(other, WeakMethod):
+            if not self.is_alive():
+                return False
+            return self.__obj == other.__obj and self.__method == other.__method
+        return False
+
+    def __ne__(self, other):
+        """Check it another obect is not equal to this.
+
+        :param object other: Object to compare with
+        """
+        if isinstance(other, WeakMethod):
+            if not self.is_alive():
+                return False
+            return self.__obj != other.__obj or self.__method != other.__method
+        return True
+
+    def __hash__(self):
+        """Returns the hash for the object."""
+        return self.__obj.__hash__() ^ self.__method.__hash__()
+
+
+class WeakMethodProxy(WeakMethod):
+    """Wraps a callable object like a function or a bound method
+    with a weakref proxy.
+    """
+
+    def __call__(self, *args, **kwargs):
+        """Dereference the method and call it if the method is still alive.
+        Else raises an ReferenceError.
+
+        :raises: ReferenceError, if the method is not alive
+        """
+        fn = super(WeakMethodProxy, self).__call__()
+        if fn is None:
+            raise ReferenceError("weakly-referenced object no longer exists")
+        return fn(*args, **kwargs)
+
+
+class WeakList(list):
+    """Manage a list of weaked references.
+    When an object is dead, the list is flaged as invalid.
+    If expected the list is cleaned up to remove dead objects.
+    """
+
+    def __init__(self, enumerator=()):
+        """Create a WeakList
+
+        :param iterator enumerator: A list of object to initialize the
+            list
+        """
+        list.__init__(self)
+        self.__list = []
+        self.__is_valid = True
+        for obj in enumerator:
+            self.append(obj)
+
+    def __invalidate(self, ref):
+        """Flag the list as invalidated. The list contains dead references."""
+        self.__is_valid = False
+
+    def __create_ref(self, obj):
+        """Create a weakref from an object. It uses the `ref` module function."""
+        return ref(obj, self.__invalidate)
+
+    def __clean(self):
+        """Clean the list from dead references"""
+        if self.__is_valid:
+            return
+        self.__list = [ref for ref in self.__list if ref() is not None]
+        self.__is_valid = True
+
+    def __iter__(self):
+        """Iterate over objects of the list"""
+        for ref in self.__list:
+            obj = ref()
+            if obj is not None:
+                yield obj
+
+    def __len__(self):
+        """Count item on the list"""
+        self.__clean()
+        return len(self.__list)
+
+    def __getitem__(self, key):
+        """Returns the object at the requested index
+
+        :param key: Indexes to get
+        :type key: int or slice
+        """
+        self.__clean()
+        data = self.__list[key]
+        if isinstance(data, list):
+            result = [ref() for ref in data]
+        else:
+            result = data()
+        return result
+
+    def __setitem__(self, key, obj):
+        """Set an item at an index
+
+        :param key: Indexes to set
+        :type key: int or slice
+        """
+        self.__clean()
+        if isinstance(key, slice):
+            objs = [self.__create_ref(o) for o in obj]
+            self.__list[key] = objs
+        else:
+            obj_ref = self.__create_ref(obj)
+            self.__list[key] = obj_ref
+
+    def __delitem__(self, key):
+        """Delete an Indexes item of this list
+
+        :param key: Index to delete
+        :type key: int or slice
+        """
+        self.__clean()
+        del self.__list[key]
+
+    def __delslice__(self, i, j):
+        """Looks to be used in Python 2.7"""
+        self.__delitem__(slice(i, j, None))
+
+    def __setslice__(self, i, j, sequence):
+        """Looks to be used in Python 2.7"""
+        self.__setitem__(slice(i, j, None), sequence)
+
+    def __getslice__(self, i, j):
+        """Looks to be used in Python 2.7"""
+        return self.__getitem__(slice(i, j, None))
+
+    def __reversed__(self):
+        """Returns a copy of the reverted list"""
+        reversed_list = reversed(list(self))
+        return WeakList(reversed_list)
+
+    def __contains__(self, obj):
+        """Returns true if the object is in the list"""
+        ref = self.__create_ref(obj)
+        return ref in self.__list
+
+    def __add__(self, other):
+        """Returns a WeakList containing this list an the other"""
+        l = WeakList(self)  # noqa: E741
+        l.extend(other)
+        return l
+
+    def __iadd__(self, other):
+        """Add objects to this list inplace"""
+        self.extend(other)
+        return self
+
+    def __mul__(self, n):
+        """Returns a WeakList containing n-duplication object of this list"""
+        return WeakList(list(self) * n)
+
+    def __imul__(self, n):
+        """N-duplication of the objects to this list inplace"""
+        self.__list *= n
+        return self
+
+    def append(self, obj):
+        """Add an object at the end of the list"""
+        ref = self.__create_ref(obj)
+        self.__list.append(ref)
+
+    def count(self, obj):
+        """Returns the number of occurencies of an object"""
+        ref = self.__create_ref(obj)
+        return self.__list.count(ref)
+
+    def extend(self, other):
+        """Append the list with all objects from another list"""
+        for obj in other:
+            self.append(obj)
+
+    def index(self, obj):
+        """Returns the index of an object"""
+        ref = self.__create_ref(obj)
+        return self.__list.index(ref)
+
+    def insert(self, index, obj):
+        """Insert an object at the requested index"""
+        ref = self.__create_ref(obj)
+        self.__list.insert(index, ref)
+
+    def pop(self, index=-1):
+        """Remove and return an object at the requested index"""
+        self.__clean()
+        obj = self.__list.pop(index)()
+        return obj
+
+    def remove(self, obj):
+        """Remove an object from the list"""
+        ref = self.__create_ref(obj)
+        self.__list.remove(ref)
+
+    def reverse(self):
+        """Reverse the list inplace"""
+        self.__list.reverse()
+
+    def sort(self, key=None, reverse=False):
+        """Sort the list inplace.
+        Not very efficient.
+        """
+        sorted_list = list(self)
+        sorted_list.sort(key=key, reverse=reverse)
+        self.__list = []
+        self.extend(sorted_list)
+
+    def __str__(self):
+        unref_list = list(self)
+        return "WeakList(%s)" % str(unref_list)
+
+    def __repr__(self):
+        unref_list = list(self)
+        return "WeakList(%s)" % repr(unref_list)

preditor-1.0.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: PrEditor
+Version: 1.0.0
+Summary: A python REPL and Editor and console based on Qt.
+Author-email: Blur Studio <opensource@blur.com>
+License: LGPL-3.0
+Project-URL: Homepage, https://github.com/blurstudio/PrEditor
+Project-URL: Source, https://github.com/blurstudio/PrEditor
+Project-URL: Tracker, https://github.com/blurstudio/PrEditor/issues
+Platform: any
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Qt.py
+Requires-Dist: configparser>=4.0.2
+Requires-Dist: future>=0.18.2
+Requires-Dist: signalslot>=0.1.2
+Requires-Dist: importlib-metadata>=4.8.3
+Provides-Extra: cli
+Requires-Dist: click>=7.1.2; extra == "cli"
+Requires-Dist: click-default-group; extra == "cli"
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: covdefaults; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-bugbear; extra == "dev"
+Requires-Dist: Flake8-pyproject; extra == "dev"
+Requires-Dist: pep8-naming; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Provides-Extra: shortcut
+Requires-Dist: casement>=0.1.0; platform_system == "Windows" and extra == "shortcut"
+Dynamic: license-file
+
+# PrEditor
+
+A python REPL, editor and console based on Qt. It allows you to interact
+directly with the current python session and write/run complex code in workbox's.
+It also has an interface for configuring python logging.
+
+# Use and Features
+
+![preview](https://github.com/blurstudio/PrEditor/assets/2424292/5425aa5f-0f9b-4b04-8e98-5a58546eb93c)
+
+* **Console:** The top section is a python REPL allowing you to run code like you
+are in the python interactive shell. However, you can't use code
+blocks([...](https://docs.python.org/3/glossary.html#term-...)), use the workbox instead.
+    * Python's stdout and stderr are written here including exceptions.
+    * If the cursor is at the very end of the last line, and that line starts with
+    a prompt (`>>> ` this includes 1 space) the code is executed when you press return.
+    Pressing return on any other prompt line copies that line to the end ready to
+    execute.
+    * Pressing `Ctrl + Up/Down` will cycle through previous command history.
+    * The console is a text edit and you can edit any of the text so you can fix
+    your mistakes as you make them
+* **Workbox:** The workbox is a place to write complex multi-line code. The contents
+    of all workboxes are saved when PrEditor is closed or pressing `Ctrl + S`.
+    * Workboxes are grouped into tabs of workboxes. You can drag and drop
+    individual workboxes between groups and re-order them.
+    * `Ctrl + Return` runs all code inside of the current workbox.
+    * `Shift + Return` or the `Number-pad Return` executes the selected text or
+    the line the cursor is on.
+    * `run_workbox("group/tab")` This command is added allowing you to run the
+    contents of a workbox. Pass the name of the group and workbox tabs separated
+    by a forward slash.
+* **Logging Level button:** Tools for managing python loggers.
+    * This button shows all known python loggers and lets you view/change their
+    logging levels.
+    * You can install logging handlers that have had PrEditor plugins written for them.
+    * Known python logger levels are saved and restored.
+* All code is run in `__main__`. In code you can add objects to it for inspection in PrEditor.
+* `Ctrl + Shift + PgUp/PgDown` changes focus between the console and workbox.
+* `Ctrl + Alt + Shift + PgUp/PgDown` changes focus and copies the current prompt
+line of the console, or the current line of the workbox to the other.
+
+
+# Examples
+
+See [examples](examples) for more complete examples of using PrEditor.
+
+For simple standalone applications that only exist for the life of the main window
+you can simply call `connect_preditor` in your class `__init__` and optionally add
+the created QAction into your GUI's menu. All `sys.stdout` and `sys.stderr` output
+written after `connect_preditor` is called, will be shown in the PrEditor window
+if it shown. If a exception is raised, and PrEditor is not visible, the user will
+be notified and can easily show PrEditor.
+```py
+import preditor
+
+# Create a keyboard shortcut(F2) to launch PrEditor and start capturing sys.stdout
+# and sys.stderr writes. The name argument makes this instance use it for prefs
+action = preditor.connect_preditor(window, name="Example")
+
+# Add the newly created action to a menu
+window.menuBar().actions()[0].menu.addAction(action)
+```
+
+Steps for initialization of a more complex application where you don't have
+control over the initialization of the Gui(like Maya).
+See [examples/add_to_app.py](examples/add_to_app.py) for a simple implementation.
+
+
+```py
+# Step 1: Capture sys.stdout and sys.stderr output to a buffer as early as
+# possible without creating the gui. Add this code to a plugin that gets loaded
+# as early as possible. This can even be run before the gui is created.
+import preditor
+# The name "maya" specifies the core_name that will be used to load/save prefs.
+preditor.configure("maya")
+
+# Step 2: Add a way for the user to trigger calling launch to show the PrEditor
+# gui. This is the first time the PrEditor GUI is initialized.
+preditor.launch()
+
+# Step 3: When closing the application, calling this will ensure that the
+# current PrEditor gui's state is saved. It's safe and fast to call this even
+# if the gui was never created.
+preditor.shutdown()
+```
+
+Up to the point where the PrEditor instance is created you can update the config
+data set by `preditor.configure`. For example you can change the name(used to load
+a set of user prefs) by calling `preditor.config.name = 'NewName'`. This is useful
+for configuring PrEditor before you import your specific setup code that implements
+a better `parent_callback`.
+
+# Installing
+
+`pip install preditor`
+
+## Installing Qt
+
+PrEditor is built on Qt, but uses [Qt.py](https://github.com/mottosso/Qt.py) so
+you can choose to use PySide2 or PyQt5. We have elected to not directly depend
+on either of these packages as if you want to use PrEditor inside of a an existing
+application like Maya or Houdini, they already come with PySide2 installed. If
+you are using it externally, add them to your pip install command.
+
+- PySide2: `pip install preditor PySide2`
+- PyQt5: `pip install preditor PyQt5`
+
+## Cli
+
+PrEditor is intended to be installed inside existing applications like Maya,
+Houdini, Nuke etc, so it doesn't make sense to require installing packages like
+click for those installs. If you are setting up a system wide install and want
+to use the cli interface, you will need to install the cli optional dependencies.
+
+`pip install preditor[cli]`
+
+### Creating shortcuts
+
+If you want to be able to create desktop shortcuts from the cli to launch
+PrEditor, you will also need to include the `shortcut` dependencies. Currently
+this is only useful for windows.
+
+- `pip install preditor[cli,shortcut]`
+
+## QScintilla workbox
+
+The more mature QScintilla workbox requires a few extra dependencies that must
+be passed manually. It hasn't been added to `extras_require` because we plan to
+split it into its own pip module due to it requiring PyQt5 which is a little hard
+to get working inside of DCC's that ship with PySide2 by default. Here is the
+python 3 pip install command.
+
+- `pip install preditor PyQt5, QScintilla>=2.11.4 aspell-python-py3`
+
+The aspell-python-py3 requirement is optional to enable spell check.
+
+
+# DCC Integration
+
+## Maya
+
+PrEditor is pre-setup to use as a Maya module. To use it, create a virtualenv
+with the same python as maya, or install it using mayapy.
+
+```
+virtualenv venv_preditor
+venv_preditor\Scripts\activate
+pip install PrEditor
+set MAYA_MODULE_PATH=c:\path\to\venv_preditor\Lib\site-packages\preditor\dccs
+```
+Note: Due to how maya .mod files works if you are using development installs you
+can't use pip editable installs. This is due to the relative path used
+`PYTHONPATH +:= ../..` in `PrEditor_maya.mod`. You can modify that to use a hard
+coded file path for testing, or add a second .mod file to add the virtualenv's
+`site-packages` file path as a hard coded file path.
+
+
+# Plugins
+
+PrEditor is can be extended using entry point plugins defined by other pip packages.
+
+* `preditor.plug.about_module`: Used to add information about various packages
+like version and install location to the output of `preditor.about_preditor()`.
+This is what generates the text shown by Help menu -> About PrEditor. See
+sub-classes of `AboutModule` in `preditor.about_module` and how those are
+added in [setup.cfg](setup.cfg).
+
+* `preditor.plug.editors`: Used to add new workbox editors to PrEditor. See
+[workbox_text_edit.py](preditor/gui/workbox_text_edit.py) for an example of
+implementing a workbox. See [workbox_mixin.py](preditor/gui/workbox_mixin.py)
+for the full interface to implement all features of an editor.
+
+* `preditor.plug.loggerwindow`: Used to customize the LoggerWindow instance when
+the LoggerWindow is created. For example, this can be used to create extra Toolbars
+or add menu items. When using this plugin, make sure to use the
+`preditor.gui.logger_window_plugin.LoggerWindowPlugin` class for your base class.
+
+* `preditor.plug.logging_handlers`: Used to add custom python logging handlers
+to the LoggingLevelButton's handlers sub-menus. This allows you to install a
+handler instance on a specific logging object.