Upload
others
View
11
Download
0
Embed Size (px)
Citation preview
Jukebox Core DocumentationRelease 3.3.1
David Zuber
June 01, 2015
Contents
1 Documentation 31.1 Welcome to Jukebox Core‘s documentation! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Contents: 52.1 Usermanual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Developer’s Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.4 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.5 Credits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.6 History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
3 Feedback 533.1 Indices and tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Python Module Index 55
i
ii
Jukebox Core Documentation, Release 3.3.1
This is the core package for the jukebox cg-pipeline. It is a framework for developing pipeline tools for differentsoftwares in python.
Contents 1
Jukebox Core Documentation, Release 3.3.1
2 Contents
CHAPTER 1
Documentation
The documentation can be found under http://pythonhosted.org/jukebox-core.
1.1 Welcome to Jukebox Core‘s documentation!
3
Jukebox Core Documentation, Release 3.3.1
4 Chapter 1. Documentation
CHAPTER 2
Contents:
2.1 Usermanual
2.1.1 Installation
It is recommended to use python 2.7 64-bit.
Install jukebox-core via pip or easy-install. Pip is recommended:
$ pip install jukebox-core$ easy_install jukebox-core
Or, if you have virtualenvwrapper installed:
$ mkvirtualenv jukebox-core$ pip install jukebox-core
Windows
Jukebox Core has a psycopg dependency that might not be able to be installed via pip. So before you install jukebox-core download the binary from Psycopg2 for Windows and install it via:
easy_install path/to/downloadedbinary.exe
I recommend the python 2.7 64-bit version.
Linux
Jukebox Core has a psycopg dependency that might not be able to be installed via pip. Check this Guide on how toinstall psycopg on linux. On Debian, Ubuntu and other deb-based distributions you should just need:
sudo apt-get install python-psycopg2
2.1.2 Database
Jukebox core depends on a PostgreSQL database. If you do not have a configured PostgreSQL database, see sectionInstalling the Database. If you already have an existing, configured PostgeSQL database, see section Connect to anexisting Database.
5
Jukebox Core Documentation, Release 3.3.1
Installing and Configuring the Database
To install a postgresql database, you first need postgresql itself. Choose the right binary for your OS from PostgreSQLBinaries.
Start PgAdmin:
userdoc/../images/pgadmin_plain.png
Fig. 2.1: PgAdmin after startup. Ignore the CA-Linux-DB Server. You should only have a PostgreSQL Server onlocalhost.
It is recommended to create a new login role for all users of the new database we create. Right click on the PostgreSQLServer and choose New Object -> New login role:
userdoc/../images/pgadmin_newlogin.png
Fig. 2.2: Enter a name for the login role. E.g. jukebox_user.
Switch to the definition tab and give this role a password:
userdoc/../images/pgadmin_newloginpw.png
Fig. 2.3: Assign a new password.
Switch to the role privileges tab and check Can create databases
Then click on OK.
This is your new user for the database. To create a new database, rightclick on Databases under the server andchoose New database:
Switch to the definition tab and make user you use UTF-8 as encoding.
6 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
userdoc/../images/pgadmin_newloginrights.png
Fig. 2.4: Check Can create databases
userdoc/../images/pgadmin_newdb.png
Fig. 2.5: Enter Name and Owner. Owner can be the new login role you just created.
Click on OK.
Now we have a new empty database! Now we have to populate the database with the tables from jukebox. Before wecan do that, you have to configure your user config to access the newly created database. See section Connect to anexisting Database.
Your PgAdmin Window should look similar to this one:
..figure:: ../images/pgadmin_dbadded.png
alt The new database in pgadmin
Image of the new database in PgAdmin. Note that there are no tables yet!
After you configured your user settings correctly with the information you entered in PgAdmin, go to your comman-dline and execute:
jukebox manage migrate
Wait for the command to finish. Now your database is installed and configured. Congratulations!
Connect to an existing Database
If you have already have a database, you have to configure your user settings, so jukebox knows which database touse. If you have jukebox already installed, got to your commandline and execute:
userdoc/../images/pgadmin_definition.png
Fig. 2.6: Set encoding to UTF-8.
2.1. Usermanual 7
Jukebox Core Documentation, Release 3.3.1
jukebox launch Configer
After a short amount of time, a window will appear. Under the jukedj section, fill in the database name, databaseusername, password, host, port and secret key. The secret key is a random string, which is needed by the databasebackend. Make sure that all users who use this database have the same secret key.
userdoc/../images/configer.png
Fig. 2.7: Fill in the information under the jukedj section.
Warning: The secret key and password are saved in plain text and might be a security hazard! The currentimplementation does not allow for anything different.
2.1.3 Environment Variables
Here is a list of important environment variables you can set/override:
JUKEBOX_PLUGIN_PATHS In addition to adding the plugin paths for the pipeline to youruser config you can use this environment variable to include additional directories. Ifplugins in this path have the same name as built-in plugins or plugins from the user config,then they override them.
JUKEBOX_LOG_LEVEL The logging level of the pipeline. Choose from "NOTSET","Debug", "INFO", "WARNING", "ERROR", "CRITICAL".
2.1.4 Configuration
Inside the the pipeline user directory there is a config dir. You can edit the .ini -files inside there. There is also atool called Configer, that lets you edit these files in an special editor that validates your input. Some plugins and toolsmight provide own interfaces for editing their config data. They might also override some stuff while they are running(e.g. to save the last selection). To edit these files, start Configer via:
$ jukebox launch Configer
The most importent section to configure might be the jukedj-section under core.ini. For more information seeConnect to an existing Database.
The Configer Tool will show you, if your settings are acceptable by displaying them either in green or red. If you wantto enter a string with a lot of special characters, try to put them in double quotes. The reset button on the lower rightcornor will reset the selected field to its default.
Note: All keys that ask for paths should be a list of paths seperated by either : on linux or ; on windows.
8 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
2.2 Developer’s Documentation
Welcome to the developer’s documenation. All necessary information for contributors who want to extend the pipeline.
2.2.1 Get Started
Developing the package
If you are a pipeline developer, that wants to improve the jukebox pipeline directly follow this guide:
1. Clone the repository from either github or stash. See the in-depth description Git for more information.
2. Read the Python documentation on how to setup virtual environments and read the coding conventions. In short:make sure to have Python 2.7 installed. I recommend 64-bit version.
3. Install jukecore in development mode:
$ pip install -e path/to/jukeboxcorerepository
4. If the psycopg2 dependency fails to install with pip, see Installation for more information.
5. Follow the Database guide and make sure to have a configured database and userconfig.
6. Create a new gitbranch, write your code and tests. Read the Unittests for more information on how to test. Tosimply test everything use:
$ tox
7. Commit your code. If tests are successful merge your branch in dev. See ref:git for more information on thebranching model we use.
Note: When increasing the version number you might have to reinstall jukeboxcore in development mode in orderto make the launcher work again. pkg_resources might raise a pkg_resources.DistributionNotFound error because thelauncher was registered to another version.
Developing a addon for jukebox
If you want to create addons for jukebox follow this guide:
1. Make sure you have Python 2.7 installed. I recoomend the 64-bit version.
2. Install jukeboxcore as explained here.
3. Follow the Database guide and make sure to have a configured database and userconfig.
4. Create folder or package for your addon code.
5. Edit your pluginpaths in the userconfiguration and append the new folder to the paths. Multiple paths areseperated by either : on linux or ; on windows. See Configuration for more information. Alternatively you canset the environment variable JUKEBOX_PLUGIN_PATHS.
6. Create a python file in your new folder and start coding the plugin. Create a new subclass fromone of the jukeboxcore.plugins.JB_Plugin classes and implement the abstract functions. Thejukeboxcore.plugin.PluginManager is used for loading and initializing the plugins. Stan-dalone plugins should subclass from jukeboxcore.plugins.JB_CoreStandalonePlugin orjukeboxcore.plugins.JB_CoreStandaloneGuiPlugin. Standalone plugins can be launched via:
2.2. Developer’s Documentation 9
Jukebox Core Documentation, Release 3.3.1
$ jukebox launch <pluginname>
Plugin in name is the name of your plugin subclass.
2.2.2 Git
Git is our version control system for the sourcecode (http://git-scm.com/). Every computer in the CA-Pool shouldhave an installed git version. You can use the git bash for your ordinary git workflow. If you feel more comfortablewith a GUI, then you might look into Sourcetree. A good basic git tutorial can be found here.
Please read this article about the branching model we use. I recommend using gitflow. Git flow is a set of commandsfor git, that perform high level repository operations. It is basically an implementation of the branching model, withsimpler commands. To use it in your gitbash on windows, might be a little bit troublesome. There is a nice tutorial onhow to install gitflow on Windows.
The code is hosted on github and a private stash server for members of Hochschule der Medien Stuttgart. If you canaccess the stash server clone the repository with:
$ # ssh$ git clone ssh://[email protected]:7999/jp/jukebox-core.git$ # http$ git clone http://[email protected]:7990/scm/jp/jukebox-core.git
If you do not have access to the stash server use github:
$ # ssh$ git clone [email protected]:JukeboxPipeline/jukebox-core.git$ # https$ git clone https://github.com/JukeboxPipeline/jukebox-core.git
You can edit code and push it back with:
$ git push origin <branch>
When another developer updates the global repository, you have to pull the changes first:
$ git pull origin <branch>
Git Flow
Initialize your cloned repository for git flow with:
$ git flow init
Choose master for master branches and instead of develop use dev. Version prefix is v. Now you can use:
$ git flow feature start <featurename>
and all other git flow commands. See this useful and BEATIFUL cheatsheet for more information.
2.2.3 Python
We use almost only python code for our pipeline. So here are a few infos to you should know. I recommend python2.7 64-bit because it compatible with the jukebox-maya package.
10 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Virtual Environments
I recommend using virtualenv or even better virtualenvwrapper. To install virtualenvwrapper on Windows might be alittle hard to do. It is possible by downloading several dependencies and putting them in your Git bin directory. Butfor that you also need msys and edit your .bashrc. It might be easier to try virtualenvwrapper for Windows.
Create a new virtual environment for jukecore. Then install tox for unittesting. I also recommend to install jukebox-core in edit mode:
$ pip install -e path/to/jukeboxcorerepository
Coding Conventions
The general conventions for python are described in these official PEPs: PEP8, PEP257. For writing docstrings, alsolook at Docstring Guide!
Organize your imports should be in the following order:
1. standard library imports
2. related third party imports
3. local application/library specific imports
PySide
When writing pyside code it is hard to adhere the peps because PySide follows the C++-Conventions more or less. Soif you override a pyside function you have to use camelcase. When defining your own use underscores! That way it isalso easier to distinguish between our code and pyside code.
When using the designer, it is important how to name your widgets. Find a name for the widget that describes itsfunction and/or location in the gui and add a suffix that is a abbreviation for the widget, e.g. ‘_lb’ for label.
Here is a list for the most common widgets and layouts:
QWidget _widget
QFrame _fr
QMainWindow _mwin
QPushButton _pb
QToolButton _tb
QRadioButton _rb
QCheckBox _checkb
QListView _lv
QTreeView _treev
QTableView _tablev
QGroupBox _gb
QScrollArea _sa
QTabWidget _tabw
QComboBox _cb
2.2. Developer’s Documentation 11
Jukebox Core Documentation, Release 3.3.1
QLineEdit _le
QTextEdit _te
QPlainTextEdit _pte
QSpinBox _sb
QDoubleSpinBox _dsb
QScrollBar _scrollb
QLabel _lb
QTextBrowesr _brw
QHBoxLayout _hbox
QVBoxLayout _vbox
QGridLayout _grid
QFormLayout _form
Note: This list is in alpha stadium and can change!
Some widgets in the designer have internal layouts. These layouts can often be renamed directly in the designer.Especially the ones under container.
Compiling Designer Files With QtDesigner you can easily create widgets with a WYSIWYG editor. But in orderto use these files, you have to compile them first. The convention is, that ui-files are placed in the same directory asthe compiled python file. The compiled file name has the suffix _ui followed by the python file extension. For easycompiling you can use the compileUi module. To use is in commandline execute the following:
$ jukebox compileui path/to/uifile.ui
This will the compile the specified uifile and place the compiled file in the same path. In this case it would be nameduifile_ui.py.
Project Structure Overview
All jukebox projects are python packages. So there are a couple of files worth mentioning.
rst-files
There are some rst-files in the root folder (AUTHORS.rst, README.rst, CONTRIBUTING.rst, etc.). These arestandard files and should not be removed. They are the first files a developer might read. Feel free to edit them andmake them look nicer.
License
The current license is a BSD License. The license file is very important, so do not delete or move it.
MANIFEST.in
This file declares which files to include when distributing the package.
12 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
setup.py
A very important file! It is responsible for all the distribution and packaging. If you add dependencies to the project,include them here. The setup.py also creates the jukebox launcher scripts. Have a look at it’s entry points.
.gitignore
Do not ignore the gitignore. A file that describes which files not to ignore for version control. Every developer shouldhave the same gitignore.
docs
This directory is for the documentation. See Documenting for more information.
src
Contains the source code with all the packages.
test
Directory for unittests
2.2.4 Unittests
Unittesting is a way to automatically test the functionality of your code. There are numerous ways for unittesting.This is a description of the current test setup
“Something that is always appropriate, regardless of general style, is when you get a bug report. ALWAYScreate a test case first & run your tests. Make sure it demonstrates the failure, THEN go fix the bug. Ifyour fix is correct, that new test should pass! It’s an excellent way to sanity check yourself & is a greatway to get started with testing to boot.”
—Daniel Lindsley on his ToastDriven blog.
Organisation
We use tox for running a whole array of unittests. Tox as is a generic virtualenv management and test command linetool you can use for:
• checking your package installs correctly with different Python versions and interpreters
• running your tests in each of the environments, configuring your test tool of choice
• acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and shell-based testing.
Because all jukebox products are packages it is important to test them in their installed configuration and not in yourdevelopment environment. Tox lets you configure multiple environments with different dependencies and executesthe tests in these environments. So you could test your code with python 2.7, 3.3, 3.4, pypy etc. There are numerousenvironments already configured. Some have special usecases, e.g. they test building the documentation.
2.2. Developer’s Documentation 13
Jukebox Core Documentation, Release 3.3.1
Tox itselfs basically invokes any command you tell it to. So for the unittesting itself we use pytest. Pytest is a toolfor testing in python. It helps you with writing your tests, collects them, executes them and reports the results. Sofor testing our package, tox invokes the pytest command. If you are familiar with other test frameworks like nose orunittest, pytest is really easy. Pytest even understands a good amount of nose, and unittest. So some tests are alreadyportable.
All tests for the jukebox-core package are inside the test directory. So in most cases it might be enough to just throwyour tests in there and execute the tox command. The next sections will teach you more in depth about the purpose ofevery file involved in the testsetup, how to setup environments, how to have a special local test system and some tipswhen using tox.
Overview
This is a little overview for every file and directory involved in the testing process.
conf
The conf directory in root holds templates for the different configuration files. Depending on your configuration insetup.cfg these files are processed by a tempalte engine and placed inside the root directory. See bootstrap.py belowfor more information.
setup.cfg
This file has different sections for all kind of unittest related actions:
flake8 This section is used for the flake8 tool that checks if the python code is conform to thepython conventions. There is a special tox environment check which will do that.
pytest Here are some general settings for pytest, like what dirs to ignore or what arguments touse by default when executing pytest.
matrix This is a special section for bootstrap.py and the config templates inside conf . Youcan define a test matrix so tox tests with multiple python versions or different dependencyversions.
bootstrap.py
bootstrap.py parses the matrix section of setup.cfg and uses the configuration for rendering all templates inside conf .Execute the script and all the config files you had templates for should be updated.
tox.ini
This is where the magic happens. Here you can define all test environments, their dependencies and the commandsto use for testing. See this documentation on how to write these config files. This file has a template inside conf . Sorather than changing this file directly edit the template and use bootstrap.py. Here is a brief overview for the mostcommon sections:
tox The main section defines global settings. It might be worth noting that i changed the toxworkdir to a folderoutside the actual package. The reason for this was that the .tox dir that tox creates during testing got really heavy(over 40k files). This slowed down the building process and therefore also the testing. The envlist is a collection ofenvironments that are used by default if no other environments are specified.
14 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
testenv The most common options for all testenvironments gatherd. Other environments might override some of thesettings again. But basically they all share this one. Note that all other environments have the testenv: prefix.
spell Spell checking for the documentation.
docs This env tests building the documentation. It invokes sphinx-build two times. The first time it checks all linksinside the documentation. The second time it just tries to build the documentation and reports the result.
configure The same as using bootstrap.py.
check Performs multiple checks, e.g. executes flake8 to check conformity of the python code.
coveralls Collects the coverage reports of the tests and submits the result to coveralls.
report Combines and reports all coverage reports. This is nice if you have multiple environments with differentcoverage results.
clean Erases the old coverage reports by calling:
$ coverage erase
python test environments The rest of the environments are test the actual python code. Usually you have twoenvironments for every python version. One with coverage and one without. Because certain race conditions cannotbe tested with coverage as it introduces a slight overhead.
localtox.ini
This is like a mirror of the regular tox.ini. But for the install command it uses a special script calledlocaltoxinstall.py. The reason why you might want to use this file is the following:
Sometimes you want more control over your dependencies. Some might be really hard to install onwindows or take a long time from source. You might also be developing a dependency in parallel or thedependency is not on any package index yet. In this case You can use this file as a tox config file. Forinstallation of the dependencies it will execute a shell script localtoxinstall. Put in all your specialinstall commands for various dependencies like psycopg2. Look at localtoxinstall_templatefor examples.
Note: There is a template in the conf dir. So instead of editing this file directly edit the template. Do not put thelocaltoxinstall shell script under version control.
.travis.yml
Ignore this file. If somebody manages to make jukeboxcore work on Travis-CI this might be interesting.
2.2. Developer’s Documentation 15
Jukebox Core Documentation, Release 3.3.1
Testing with pytest
pytest is very easy to use. To execute all tests use:
$ py.test
or for better verbosity:
$ py.test -vv
If you only want to execute one test file use:
$ py.test path/to/testfile.py -vv
For coverage reports you need coverage and pytest-cov. The use:
$ py.test --cov src -vv
This will capture coverage for all python files in source.
Testing with tox
Testing with tox is preferred because it will offer preconfigured environments and will test the package in its distributedform in a virutal env. It is really easy to use:
$ # test all environments of tox at once that are specified in the envlist of the tox.ini$ tox$ # test special environments, e.g. just the test for documentation$ tox -e docs$ # test with the localtox.ini$ tox -c localtox.ini
You might want to use localtox instead of the regular tox.ini when working on windows. Follow the guide above onhow to configure a local tox settings file, so you can have custom dependencies installed, which are not on any packageindex.
2.2.5 Documenting
This page will give you a brief introduction in writing and extending the documentation with Sphinx. Sphinx automat-ically creates the documentation for our source code but can be manually extended via reStructuredText. The sphinxwebsite features a nice introduction that explains some of the basics. It is advised to read the official documentationand use this guide as a short reference.
Project Structure
The sphinx project is located in the /docs folder of our project. In there are several important components:
conf.py Contains the configuration of our documentation. There are some modifications at the end ofconf.py. Most notably: updatedoc ist automatically invoked when building the documentation.
index.rst This is the root document. It is the top-level document and the first page of our documen-tation.
make.bat The Makefile for windows users. Use it to build the documentation
_static Contains static files such as style sheets and script files.
16 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
_templates Contains templates that can be rendered out to e.g. html-pages
userdoc The usermanual for non-developer. Explains how to use the pipeline in production. Thisfolder contains the rst-files.
devdoc A manual for developers. Information for developing and source code documentation. Thisfolder contains the rst-files.
_build Contains the built documentation. So here are the rendered html-pages. This should not beversion controlled. So you should rebuild your documentation at appropriate times.
Building the documentation
This requires you to install the sphinx package. Just run setuptools or pip:
$ pip install sphinx
After the succesful installation you are able to run the make.bat on windows. Run it with html as argument to renderthe html-pages in _build:
$ make.bat html
This will also run updatedoc.py automatically. This is a modification of the sphinx extension apidoc. It willcollect the source code and create rst-files for each module. See Advanced Building for more information.
Warning: The content of the docs/reference dir will be deleted.
Please note that all modules will be imported. So your code has to be importable. If not, the reference part of thedocumentation will be empty. If importing is not possible for some reason, try to mock the modules with this guide. Inoticed that the order of mocking the modules is important.
Advanced Building
The section on toc-trees shows you how to include several rst-files into your doc. When you write a huge api, you haveto create a rst-file for at least each package and let autodoc do the rest of the work. This can get tedious and developerstend to forget to include their modules and packages. To work around this problem, sphinx includes a apidoc script,that generates rst files with autodoc directives automatically by scanning your sourcecode. This is incredible helpfulbut also limited. Because there was no way to change the formating, we use a modified version of the script. Thescript can be found under docs/gendoc.py and provides the exact same usage. You should run the script like this:
python gendoc.py -Tfe -o devdoc/source/ ../jukebox/
For your convenience, there is also a pythonscript that runs gendoc. The script can be found underdocs/updatedoc.py. The config file for sphinx invokes updatedoc.py on every sphinx build. So you shouldnot worry about that in most cases.
Warning: Using the updatedoc.py script does delete the content of the apidoc folder. You might loose data!Because we use updatedoc frequently, there is no point in altering files inside the apidoc folder.
Writing reStructuredText
To be able to write reStructuredText (short: rst) will be essential for every developer. All articles in the documentationare written in rst. This also includes everything created by the autodoc. So even if you are not writing a sectionmanually, as soon as you contribute source code you should have written some rst already. Every docstring in your
2.2. Developer’s Documentation 17
Jukebox Core Documentation, Release 3.3.1
python modules (the stuff in triple-quotes) will be collected by the autodoc extension and inserted in our source doc-umentation. These docstrings should therefore be written in rst. You can find information on how to write docstringshere.
Here is a short reference to rst. A more extensive guide can be found here or here with html-comparisons. You canalso use the Show Source-Button in the sidebar, if you ever wonder how the current page is written in rst.
TOC-Trees
The toctree directive inserts table of contents at the current location. In the body of the toctree you can specifynames of rst documents (relative or absolute). The toctree will also include all toctrees of these documents untila certain maxdepth is reached (you can ommit the maxdepth option to have unlimited depth). The root document(index.rst in the doc/ directory) contains the first toctree. All documents have to be in either that toctree or intoctrees of included documents. If they are not included, sphinx will warn you at build-time and you will not find thedocument rendered. Here is a basic example of a toctree:
.. toctree:::maxdepth: 2:numbered:
introuserdocThis is the devdoc! <devdoc>
This could be the top-level toctree. After the .. toctree:: directive you can specify a few options.:maxdepth: will include subtrees only to a certain depth. :numbered: will make the table numbered.
Sections
Longer texts can be broken up into sections with headings. A section will automatically appear in the appropriatetoctree. To write a section heading you have to underline (optional overline too) it with non-alphanumeric characters:= - ‘ : ’ " ~ ^ _ * + # < > It does not matter what character you take. Sphinx will automaticallyfigure out what level of section it is. That way you can define subsections if you choose a different character thanbefore. In our documentation we use = for top-level headings, - for 2. level and + or something else for 3. level. Theunderline should always have at least as many characters as the above headline. After the underline follows an emptyline and then the section content. You have to insert an empty line before a new section two.
Source Code
To display sourcecode end you current paragraph with a double colon. Then write a new indented paragraph with thesource code. So now follows a litte bit of rst source code that will not be rendered and displayed in monospaced font:
Check out my awesome sourcecode::
print "Hello world!"if bar():
foo('python is awesome')
Links
Sphinx allows for quite a few ways to deploy links in your documentation. One way to link between different locationsin the documentation (also across files) is to write:
18 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
:ref:`somdetext <label-name>`
.. _label-name:
text paragraph or section after a label. this will be shown if you click on the 'sometext'-link in the documentation
Python objects like modules can be referenced as well. To reference to jukeboxcore.constants use:
:mod:`jukeboxcore.constants`
Hyperlinks to websites like this one work like this:
`one <https://www.python.org/>`_
Viewdoc is an extension for sphinx that allows a link to a python object in the source code:
this will link to a python function in my source :func:`jukeboxcore.main.init`this will link to a module :mod:`jukeboxcore.main`this will link to a variable :data:`jukeboxcore.constants.DEFAULT_LOGGING_LEVEL`this will link to a class :class:`jukeboxcore.plugins.JB_Plugin`this will link to a method :meth:`jukeboxcore.JB_Plugin.init`
Docstrings
Docstrings are very important! All of our source code should have docstrings. This applies for packages, modules,classes, functions, methods, public and private members etc. Docstrings are written in triple quotes in the source codeand describe the object above. The most common docstring you will write is for a function or method. Here is atemplate:
def foo(self, arg1, arg2, kwarg1=None, kwarg2=False):""" Do foo and return the bar
A much more detailed description on how this function works and what it does.Give examples on how to use it and explain your code a little too.
:param arg1: just a random parameter description:type arg1: object:param arg2: another description for the second argument:type arg2: int:param kwarg1: Optional - specify a keyword argumnt for fun:type kwarg1: str|unicode:param kwarg2: Optional - If True, some stuff happens in the function, default is False:type kwarg2: bool:returns: the bar of foo:rtype: Bar:raises: ValueError, IndexError, MyOwnLittleError"""pass
This structure can be adapted for the rest of python objects. Always start with a very short one-line description, anemptyline and then a detailed description. To make the creation of parameter docstrings faster there are also yasnippetsfor emacs, which create them automatically. For more information have a look at these examples and the official syntaxmarkup documentation.
2.2. Developer’s Documentation 19
Jukebox Core Documentation, Release 3.3.1
2.2.6 Plugins
The pipeline is extensible via plugins. Plugins are simple python scripts that implement a certain class(jukeboxcore.plugins.JB_Plugin). In order to load the plugin, you have to put the script to a accessiblelocation. Now you have two options.
Environment variable
Set the JUKEBOX_PLUGIN_PATH environment variable. You can add multiple paths if seperated by ; on Windowsand : on Linux. E.g. your plugin scripts live in ~/myjukeboxplugins and /jukeboxplugins/ then set theJUKEBOX_PLUGIN_PATH to ~/myjukeboxplugins;/jukeboxplugins/.
Important: The order is important. Plugins in can overwrite other Plugins with the same name. The overridingPlugin has to live on a path that comes before the overridden Plugin. If you have two Plugins on the same path withthe same name, there is no guarantee which one is loaded first.
Settings
You can also add paths to plugins in the core settings file. See <configuration>.
Plugin types
There are different plugin types. All plugin(type)s are subclasses from jukeboxcore.plugins.JB_Plugin.You can only load a certain set of plugin classes depending on the context.
Plugins might require a certain software suite like Maya or nuke. If your plugin needs Maya,the jukeboxmaya.plugins module has a collection of plugin classes that require maya to run.They only get loaded in Maya. If a plugin is of general purpose it should subclass from eitherjukeboxcore.plugins.JB_CorePlugin, jukeboxcore.plugins.JB_CoreStandalonePlugin,jukeboxcore.plugins.JB_CoreStandaloneGuiPlugin.
Plugin classes with standalone in their name are like little seperate programms. For example the editor for the prefer-ences can be launched on it’s own via the jukeboxcore.launcher. StanaloneGui plugins require a QApplicationto run.
Maya has it’s own set of plugin types which are derived from the core ones.
Confused??? Good. Me too. So here are some examples when to use which plugin subclass.
JB_CorePlugin
A jukeboxcore.plugins.JB_CorePlugin does extend the pipeline and does not require a software suite. Itcould be a logging plugins, which logs all database access. It does not just run a procedure but extends the existingones.
JB_CoreStandalonePlugin
A jukeboxcore.plugins.JB_CoreStandalonePlugin does not require a software suite. It can belaunched on its own or from within any software suite. It could be a plugin that does database migrations. Basi-cally it runs some procedure (without a gui).
20 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
JB_CoreStandaloneGuiPlugin
A jukeboxcore.plugins.JB_CoreStandaloneGuiPlugin is similar to the previous one. But it wants torun a GUI. For example the prefernce editor is a subclass of this class. It can run on its own or from within a softwaresuite like maya and has a gui.
JB_MayaPlugin
jukeboxmaya.plugins.JB_MayaPlugin is part of the jukeboxmaya package. It requires maya in order towork. It could override the save command in maya or create a menu in maya etc.
JB_MayaStandalonePlugin
jukeboxmaya.plugins.JB_MayaStandalonePlugin also requires maya. It can either run inside maya orin a maya standalone process (A maya without a gui). The plugin could open all scene files of a project and import allreferences automatically when run.
JB_MayaStandaloneGuiPlugin
jukeboxmaya.plugins.JB_MayaStandaloneGuiPlugin requires maya, can run on its own and needs agui. The release tool of the maya pipeline is such an example. In order to release a maya scene file, a maya standaloneinstance is sufficient. But it also requires a GUI so the user can select a file to release.
Minimal Plugin
Here is an example of a minimal plugin:
from jukeboxcore import plugins
class MinimalPlugin(plugins.JB_Plugin):
required = () # a list of class names of other plugins that should be loaded beforehand
# 'useless' metadataauthor = 'David Zuber'copyright = '2015'license = 'BSD'version='0.1.0'description='Does exactly nothing.'
def init(self):# gets called when the plugin is loaded
print 'loaded my useless plugin'
def uninit(self):print 'unloaded my useless plugin'
Plugin Configs
Some plugins might want to allow configuration by the user. If a plugin wants such a configuration, it needs aconfigspec file. This file specifies the values the user can modify and the valid values. The name of the config file has
2.2. Developer’s Documentation 21
Jukebox Core Documentation, Release 3.3.1
to be exactly like the plugin class but the ending is ini. For a tutorial on how to write configspecs see: Configobjdocumentation.
Example config spec for our MinimalPlugin:
# contents of MinimalPlugin.iniport = integer(0, 100)user = string(max=25)mode = option('quiet', 'loud', 'silent')
2.3 Reference
Automatic generated Documenation by apidoc and autodoc.
2.3.1 jukeboxcore
Subpackages
jukeboxcore.addons
Subpackages
jukeboxcore.addons.configer
Submodules
configer
configer_ui
Module contents
jukeboxcore.addons.genesis
Submodules
genesis
genesis_ui
Module contents
jukeboxcore.addons.guerilla
22 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Submodules
guerillamgmt
Module contents
Module contents
jukeboxcore.gui
Subpackages
jukeboxcore.gui.resources
Submodules
main_rc
Module contents Module with compiled resources that can be registered by importing them.
jukeboxcore.gui.widgets
Subpackages
jukeboxcore.gui.widgets.guerilla
Submodules
assetadder_ui
assetcreator_ui
atypeadder_ui
atypecreator_ui
depadder_ui
depcreator_ui
prjadder_ui
2.3. Reference 23
Jukebox Core Documentation, Release 3.3.1
projectcreator_ui
seqcreator_ui
shotcreator_ui
taskcreator_ui
useradder_ui
usercreator_ui
Module contents
Submodules
actionreportdialog
actionreportdialog_ui
browser
commentwidget
commentwidget_ui
filebrowser
filebrowser_ui
guerillamgmt_ui
optionselector_ui
reftrackadder_ui
reftrackwidget
reftrackwidget_ui
reftrackwin
24 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
reftrackwin_ui
releasewin
releasewin_ui
textedit
tooltip
Module contents
Submodules
actionreport
configeditor
djitemdata
filesysitemdata
main
qtcompile
reftrackitemdata
treemodel
widgetdelegate
Module contents This module bundles a lot of tools and convenience functions for PySide and collects all reusablewidgets, models etc that can be used in many tools independantly.
2.3. Reference 25
Jukebox Core Documentation, Release 3.3.1
Submodules
action
Module for performing arbitrary actions on objects
A FileAction object is a collection of multiple ActionUnit. When executing the FileAction eachActionUnit is run. Later you can query or display the result.
class jukeboxcore.action.ActionStatus(value=None, msg=’Not executed.’, traceback=’‘, return-value=None)
Bases: object
A status object that holds a status value and a short description of what the status means.
So when an action is performed, the action status shows, if the action has been successful or failed and alsoshows why.
You can query and set 4 attributes:
value the status value as a string
message the status message as a string
traceback in case of an error, the traceback as a string
returnvalue If the action wants to provide some value for further processing.
Possible status values are ActionStatus.SUCCESS, ActionStatus.SKIPPED,ActionStatus.FAILURE, ActionStatus.ERROR and None. Before a action gets executed, thestatus is None
Initialize a new action status with the given value, message and traceback
Parameters
• value (str) – The status value
• msg (str) – The status message. A better description of the status
• traceback (str) – The traceback if an error occured during action execution.
• returnvalue (None|object) – If the actions wants to return values, this can be used tostore the return value
Raises None
SUCCESS = ‘Success’Status for when the action succeded
SKIPPED = ‘Skipped’Status for when the action has been skipped, because a dependency was not met
FAILURE = ‘Failure’Status for when the action failed in doing what it should. But the action did not raise an error. So it is likean error that the action expected.
ERROR = ‘Error’Status for when the action crashed and raised an error.
class jukeboxcore.action.ActionUnit(name, description, actionfunc, depsuccess=None, dep-fail=None)
Bases: object
A single action to be performed on a object.
26 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Actions might depend on others and only get executed when the dependency was successful. Other actionsmight depend on the failure of another action and only get executed when the dependency failed.
ActionUnit has the following data you can query:
name the name of the action.
description the description of what the action does.
status the status of the action. A ActionStatus object.
Note: The given object must be ready to be processed. So if the object is a file, the file needs to be opened first,create an action that opens the file, and put it as dependency for all other actions. The same goes for closing orsaving files.
Initialize a new action unit that can depends on the success of depsucess or the failure of depfail
Parameters
• name (str) – The name of the action
• description (str) – A short description of what the action unit does
• actionfunc (callable) – A function that takes an object as argument and performs aaction. the function should return a ActionStatus object. Use the returnvalueattribute of the status, if you need to return something else.
• depsuccess (list|None) – a list of action units that has to succeed first before this actioncan be executed
• depfail (list|None) – a list of action units that has to fail first before this action can beexecuted
Raises None
run(obj)Execute the actions on the given object.
Parameters obj (object) – The object that the action should process
Returns None
Return type None
Raises None
class jukeboxcore.action.ActionCollection(actions)Bases: object
Perform a collection of ActionUnit on a object.
Actions get executed in the given order.
Note: The given object must be ready to be processed. So if the object is a file, the file needs to be opened first,create an action that opens the file, and put it as dependency for all other actions. The same goes for closing orsaving files.
You can access the action objects with these attributes:
actions a list of action units.
Initializes a FileAction object. The actions will be performed on a object when FileAction.execute() iscalled.
Parameters actions (list) – a list of action units
2.3. Reference 27
Jukebox Core Documentation, Release 3.3.1
Raises None
execute(obj)Run all action units on the given object.
Parameters obj – the object to be processed
Returns None
Return type None
Raises None
status()The global status that summerizes all actions
The status will be calculated in the following order:
If any error occured, the status will be ActionStatus.ERROR. If any failure occured, thestatus will be ActionStatus.FAILURE. If all actions were successful or skipped, the statuswill be ActonStatus.SUCCESS
Returns a status object that represents a summary of all actions
Return type ActionStatus
Raises None
constants
Define constant values that matter for the whole pipeline here
The paths for data are relative paths from the package dir. To get the path to the actual data that is installed use:
pgk_resources.resource_filename('jukeboxcore', <data_path>)
jukeboxcore is the name of the package and datapath the relative path inside the package. Usually all data is insidea data directory of the package.
jukeboxcore.constants.loglvl_mapping = {‘INFO’: 20, ‘CRITCAL’: 50, ‘WARNING’: 30, ‘ERROR’: 40, ‘DEBUG’: 10, ‘NOTSET’: 0}Mapping of for the environment variable JUKEBOX_LOG_LEVEL
jukeboxcore.constants.DEFAULT_LOGGING_LEVEL = 10All loggers should use this level by default. When you obtain a logger withjukeboxcore.log.get_logger(), it will have this level. Can be overwritten by the environmentvariable "JUKEBOX_LOG_LEVEL". Possible values for the environment variable are:
NOTSET DEBUG INFO WARNING ERROR CRITICAL
jukeboxcore.constants.BUILTIN_PLUGIN_PATH = ‘/var/build/user_builds/jukebox-core/checkouts/latest/src/jukeboxcore/addons’Path to all builtin plugins. The pluginmanager will load these by default.
jukeboxcore.constants.USERDIR = ‘/home/docs/.jukebox’The pipeline userdirectory. Here the pipeline can store or load userpreferences etc.
jukeboxcore.constants.CONFIG_EXT = ‘ini’All config files should have this extension.
jukeboxcore.constants.CONFIG_DIR = ‘/home/docs/.jukebox/config’The directory where user configs are stored.
jukeboxcore.constants.PLUGIN_CONFIG_DIR = ‘/home/docs/.jukebox/config/plugins’The directory where plugins store their configs.
28 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
jukeboxcore.constants.CORE_CONFIG_PATH = ‘/home/docs/.jukebox/config/core.ini’The filepath of the core config.
jukeboxcore.constants.DATA_DIR = ‘data’Location of the data directory of this package relative to the package path.
jukeboxcore.constants.CORE_CONFIG_SPEC_PATH = ‘/var/build/user_builds/jukebox-core/checkouts/latest/src/jukeboxcore/data/corespec.ini’The filepath to the configspec of core.ini
jukeboxcore.constants.ICON_PATH = ‘data/icons’Data path to the icons.
jukeboxcore.constants.STYLESHEET_PATH = ‘data/stylesheets’Data path to the stylesheet directory
jukeboxcore.constants.MAIN_STYLESHEET = ‘/var/build/user_builds/jukebox-core/checkouts/latest/src/jukeboxcore/data/stylesheets/main.qss’The default or main stylesheet that should be used by all our guis. Usuallyjukeboxcore.gui.main.set_main_style() will do that for standalone apps.
jukeboxcore.constants.MAYA_VERSIONS = [‘2016’, ‘2015’]The supported maya versions for jukebox.
jukeboxcore.constants.MAYA_REG_KEY = ‘Software\\Autodesk\\Maya\\{mayaversion}\\Setup\\InstallPath’Registry key on windows to access maya install path
djadapter
This module provides a adapter for django to use in your tools
On import django will be setup to work. This might take 1-5 seconds! From there on you have access to the database.If we are testing, this means the env var JUKEBOX_TESTING is set, then the import will create a test databaseautomatically! Creating a test db will set the env var ‘TEST_DB’ to the name of the test db, so we can destroy it later.
The djadapter has shotcuts to the manger objects for each model. To make a query, use these managers. See thedocumentation of Managers, Retrieving objects and QuerySets. Just instead of <Model>.objects use a managerof djadapter as shortcut.
For example to query projects use:
from jukeboxcore import djadapterdjadapter.projects.all() # returns a QuerySet that can be used similar to a listdjadapter.projects.get(name='Some Project') # returns an instance of project if
# there is one but only one project with this namedjadapter.projects.filter(semester='SS14') # returns only projects of the summer semester 2014
jukeboxcore.djadapter.setup_testdatabase()Create test database
We have to do some setup manually. manage.py test does that usually. Writes the db in the env varTEST_DB. This can be torn down afterwards.
jukeboxcore.djadapter.GLOBAL_NAME = ‘Global’Name for global shots and sequences
jukeboxcore.djadapter.RNDSEQ_NAME = ‘RnD’Name for the rnd sequence
jukeboxcore.djadapter.DEFAULT_ASSETTYPES = [’prop’, ‘char’, ‘loc’]Tuples with name and description for the default assettypes that should always be available.
2.3. Reference 29
Jukebox Core Documentation, Release 3.3.1
jukeboxcore.djadapter.DEFAULT_DEPARTMENTS = [(‘Modeling’, ‘mod’, 100, True), (‘Shading’, ‘shd’, 200, True), (‘Rigging’, ‘rig’, 300, True), (‘Animation’, ‘ani’, 100, False), (‘Fx’, ‘fx’, 200, False), (‘Lighting’, ‘lgt’, 300, False), (‘Rendering’, ‘rdr’, 400, False), (‘Compositing’, ‘comp’, 500, False), (‘Grading’, ‘grd’, 600, False)]Tuples with name, short, ordervalue and assetflag for the default departments. Asset flag indicates if it is adepartment for assets or for shots. Every project will get these departments by default.
jukeboxcore.djadapter.RELEASETYPES = {‘release’: ‘release’, ‘work’: ‘work’, ‘handoff’: ‘handoff’}Releasetype values for the different releasetypes
the values consist of tuples with the actual name and a description.
jukeboxcore.djadapter.FILETYPES = {‘mayamainscene’: ‘mayamainscene’}A dict for file types that can be used in a TaskFile
the values are the actual data that gets stored in the database.
Explanations:
mayamainscene probably the most common for maya scenes. these are the usual releaseand workfiles maybe even a handoff file, if it does not need a direct subfolder. Mainscenes hold the main information, not just extracted parts. If you export shader ormaybe some blendshapes in a scene, do not use this one.
jukeboxcore.djadapter.projects = <django.db.models.manager.Manager object>The Project manager. Use it to query the database for projects.
jukeboxcore.djadapter.atypes = <django.db.models.manager.Manager object>The Atype manager. Use it to query the database for atypes.
jukeboxcore.djadapter.sequences = <django.db.models.manager.Manager object>The Sequence manager. Use it to query the database for sequences.
jukeboxcore.djadapter.departments = <django.db.models.manager.Manager object>The Department manager. Use it to query the database for departments.
jukeboxcore.djadapter.tasks = <django.db.models.manager.Manager object>The Task manager. Use it to query the database for tasks.
jukeboxcore.djadapter.assets = <django.db.models.manager.Manager object>The Asset manager. Use it to query the database for assets.
jukeboxcore.djadapter.shots = <django.db.models.manager.Manager object>The Shot manager. Use it to query the database for shots.
jukeboxcore.djadapter.softwares = <django.db.models.manager.Manager object>The Software manager. Use it to query the database for softwares.
jukeboxcore.djadapter.files = <django.db.models.manager.Manager object>The File manager. Use it to query the database for files.
jukeboxcore.djadapter.taskfiles = <django.db.models.manager.Manager object>The Taskfile manager. Use it to query the database for taskfiles.
jukeboxcore.djadapter.users = <django.contrib.auth.models.UserManager object>The user manager. Use it to query the database for users.
jukeboxcore.djadapter.notes = <django.db.models.manager.Manager object>The note manager. Use it to query the database for notes.
jukeboxcore.djadapter.get_current_user()Return the User instance for the currently logged in user
Returns user instance
Return type models.User
Raises DoesNotExist
30 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
djsettings
Django settings for jukebox core.
For more information on this file, see https://docs.djangoproject.com/en/1.6/topics/settings/
For the full list of settings and their values, see https://docs.djangoproject.com/en/1.6/ref/settings/
Note that some of the settings are pulled out of the user config.
errors
Module for all our custom exceptions
exception jukeboxcore.errors.JukeboxExceptionBases: exceptions.Exception
Base Exceptions for all our jukebox related Exceptions!
Subclass this for your own exceptions. Do not recreate the builtin exceptions! We still use them. But wheneveryou want to raise a custom exception, use this as baseclass.
exception jukeboxcore.errors.PluginInitErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when a Plugin fails initializing.
exception jukeboxcore.errors.PluginUninitErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when a Plugin fails uninitializing.
exception jukeboxcore.errors.UnsupportedPlatformErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when the platform you are on does not support some actions.
exception jukeboxcore.errors.SoftwareNotFoundErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when the pipeline cannot find a required software.
exception jukeboxcore.errors.ConfigErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when some error occurs concerning Config files.
exception jukeboxcore.errors.MenuExistsErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when a MenuManger tries to create a menu that already exists.
exception jukeboxcore.errors.IntegrityErrorBases: jukeboxcore.errors.JukeboxException
Jukebox Exception that is raised when the pipeline cannot execute an action because it would affect the integrityof the pipeline.
exception jukeboxcore.errors.ReftrackIntegrityError(msg=None, reftracks=None)Bases: jukeboxcore.errors.IntegrityError
Jukebox Integrity Exception that is raised when an action concerning the reference workflow cannot be executedbecause it would affect the integrity of the reference workflow.
2.3. Reference 31
Jukebox Core Documentation, Release 3.3.1
You can access a list of jukeboxcore.reftrack.Reftrack that would cause the error withReftrackIntegrityError.reftracks.
Initialize a new exception with a error message and the reftracks that would cause an integrity error.
Parameters
• msg (str | None) – the error message
• reftracks (list of jukeboxcore.reftrack.Reftrack | None) – the reftracks thatwould cause an integrity error
Raises None
filesys
jukeboxcore.filesys.copy_file(old, new)Copy the old file to the location of the new file
Parameters
• old (JB_File) – The file to copy
• new (JB_File) – The JB_File for the new location
Returns None
Return type None
Raises None
jukeboxcore.filesys.delete_file(f)Delete the given file
Parameters f (JB_File) – the file to delete
Returns None
Return type None
Raises OSError
class jukeboxcore.filesys.FileInfoBases: object
Abstract class that can be used for implementing info objects that can be used with FileElements
You don’t have to use this, but it provides an interface for getting the latest or next version.
classmethod get_latest()Get the latest existing file for the given info or None if there is no existing one
You should reimplement this method so it accepts some arguments with infos and returns a FileInfo that isthe latest version for the given info.
Returns a fileinfoobject that is the latest existing file for the given info
Return type FileInfo | None
Raises None
classmethod get_next()Return a file info object that would be the next version for the given info
You should reimplement this method so it accepts some arguments with infos and returns a FileInfo thatwould be the next version after the latest for the given info
32 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Returns a fileinfoobject that is the latest existing file for the given info
Return type FileInfo
Raises None
class jukeboxcore.filesys.TaskFileInfo(task, version, releasetype, typ, descriptor=None)Bases: jukeboxcore.filesys.FileInfo
FileInfo for a taskfile
Can get the latest or the next version if you provide a task, releasetype (and a descriptor).
Constructs a new TaskFileInfo
Parameters
• task (jukeboxcore.djadapter.models.Task) – the task of the taskfile
• version (int) – the version of the TaskFile
• releasetype (str - jukeboxcore.djadapter.RELEASETYPES) – the releasetype
• typ (str) – the file type, see TaskFileInfo.TYPES
• descriptor (str|None) – the descriptor, if the taskfile has one.
Raises None
TYPES = {‘mayamainscene’: ‘mayamainscene’}A dict for file types that can be used in a TaskFile
the values are the actual data that gets stored in the database.
Explanations:
mayamainscene probably the most common for maya scenes. these are the usual re-lease and workfiles maybe even a handoff file, if it does not need a direct subfolder.Main scenes hold the main information, not just extracted parts. If you export shaderor maybe some blendshapes in a scene, do not use this one.
classmethod get_latest(task, releasetype, typ, descriptor=None)Returns a TaskFileInfo that with the latest existing version and the provided info
Parameters
• task (jukeboxcore.djadapter.models.Task) – the task of the taskfile
• releasetype (str - jukeboxcore.djadapter.RELEASETYPES) – the release-type
• typ (str) – the file type, see TaskFileInfo.TYPES
• descriptor (str|None) – the descriptor, if the taskfile has one.
Returns taskfileinfoobject with the latest extisting version and the provided info or none if thereis no latest.
Return type TaskFileInfo | None
Raises None
classmethod get_next(task, releasetype, typ, descriptor=None)Returns a TaskFileInfo that with the next available version and the provided info
Parameters
• task (jukeboxcore.djadapter.models.Task) – the task of the taskfile
2.3. Reference 33
Jukebox Core Documentation, Release 3.3.1
• releasetype (str - jukeboxcore.djadapter.RELEASETYPES) – the release-type
• typ (str) – the file type, see TaskFileInfo.TYPES
• descriptor (str|None) – the descriptor, if the taskfile has one.
Returns taskfileinfoobject with next available version and the provided info
Return type TaskFileInfo
Raises None
classmethod create_from_taskfile(taskfile)Create a new TaskFileInfo and return it for the given taskfile
Parameters taskfile (jukeboxcore.djadapter.models.TaskFile) – the taskfileto represent
Returns a taskfileinfo
Return type TaskFileInfo
Raises None
is_latest()Return True, if the version is the newest.
Returns None
Return type None
Raises None
create_db_entry(comment=’‘)Create a db entry for this task file info and link it with a optional comment
Parameters comment (str) – a comment for the task file entry
Returns The created TaskFile django instance and the comment. If the comment was empty,None is returned instead
Return type tuple of dj.models.TaskFile and dj.models.Note
Raises ValidationError, If the comment could not be created, the TaskFile is deleted and theException is propagated.
class jukeboxcore.filesys.FileElementBases: object
A file element uses a file info object to retrieve some information and generate part of the path or name of a file.This Class is meant to be used as a baseclass. Override at least one of the functions:
FileElement.get_dir() FileElement.get_chunk()
A filepath consists of multiple directories. Each element can, but must not, contribute to this path. A filenameconsits of multiple chunks, that are seperated by underscores.
get_dir(obj)Return a part of the filepath for the given object, or none if the element does not contribute a directory.
Some Elements might only add a chunk to the filename. These elements should always return None. Eachelement is responsible for a certain aspect/attribute of the obj and uses this attribute to generate part of thefilepath. E.g. an element, that creates a folder for every version of obj, could return a string like ’v###’with the version numbers inserted. A element that is responsible for the project, might return the completeroot path for that objects project.
34 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
The default will return None. So override it if necessary.
Parameters obj (FileInfo) – the fileinfo with information.
Returns a part of the filepath or None
Return type str|None
Raises None
get_chunk(obj)Return a filename chunk, or None if the element does not contribute to the filename.
Some Elements might only add a directory to the filepath. These elements should always return None.Each element is responsible for a certain aspect/attribute of the obj and uses this attribute to generate partof the filename (chunk). Chunks are seperated by underscores and should not contain any spaces. E.g. anelement that inserts the username to the filename might return the username as a string.
The default will return None. So override it if necessary.
Parameters obj (FileInfo) – the fileinfo with information.
Returns a filename chunk or None
Return type str|None
Raises None
class jukeboxcore.filesys.StaticElement(dirname=None, chunk=None)Bases: jukeboxcore.filesys.FileElement
A static element that will always give the same dir or chunk and is independent of the object
Can be used to insert static folders like a folder where all maya files go.
Constructs a new static element that will always give the specified dir and/or chunk
Parameters
• dirname (str|None) – the dirname the element will contribute or None
• chunk (str|None) – the chunk for the filename the element will contribute or None
Raises None
get_dir(obj)Return a part of the filepath for the given object, or None if the element does not contribute a directory.
This will always return the dirname that was specified in the constructor
Parameters obj (FileInfo) – the fileinfo with information.
Returns the directory that was given in the constructor
Return type str|None
Raises None
get_chunk(obj)Return a filenamechunk or None, if the element does not contribute a directory
This will always return the chunk that was specified in the constructor
Parameters obj (FileInfo) – the fileinfo with information.
Returns the chunk that was given in the contructor
Return type str|None
2.3. Reference 35
Jukebox Core Documentation, Release 3.3.1
Raises None
class jukeboxcore.filesys.AttrElement(dirattr=None, chunkattr=None, dirformat=’%s’, chunk-format=’%s’)
Bases: jukeboxcore.filesys.FileElement
A simple element that will always return a certain attribute for a dir or chunk
You can also specify a format string.
Constructs a new attr element. It will use the given attribute to query with operator.attrgetter andformat it with the corresponding format string. So it is possible to get nested attributes. For nested attributesspecify something like this: attr1.attr2.attr3.
Parameters
• dirattr (str|None) – the attribute to use for directories
• chunkattr (str|None) – the attribute to use for chunks
• dirformat (str) – the format string for directories. formating will be done with the %operator.
• chunkformat (str) – the format string for chunks. formating will be done with the %operator.
Raises None
get_dir(obj)Return the dirattr of obj formatted with the dirfomat specified in the constructor. If the attr is None thenNone is returned not the string ’None’.
Parameters obj (FileInfo) – the fileinfo with information.
Returns the directory or None
Return type str|None
Raises None
get_chunk(obj)Return the chunkattr of obj formatted with the chunkfomat specified in the constructor If the attr is Nonethen None is returned not the string ’None’.
Parameters obj (FileInfo) – the fileinfo with information.
Returns the chunk or None
Return type str|None
Raises None
class jukeboxcore.filesys.SoftwareElementBases: jukeboxcore.filesys.FileElement
This element checks a TaskFileInfo for the typ and returns the directory name for the software branch.
typmapping = {‘mayamainscene’: ‘Maya’}
get_dir(taskinfo)Return a directory for the software, depending on the typ of taskinfo
Parameters obj (TaskFileInfo) – the fileinfo with information.
Returns directory for the software, depending on the typ of taskinfo
Return type str
36 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Raises None
class jukeboxcore.filesys.TaskGroupElementBases: jukeboxcore.filesys.FileElement
This element checks a TaskFileInfo and returns the top directory name for either shots or assets joined by eitherthe sequence name or the assettype name
get_dir(taskinfo)Return assets/ + assettypename if it is for an assettask or shots/ + sequencename if is is for a shottask
Parameters obj (TaskFileInfo) – the fileinfo with information.
Returns assets or shots depending on the assetflag of the task of taskinfo
Return type str
Raises None
class jukeboxcore.filesys.ExtElementBases: object
The ExtElement uses a file info object to determine the file extension
get_ext(obj)Return a file extension (without the extension seperator) for the given file info obj
Parameters obj (TaskFileInfo) – the fileinfo with information.
Returns None
Return type None
Raises None
class jukeboxcore.filesys.StaticExtElement(ext)Bases: jukeboxcore.filesys.ExtElement
This extension element will always return the same extension no matter what the file info is
Constructs a new static extension element that always returns the given file extension
Parameters ext (str) – the extension
Raises None
get_ext(obj)
Parameters obj (FileInfo) – the fileinfo with information.
Returns the extension that was specified in the constructor
Return type str
Raises None
class jukeboxcore.filesys.TaskFileExtElementBases: jukeboxcore.filesys.ExtElement
This extension element uses a TaskFileInfo and returns an appropriate extension
typmapping = {‘mayamainscene’: ‘mb’}
get_ext(taskinfo)Return a file extension (without the extension seperator) for the given file info obj
Parameters obj (TaskFileInfo) – the fileinfo with information.
Returns the appropriate extension without extension seperator (.)
2.3. Reference 37
Jukebox Core Documentation, Release 3.3.1
Return type str
Raises None
class jukeboxcore.filesys.JB_File(obj)Bases: object
This class generates filenames for arbitrary objects
The object should contain all the information that is needed for constructing a distinct filepath. It should be asubclass of FileInfo. This class uses a list of FileElement to generate the filepath. Each element shouldknow how to handle the object. So only use certain objects with certain elements. Each element contributes toeither the path or the name or both. The JB_File has a dictionary JB_File.ELEMENTPRESETS that have alist of element for every FileInfo sublcass.
Constructs a new JB_File. the type of object determines the elementspreset (the generation of the path).
Parameters obj (FileInfo) – the fileinfo with information.
Raises None
ELEMENTPRESETS = {<class ‘jukeboxcore.filesys.TaskFileInfo’>: [<jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5d910>, <jukeboxcore.filesys.StaticElement object at 0x7f3fdaf5d990>, <jukeboxcore.filesys.SoftwareElement object at 0x7f3fdaf5d9d0>, <jukeboxcore.filesys.TaskGroupElement object at 0x7f3fdaf5da10>, <jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5da50>, <jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5da90>, <jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5dad0>, <jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5db10>, <jukeboxcore.filesys.AttrElement object at 0x7f3fdaf5db50>]}this dict has a list of elements for each file info type
EXTENSIONS = {<class ‘jukeboxcore.filesys.TaskFileInfo’>: <jukeboxcore.filesys.TaskFileExtElement object at 0x7f3fdaf5db90>}this dict has extensionelement for each file info type
get_ext(obj=None)Return the file extension
Parameters obj (FileInfo) – the fileinfo with information. If None, this will use the storedobject of JB_File
Returns the file extension
Return type str
Raises None
get_path(obj=None)Return the path (excluding the filename)
Parameters obj (FileInfo) – the fileinfo with information. If None, this will use the storedobject of JB_File
Returns the path to the file
Return type str
Raises None
get_name(obj=None, withext=True)Return the filename
Parameters
• obj (FileInfo) – the fileinfo with information. If None, this will use the stored objectof JB_File
• withext (bool) – If True, return with the fileextension.
Returns the filename, default is with fileextension
Return type str
Raises None
38 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
get_fullpath(withext=True)Return the filepath with the filename
Parameters withext (bool) – If True, return with the fileextension.
Returns None
Return type None
Raises None
get_obj()Return the object that contains the information
Returns the object with information
Return type FileInfo
Raises None
set_obj(obj)Set the object that contains the information
Parameters obj (FileInfo) – the fileinfo with information.
Returns None
Return type None
Raises None
get_elements()Return the file elements
Returns list with FileElements that are used to generate the filepath
Return type list of FileElement
Raises None
create_directory(path=None)Create the directory for the given path. If path is None use the path of this instance
Parameters path (str) – the path to create
Returns None
Return type None
Raises OSError
iniconf
The config module manages writing and loading of user preferences
We use ConfigObj Module. With its help, we can read and write ini-files. We are also able to validate it against aspecification ini, so there are always correct values after loading.
Use the jukeboxcore.iniconf module for loading the core config file. As a plugin developer, usejukeboxcore.plugins.JB_Plugin.get_config() to obtain the ConfigObj. The ConfigObj behaves likea dictionary. It will have all keys, that you specified in your spec file.
Important: Make sure that every value in your config specification has a valid default value!
For editing a configfile there is the Configer plugin.
2.3. Reference 39
Jukebox Core Documentation, Release 3.3.1
jukeboxcore.iniconf.get_section_path(section)Return a list with keys to access the section from root
Parameters section (Section) – A Section
Returns list of strings in the order to access the given section from root
Raises None
jukeboxcore.iniconf.check_default_values(section, key, validator=None)Raise an MissingDefaultError if a value in section does not have a default values
Parameters
• section (section) – the section of a configspec
• key (str) – a key of the section
• validator (Validator) – a Validator object to get the default values
Returns None
Raises MissingDefaultError
Use this in conjunction with the walk method of a ConfigObj. The ConfigObj should be the configspec! Whenyou want to use a custom validator, try:
configinstance.walk(check_default_values, validator=validatorinstance)
jukeboxcore.iniconf.fix_errors(config, validation)Replace errors with their default values
Parameters
• config (ConfigObj) – a validated ConfigObj to fix
• validation (ConfigObj) – the resuts of the validation
Returns The altered config (does alter it in place though)
Raises None
jukeboxcore.iniconf.set_to_default(section, key)Set the value of the given seciton and key to default
Parameters
• section (section) – the section of a configspec
• key (str) – a key of the section
Returns None
Raises None
jukeboxcore.iniconf.clean_config(config)Check if all values have defaults and replace errors with their default value
Parameters config (ConfigObj) – the configobj to clean
Returns None
Raises ConfigError
The object is validated, so we need a spec file. All failed values will be replaced by their default values. Ifdefault values are not specified in the spec, a MissingDefaultError will be raised. If the replaced values still failvalidation, a ValueError is raised. This can occur if the default is of the wrong type.
If the object does not have a config spec, this function does nothing. You are on your own then.
40 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
jukeboxcore.iniconf.load_config(f, spec)Return the ConfigObj for the specified file
Parameters
• f (str) – the config file path
• spec (str) – the path to the configspec
Returns the loaded ConfigObj
Return type ConfigObj
Raises ConfigError
jukeboxcore.iniconf.get_core_config()Return the ConfigObj of the main jukebox config file
Returns the loaded ConfigObj
Return type ConfigObj
Raises None
launcher
log
Here we provide standard loggers for our pipeline. It is advised to use them instead of the print function.
jukeboxcore.log.setup_jukebox_logger()Setup the jukebox top-level logger with handlers
The logger has the name jukebox and is the top-level logger for all other loggers of jukebox. It does notpropagate to the root logger, because it also has a StreamHandler and that might cause double output.
The logger default level is defined in the constants jukeboxcore.constants.DEFAULT_LOGGING_LEVELbut can be overwritten by the environment variable “JUKEBOX_LOG_LEVEL”
Returns None
Return type None
Raises None
jukeboxcore.log.get_logger(name, level=None)Return a setup logger for the given name
Parameters
• name (str) – The name for the logger. It is advised to use __name__. The logger name willbe prepended by “jb.”.
• level (int) – the logging level, e.g. logging.DEBUG, logging.INFO etc
Returns Logger
Return type logging.Logger
Raises None
The logger default level is defined in the constants jukeboxcore.constants.DEFAULT_LOGGING_LEVELbut can be overwritten by the environment variable “JUKEBOX_LOG_LEVEL”
2.3. Reference 41
Jukebox Core Documentation, Release 3.3.1
main
Bundles common core functions.
There are different init functions to initialize jukebox. jukeboxcore.main.init() should be called once beforeusing the pipeline.
jukeboxcore.main.init_environment()Set environment variables that are important for the pipeline.
Returns None
Return type None
Raises None
jukeboxcore.main.init()Initialize the pipeline so everything works
Initiealizes environment variables and loads the plugins
jukeboxcore.main.unload_modules()Unload all modules of the jukebox package and all plugin modules
Python provides the reload command for reloading modules. The major drawback is, that if this module isloaded in any other module the source code will not be resourced! If you want to reload the code because youchanged the source file, you have to get rid of it completely first.
Returns None
Return type None
Raises None
ostool
Module for platform specific operations
There are 3 important parts:
jukeboxcore.ostool.detect_sys() detects the platform you are working on.
jukeboxcore.ostool.PlatformInterface is an abstract class that defines a set of methods Tosupport a special plattform, subclass it and implement the abstract methods. Then put your Class insidejukeboxcore.ostool.interfaces. The system should be the key for the dict.
jukeboxcore.ostool.get_interface() will detect your system, then searches insidejukeboxcore.ostool.interfaces for a match.
jukeboxcore.ostool.detect_sys()Tries to identify your python platform
Returns a dict with the gathered information
Return type dict
Raises None
the returned dict has these keys: ‘system’, ‘bit’, ‘compiler’, ‘python_version_tuple’
eg.:
{'system':'Windows', 'bit':'32bit', 'compiler':'MSC v.1500 32bit (Intel)', 'python_version_tuple':('2', '7', '6')}
42 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
class jukeboxcore.ostool.PlatformInterfaceBases: object
An abstract class that has platform specific methods
Sublcasses have to implement those methods!
get_maya_location()Return the installation path to maya
Returns path to maya
Return type str
Raises errors.SoftwareNotFoundError
get_maya_sitepackage_dir()Return the sitepackage dir for maya
Returns path to the maya sitepackages
Return type str
Raises errors.SoftwareNotFoundError
get_maya_bin()Return the path to the maya bin dir
Returns path to maya bin dir
Return type str
Raises errors.SoftwareNotFoundError
get_maya_python()Return the path to the mayapy executable
Returns path to the maya python intepreter
Return type str
Raises errors.SoftwareNotFoundError
get_maya_exe()Return the path to the maya executable
Returns path to the maya exe
Return type str
Raises errors.SoftwareNotFoundError
get_maya_envpath()Return the PYTHONPATH neccessary for running mayapy
Returns the PYTHONPATH that is used for running mayapy
Return type str
Raises None
open_path(path)Open the given path in the file browser
Parameters path (str) – the path to open
Returns None
Return type None
2.3. Reference 43
Jukebox Core Documentation, Release 3.3.1
Raises None
class jukeboxcore.ostool.WindowsInterfaceBases: jukeboxcore.ostool.PlatformInterface
Interface for all windows related operations
implements all methods of PlatformInterface
get_maya_location()Return the installation path to maya
Returns path to maya
Return type str
Raises errors.SoftwareNotFoundError
get_maya_sitepackage_dir()Return the sitepackage dir for maya
Returns path to the maya sitepackages
Return type str
Raises errors.SoftwareNotFoundError
get_maya_bin()Return the path to the maya bin dir
Returns path to maya bin dir
Return type str
Raises errors.SoftwareNotFoundError
get_maya_python()Return the path to the mayapy executable
Returns path to the maya python intepreter
Return type str
Raises errors.SoftwareNotFoundError
get_maya_exe()Return the path to the maya executable
Returns path to the maya exe
Return type str
Raises errors.SoftwareNotFoundError
get_maya_envpath()Return the PYTHONPATH neccessary for running mayapy
If you start native mayapy, it will setup these paths. You might want to prepend this to your path if runningfrom an external intepreter.
Returns the PYTHONPATH that is used for running mayapy
Return type str
Raises None
open_path(path)Open the given path in the file browser
44 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Parameters path (str) – the path to open
Returns None
Return type None
Raises None
jukeboxcore.ostool.interfaces = {‘Windows’: <class ‘jukeboxcore.ostool.WindowsInterface’>}Dictionary for platforminterfaces. Values are PlatformInterface subclasses and keys are values of de-tect_sys()[’system’]
jukeboxcore.ostool.get_interface()Return the appropriate PlatformInterface implementation for your platform
Returns the appropriate platform interface for my platform
Return type PlatformInterface‘
Raises errors.UnsupportedPlatformError
plugins
A collection of classes, metaclasses and functions for Plugins
As a plugin developer: Subclass from one of the JB_Plugin classes and implement the abstract functions. The pluginmanagers load and hold plugins.
class jukeboxcore.plugins.JB_PluginBases: object
Abstract Base Class for jukebox plugins.
Subclass this to create your own types of plugins. The name of the subclass will be the name of the plugin itself,so be sure to pick a unique one. Else you will override an existing plugin (maybe that is your intend, then do it).If you write a plugin, always subclass from a subclass of JB_Plugin but not JB_Plugin directly!
For subclassing: you have to implement init and uninit!
Metadata:
This class has a few public attributes. Override them to supply metadata for your plugin.
User Config:
Every Plugin can have its own userpreference file. The user preferences are ini-files that lie in theconfig folder inside the pipeline user directory. As a plugin developer, create a configspec file in thesame folder as your plugin module. Do it only, if you need to use get_config().
Constructs a new Plugin
Returns None
Return type None
Raises None
required = ()The plugins required to run this one successfully. Set this to a list of strings with the required classnames.
author = NoneThe author of the plugin.
copyright = NoneCopyright information.
2.3. Reference 45
Jukebox Core Documentation, Release 3.3.1
license = NoneLicense information.
version = NoneThe version of the plugin.
description = NoneA descriptive text for the plugin.
init()Initialize the plugin
This function gets called when the plugin is loaded by the plugin manager. It is abstract and has to beimplemented in a subclass
Returns
Return type
Raises
uninit()Uninitialize the plugin
This function gets called when the plugin is unloaded by the plugin manager. It is abstract and has to beimplemented in a subclass
Returns
Return type
Raises
is_loaded()Return True if the plugin is loaded
Returns Returns False if the plugin is not loaded
Return type bool
Raises None
get_config()Return the user config for this plugin
You have to provide a configspec, put the configspec file in the same folder as your plugin. Name it likeyour class and put ‘ini’ as extension.
nameReturn the name of the plugin. Equivalent quering __class__.__name__
Returns The name of the plugin
Return type str
Raises None
class jukeboxcore.plugins.JB_StandalonePluginBases: jukeboxcore.plugins.JB_Plugin
Abstract plugin class for standalone addons.
Standalone addons feature a special run method an can be run with the jukebox launcher. The launcher will firstinitialize the plugin and then call the run method.
For subclassing: you have to implement init, unit and run!
46 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
Constructs a new Plugin
Returns None
Return type None
Raises None
run()Start the plugin. This method is also called by the jukebox launcher.
Returns None
Return type None
Raises None
class jukeboxcore.plugins.JB_StandaloneGuiPluginBases: jukeboxcore.plugins.JB_StandalonePlugin
Abstract plugin class for standalone addons that need a gui.
Standalone addons feature a special run method an can be run with the jukebox launcher. The launcher will firstinitialize the plugin and then call the run method. The launcher will also initialize the gui before running theplugin.
For subclassing: you have to implement init, unit and run!
Constructs a new Plugin
Returns None
Return type None
Raises None
class jukeboxcore.plugins.JB_CorePluginBases: jukeboxcore.plugins.JB_Plugin
Core plugin class
Core plugins should be loadable at all times and not require a specific software to run.
For subclassing: you have to implement init and uninit!
Constructs a new Plugin
Returns None
Return type None
Raises None
class jukeboxcore.plugins.JB_CoreStandalonePluginBases: jukeboxcore.plugins.JB_StandalonePlugin, jukeboxcore.plugins.JB_CorePlugin
Core plugin for standalone addons.
Standalone addons feature a special run method an can be run with the jukebox launcher. The launcher will firstinitialize the plugin and then call the run method.
For subclassing: you have to implement init, unit and run!
Constructs a new Plugin
Returns None
Return type None
2.3. Reference 47
Jukebox Core Documentation, Release 3.3.1
Raises None
class jukeboxcore.plugins.JB_CoreStandaloneGuiPluginBases: jukeboxcore.plugins.JB_StandaloneGuiPlugin, jukeboxcore.plugins.JB_CoreStandalonePlugin
Core plugin for standalone addons that also need a gui.
Standalone addons feature a special run method an can be run with the jukebox launcher. The launcher will firstinitialize the plugin and then call the run method.
For subclassing: you have to implement init, unit and run!
Constructs a new Plugin
Returns None
Return type None
Raises None
class jukeboxcore.plugins.PluginManagerBases: object
Loads and unloads core plugins.
A plugin manager scanns the plugin directories for plugins. Only plugins types that are supported can be loaded.If you need special plugins for a software, subclass JB_Plugin. Then create a subclass of this plugin managerand override supportedTypes. Core plugins should always be supported.
The gathering of plugins is done during initialisation. To load the plugins, call load_plugins(). This will load allfound plugins.
Constructs a new PluginManager, use the get method in 99% of cases!
Raises None
instance = NonePluginManager instance when using PluginManager.get()
supportedTypes = [<class ‘jukeboxcore.plugins.JB_CorePlugin’>, <class ‘jukeboxcore.plugins.JB_CoreStandalonePlugin’>, <class ‘jukeboxcore.plugins.JB_CoreStandaloneGuiPlugin’>]A list of plugin classes, the manager can load. Override this list in a subclass if you want to support morethan just core plugins, e.g. plugins that are meant for a specific software.
classmethod get()Return a PluginManager Instance.
This will always return the same instance. If the instance is not available it will be created and returned.There should only be one pluginmanager at a time. If you create a PluginManager with get() and use get()on for example a MayaPluginManager, the PluginManager instance is returned (not a MayaPluginMan-ager).
Returns always the same PluginManager
Return type PluginManager
Raises None
find_plugins(path)Return a list with all plugins found in path
Parameters path (str) – the directory with plugins
Returns list of JB_Plugin subclasses
Return type list
Raises None
48 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
gather_plugins()Return all plugins that are found in the plugin paths
Looks in the envvar JUKEBOX_PLUGIN_PATH.
Returns
Return type
Raises
load_plugins()Loads all found plugins
Returns None
Return type None
Raises None
load_plugin(p)Load the specified plugin
Parameters p (Subclass of JB_Plugin) – The plugin to load
Returns None
Return type None
Raises errors.PluginInitError
unload_plugins()Unloads all loaded plugins
Returns None
Return type None
Raises None
get_plugin(plugin)Return the plugin instance for the given pluginname
Parameters plugin (str) – Name of the plugin class
Returns the plugin that matches the name
Return type JB_Plugin like
Raises None
get_all_plugins()Return all plugins
Returns a list of all plugins found by the manager
2.3. Reference 49
Jukebox Core Documentation, Release 3.3.1
reftrack
release
signals
Module contents
2.4 Contributing
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
2.4.1 Types of Contributions
Report Bugs
Report bugs at https://github.com/JukeboxPipeline/jukebox-core/issues.
If you are reporting a bug, please include:
• Your operating system name and version.
• Any details about your local setup that might be helpful in troubleshooting.
• Detailed steps to reproduce the bug.
Fix Bugs
Look through the GitHub issues for bugs. Anything tagged with “bug” is open to whoever wants to implement it.
Implement Features
Look through the GitHub issues for features. Anything tagged with “feature” is open to whoever wants to implementit.
Write Documentation
Jukebox Core could always use more documentation, whether as part of the official Jukebox Core docs, in docstrings,or even on the web in blog posts, articles, and such.
Submit Feedback
The best way to send feedback is to file an issue at https://github.com/JukeboxPipeline/jukebox-core/issues.
If you are proposing a feature:
• Explain in detail how it would work.
• Keep the scope as narrow as possible, to make it easier to implement.
• Remember that this is a volunteer-driven project, and that contributions are welcome :)
50 Chapter 2. Contents:
Jukebox Core Documentation, Release 3.3.1
2.4.2 Get Started!
Ready to contribute? Here’s how to set up jukebox-core for local development.
1. Fork the jukebox-core repo on GitHub.
2. Clone your fork locally:
$ git clone [email protected]:your_name_here/jukebox-core.git
3. Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
4. When you’re done making changes, check that your changes pass style and unit tests, including testing otherPython versions with tox:
$ tox
To get tox, just pip install it.
5. Commit your changes and push your branch to GitHub:
$ git add .$ git commit -m "Your detailed description of your changes."$ git push origin name-of-your-bugfix-or-feature
6. Submit a pull request through the GitHub website.
2.4.3 Pull Request Guidelines
Before you submit a pull request, check that it meets these guidelines:
1. The pull request should include tests.
2. If the pull request adds functionality, the docs should be updated. Put your new functionality into a functionwith a docstring, and add the feature to the list in README.rst.
3. The pull request should work for Python 2.7. Run the tox command and make sure that the tests pass for allsupported Python versions.
2.4.4 Tips
To run a subset of tests:
$ py.test test/test_jukeboxcore.py
2.5 Credits
2.5.1 Development Lead
• David Zuber <[email protected]>
2.5. Credits 51
Jukebox Core Documentation, Release 3.3.1
2.5.2 Contributors
None yet. Why not be the first?
2.6 History
2.6.1 0.1.0 (2014-09-27)
• Migration from old project
2.6.2 1.0.3 (2014-10-23)
• First release on PyPI
2.6.3 1.0.4 (2014-10-24)
• Fix for missing dependency
• Documentation hosted on pythonhosted.org
2.6.4 2.0.0 (2014-11-10)
• Release mechanism.
• Fixes for widgetdelegate.
• Browser for taskfiles.
• Qt resource files compilation and proper integration in stylesheets.
2.6.5 3.0.0 (2015-01-09)
• Reference workflow
• Fixes for widgetdelegate
2.6.6 3.3.0 (2015-05-29)
• Better ui for project management
52 Chapter 2. Contents:
CHAPTER 3
Feedback
If you have any suggestions or questions about Jukebox Core feel free to email me at [email protected].
If you encounter any errors or problems with Jukebox Core, please let me know! Open an Issue at the GitHubhttps://github.com/JukeboxPipeline/jukebox-core main repository.
3.1 Indices and tables
• genindex
• modindex
• search
53
Jukebox Core Documentation, Release 3.3.1
54 Chapter 3. Feedback
Python Module Index
jjukeboxcore, 50jukeboxcore.action, 26jukeboxcore.addons, 23jukeboxcore.addons.configer, 22jukeboxcore.addons.genesis, 22jukeboxcore.addons.guerilla, 23jukeboxcore.constants, 28jukeboxcore.djadapter, 29jukeboxcore.djsettings, 31jukeboxcore.errors, 31jukeboxcore.filesys, 32jukeboxcore.gui, 25jukeboxcore.gui.resources, 23jukeboxcore.gui.widgets, 25jukeboxcore.gui.widgets.guerilla, 24jukeboxcore.iniconf, 39jukeboxcore.log, 41jukeboxcore.main, 42jukeboxcore.ostool, 42jukeboxcore.plugins, 45
55
Jukebox Core Documentation, Release 3.3.1
56 Python Module Index
Index
AActionCollection (class in jukeboxcore.action), 27ActionStatus (class in jukeboxcore.action), 26ActionUnit (class in jukeboxcore.action), 26assets (in module jukeboxcore.djadapter), 30AttrElement (class in jukeboxcore.filesys), 36atypes (in module jukeboxcore.djadapter), 30author (jukeboxcore.plugins.JB_Plugin attribute), 45
BBUILTIN_PLUGIN_PATH (in module jukebox-
core.constants), 28
Ccheck_default_values() (in module jukeboxcore.iniconf),
40clean_config() (in module jukeboxcore.iniconf), 40CONFIG_DIR (in module jukeboxcore.constants), 28CONFIG_EXT (in module jukeboxcore.constants), 28ConfigError, 31copy_file() (in module jukeboxcore.filesys), 32copyright (jukeboxcore.plugins.JB_Plugin attribute), 45CORE_CONFIG_PATH (in module jukebox-
core.constants), 28CORE_CONFIG_SPEC_PATH (in module jukebox-
core.constants), 29create_db_entry() (jukeboxcore.filesys.TaskFileInfo
method), 34create_directory() (jukeboxcore.filesys.JB_File method),
39create_from_taskfile() (jukeboxcore.filesys.TaskFileInfo
class method), 34
DDATA_DIR (in module jukeboxcore.constants), 29DEFAULT_ASSETTYPES (in module jukebox-
core.djadapter), 29DEFAULT_DEPARTMENTS (in module jukebox-
core.djadapter), 29
DEFAULT_LOGGING_LEVEL (in module jukebox-core.constants), 28
delete_file() (in module jukeboxcore.filesys), 32departments (in module jukeboxcore.djadapter), 30description (jukeboxcore.plugins.JB_Plugin attribute), 46detect_sys() (in module jukeboxcore.ostool), 42
EELEMENTPRESETS (jukeboxcore.filesys.JB_File at-
tribute), 38ERROR (jukeboxcore.action.ActionStatus attribute), 26execute() (jukeboxcore.action.ActionCollection method),
28ExtElement (class in jukeboxcore.filesys), 37EXTENSIONS (jukeboxcore.filesys.JB_File attribute),
38
FFAILURE (jukeboxcore.action.ActionStatus attribute),
26FileElement (class in jukeboxcore.filesys), 34FileInfo (class in jukeboxcore.filesys), 32files (in module jukeboxcore.djadapter), 30FILETYPES (in module jukeboxcore.djadapter), 30find_plugins() (jukeboxcore.plugins.PluginManager
method), 48fix_errors() (in module jukeboxcore.iniconf), 40
Ggather_plugins() (jukeboxcore.plugins.PluginManager
method), 48get() (jukeboxcore.plugins.PluginManager class method),
48get_all_plugins() (jukeboxcore.plugins.PluginManager
method), 49get_chunk() (jukeboxcore.filesys.AttrElement method),
36get_chunk() (jukeboxcore.filesys.FileElement method),
35get_chunk() (jukeboxcore.filesys.StaticElement method),
35
57
Jukebox Core Documentation, Release 3.3.1
get_config() (jukeboxcore.plugins.JB_Plugin method), 46get_core_config() (in module jukeboxcore.iniconf), 41get_current_user() (in module jukeboxcore.djadapter), 30get_dir() (jukeboxcore.filesys.AttrElement method), 36get_dir() (jukeboxcore.filesys.FileElement method), 34get_dir() (jukeboxcore.filesys.SoftwareElement method),
36get_dir() (jukeboxcore.filesys.StaticElement method), 35get_dir() (jukeboxcore.filesys.TaskGroupElement
method), 37get_elements() (jukeboxcore.filesys.JB_File method), 39get_ext() (jukeboxcore.filesys.ExtElement method), 37get_ext() (jukeboxcore.filesys.JB_File method), 38get_ext() (jukeboxcore.filesys.StaticExtElement method),
37get_ext() (jukeboxcore.filesys.TaskFileExtElement
method), 37get_fullpath() (jukeboxcore.filesys.JB_File method), 38get_interface() (in module jukeboxcore.ostool), 45get_latest() (jukeboxcore.filesys.FileInfo class method),
32get_latest() (jukeboxcore.filesys.TaskFileInfo class
method), 33get_logger() (in module jukeboxcore.log), 41get_maya_bin() (jukeboxcore.ostool.PlatformInterface
method), 43get_maya_bin() (jukeboxcore.ostool.WindowsInterface
method), 44get_maya_envpath() (jukebox-
core.ostool.PlatformInterface method), 43get_maya_envpath() (jukebox-
core.ostool.WindowsInterface method), 44get_maya_exe() (jukeboxcore.ostool.PlatformInterface
method), 43get_maya_exe() (jukeboxcore.ostool.WindowsInterface
method), 44get_maya_location() (jukebox-
core.ostool.PlatformInterface method), 43get_maya_location() (jukebox-
core.ostool.WindowsInterface method), 44get_maya_python() (jukebox-
core.ostool.PlatformInterface method), 43get_maya_python() (jukebox-
core.ostool.WindowsInterface method), 44get_maya_sitepackage_dir() (jukebox-
core.ostool.PlatformInterface method), 43get_maya_sitepackage_dir() (jukebox-
core.ostool.WindowsInterface method), 44get_name() (jukeboxcore.filesys.JB_File method), 38get_next() (jukeboxcore.filesys.FileInfo class method), 32get_next() (jukeboxcore.filesys.TaskFileInfo class
method), 33get_obj() (jukeboxcore.filesys.JB_File method), 39get_path() (jukeboxcore.filesys.JB_File method), 38
get_plugin() (jukeboxcore.plugins.PluginManagermethod), 49
get_section_path() (in module jukeboxcore.iniconf), 39GLOBAL_NAME (in module jukeboxcore.djadapter), 29
IICON_PATH (in module jukeboxcore.constants), 29init() (in module jukeboxcore.main), 42init() (jukeboxcore.plugins.JB_Plugin method), 46init_environment() (in module jukeboxcore.main), 42instance (jukeboxcore.plugins.PluginManager attribute),
48IntegrityError, 31interfaces (in module jukeboxcore.ostool), 45is_latest() (jukeboxcore.filesys.TaskFileInfo method), 34is_loaded() (jukeboxcore.plugins.JB_Plugin method), 46
JJB_CorePlugin (class in jukeboxcore.plugins), 47JB_CoreStandaloneGuiPlugin (class in jukebox-
core.plugins), 48JB_CoreStandalonePlugin (class in jukeboxcore.plugins),
47JB_File (class in jukeboxcore.filesys), 38JB_Plugin (class in jukeboxcore.plugins), 45JB_StandaloneGuiPlugin (class in jukeboxcore.plugins),
47JB_StandalonePlugin (class in jukeboxcore.plugins), 46jukeboxcore (module), 50jukeboxcore.action (module), 26jukeboxcore.addons (module), 23jukeboxcore.addons.configer (module), 22jukeboxcore.addons.genesis (module), 22jukeboxcore.addons.guerilla (module), 23jukeboxcore.constants (module), 28jukeboxcore.djadapter (module), 29jukeboxcore.djsettings (module), 31jukeboxcore.errors (module), 31jukeboxcore.filesys (module), 32jukeboxcore.gui (module), 25jukeboxcore.gui.resources (module), 23jukeboxcore.gui.widgets (module), 25jukeboxcore.gui.widgets.guerilla (module), 24jukeboxcore.iniconf (module), 39jukeboxcore.log (module), 41jukeboxcore.main (module), 42jukeboxcore.ostool (module), 42jukeboxcore.plugins (module), 45JukeboxException, 31
Llicense (jukeboxcore.plugins.JB_Plugin attribute), 45load_config() (in module jukeboxcore.iniconf), 41
58 Index
Jukebox Core Documentation, Release 3.3.1
load_plugin() (jukeboxcore.plugins.PluginManagermethod), 49
load_plugins() (jukeboxcore.plugins.PluginManagermethod), 49
loglvl_mapping (in module jukeboxcore.constants), 28
MMAIN_STYLESHEET (in module jukebox-
core.constants), 29MAYA_REG_KEY (in module jukeboxcore.constants),
29MAYA_VERSIONS (in module jukeboxcore.constants),
29MenuExistsError, 31
Nname (jukeboxcore.plugins.JB_Plugin attribute), 46notes (in module jukeboxcore.djadapter), 30
Oopen_path() (jukeboxcore.ostool.PlatformInterface
method), 43open_path() (jukeboxcore.ostool.WindowsInterface
method), 44
PPlatformInterface (class in jukeboxcore.ostool), 42PLUGIN_CONFIG_DIR (in module jukebox-
core.constants), 28PluginInitError, 31PluginManager (class in jukeboxcore.plugins), 48PluginUninitError, 31projects (in module jukeboxcore.djadapter), 30
RReftrackIntegrityError, 31RELEASETYPES (in module jukeboxcore.djadapter), 30required (jukeboxcore.plugins.JB_Plugin attribute), 45RNDSEQ_NAME (in module jukeboxcore.djadapter), 29run() (jukeboxcore.action.ActionUnit method), 27run() (jukeboxcore.plugins.JB_StandalonePlugin
method), 47
Ssequences (in module jukeboxcore.djadapter), 30set_obj() (jukeboxcore.filesys.JB_File method), 39set_to_default() (in module jukeboxcore.iniconf), 40setup_jukebox_logger() (in module jukeboxcore.log), 41setup_testdatabase() (in module jukeboxcore.djadapter),
29shots (in module jukeboxcore.djadapter), 30SKIPPED (jukeboxcore.action.ActionStatus attribute), 26SoftwareElement (class in jukeboxcore.filesys), 36
SoftwareNotFoundError, 31softwares (in module jukeboxcore.djadapter), 30StaticElement (class in jukeboxcore.filesys), 35StaticExtElement (class in jukeboxcore.filesys), 37status() (jukeboxcore.action.ActionCollection method),
28STYLESHEET_PATH (in module jukebox-
core.constants), 29SUCCESS (jukeboxcore.action.ActionStatus attribute),
26supportedTypes (jukeboxcore.plugins.PluginManager at-
tribute), 48
TTaskFileExtElement (class in jukeboxcore.filesys), 37TaskFileInfo (class in jukeboxcore.filesys), 33taskfiles (in module jukeboxcore.djadapter), 30TaskGroupElement (class in jukeboxcore.filesys), 37tasks (in module jukeboxcore.djadapter), 30TYPES (jukeboxcore.filesys.TaskFileInfo attribute), 33typmapping (jukeboxcore.filesys.SoftwareElement
attribute), 36typmapping (jukeboxcore.filesys.TaskFileExtElement at-
tribute), 37
Uuninit() (jukeboxcore.plugins.JB_Plugin method), 46unload_modules() (in module jukeboxcore.main), 42unload_plugins() (jukeboxcore.plugins.PluginManager
method), 49UnsupportedPlatformError, 31USERDIR (in module jukeboxcore.constants), 28users (in module jukeboxcore.djadapter), 30
Vversion (jukeboxcore.plugins.JB_Plugin attribute), 46
WWindowsInterface (class in jukeboxcore.ostool), 44
Index 59