omni.graph: OmniGraph Python Scripting
##############################################

While the core part of OmniGraph is built in C++ there are Python bindings and scripts built on top of it to make
it easier to work with.

Importing
---------

The Python interface is exposed in a consistent way so that you can easily find any of the OmniGraph scripting
information. Any script can start with this simple import, in the spirit of how popular packages such as `numpy`
and `pandas` work:

.. code-block:: python

    import omni.graph.core as og

Using this module you can access internal documentation through the usual Python mechanisms:

.. code-block:: python

    help(og)
    dir(og)

Bindings
--------

The first level of support is the :doc:`Python Bindings<../bindings/README>` which provide a wrapper on top of the
C++ ABI of the OmniGraph core. These have been made available from the same import to make user of all OmniGraph
functionality consistent. When you are programming in Python you really don't need to be aware of the C++
underpinnings.

The bound functions have all of the same documentation available at runtime so they can be inspected in the same way
you would work with any regular Pythyon scripts. For the most part the bindings follow the C++ ABI closely, with the
minor exception of using the standard PEP8 naming conventions rather than the established C++ naming conventions.

For example a C++ ABI function `getAttributeType` will be named `get_attribute_type` in the Python binding. This was
primarily done to deemphasize the boundary between Python and C++ so that Python writers can stick with Python
conventions and C++ writers can stick with C++ conventions.

As the Python world doesn't have the C++ concept of an interface definition there is no separation between the
objects providing the functionality and the objects storing the implementation and data. For example in C++ you
would have an `AttributeObj` which contains a handle to the internal data and a reference to the `IAttribute`
interface definition. In Python you only have the `og.Attribute` object which encapsulates both.

You can see the online version of the Python documentation at :ref:`omnigraph_python_api`.


The One Thing You Need
----------------------

A lot of the imported submodules and functions available are used internally by generated code and you won't have
much occasion to use them. You can explore the internal documentation to see if any look useful to you. The naming
was intentionally made verbose so that it's easier to discover functionality.

.. _ogn_omnigraph_controller:

One class deserves special attention though, as it is quite useful for interacting with the OmniGraph.

.. code-block:: python

    import omni.graph.core as og
    controller = og.Controller()

The `Controller` class provides functionality for you to change the graph topology, or modify and inspect
values within the graph.

.. literalinclude:: ../python/_impl/controller.py
    :language: python
    :start-after: begin-controller-docs
    :end-before: end-controller-docs

See the internal documentation at :py:class:`omni.graph.core.Controller` for details, or take a tour of how to use
the controller with :ref:`this how-to documentation<howto_omnigraph_controller>`

.. toctree::
    :maxdepth: 1
    :caption: Contents

    OmniGraph Commands <commands>
    How-To Guides<../../omni.graph.core/docs/how_to.rst>
    Python API <python_api>
    ../bindings/README
    autonode
    CHANGELOG
    How previous versions are deprecated <../../omni.graph.tools/docs/deprecation.rst>