Examples

Note

This section is a work-in-progress. Over time we will add flow diagrams for key operations that happen through the API, along with more extensive sample implementations for both hosts and managers. Currently it is limited to illustrating a few common operations that a host of the API may perform.

Warning

At this stage, until we ship a sample manager implementation, the code for later examples won't actually function.

Initializing the API in a Host

This example covers the steps required to initialize the API within a 'host' tool, script or application that wishes to interact with an Asset Management System.

It makes use of the Plugin System to discover available PythonPluginSystemManagerPlugins.

It also includes a bare-minimum example of a HostInterface implementation.

from openassetio.log import ConsoleLogger, SeverityFilter
from openassetio.hostApi import HostInterface, Manager, ManagerFactory
from openassetio.pluginSystem import PythonPluginSystemManagerImplementationFactory

class ExamplesHost(HostInterface):
    """
    A minimal host implementation.
    """
    def identifier(self):
        return "org.openassetio.examples"

    def displayName(self):
        return "OpenAssetIO Examples"

# For simplicity, use a filtered console logger, this logs to
# stderr based on the value of OPENASSETIO_LOGGING_SEVERITY.
# Practically you may wish to provide a bridge to your own logging
# mechanism if you have one.
logger = SeverityFilter(ConsoleLogger())

# We need to provide the mechanism by which managers are created, the
# built-in plugin system allows these to be loaded from
# OPENASSETIO_PLUGIN_PATH.
factory_impl = PythonPluginSystemManagerImplementationFactory(logger)

# We then need our implementation of the HostInterface class
host_interface = ExamplesHost()

# We can now create an OpenAssetIO ManagerFactory. The ManagerFactory
# allows us to query the available managers, and pick one to talk to.
managerFactory = ManagerFactory(host_interface, factory_impl, logger)

Setting up a Manager

This example makes use of the newly initialized factory to show how to construct and configure a specific manager (it assumes that some example Asset Management System has a plugin, installed on $OPENASSETIO_PLUGIN_PATH).

We will be providing an example manager implementation soon!

availableManagers = managerFactory.availableManagers()
> {
>    'org.openassetio.example.manager':
>         ManagerFactory.ManagerDetail(
>             identifier='org.openassetio.example.manager',
>             displayName='Example Asset Manager',
>             info={})
>    }
> }

# Once we know which manager we wish to use, we can ask the factory
# to create one for us.
manager = managerFactory.createManager('org.openassetio.example.manager')

# We now have an instance of the requested manager, but it is not
# quite ready for use yet. The manager returned by the
# ManagerFactory needs to be initialized before it can be used to
# query or publish assets. Setup is split into two stages to allow
# adjustments to its settings to be made prior to use if required.

# A manager's current (or in this case default) settings can be
# queried if needed:
settings = manager.settings()
# ...and updated with new values as desired.
settings["server"] = "my.server.com"

# Finally, we can initialize the manager with the desired settings,
# preparing it for use. Note that this may include non-trivial
# amounts of work. Settings updates are sparse, so if you don't have
# any custom settings, you can pass an empty dictionary here.
manager.initialize(settings)

To make it easier to deploy a range of OpenAssetIO enabled hosts, the API supports a simple file-based configuration mechanism. Users set the $OPENASSETIO_DEFAULT_CONFIG environment variable to point to a suitable TOML file, which contains their preferred manager identifier and settings. As a Host, you can use the defaultManagerForInterface method instead of creating your own ManagerFactory. This will return a fully initialized manager using this configuration if set:

manager = ManagerFactory.defaultManagerForInterface(
             host_interface, impl_factory, logger)

Resolving a Reference

This example shows how to use the instantiated manager to resolve a string (some_string) that is assumed to be an entity reference to an entity with the LocatableContent Trait (from the MediaCreation package) covering use of the correct context.

Note

The caller must convert a string to an EntityReference object in order to use any OpenAssetIO API that expects an Entity Reference. There is more than one approach to this. Below we rely on the exception thrown by createEntityReference when given an invalid reference. Alternatively, we could use createEntityReferenceIfValid and test if the result is falsey.

