v1.0.0-rc.2.0 promoted to v1.0.0 stable! 🎉

Improvements since v1.0.0-rc.2.0

• Split common C++ macros from typedefs.hpp into a separate zero-dependency macros.hpp header. #1437

This release may break source compatibility for Python and C++ hosts, see breaking changes section for more details.

Breaking changes

• Modified PythonPluginSystem.scan() method to search Python distribution entry point hooks as well as scan given paths. Added arguments to parametrise search path and entry point usage. This class is primarily an internal implementation detail, so the change will only break advanced downstream use-cases. #1445

• Modified signature of CppPluginSystem.scan() to accept more arguments to further parametrise search path usage. This class is primarily an internal implementation detail, so this change will only break advanced downstream use-cases. #1445

New features

• Added an experimental UI delegation API alongside the core manager API. This allows asset management systems to augment or replace portions of a host application's user interface. The UI delegation API has its own separate plugin system and namespace, and is entirely opt-in. #1445

• Added defaultEntityReference overloads for convenience, providing alternatives to the core callback-based workflow. Includes querying for a single result vs. a batch of results, and exception vs. result object workflows. #1170

Improvements

• Added a new constant kInfoKey_IsPython ("isPython"), and used in the Python HostInterface.info() base class implementation, allowing managers to detect if the host they're interacting with is written in Python. #1445

• Added operators and hash functions to the EntityReference type, in both C++ and Python, such that EntityReference objects can be used as keys in associative containers (e.g. dict/std::unordered_map). #573

• Added non-equality != operator to the TraitsData and ManagerDetail types in C++, providing feature parity with Python. #875

• Added bounds checking of array access to convenience methods that wrap batch-first callback-based signatures. This avoids some potential segfaults if a manager plugin calls a callback passing an invalid index argument. #1196

• Removed the requirement to define C++ destructors for classes inheriting from LoggerInterface and ManagerImplementationFactoryInterface. I.e. the destructors are no longer pure virtual. #1196

• Explicitly disabled unsafe special member functions for TraitsData and FileUrlPathConverter classes in C++. #1196

Bug fixes

• Added "raise from" behaviour in C++->Python exception translation, in case a Python exception is already active when the C++ exception occurs. #1419

This release breaks binary compatibility with C++ hosts and managers. It may break source compatibility for hosts and managers in both C++ and Python. See breaking changes section for more details.

Breaking changes

• Removed official support for Python 3.7 and 3.9. The minimum supported Python version is now Python 3.10. This includes PyPI packages. #1365 #1389

• Removed deprecated type aliases openassetio.TraitsData, openassetio.BatchElementError and openassetio.BatchElementException. Removed the deprecated explicit *BatchElementException exception subtypes under the top-level openassetio namespace. Removed the deprecated Python openassetio.exceptions module. Removed the deprecated kField_* constants. #1311

• Marked as "final" several C++ Python bindings of classes that do not support Python inheritance, such that an error will be encountered at import time if an attempt is made to inherit from them. #1357

• Updated the API contract to no longer require that managers throw an exception when an unrecognized setting is given during initialization. The openassetio.test.manager API Compliance test suite no longer asserts that this is the case. #1202

• Switched from std::unordered_set to std::set for trait sets (via TraitSet alias) in C++. This allows C++ std algorithm set operations to work. Python is unaffected. This is mostly a source-compatible change, provided the TraitSet alias is used in consuming code, and no unordered_set-specific API is used (e.g. reserve(...)). #1339

• Source values for BatchElementError error codes changed to an internally-namespaced enum rather than global macros. #1060

• Removed OPENASSETIO_GLIBCXX_USE_CXX11_ABI CMake build option. Builds will use the system default libstdc++ ABI, rather than defaulting to the old ABI. #1353

• Removed support for querying the "beta" version number of the library. #1401

New Features

• Added the Hybrid Plugin System via a HybridPluginSystemManagerImplementationFactory, allowing multiple plugin systems to be composed (i.e. Python and C++). As well as reducing host boilerplate, this also supports merging two (or more) plugins. API requests are routed to the plugin that advertises the associated capability for that API request. Performance-critical API methods can then be coded in C++, whilst other methods are coded in more developer-friendly Python. #1202

