Openassetio

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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/pull/1038)

- Migrated manager methods `entityExists` and `defaultEntityReference` to C++ with Python bindings, and redesigned to use a callback based batch API. [992](https://github.com/OpenAssetIO/OpenAssetIO/issues/992) [#993](https://github.com/OpenAssetIO/OpenAssetIO/issues/993)

- Migrated `ManagerInterface`/`Manager` `updateTerminology` to C++ with Python bindings. Tweaked interface to be returned based rather than out-param based. [996](https://github.com/OpenAssetIO/OpenAssetIO/issues/996)

- Removed `kWriteMultiple` and `kReadMultiple` access patterns, due to not having coherent use cases. [1016](https://github.com/OpenAssetIO/OpenAssetIO/issues/1016)

- Removed `Context.Retention` due to not having coherent use cases. [1048](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/1016)

- Added `BatchElementError.ErrorCode.kInvalidTraitSet` and `InvalidTraitSetBatchElementException`. [992](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/pull/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/847) [#919](https://github.com/OpenAssetIO/OpenAssetIO/issues/919) [#913](https://github.com/OpenAssetIO/OpenAssetIO/issues/913)

- Removed version query APIs (`entityVersion`, `entityVersions`, `finalizedEntityVersion`) in favour of use of the more general `resolve` and `getWithRelationship` methods. See [DR017](./doc/decisions/DR017-Entity-version-queries.md) for details. [980](https://github.com/OpenAssetIO/OpenAssetIO/issues/980)

- Updated `castToPyObject` to convert a `nullptr` input to a Python `None`, rather than throwing an exception. [988](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/971)

- Added default implementations of `getWithRelationship` and `getWithRelationships` that return empty lists, making these methods opt-in for manager implementations. [163](https://github.com/OpenAssetIO/OpenAssetIO/issues/163)

- Added coverage of the `getWithRelationship[s]` and `getWithRelationship[s]Paged` methods of the `ManagerInterface` to the `openassetio.manager.test` harness. [914](https://github.com/OpenAssetIO/OpenAssetIO/issues/914) [#972](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/914)

- Migrated the `ManagerInterface`/`Manager` `flushCaches` method to C++ with Python bindings. [994](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/566)

New Features

- Added an overload of `ManagerFactory.defaultManagerForInterface` that takes a config file path string argument, rather than using an
environment variable. [937](https://github.com/OpenAssetIO/OpenAssetIO/issues/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](https://github.com/OpenAssetIO/OpenAssetIO/issues/804)

Breaking changes

- `Manager.createChildContext` now deep-copies the parent locale to prevent subsequent modifications of the locale of one context from affecting the other. [896](https://github.com/OpenAssetIO/OpenAssetIO/issues/896)

- Removed `ManagerInterface.setRelatedReferences` pending re-design. [16](https://github.com/OpenAssetIO/OpenAssetIO/issues/16)

- Simplified the locale `TraitsData` provided to API compliance tests via the `openassetio.test.manager` test harness. The locale now contains only a single `"openassetio:test.locale"` trait with a `"case"` property giving the name of the `unittest` test case. [835](https://github.com/OpenAssetIO/OpenAssetIO/issues/835)

- Removed the `TraitBase` and `SpecificationBase` classes. Trait and specification view classes are no longer part of the core API and are instead auto-generated by the OpenAssetIO-TraitGen tool. [835](https://github.com/OpenAssetIO/OpenAssetIO/issues/835)

- Changed the arguments of `BatchElementErrorCallback` and `ResolveSuccessCallback` from reference types to value types. [858](https://github.com/OpenAssetIO/OpenAssetIO/issues/858)

New Features

- Added utility methods `castToPyObject` and `castFromPyObject` to `openassetio-python-bridge` to facilitate converting between C++ and Python objects for hosts seeking to support mixed language workflows. Note : Some methods on `Manager` and `ManagerInterface` are currently implemented in python, pending imminent port to C++. Due to this, these methods will not yet be available for use on a python object returned from `castToPyObject`. [798](https://github.com/OpenAssetIO/OpenAssetIO/issues/798)

Improvements

- Added support for running `ctest` when a python venv is used to determine which Python distribution to build against.

- `HostSession` methods `logger` and `host` now return a const reference to the held pointer rather than a copy. [815](https://github.com/OpenAssetIO/OpenAssetIO/issues/815) [#904](https://github.com/OpenAssetIO/OpenAssetIO/issues/904)

- Contexts are now created with an empty `TraitsData` in their locale, this makes testing for imbued traits easier as it can be assumed that the pointer is never null. [903](https://github.com/OpenAssetIO/OpenAssetIO/issues/903)

- `EntityReference` objects are now coercible to strings in Python, allowing more intuitive use with `format`, `print`, and others. [573](https://github.com/OpenAssetIO/OpenAssetIO/issues/573)

- Added `Ptr`/`ConstPtr` alias members to all appropriate C++ classes, aliasing the associated `shared_ptr` of that class. [918](https://github.com/OpenAssetIO/OpenAssetIO/issues/918)

- Added support for building for Python 3.11 [683](https://github.com/OpenAssetIO/OpenAssetIO/issues/683)

Breaking changes

- Renamed `TraitBase.isValid` to `isImbued` for symmetry with `imbue`/`imbueTo` methods. [815](https://github.com/OpenAssetIO/OpenAssetIO/issues/815)

- Changed the host identifier, and removed the custom locale from the `simpleResolver` example as they did not follow best practice.

- `BatchElementErrorCallback` moved from the top level `openassetio` namespace to the `openassetio::hostApi::Manager` namespace. [849](https://github.com/OpenAssetIO/OpenAssetIO/issues/849)

- Removed the `entityName` and `entityDisplayName` methods in favour of resolvable traits to minimize API calls and allow industry specific flexibility. See OpenAssetIO-MediaCreation. [837](https://github.com/OpenAssetIO/OpenAssetIO/issues/837)

New features

- Added `TraitBase.isImbuedTo` static/class method, giving a cheaper mechanism for testing whether a `TraitsData` is imbued with a trait. [815](https://github.com/OpenAssetIO/OpenAssetIO/issues/815)

- Added `resolve`, `preflight` and `register` 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. [849](https://github.com/OpenAssetIO/OpenAssetIO/issues/849) [#850](https://github.com/OpenAssetIO/OpenAssetIO/issues/850) [#851](https://github.com/OpenAssetIO/OpenAssetIO/issues/851) [#852](https://github.com/OpenAssetIO/OpenAssetIO/issues/852) [#853](https://github.com/OpenAssetIO/OpenAssetIO/issues/853) [#854](https://github.com/OpenAssetIO/OpenAssetIO/issues/854)

Improvements

- Improved the documentation for the `simpleResolver` example, to provide more context when using it as a starting point for an OpenAssetIO integration.

- Update the pybind dependency version to 2.10.1. [863](https://github.com/OpenAssetIO/OpenAssetIO/issues/863)

- Made `BatchElementError` a copyable type in the C++ API. [849](https://github.com/OpenAssetIO/OpenAssetIO/issues/849)

- Added equality/inequality comparison operators to `BatchElementError`. [862](https://github.com/OpenAssetIO/OpenAssetIO/issues/862)

- Made the C++ codebase compliant with Clang-Tidy v15. Note that this is not yet enforced on CI. [847](https://github.com/OpenAssetIO/OpenAssetIO/pull/874)

Bug fixes

- Removed `nodiscard` from `TraitsData::getTraitProperty`, and `TraitBase::getTraitProperty`, to allow "value or default" style use cases. [825](https://github.com/OpenAssetIO/OpenAssetIO/issues/825)

Breaking changes

- Disabled the (nascent) C bindings by default. To enable, the `OPENASSETIO_ENABLE_C` CMake option must be explicitly set to `ON`.

New features

- The `FixtureAugmentedTestCase` class of the `openassetio.test.manager.harness` can now be configured to create a new, uninitialized manager instance for each test case, by setting the `shareManger` class variable or derived classes to `False`. This facilitates testing of a manager's initialization behavior. [BAL26](https://github.com/OpenAssetIO/OpenAssetIO-Manager-BAL/issues/26)


Bug fixes

- Ensured that the Python GIL is acquired within `createPythonPluginSystemManagerImplementationFactory`, so that it is no longer necessary to acquire externally by the calling (host) thread. [797](https://github.com/OpenAssetIO/OpenAssetIO/issues/797)

- Fixed use-after-free issue in hybrid C++/Python applications, where the Python interpreter is destroyed before OpenAssetIO objects are cleaned up. This could manifest as segfaults or hangs at program exit. [805](https://github.com/OpenAssetIO/OpenAssetIO/pull/805)