OmniGraph Tools Python API Documentation

Tools that support all of OmniGraph in general, and the .ogn format in particular.

General tools can be imported directly with the top level import:

import omni.graph.tools as ogt
help(ogt.deprecated_function)

This module also supports a submodule just for the .ogn handling.

# Support for the parsing and creation of the .ogn format
import omni.graph.tools.ogn as ogn

class omni.graph.tools.DeprecateMessage

Manager for deprecation messages, to make it efficient to prevent multiple logging of the same deprecation messages.

The default settings for output is usually enough to help you find where deprecated code is referenced. If more information is desired these per-class variables can be set to reduce the filtering being done. The message should contains an action item for the user to upgrade from the deprecated functionality:

DeprecateMessage.deprecated("Install the latest version instead")

# Although it's not usually necessary the class can be tuned using these class variable

SILENCE_LOG = False  # When set the output does not go to the console log; useful to disable for testing
SHOW_STACK = True  # Report stack trace in the deprecation message - can be turned off if it is too verbose
MAX_STACK_LEVELS = 3  # Maximum number of stack levels to report, after filtering
RE_IGNORE = re.compile("deprecate.py|bindings-python|importlib")  # Ignore stack levels matching these patterns

You can use some Python features to handle simple deprecation cases directly such as:

# Rename constant from A to B
A = (DeprecateMessage("A has been renamed to B") and False) or B

# Constant A will be removed
A = (DeprecateMessage("A will be removed, use B instead) and False) or B

MAX_STACK_LEVELS = 3

MESSAGES_LOGGED = {}

class NoLogging(*args, **kwargs)

Context manager class to let you import a bunch of known deprecated functions without logging warnings. Typical use would be in providing backward compatibility in a module where submodules have moved.

with DeprecateMessage.NoLogging():

import .v1_0.my_old_function as my_old_function

RE_IGNORE = re.compile('deprecate.py|bindings-python|importlib')

SHOW_STACK = True

SILENCE_LOG = False

classmethod deprecated(message: str)

Log the deprecation message if it has not yet been logged, otherwise do nothing

Parameters

message – Message to display; only displays once even if this is called many times

Adds stack trace information if the class member SHOW_STACK is True. Skips the Carbonite logging if the class member SILENCE_LOG is True (mostly useful for testing when a warning is the expected result).

class omni.graph.tools.DeprecatedClass(deprecation_message: str)

Decorator to deprecate a class. Takes one argument that is a string to describe the action the user is to take to avoid the deprecated class. A deprecation message will be shown once, the first time the deprecated class is instantiated.

@DeprecatedClass("After version 1.5.0 use og.NewerClass instead")
class OlderClass:
    pass

message(deprecated_cls, deprecated_member: Optional[str] = None)

Emit a deprecation message with useful information attached

omni.graph.tools.DeprecatedImport(deprecation_message: str)

Decorator to deprecate a specific file or module import. Usually the functionality has been deprecated and moved to a different file.

Parameters

deprecation_message – String with the action the user is to perform to avoid the deprecated import

Usage:

'''This is the top line of the imported file'''
import omni.graph.tools as og
og.DeprecatedImport("Import 'omni.graph.tools as og' and use og.new_function() instead")

# The rest of the file can be left as-is for best backward compatibility, or import non-deprecated versions
# of objects from their new location to avoid duplication.

class omni.graph.tools.IndentedOutput(output: IO)

Helper class that provides output capabilities to messages with preserved indentation levels

Properties:

output: File type that receives the output indent_level: Number of indentation levels for the current output indent_string: String representing the current indentation level

exdent(message: Optional[str] = None)

Decrease the indentation level for emitted code

If a message is specified then emit that message immediately after exdenting, allowing you to easily close sections like: out.exdent(“}”)

indent(message: Optional[str] = None) → bool

Increase the indentation level for emitted code

If a message is specified then emit that message immediately before indenting, allowing you to easily open sections like: out.indent(“{“)

Returns True so that indented sections can be indented in the code:

if output.indent(“begin {“):

output.exdent(“})

prepend(message: str)

Write the message line at the beginning of the output.

This rewrites the entire output so it is best to minimize its use, and stick with string implementations. The message is written as-is with no newlines or indenting

write(message: Union[List, str] = '')

Output a single message line to the file. This assumes indentation will be used and a newline will be appended. Passing in a list will write each list member on its own line.

Parameters

message – Line of text being emitted

write_as_is(message: Union[List, str])

Output a string to the output file without indentation or added newline Passing in a list will write each list member on its own line.

Parameters

message – Line of text being emitted

omni.graph.tools.RenamedClass(cls, old_class_name: str, rename_message: Optional[str] = None) → object

Syntactic sugar to provide a class deprecation that is a simple renaming, where all of the functions in the old class are still present in backwards compatible form in the new class.

Parameters

• old_class_name – The name of the class that was renamed

• rename_message – If not None, what to use instead of the old class. If None then assume the new class is used.

Usage:

MyDeprecatedClass = RenamedClass(MyNewClass, "MyDeprecatedClass")

omni.graph.tools.deprecated_function(deprecation_message: str, is_property: bool = False)

Decorator to deprecate a function.

Parameters

• deprecation_message – A description of the action the user is to take to avoid the deprecated function.

• is_property – Set this True if the function is a property getter or setter.

A deprecation message will only be shown once, the first time the deprecated function is called.

@deprecated_function("After version 1.5.0 use og.newer_function() instead")
def older_function():
    pass

For property getters/setters use this decorator after the property decorator.

@property
@deprecated_function("use 'your_prop' instead.", is_property=True)
def my_prop(self):
    return self.your_prop

@my_prop.setter
@deprecated_function("use 'your_prop' instead.", is_property=True)
def my_prop(self, value):
    self.your_prop = value

omni.graph.tools.destroy_property(self, property_name: str)

Call the destroy method on a property and set it to None - helps with garbage collection

In a class’s destroy() or __del__ method you can call this to generically handle member destruction when such things do not happen automatically (e.g. when you cross into the C++-bindings, or the objects have circular references)

def destroy(self):

destroy_property(self, “_widget”)

If the property is a list then the list members are individually destroyed. If the property is a dictionary then the values of the dictionary are individually destroyed.

NOTE: Only call this if you are the ownder of the property, otherwise just set it to None.

Parameters

• self – The object owning the property to be destroyed (can be anything with a destroy() method)

• property_name – Name of the property to be destroyed

omni.graph.tools.function_trace(env_var=None)

Debugging decorator that adds function call tracing, potentially gated by an environment variable.

Use as a normal function decorator:

@function_trace()
def my_function(value: str) -> str:
    return value + value

Calling my_function(“X”) with debugging enabled will print this:

Calling my_function(‘X’)

‘my_function’ returned ‘XX’

The extra parameter lets you selectively disable it based on environment variables:

@function_trace("OGN_DEBUG")
def my_function(value: str) -> str:
    return value + value

This version only enables debugging if the environment variable “OGN_DEBUG” is set