Ensuring that an entity reference is valid before handing it to the manager reduces the validation overhead in the manager's implementation of the API. This affords significant gains in real-world production use cases where thousands of references may be operated upon in time-critical scenarios.

The API middleware provides assorted short-circuit validation optimisations that can reduce the number of inter-language hops required. See ManagerInterface.info and the kInfoKey_EntityReferencesMatchPrefix key.

from openassetio.access import ResolveAccess
from openassetio_mediacreation.traits.content import LocatableContentTrait

# Note: this will raise an exception if given a string that is not
# recognized by this manager as a valid entity reference (ValueError
# in Python, std::domain_error in C++). Consider
# createEntityReferenceIfValid, if unsure of the string.
entity_reference = manager.createEntityReference(some_string)

# All calls to the manager must have a Context, these should always
# be created by the target manager. The Context ensures that any
# manager state is properly managed between API calls.
context = manager.createContext()

# We can now resolve a token we may have if it is a reference. In
# this example, we'll attempt to resolve the LocatableContent trait
# for the entity. We inform the manager that we just want to read the
# current data for the entity (kRead). See the publishing examples
# for use of the alternative `kWrite` access mode.

# First check that the manager has implemented resolution capability.
if not manager.hasCapability(Manager.Capability.kResolution):
  return

resolved_asset = manager.resolve(
        entity_reference, {LocatableContentTrait.kId},
        ResolveAccess.kRead, context)
url = LocatableContentTrait(resolved_asset).getLocation()  # May be None

Inspecting a reference

This example shows how an entity reference of unknown provenance can be inspected to determine the qualities of the entity it points to.

Let's say we're an audio application written in Qt, and someone has just dragged and dropped a line of text into the application. We want to know if the text is an entity reference, and if so, does it point to an audio clip.

from openassetio.access import EntityTraitsAccess
from openassetio_mediacreation.traits.content import LocatableContentTrait
from openassetio_mediacreation.specifications.audio import SampledAudioResource

class MyAudioApp(QMainWindow):

  def __init__(self, manager):
    super().__init__()
    self.__manager = manager
    self.__context = manager.createContext()
    self.setAcceptDrops(True)
    # [... Other Qt setup]

  def dragEnterEvent(self, event):
    if event.mimeData().hasUrls():
      event.acceptProposedAction()

  def dropEvent(self, event):
    if not event.mimeData().hasUrls():
      return
    uri = event.mimeData().urls().first().toString()
    ref = self.__manager.createEntityReferenceIfValid(uri)
    if ref is None:
      return

    entity_trait_set = self.__manager.entityTraits(
      ref, EntityTraitsAccess.kRead, self.__context)

    # Ignore this drop if the entity is not of the correct type for
    # this application.
    if not SampledAudioResource.kTraitSet <= entity_trait_set
      return

    resolved_asset = manager.resolve(
       entity_reference, {LocatableContentTrait.kId},
       ResolveAccess.kRead, context)
    url = LocatableContentTrait(resolved_asset).getLocation()

    self.load_audio_from_url(url)

 # [... Other application setup]

Discovering capability

In the previous example, we saw how to resolve a specific trait for an entity. In a real-world scenario, it is important to remember that:

• Managers may not support a particular workflow at all.
• Managers may not handle certain types of entity (determined by their Trait Set).
• Managers may not be able to provide data for all traits.

Capabilities

The hasCapability method allows a host to determine which workflows that a manager has implemented.

This is achieved by grouping sets of methods potentially implemented by the manager into "capabilities". These capabilities are defined in Capability.

Calling a method not implemented by the manager will result in an exception. Therefore hosts should check hasCapability before calling into any of these optional methods. The return value of hasCapability is runtime invariant, post-initialize, therefore the check only needs to be made once per manager.

Policy

The managementPolicy method allows a host to query a manager's behaviours and intentions towards different types of entity.

