# 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
* **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()
```
# 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(For python 2 you will need to compile QScintilla
yourself.)
- `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.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.
Raw data
{
"_id": null,
"home_page": "https://github.com/blurstudio/PrEditor.git",
"name": "PrEditor",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"maintainer_email": null,
"keywords": null,
"author": "Blur Studio",
"author_email": "opensource@blur.com",
"download_url": null,
"platform": "any",
"description": "# PrEditor\n\nA python REPL, editor and console based on Qt. It allows you to interact\ndirectly with the current python session and write/run complex code in workbox's.\nIt also has an interface for configuring python logging.\n\n# Use and Features\n\n\n\n* **Console:** The top section is a python REPL allowing you to run code like you\nare in the python interactive shell. However, you can't use code\nblocks([...](https://docs.python.org/3/glossary.html#term-...)), use the workbox instead.\n * Python's stdout and stderr are written here including exceptions.\n * If the cursor is at the very end of the last line, and that line starts with\n a prompt (`>>> ` this includes 1 space) the code is executed when you press return.\n Pressing return on any other prompt line copies that line to the end ready to\n execute.\n * Pressing `Ctrl + Up/Down` will cycle through previous command history.\n * The console is a text edit and you can edit any of the text so you can fix\n your mistakes as you make them\n* **Workbox:** The workbox is a place to write complex multi-line code. The contents\n of all workboxes are saved when PrEditor is closed or pressing `Ctrl + S`.\n * Workboxes are grouped into tabs of workboxes. You can drag and drop\n individual workboxes between groups and re-order them.\n * `Ctrl + Return` runs all code inside of the current workbox.\n * `Shift + Return` or the `Number-pad Return` executes the selected text or\n the line the cursor is on.\n * `run_workbox(\"group/tab\")` This command is added allowing you to run the\n contents of a workbox. Pass the name of the group and workbox tabs separated\n by a forward slash.\n* **Logging Level button:** Tools for managing python loggers.\n * This button shows all known python loggers and lets you view/change their\n logging levels.\n * You can install logging handlers that have had PrEditor plugins written for them.\n * Known python logger levels are saved and restored.\n* All code is run in `__main__`. In code you can add objects to it for inspection in PrEditor.\n* `Ctrl + Shift + PgUp/PgDown` changes focus between the console and workbox.\n* `Ctrl + Alt + Shift + PgUp/PgDown` changes focus and copies the current prompt\nline of the console, or the current line of the workbox to the other.\n\n\n# Examples\n\nSee [examples](examples) for more complete examples of using PrEditor.\n\nFor simple standalone applications that only exist for the life of the main window\nyou can simply call `connect_preditor` in your class `__init__` and optionally add\nthe created QAction into your GUI's menu. All `sys.stdout` and `sys.stderr` output\nwritten after `connect_preditor` is called, will be shown in the PrEditor window\nif it shown. If a exception is raised, and PrEditor is not visible, the user will\nbe notified and can easily show PrEditor.\n```py\nimport preditor\n\n# Create a keyboard shortcut(F2) to launch PrEditor and start capturing sys.stdout\n# and sys.stderr writes. The name argument makes this instance use it for prefs\naction = preditor.connect_preditor(window, name=\"Example\")\n\n# Add the newly created action to a menu\nwindow.menuBar().actions()[0].menu.addAction(action)\n```\n\nSteps for initialization of a more complex application where you don't have\ncontrol over the initialization of the Gui(like Maya).\nSee [examples/add_to_app.py](examples/add_to_app.py) for a simple implementation.\n\n\n```py\n# Step 1: Capture sys.stdout and sys.stderr output to a buffer as early as\n# possible without creating the gui. Add this code to a plugin that gets loaded\n# as early as possible. This can even be run before the gui is created.\nimport preditor\n# The name \"maya\" specifies the core_name that will be used to load/save prefs.\npreditor.configure(\"maya\")\n\n# Step 2: Add a way for the user to trigger calling launch to show the PrEditor\n# gui. This is the first time the PrEditor GUI is initialized.\npreditor.launch()\n\n# Step 3: When closing the application, calling this will ensure that the\n# current PrEditor gui's state is saved. It's safe and fast to call this even\n# if the gui was never created.\npreditor.shutdown()\n```\n\n# Installing\n\n`pip install preditor`\n\n## Installing Qt\n\nPrEditor is built on Qt, but uses [Qt.py](https://github.com/mottosso/Qt.py) so\nyou can choose to use PySide2 or PyQt5. We have elected to not directly depend\non either of these packages as if you want to use PrEditor inside of a an existing\napplication like Maya or Houdini, they already come with PySide2 installed. If\nyou are using it externally, add them to your pip install command.\n\n- PySide2: `pip install preditor PySide2`\n- PyQt5: `pip install preditor PyQt5`\n\n## Cli\n\nPrEditor is intended to be installed inside existing applications like Maya,\nHoudini, Nuke etc, so it doesn't make sense to require installing packages like\nclick for those installs. If you are setting up a system wide install and want\nto use the cli interface, you will need to install the cli optional dependencies.\n\n`pip install preditor[cli]`\n\n### Creating shortcuts\n\nIf you want to be able to create desktop shortcuts from the cli to launch\nPrEditor, you will also need to include the `shortcut` dependencies. Currently\nthis is only useful for windows.\n\n- `pip install preditor[cli,shortcut]`\n\n## QScintilla workbox\n\nThe more mature QScintilla workbox requires a few extra dependencies that must\nbe passed manually. It hasn't been added to `extras_require` because we plan to\nsplit it into its own pip module due to it requiring PyQt5 which is a little hard\nto get working inside of DCC's that ship with PySide2 by default. Here is the\npython 3 pip install command(For python 2 you will need to compile QScintilla\nyourself.)\n\n- `pip install preditor PyQt5, QScintilla>=2.11.4 aspell-python-py3`\n\nThe aspell-python-py3 requirement is optional to enable spell check.\n\n\n# DCC Integration\n\n## Maya\n\nPrEditor is pre-setup to use as a Maya module. To use it, create a virtualenv\nwith the same python as maya, or install it using mayapy.\n\n```\nvirtualenv venv_preditor\nvenv_preditor\\Scripts\\activate\npip install PrEditor\nset MAYA_MODULE_PATH=c:\\path\\to\\venv_preditor\\Lib\\site-packages\\preditor\\dccs\n```\nNote: Due to how maya .mod files works if you are using development installs you\ncan't use pip editable installs. This is due to the relative path used\n`PYTHONPATH +:= ../..` in `PrEditor_maya.mod`. You can modify that to use a hard\ncoded file path for testing, or add a second .mod file to add the virtualenv's\n`site-packages` file path as a hard coded file path.\n\n\n# Plugins\n\nPrEditor is can be extended using entry point plugins defined by other pip packages.\n\n* `preditor.plug.about_module`: Used to add information about various packages\nlike version and install location to the output of `preditor.about_preditor()`.\nThis is what generates the text shown by Help menu -> About PrEditor. See\nsub-classes of `AboutModule` in `preditor.about_module` and how those are\nadded in [setup.cfg](setup.cfg).\n\n* `preditor.plug.editors`: Used to add new workbox editors to PrEditor. See\n[workbox_text_edit.py](preditor/gui/workbox_text_edit.py) for an example of\nimplementing a workbox. See [workbox_mixin.py](preditor/gui/workbox_mixin.py)\nfor the full interface to implement all features of an editor.\n\n* `preditor.plug.logging_handlers`: Used to add custom python logging handlers\nto the LoggingLevelButton's handlers sub-menus. This allows you to install a\nhandler instance on a specific logging object.\n",
"bugtrack_url": null,
"license": "LGPL-3.0",
"summary": "A python REPL and Editor and console based on Qt.",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/blurstudio/PrEditor.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f5c75a40d4d45c232838b943de76e190a5caed7a99a8de32a9f851c4553095e",
"md5": "82699099e9f4ef487db93faf12724fe8",
"sha256": "c32d01e7beea60aa9336151e585a48dca7e1f693393c3f33921e1bd8f688510b"
},
"downloads": -1,
"filename": "PrEditor-0.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "82699099e9f4ef487db93faf12724fe8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,>=2.7",
"size": 413723,
"upload_time": "2024-08-16T23:39:37",
"upload_time_iso_8601": "2024-08-16T23:39:37.819743Z",
"url": "https://files.pythonhosted.org/packages/6f/5c/75a40d4d45c232838b943de76e190a5caed7a99a8de32a9f851c4553095e/PrEditor-0.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-16 23:39:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "blurstudio",
"github_project": "PrEditor",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "preditor"
}
JSON