• Added SimpleCppManager - a minimal C++ manager and plugin example implementation, useful for testing C++ plugin support in hosts. This has minimal API support, so Basic Asset Library (BAL) should still be preferred as a test manager when Python is available. #1324

• For Windows users, added OPENASSETIO_DLL_PATH environment variable to allow non-standard Python installations to locate openassetio.dll, if required. #1340

• Added kAuthError to the set of possible BatchElementError error codes. #1009

Improvements

• Added singular overload of managementPolicy for convenience. #856

• Updated the simpleResolver example host to support C++ plugins. #1324

• Added a type hint for the Manager instance injected into the openassetio.test.manager API Compliance test harness, to aid in IDE code completion when writing test cases for manager plugins.

• importlib_metadata is no longer a dependency for Python manager plugins to make use of Python entry point hooks. #1389

Bug fixes

• Modified OpenAssetIO Python distributions (e.g. installed with pip install) to allow C++ plugins to load. OpenAssetIO is now bundled as multiple shared libraries, allowing external libraries to link. #1340

• Fixed Python wheel builds to use the new libstdc++ ABI, reflecting their associated VFX Reference Platform version. #1352

• Fixed the (Python-only) terminology.Mapper class such that its terminology dict can be updated by the manager. #1356

This release introduces new features, and remains source compatible.

The addition of a new virtual method, LoggerInterface.isSeverityLogged, makes this release a binary incompatibility.

New Features

• Added a C++ plugin system. In particular, hosts can use the CppPluginSystemManagerImplementationFactory class (as a drop-in replacement for PythonPluginSystemManagerImplementationFactory) in order to load C++ manager plugins. Manager plugin authors provide a shared library that exposes an openassetioPlugin function that returns a PluginFactory function pointer, which in turn returns a CppPluginSystemManagerPlugin object. #1115

• openassetio.test.manager, notably used for Api Compliance tests, updated to automatically load C++ plugins if a python plugin of the requested identifier cannot be found. #1294

• Added LoggerInterface.isSeverityLogged to allow users to short-circuit log message construction if the logger indicates the intended severity will be filtered. Updated SeverityFilter to use the most pessimistic of its own severity and that of the wrapped logger. #1014

• Added utils.substitute providing a common string substitution format using named placeholders in libfmt/Python format string style syntax. #1213

Improvements

• Added getRelationship(s) and entityExists overloads for convenience, providing alternatives to the core callback-based workflow. Includes more direct methods for singular queries, as well as exception vs. result object workflows. #973 #1169

• Added .pyi stub files to the Python package to aid IDE code completion for Python bindings of C++ types. #1252

Deprecated

• Deprecated top level plugin variable for python plugins in favour of openassetioPlugin, in order to reduce risk of conflict with other plugin systems, and maintain consistency with the C++ plugin system. #1290

Improvements

• Updated FileUrlPathConverter.pathFromUrl to automatically convert long Windows paths, which exceed the Windows MAX_PATH limit, to UNC non-normalised device paths (i.e. \\?\-prefixed). #1257

• Added entityTraits overloads for convenience, providing alternatives to the core callback-based workflow. Includes a more direct method for resolving a single entity reference, and exception vs. result object workflows. #1217

Breaking changes

• Added new required core API method Manager/ManagerInterface.entityTraits, which can be used to determine the traits that an existing entity has, or that a new entity must have, for a given entity reference. #31

• Renamed access policy for resolving future entities, ResolveAccess.kWrite to ResolveAccess.kManagerDriven. This is then consistent with the newly added managementPolicy access mode. #1209

• Access policy keyword argument names in the Python bindings for ManagerInterface has changed to "resolveAccess" for resolve and "policyAccess" for managementPolicy, in order to conform to the corresponding C++ argument names.

New Features

• Added convenience utils.FileUrlPathConverter utility class for converting file:// URLs to and from paths. Both POSIX and Windows paths (including UNC) are supported in a platform-agnostic way (i.e. Windows paths can be processed on POSIX hosts and vice versa). #1117

• Propagate OpenAssetIOException-derived Python exceptions as a corresponding C++ exception if a Python method implementation raises when transparently called from C++. #947

• Add version accessor methods to allow runtime introspection of OpenAssetIO library version. version.h header distributed with install to allow compile time introspection. #1173