This method should be used wherever possible to adapt the host's behaviour so that:

• The manager is not invoked in relation to unsupported entity types.
• User workflows are appropriate to the supported behaviour for a given entity type.

Failing to check the policy leaves a host vulnerable to recieving empty, null or invalid data by making queries outside of the managers realm of understanding.

Example

This example demonstrates how to query a manager in relation to a specific entity type - in this case a simple text file, and inspect its capabilities and the data it may be able to resolve for it.

from openassetio.access import PolicyAccess

# Commented imports are illustrative and may not exist yet
from openassetio_mediacreation.traits.managementPolicy import (
    ManagedTrait,
)
from openassetio_mediacreation.traits.content import (
    LocatableContentTrait, # TextEncodingTrait
)
from openassetio_mediacreation.specifications.files import (
    # TextFileSpecification
)

# Ensure that the manager is capable of the resolution workflow.
if not manager.hasCapability(Manager.Capability.kResolution):
  return

# We use the well-known specification for a text file to determine
# the correct trait set to query. Using the standard definition
# ensures consistent behaviour across managers/hosts. We request
# the manager's policy for read access to this entity type.
[policy] = manager.managementPolicy(
 [TextFileSpecification.kTraitSet], PolicyAccess.kRead, context)

# We can now check which traits were imbued in the policy, the
# absence of a trait means it is unsupported.

if not ManagedTrait.isImbuedTo(policy):
  # The manager doesn't want to handle text files, we should not
  # attempt to resolve/publish this type of entity.
  return

# As well as policy-specific traits, the result will be imbued with
# traits from the queried trait set that the manager is capable of
# providing data for. If you have additional host-specific traits,
# you can append these to the ones from the relevant specification.
# Here we check for support for the specific text file traits we are
# interested in using.

if LocatableContentTrait.isImbuedTo(policy):
  print("The manager can provide the URL for the file")

if TextEncodingTrait.isImbuedTo(policy):
  print("The manager can provide the text encoding used")

Publishing a File

This example demonstrates how an API host should involve the manager in the creation of new data. In this case, a simple text file.

from openassetio.access import (
    PolicyAccess, ResolveAccess, PublishingAccess)
# Commented imports are illustrative and may not exist yet
from openassetio_mediacreation.traits.managementPolicy import ManagedTrait
from openassetio_mediacreation.specifications.files import (
    # TextFileSpecification
)

# Ensure that the manager supports publishing.
if not manager.hasCapability(Manager.Capability.kPublishing):
  return

# As ever, an appropriately configured context is required
context = manager.createContext()

# The first step is to see if the manager wants to manage text files.
# Note that this time we request the manager's policy for write
# access.
[policy] = manager.managementPolicy(
    [TextFileSpecification.kTraitSet], PolicyAccess.kWrite, context)

if not ManagedTrait.isImbuedTo(policy):
  # The manager doesn't care about this type of asset
  return

# Managers may want to dictate to the host some of the data to be
# published, e.g. tell us where to put files. So we ask the manager
# which traits, if any, it is interested in "driving" itself.
[manager_driven_policy] = manager.managementPolicy(
    [TextFileSpecification.kTraitSet], PolicyAccess.kManagerDriven, context)

# Choose some defaults in case the manager cannot drive these values.
save_path = os.path.join(os.path.expanduser('~'), 'greeting.txt')
encoding = "utf-8"

# Whenever we make new data, we always tell the manager first,
# This allows it to create a placeholder version or similar.
# We must provide the manager with any relevant information that the
# host owns (i.e. won't be queried from the manager during
# publishing) and can be provided up-front.
file_spec = TextFileSpecification.create()
file_spec.markupTrait().setMarkupType("plain")

# Our intent is to write data to this entity, not to create a new
# related entity (kCreateRelated), so we use the kWrite access mode.
# NOTE: It is critical to always use the working_ref from now on.
working_ref = manager.preflight(
   entity_ref, file_spec, PublishingAccess.kWrite, context)

