shotgunsoftware / cplusplus-api Goto Github PK

Shotgun C++ / Python API

http://github.com/shotgunsoftware/cplusplus-api



Background
----------

    Tippett Studio has been using Shotgun in production for several years. 
During that time, we've developed a number of tools and processes that work with
data in Shotgun, almost all of which are written in Python.  

We wanted an object-oriented framework for adding "business logic" to Shotgun. 
That is, we wanted to work with Shotgun's entities in an object-oriented
fashion, and extend them by adding useful behavior that was meaningful to 
our shop.  From this desire, an extensive Python library grew.  

Thought it was a very successful first-gen API, unfortunately, there wasn't a
good separation between the object/entity interface, and a lot of
Tippett-specific attributes and behavior crept into our original API.  It didn't
provide a C++ interface either.

This library is a ground-up rewrite, with the following design goals:

    - C++ core and a thin Python wrapper, possible to extend to other languages.

    - Clean separation between the object/entity representation and any
      business logic.

    - Easy to use.  Don't expose the underlying transport.  Users don't need
      to know about the underlying xmlrpc transport.

    - Easy to extend.  Using this library as a core, studios can derive
      site-specific classes to add business logic and manage dynamic
      attributes.


Directory hierarchy
-------------------

  * Source code and "Makefile.am" are omitted:

        |-- AUTHORS
        |-- COPYING
        |-- ChangeLog
        |-- INSTALL
        |-- Makefile.am
        |-- NEWS
        |-- README
        |-- TODO
        |-- bootstrap                   // Autoconf script that generates the configure file
        |-- configure.ac
        |-- lib                         // Cplusplus lib source
        |   `-- Shotgun
        |       |-- *.cpp
        |       `-- *.h
        |-- test                        // Cplusplus lib tests
        |   `-- *.cpp
        |-- plugins
        |   `-- python
        |       |-- configure.py        // SIP configuration script used to generate SIP .cpp source
        |       |-- shotgun.py          // Python wrapper module that strips off namespaces
        |       |-- sip                 // SIP source
        |       |   |-- *.sip
        |       |   `-- _shotgun.sip
        |       `-- test                // Python module tests
        |           `-- *.py
        |-- doc                         // Where the Doxygen configuration file and the generated HTML files live
        |   `-- config.dox
        `-- example                     // Example source code on how to derive a site-specific Shotgun library


Building
--------

  * The only dependency is the xmlrpc-c library, available at
    http://xmlrpc-c.sourceforge.net/  Make sure the xmlrpc-c-config binary is in
    your path so configure can find it.

  * Run "bootstrap" first to generate a "configure" file

  * configure

      --with-default-url
      Specify a URL to use by default when creating a Shotgun instance (you can
      always override it at runtime).  If you don't give it a default URL, 'make
      check' skips the tests, but you can still run them manually with a URL on
      the command line.

      --with-authenticate-name
      Specify an authentication "script_name" when transfering Shotgun data. It
      corresponds to "Script Name" on Shotgun's [Admin] > [Scripts] page. It is
      recommended that the default value is set when building the library. If not, 
      it can be set within the end-user application when the Shotgun class object 
      is instantiated.

      --with-authenticate-key
      Specify an authentication "script_key" when transfering Shotgun data. It
      corresponds to "Application Key" on Shotgun's [Admin] > [Scripts] page. 
      It is recommended that the default value is set when building the library. 
      If not, it can be set within the end-user application when the Shotgun class 
      object is instantiated.

      --enable-python
      Turning this on will also build the sip-based Python interface.  

      --with-pic --disable-shared
      These flags are recommended for building the sip-based Python module. 
      Linking against the dynamic C++ lib will cause Python not be able to catch 
      the exceptions that are defined in C++ API.

  * make 

  * make install


Examples
--------

  * The /example/ directory contains sample source code on how to derive a 
    site-specific Shotgun library from the main library. The structure in
    this directory mirrors the one in the main library. Here is a hierarchical
    representation of the directory (source code and "Makefile.am" are omitted):

        example
        |-- lib
        |   `-- SiteShotgun                 // Site-specific cplusplus lib source
        |       |-- *.cpp
        |       `-- *.h
        |-- test                            // Site-specific cplusplus lib tests
        |   `-- *.cpp
        `-- plugins
            `-- python
                |-- siteconfigure.py        // Site-specific SIP configuration script used to generate SIP .cpp source
                |-- siteshotgun.py          // Site-specific Python wrapper module that strips off namespaces
                |-- sip                     // Site-specific SIP source
                |   |-- *.sip
                |   `-- _siteshotgun.sip
                `-- test                    // Site-specific Python module tests
                    `-- *.py


Testing
-------

  * Make sure to include the paths of the sip-based Python modules to PYTHONPATH
    before doing any Python tests.

      - $(TOP_DIR)/plugins/python/          (shotgun module)
      - $(TOP_DIR)/example/plugins/python   (siteshotgun module)

  * make check - To check on the test programs