1 files changed, 147 insertions, 0 deletions
diff --git a/docs/developers/bindings/PythonAPI.rst b/docs/developers/bindings/PythonAPI.rst
new file mode 100644
index 0000000..839e9d2
--- /dev/null
+++ b/docs/developers/bindings/PythonAPI.rst
@@ -0,0 +1,147 @@
+##########
+Python API
+##########
+
+Description
+===========
+
+A color configuration (:py:class:`Config`) defines all the color spaces to be
+available at runtime.
+
+(:py:class:`Config`)  is the main object for interacting with this library. 
+It encapsulates all the information necessary to use customized
+:py:class:`PyOpenColorIO.ColorSpaceTransform` and
+:py:class:`PyOpenColorIO.DisplayTransform` operations.
+
+See the :ref:`user-guide` for more information on selecting, creating, 
+and working with custom color configurations.
+
+For applications interested in using only one color configuration at
+a time (this is the vast majority of apps), their API would
+traditionally get the global configuration and use that, as
+opposed to creating a new one. This simplifies the use case
+for plugins and bindings, as it alleviates the need to pass
+around configuration handles.
+
+An example of an application where this would not be
+sufficient would be a multi-threaded image proxy server
+(daemon) that wants to handle multiple show configurations
+concurrently in a single process. This app would need to keep
+multiple configurations alive, and manage them appropriately.
+
+Roughly speaking, a novice user should select a default
+configuration that most closely approximates the use case
+(animation, visual effects, etc.), and set the :envvar:`OCIO`
+environment variable to point at the root of that configuration.
+
+.. note::
+   Initialization using environment variables is typically preferable
+   in a multi-app ecosystem, as it allows all applications to be consistently configured.
+
+.. note::
+   Paths to LUTs can be relative. The search paths are defined in :py:class:`Config`.
+
+See :ref:`developers-usageexamples`
+
+Examples of Use
+---------------
+
+.. code-block:: python
+
+    import PyOpenColorIO as OCIO
+    
+    # Load an existing configuration from the environment.
+    # The resulting configuration is read-only. If $OCIO is set, it will use that.
+    # Otherwise it will use an internal default.
+    config = OCIO.GetCurrentConfig()
+    
+    # What color spaces exist?
+    colorSpaceNames = [ cs.getName() for cs in config.getColorSpaces() ]
+    
+    # Given a string, can we parse a color space name from it?
+    inputString = 'myname_linear.exr'
+    colorSpaceName = config.parseColorSpaceFromString(inputString)
+    if colorSpaceName:
+        print 'Found color space', colorSpaceName
+    else:
+        print 'Could not get color space from string', inputString
+    
+    # What is the name of scene-linear in the configuration?
+    colorSpace = config.getColorSpace(OCIO.Constants.ROLE_SCENE_LINEAR)
+    if colorSpace:
+        print colorSpace.getName()
+    else:
+        print 'The role of scene-linear is not defined in the configuration'
+    
+    # For examples of how to actually perform the color transform math,
+    # see 'Python: Processor' docs.
+    
+    # Create a new, empty, editable configuration
+    config = OCIO.Config()
+    
+    # Create a new color space, and add it
+    cs = OCIO.ColorSpace(...)
+    # (See ColorSpace for details)
+    config.addColorSpace(cs)
+    
+    # For additional examples of config manipulation, see
+    # https://github.com/imageworks/OpenColorIO-Configs/blob/master/nuke-default/make.py
+
+Exceptions
+==========
+
+.. autoclass:: PyOpenColorIO.Exception
+    :members:
+    :undoc-members:
+
+.. autoclass:: PyOpenColorIO.ExceptionMissingFile
+    :members:
+    :undoc-members:
+
+Global
+======
+
+.. autofunction:: PyOpenColorIO.ClearAllCaches
+
+.. autofunction:: PyOpenColorIO.GetCurrentConfig
+
+.. autofunction:: PyOpenColorIO.GetLoggingLevel
+
+.. autofunction:: PyOpenColorIO.SetCurrentConfig
+
+.. autofunction:: PyOpenColorIO.SetLoggingLevel
+
+Config
+======
+
+.. autoclass:: PyOpenColorIO.Config
+    :members:
+    :undoc-members:
+
+ColorSpace
+==========
+
+.. autoclass:: PyOpenColorIO.ColorSpace
+    :members:
+    :undoc-members:
+
+Look
+====
+
+.. autoclass:: PyOpenColorIO.Look
+    :members:
+    :undoc-members:
+
+Processor
+=========
+
+.. autoclass:: PyOpenColorIO.Processor
+    :members:
+    :undoc-members:
+
+Context
+=======
+
+.. autoclass:: PyOpenColorIO.Context
+    :members:
+    :undoc-members: