The Pyblish QML project provides a graphical frontend to Pyblish.
Pyblish QML requires an external Python 2 or 3 distribution with PyQt5.6+.
- Pyblish 1.2.1 or higher
- Python 3.5 any platform
- Python 2.7 on Windows
- Python 2.7 on CentOS 7
- Python 2.7 on Ubuntu 14.10
- Python 2.7 on MacOS
Before use, point to your Python executable like this.
$ set PYBLISH_QML_PYTHON_EXECUTABLE=c:\python27\python.exe
This assumes the Python distribution has access to PyQt5 via e.g.
python -c "import PyQt5". If not, you may point to the directory containing it like this.
$ set PYBLISH_QML_PYQT5=c:\path\to\pyqt
$ pip install pyblish-qml
Test out the installation with..
$ python -m pyblish_qml --demo
In any of the supported hosts, call show().
import pyblish_qml pyblish_qml.show()
First you need to tell QML where Python and PyQt5 is.
from pyblish_qml import api, show # Tell QML about dependencies api.register_python_executable("C:/Python27/python.exe") api.register_pyqt5("C:/modules/python-qt5") show()
Alternatively, you may use environment variables instead.
$ set PYBLISH_QML_PYTHON_EXECUTABLE=c:\python27\python.exe $ set PYBLISH_QML_PYQT5=c:\modules\python-qt5 $ maya # for example..
Keep in mind that you don't have to register PyQt5 unless the Python executable you register isn't able to find it on its own. Also keep in mind that the directory you need to register is the parent directory of the
Either way, once QML is aware of where dependencies are, you may register it with
pyblish-base and have it appear automatically in file-menus of software, like with
from pyblish import api api.register_gui("pyblish_qml")
See pyblish-maya for an example.
Below is the current and full documentation of QML.
- Supported hosts
- Visualise order of operation
- Optional plugins
- Plug-in documentation
- Log messages
- Exception messages
These are the hosts automatically recognised by pyblish-qml.
Some data within each Instance and Context are special to QML.
||Instance||The on/off state of the toggle.|
||Context/Instance||Draw this instead of an instance's
||Context||Display and edit comment in GUI|
Dive into any item to find a curated list of data related to a particular item.
The order in which items are listed in the interface is a representation of how they are about to be processed. The top-most item processes first, and the bottom-most item processes last.
You can control the order by modifying the order attribute.
Plug-ins can be made optional by adding a particular attribute to your plug-ins.
class MyPlugin(...): optional = True
When a plug-in is optional, an artist may choose whether or not it should perform any processing.
Provide your users with thorough information of what to expect of a plug-in.
Pyblish QML visualises documentation per-plugin, here are some best practices for writing it along with technical information about how the data is parsed before being displayed.
The following are some guidelines to adhere to when writing documentation for your plug-in, but are in no way mandatory nor have any effect on the operation of Pyblish or Pyblish QML.
- Provide a general understanding of what the plug-in is doing.
- In case of a validator, propose general solutions and best-practices for how to avoid failing.
- Do not provide specific solutions; save those for Exception messages.
Documentation is taken from the
__doc__ member of your plug-in class.
class MyValidator(...): """General description Longer description here. """
As per PEP08, the first line of the above docstring is treated as a summary of the below description and used in the GUI right after drawing the name of the plug-in.
The longer portion is then shown when expanded.
If a line should be too long to display in the GUI, the end of it is elided.
Before showing the docstring, it is parsed. Parsing is currently very straightforward and operates on two rules.
- Remove all newlines
- Keep paragraphs
This happens so as to ensure that the maximum amount of space is used in the GUI and to get rid of the leading tabs present in any docstring.
Which means that this...
class MyValidator(...): """General description Longer description here. """
General description Longer description here.
As a side-effect of the above two rules, you cannot make lists or other entries that depend on newlines.
Provide users with information about what happens during the processing of a plug-in.
Logging uses the Python standard library
logging module and is visualised graphically by its 5 levels of severity.
Each produced via it's corresponding call to
self.log within a plug-in.
class MyValidator(...): ... def process(...): self.log.debug("e=mc^2") self.log.info("Processing instance..") self.log.warning("Something may be wrong..") self.log.error("Something's *definitely* wrong!") self.log.critical("Call the president!")
Each level is then represented by its unique color, starting from Blue moving into Red.
A log message may be short or span multiple lines. Only the first line is visualised unless an item is expanded. Once expanded, similar rules apply to parsing as the parsing of docstring (See Plug-in Documentation for more information.
- Short version
- Expanded version
Provide users with specifics about why a plug-in failed.
Exception messages are logged when exceptions are raised by plug-ins and are designed for describing the exact resort to take when plug-ins fail.
Contrary to Plug-in Documentation, Exception Messages may get very specific about a problem, such as naming items in a host relevant to the error, or point to a particular portion of the documentation.
raise ValidationError("""This is a long message And this will appear once expanded. """)
Pro tip: It's considered good practice to include as much information as is needed here, this is where users are meant to go for specifics about what to do about a particular problem.
Customise Context label and Window title.
from pyblish_qml import settings settings.WindowTitle = "My Title" settings.WindowSize = (430, 600) settings.WindowPosition = (100, 100) settings.ContextLabel = "The World" settings.HiddenSections = ["Collect"]
Each setting is applied when the GUI is shown, which means you can change them any time before then, including between subsequent runs.
Alternatively, set context label during processing.
class CollectContextLabel(pyblish.api.ContextPlugin): order = pyblish.api.CollectorOrder def process(self, context): context.data["label"] = "The World"
The GUI will read the current label after having processed all collectors. Any change after Collection will not be visible in the GUI.
Pyblish QML fills the same gap as Pyblish Lite, with a few notable differences.
- Asynchronous operation - use the GUI during intense processing
- Smoother visuals - animations galore
- Inspect individual items - tens of instances, hundreds of plug-ins? no problem
- Filter terminal via keyword search - thousands of log entries? no problem
- Requires PyQt5 (and either Python 2 or 3)
Development wise, Pyblish QML is written in.. you guessed it, QML. Whereas Pyblish Lite is written using classic widgets. QML is a new graphical user interface language for OpenGL developed by the same group, Qt.
Tests are automatically run at each commit to GitHub via Travis-CI. You can run these tests locally via Docker too.
$ git clone https://github.com/pyblish/pyblish-qml.git $ cd pyblish-qml $ . build_docker.sh # Only needed once $ . test_docker.sh # Doctest: pyblish_qml.models.Item ... ok # Doctest: pyblish_qml.util.ItemList ... ok # Reset works ... ok # Publishing works ... ok # ... # util.chain works with lambdas ... ok # # ---------------------------------------------------------------------- # Ran 20 tests in 1.430s # # OK
If you don't have Docker available you can test with these commands, for both Python 2 and Python 3:
$ cd pyblish-qml $ python -m nose --verbose --with-doctest --exe --exclude=vendor