• Add managementPolicy support for querying traits whose required properties must be set in order for a publish to succeed, via a kRequired access mode; and support for querying traits whose properties the manager wishes to dictate when publishing, via a kManagerDriven access mode. #1209

Improvements

• Added the string representation of an EntityReference when repr'd in Python. #1186

• Added basic string representation of a TraitsData when repr'd in Python. #1209

Bug fixes

• Throw an exception when attempting to copy-construct a null TraitsData. #1153

• Modified no-argument constructor of Context to create an empty (but non-null) locale. #1153

Deprecated

Note
The following deprecated code paths are still available in this release, but will be removed in a future version.

• Moved TraitsData into the trait namespace along with its peer container/type definitions. #1127

• Removed python exceptions module in favour of new errors module. #1071

• Moved BatchElementError and BatchElementException into the errors namespace. #1071 #1073

• Removed all subtypes of BatchElementException, in favour of a single exception type for batch errors raised by the exception throwing convenience overloads. #1073

Breaking changes

• Updated ManagerInterface to reflect which methods are required and which are optional, default method implementations have been updated:

  • Pre-initialization methods are a no-op or return empty data.
  • Post-initialization methods raise a NotImplementedException.

  Note that in order to support multi-language plugins, pure virtual/ABC is not used to denote required methods in all cases. See the class API documentation for more details. #163

• Added the (required) Manager/ManagerInterface hasCapability method. A mechanism to query which particular capabilities a manager implements. This allows a Host to avoid NotImplementedExceptions when a specific capability has not been implemented by any given manager. #DR022, #1113

• Removed non-paged versions of the Manager/ManagerInterface relationship query methods and renamed the paged methods to remove the Paged suffix. PagedRelationshipSuccessCallback has been renamed to RelationshipQuerySuccessCallback to better reflect the default of pagination, and reduce ambiguity when relationship creation methods are added in the future. #1125

• Attempting to retrieve a trait property with TraitsData.getTraitProperty or using trait view classes no longer raises an exception if the trait itself is missing. This simplifies many common access patterns, and can remove the need for hasTrait/isImbuedTo checks. #970

• Added fmt as a new header-only private dependency. #1070

• Removed const from the majority of interface methods to allow implementations to make use of private state for efficiency reasons. #518

• errors.h renamed to errors/errorCodes.h #1073

• Removed the "Sample Asset Manager" example, which was wholly out of date, and has been superseded by the standalone manager template repository.

• Changed success/return type of defaultEntityReference to wrap in std::optional. Updated expected manager response such that an optional without a value signals that no default is available for an otherwise valid query. Changed default implementation to respond with an empty optional in the success callback, rather than error. #1100

• The middleware will validate that the manager's implementation provides the kEntityReferenceIdentification and kManagementPolicyQuery capabilities upon initialization. #1148

New Features

• Added new exception types, allowing all OpenAssetIO exceptions to share a common base. #1071

• Exceptional conveniences now provide additional information such as entityReference, index, access, and error type in the message of the exception. #1073

Improvements

• Modified Python bindings for all non-trivial methods such that they release the GIL before calling any underlying C++ implementation. #554

• Improved error messaging when defaultManagerForInterface points to a directory not a file.

• Added some protection for accidental overwrites of a CMake installed openassetio Python package, by installing a .dist-info metadata directory alongside the package. pip install will then fail/warn against accidental overwrites/overrides. Added a CMake variable OPENASSETIO_ENABLE_PYTHON_INSTALL_DIST_INFO to disable this feature. #1088

• Manager.createContext does not call ManagerInterface.createState if manager is not capable of kStatefulContexts, in which case the Context is returned without a managerState. #163

• Removed the unused PythonPluginSystemManagerPlugin.uiDelegate method, along with associated UI related documentation that referenced non-existent functionality. #1150

• Clarified ManagerInterface documentation around the relative "stateless" nature of the API and its reentrant design. #1143

Breaking changes

Warning

• Removed Context.Access and instead added per-workflow access mode enumerations under an access namespace. Added these enums as required arguments to various API functions, replacing the usage of Context.Access. #1054

• Changed signature of preflight to accept a TraitsData per reference, rather than a single trait set. The host is now expected to communicate any relevant information that it owns and is known at preflight time. #1028

