# -------------------------------------------------------------
What
# -------------------------------------------------------------
This is an API wrapper for Shotgun aimed to provide speed enhancements.
It has been designed specifically for scripts that quickly connect, get some
data, and then disconnect.

This also improves slow performance from within Maya and 3DS Max. Both
of these programs have serious speed issues when calling Shotgun directly.
Query times that can be 10-50 seconds from within these programs, but
when using this wrapper the times are the same as usual.


# -------------------------------------------------------------
Test results
# -------------------------------------------------------------
Here are the results of a time test for the wrapper vs. the regular Shotgun
API. There are two different tests happening.

The first test is of 100 individual queries being made. An individual query
is creating a database connection, making a single query, disconnecting,
and then repeating the process for the next query.

The second test is of 100 multiple queries. A multiple query is connecting
to the database and then running 100 queries before disconnecting.

The first chunk below is showing data for 100 individual queries using
DoubleBarrel. The second chunk is showing data for 100 individual queries
using Shotgun's API. The third chunk is showing data for 100 multiple
queries using DoubleBarrel. The forth chunk is showing data for 100 
multiple queries using Shotgun's API.


    Speed test - Class: DoubleBarrel Function: individualQuery Units: Seconds
        Total time: 11.2291147709
        Mean time: 0.112291147709
        Median time: 0.0993931293488
        Mode time(s): ['0.1']
        Fastest time: 0.0913400650024
        Slowest time: 0.203774213791
        Time hits: [('0.1', '83 hits'), ('0.2', '17 hits')]
    
    Speed test - Class: Shotgun Function: individualQuery Units: Seconds
        Total time: 44.5533914566
        Mean time: 0.445533914566
        Median time: 0.432259082794
        Mode time(s): ['0.4']
        Fastest time: 0.411613941193
        Slowest time: 0.54580283165
        Time hits: [('0.4', '75 hits'), ('0.5', '25 hits')]
    
    
    Speed test - Class: DoubleBarrel Function: multipleQueries Units: Seconds
        Total time: 11.3314521313
        Mean time: 0.113314521313
        Median time: 11.3314521313
        Mode time(s): ['11.3']
        Fastest time: 11.3314521313
        Slowest time: 11.3314521313
        Time hits: [('11.3', '1 hits')]
    
    Speed test - Class: Shotgun Function: multipleQueries Units: Seconds
        Total time: 11.4555420876
        Mean time: 0.114555420876
        Median time: 11.4555420876
        Mode time(s): ['11.5']
        Fastest time: 11.4555420876
        Slowest time: 11.4555420876
        Time hits: [('11.5', '1 hits')]
        
As you can see, DoubleBarrel provides a significant speed enhancement
when making individual database queries and is about equal when making
multiple queries.


# -------------------------------------------------------------
Why
# -------------------------------------------------------------
The regular Shotgun API can be slow when initializing a Shotgun object. It
can add anywhere from .5 to 5 seconds onto the startup time. This is just
because it needs to go communicate down to wherever the server is being
hosted and go through some certification. Once connected, however,
talking to the database can be quite fast. This can cause an annoyance
for tools that simply need to connect to grab one piece of data and then
disconnect. Think along the lines of setting a shot's frame range upon
opening a Maya file or Nuke script.


# -------------------------------------------------------------
Usage
# -------------------------------------------------------------
Add the folder doubleBarrel/doubleBarrel to your Python's site-packages,
then import the DoubleBarrelServer object and DoubleBarrel object as
follows:

    from doubleBarrel import DoubleBarrel, DoubleBarrelServer

DoubleBarrel can be used the same as the regular Shotgun API. In this
version of the plugin, no host and port need to be provided as they are
dynamically generated based on your local machine and the API key
you provide to connect to Shotgun.

DoubleBarrel objects will still work without a DoubleBarrelServer running,
but you will not get the speed enhancements you see above. To see the
speed improvements, you must first start a DoubleBarrelServer. You start
a DoubleBarrelServer by creating an instance (the same as you would create
a Shotgun or DoubleBarrel instance) and then call it's .run() method.

You can provide host and port keyword arguments when creating an 
instance of either the DoubleBarrel or DoubleBarrelServer objects, if you
would like to override the machine and port that is being dynamically
generated.

In addition to being created the same as a regular Shotgun API object, you
can also define a .sg file containing your login credentials and provide it as
the main argument instead. See tests/serverTest.py, tests/wrapperTest.py
and tests/myShotgunScript.sg for details.

For a quick example of the wrapper, please go to the tests folder included,
include your Shotgun details in the myShotgunScript.sg file and then
run the serverTest.py file. Leaving serverTest.py running, then run
wrapperTest.py. You will see serverTest.py being polled and your test
results will be displayed in wrapperTest.py. 


# -------------------------------------------------------------
History
# -------------------------------------------------------------
v2.0 - August 18th
    - Added automatic host and port generation feature.
    - Partially completed GUI for a manager/monitor. Figured this would be
    a good addition since this is a daemon tool. The GUI is almost completed,
    but I have been hard pressed to find time to do so. Didn't want an
    incomplete GUi to prevent me from releasing a new version.
    - Added new feature to create a DoubleBarrel instance using a .sg file
    rather than having to pass the arguments directly.
    
v1.0 - May 28th
    - Released the initial version on GitHub.

    
# -------------------------------------------------------------
Future
# -------------------------------------------------------------
- There are plans to add a GUI to make this work better running on local
workstations. The server script needs to be left running continuously, and
this makes things a bit sloppy when the server script is running locally.
There must always be a shell running. The plan is to have this run as a GUI
that is then dockable to the system tray and continue to run in the
background. The GUI will also allow the user to add sg files to be run when
the script is started, starting however many servers there are in the file.
- When providing a Shotgun script to the manager (what the GUI would
be controlling) with the name "DoubleBarrel" it would query Shotgun for
all of the scripts available and just start servers for all of them.