# If the manager wants to drive at least one of the traits we're
# publishing, we can `resolve` with the `kManagerDriven` access mode
# to retrieve the values the manager wants us to use. If we attempt
# to `resolve` without checking the policy first, we risk an error if
# the manager does not support this operation.
if (LocatableContentTrait.isImbuedTo(manager_driven_policy) or
      TextEncodingTrait.isImbuedTo(manager_driven_policy)):
  working_data = manager.resolve(
          working_ref,
          {LocatableContentTrait.kId, TextEncodingTrait.kId},
          ResolveAccess.kManagerDriven, context)
  if save_url := LocatableContentTrait(working_data).getLocation():
    # Assume `file://` URL
    save_path = utils.pathFromUrl(save_url)
  encoding = TextEncodingTrait(working_data).getEncoding(defaultValue=encoding):

# Now we can write the file
with open(save_path, 'w', encoding=encoding) as f:
   f.write("Hello from the documentation example\n")

# Prepare the entity specification to register, with the data about
# where we actually wrote the data to, and with what encoding.
file_spec.locatableContentTrait().setLocation(pathToURL(save_path))
file_spec.textEncodingTrait().setEncoding(encoding)

# Now the data has been written, we register the file and the publish
# is complete.
final_ref = manager.register(working_ref, file_spec.traitsData(),
    PublishAccess.kWrite, context)

# Keep this around for later, in case it is useful
with open(os.path.join(os.path.expanduser('~'), 'history', 'a') as f:
    f.write(f"{final_ref}\n")

Generating a Thumbnail During Publish

This example demonstrates the correct handling in a host of a hypothetical WantsThumbnail trait if set by a manager in its managementPolicy response.

It follows on from the preceding publishing example.

Note

This example uses imaginary, illustrative traits and specifications that are yet to be finalized.

# Ensure that the manager supports publishing.
if not manager.hasCapability(Manager.Capability.kPublishing):
  return

# See if the manager wants a thumbnail
if not WantsThumbnailTrait.isImbuedTo(policy):
  return

# Preflight the thumbnail spec's traits with the target entity's
# reference, this gives us a reference we can now use for all
# interactions relating to the thumbnail itself.
thumbnail_ref = manager.preflight(
        final_ref, ThumbnailFileSpecification.kTraitSet,
        PublishAccess.kCreateRelated, context)

thumbnail_path = os.path.join(os.path.expanduser('~'), 'greeting.preview.png')
thumbnail_attr = {"width": 128, "height": 128}

# See if the manager can tell us where to put it, and what it should be like
if (LocatableContentTrait.isImbuedTo(manager_driven_policy) or
      RasterTrait.isImbuedTo(manager_driven_policy)):
  requested = manager.resolve(
          thumbnail_ref,
          {LocatableContentTrait.kId, RasterTrait.kId},
          ResolveAccess.kManagerDriven, context)
  if requested_path := LocatableContentTrait(requested).getLocation():
    thumbnail_path = utils.pathFromURL(requested_path)
  raster_trait = RasterTrait(requested)
  if raster_trait.isImbued():
    # 'get' calls can take a default value to avoid `None` if missing.
    thumbnail_attr["width"] = raster_trait.getWidth(thumbnail_attr["width"])
    thumbnail_attr["height"] = raster_trait.getHeight(thumbnail_attr["height"])

# Generate a thumbnail using the supplied criteria
mk_thumbnail(thumbnail_path, thumbnail_attr["width"], thumbnail_attr["height"])

# Register the thumbnail to the thumbnail ref (not the entity),
# configuring the context to say we're going to ignore the final ref

thumbail_spec = ThumbnailFileSpecification.create()
thumbnail_spec.fileTrait().setPath(thumbnail_path)
raster_trait = thumbnail_spec.rasterTrait()
raster_trait.setWidth(thumbnail_attr["width"])
raster_trait.setHeight(thumbnail_attr["height"])

manager.register(
    thumbnail_ref, thumbnail_spec.traitsData(),
    PublishAccess.kWrite, context)