• Relaxed the restriction on register that all trait sets of the provided TraitsData elements must match. This allows batched publishing of heterogeneous entity types. #1029

• Removed cpython dependency from conanfile.py. When building OpenAssetIO, it is now expected that a development install of the appropriate Python version is discoverable on the system. #1038

• Migrated manager methods entityExists and defaultEntityReference to C++ with Python bindings, and redesigned to use a callback based batch API. #992 #993

• Migrated ManagerInterface/Manager updateTerminology to C++ with Python bindings. Tweaked interface to be returned based rather than out-param based. #996

• Removed kWriteMultiple and kReadMultiple access patterns, due to not having coherent use cases. #1016

• Removed Context.Retention due to not having coherent use cases. #1048

New Features

• Added kCreateRelated access pattern, to indicate when a workflow specifically creates a new entity as a relation to an existing one. #1016

• Added BatchElementError.ErrorCode.kInvalidTraitSet and InvalidTraitSetBatchElementException. #992

Improvements

• Increased verbosity when running the openassetio.test.manager API compliance suite test harness. The report includes tests that were skipped, helping to detect accidentally omitted fixtures. 1032

• Added some aliases to the Doxygen API documentation. In particular, Ptr and ConstPtr aliases are now cross-referencable.

• Altered the fixture that causes a skip in relationship based API compliance tests, to be the more specific relationship traitset. #1022

• Set the correct context for various tests in the API Compliance openassetio.manager.test test harness.

Breaking changes

• Refactored getRelatedReferences into getWithRelationship and getWithRelationships to better define the two possible batch-axis, and simplify implementation on both sides of the API. This also changes the methods over to callback signatures for consistency with the rest of the API, and migrates them to C++ with Python bindings. #847 #919 #913

• Removed version query APIs (entityVersion, entityVersions, finalizedEntityVersion) in favour of use of the more general resolve and getWithRelationship methods. See DR017 for details. #980

• Updated castToPyObject to convert a nullptr input to a Python None, rather than throwing an exception. #988

• Removed out of date constants from the Python openassetio.constants module. These have been replaced by domain-specific traits and specifications defined in their own repositories, such as OpenAssetIO-MediaCreation.

• Migrated remaining constants to C++ with Python bindings. This means that from openassetio.constants import <name> no longer works - the constants module must be imported wholesale. #998

Deprecated

• Renamed manager info dictionary key constants, which were prefixed with kField_, to use an InfoKey_ prefix instead. The deprecated constant variables will be removed in a future release. #998

Improvements

• Added paged implementations of getWithRelationship and getWithRelationships, called getWithRelationshipPaged and getWithRelationshipsPaged. These methods are the equivalent of the non-paged versions, but provide an EntityReferencePager object, rather than a direct list of results, allowing for correct handling of extremely large/unbounded data sets. #971

• Added default implementations of getWithRelationship and getWithRelationships that return empty lists, making these methods opt-in for manager implementations. #163

• Added coverage of the getWithRelationship[s] and getWithRelationship[s]Paged methods of the ManagerInterface to the openassetio.manager.test harness. #914 #972

• Added requireEntityReferenceFixture and requireEntityReferencesFixture utility methods for cases written for the openassetio.test.manager (aka apiComplianceSuite) test harness. These convert a string fixture into an EntityReference object, or a list-of-strings fixture into a list of EntityReference objects, respectively. #914

• Migrated the ManagerInterface/Manager flushCaches method to C++ with Python bindings. #994

• Added a call to flushCaches after every openassetio.test.manager (aka apiComplianceSuite) test case, giving the manager plugin a chance to clean up between tests. #994

Bug fixes

• Reintroduced the optional optimized entity reference prefix check for isEntityReferenceString, allowing the plugin's implementation to be short-circuited. In particular, if the plugin's implementation is written in Python, then a prefix check short-circuits the need for a costly Python function call for this hot code path. #566

New Features

• Added an overload of ManagerFactory.defaultManagerForInterface that takes a config file path string argument, rather than using an
  environment variable. #937

• Added support for ${config_dir} interpolation within manager string settings retrieved from the TOML config file used by defaultManagerForInterface. This token expands to the absolute directory of the TOML config file. #804