Openassetio

Breaking changes

- The `openassetio.traits` module has been removed. OpenAssetIO itself no longer contains any trait definitions. Integrations of the API should use the established standards particular to the area of use. See [OpenAssetIO-MediaCreation](https://github.com/OpenAssetIO/OpenAssetIO-MediaCreation) for traits previously included here. [#717](https://github.com/OpenAssetIO/OpenAssetIO/issues/717)

Breaking changes

- OpenAssetIO now has a soft dependency on the `importlib_metadata` Python package (>=3.6.0). If you have been installing the project manually by extending `PYTHONPATH` (instead of using `pip`) you may also need to additionally satisfy this dependency if you wish to make use of entry point based discovery of Python plugins. [762](https://github.com/OpenAssetIO/OpenAssetIO/issues/762)

- The `PythonPluginSystem` no longer clears existing plugin registrations when `scan` is called. The `PythonPluginSystemManagerImplementationFactory` has been updated to call `reset` itself, so this change only affects any direct use of the `PythonPluginSystem` by third party code. [703](https://github.com/OpenAssetIO/OpenAssetIO/issues/703)

- The `PythonPluginSystemManagerImplementationFactory` now checks fall-back environment variables during construction, rather than the first time plugins are queried. This means changes to the environment made after a factory has been created will not affect that factory. [762](https://github.com/OpenAssetIO/OpenAssetIO/issues/762)

- Removed references to `openassetio-traitgen` from codebase, is now in [own repository](https://github.com/OpenAssetIO/OpenAssetIO-TraitGen) [#715](https://github.com/OpenAssetIO/OpenAssetIO/issues/715)

- Removed `toml++` as vendored library. Is now an external dependency similar to other external dependencies.

- Moved `setup.py` and `pyproject.toml` under the Python component's directory, i.e. `src/openassetio-python`. This means the minimum version of `pip` used to build wheels (or install from source) is now 21.3, where in-tree builds are the default. [728](https://github.com/OpenAssetIO/OpenAssetIO/issues/728)

- Updated various Python method argument names to match their C++ equivalent. Specifically this affects `Manager`/`ManagerInterface.managementPolicy`, `SeverityFilter.setSeverity`, `TraitsData.hasTrait` / `.addTrait` / `.addTraits` / `.setTraitProperty` / `.getTraitProperty` / `.traitPropertyKeys` / copy-constructor. [743](https://github.com/OpenAssetIO/OpenAssetIO/issues/743)


New features

- Added entry point based discovery of Python manager plugins. This allows pure Python manager plugins to be deployed and managed as Python packages, without the need to wrangle `OPENASSETIO_PLUGIN_PATH`. The `openassetio.manager_plugin` entry point should expose a module providing a top-level `plugin` variable, holding a `ManagerPlugin` derived class. This can be disabled by setting the `OPENASSETIO_DISABLE_ENTRYPOINTS_PLUGINS` env var to any value. [762](https://github.com/OpenAssetIO/OpenAssetIO/issues/762)


Improvements

- Added `openassetio-build` docker image. This is an extension of the already used [ASFW CY22 docker image](https://hub.docker.com/r/aswf/ci-base/tags?name=2022), but with the additional OpenAssetIO dependencies installed into it. As we have also installed test dependencies into this image, this unlocks out-of-the-box sandboxed testing workflows via docker. [#716](https://github.com/OpenAssetIO/OpenAssetIO/issues/716)

- Reorganized the directory structure to better reflect the fact that the project is split into distinct components, and that it is primarily a CMake-driven project with optional Python component. [655](https://github.com/OpenAssetIO/OpenAssetIO/issues/655)

- Improved documentation for users that wish to build/release OpenAssetIO. [624](https://github.com/OpenAssetIO/OpenAssetIO/issues/624) [#716](https://github.com/OpenAssetIO/OpenAssetIO/issues/716) [#749](https://github.com/OpenAssetIO/OpenAssetIO/pull/749)

- Improved support for consumption of OpenAssetIO by downstream CMake projects. `OpenAssetIOConfig.cmake` provides variables for locating the installation location of binaries and Python sources. When used as a CMake subproject, namespaced `ALIAS` targets match the exported targets, and the build-tree has `RPATH` support. [675](https://github.com/OpenAssetIO/OpenAssetIO/pull/675)


Bug fixes

- Fixed various broken URLs in markdown docs. [744](https://github.com/OpenAssetIO/OpenAssetIO/pull/744)

- Fixed unnecessary link dependencies on Python and pybind11 when building and linking to the `openassetio-python-bridge` library. [675](https://github.com/OpenAssetIO/OpenAssetIO/pull/675)

- Fixed the file extension for Windows debug builds of the `_openassetio` Python extension module. [675](https://github.com/OpenAssetIO/OpenAssetIO/pull/675)

- Fixed `.pdb` debug symbol files installation location on Windows. [675](https://github.com/OpenAssetIO/OpenAssetIO/pull/675)

Breaking changes

- Renamed the `Trait` Python class to `TraitBase` for consistency with other classes. [703](https://github.com/OpenAssetIO/OpenAssetIO/issues/703)

- Renamed the `openassetio-codegen` tool to `openassetio-traitgen` to avoid ambiguity. [646](https://github.com/OpenAssetIO/OpenAssetIO/issues/646)

- The BasicAssetLibrary test-harness manager plugin has been extracted into its [own repository](https://github.com/OpenAssetIO/OpenAssetIO-Manager-BAL) to simplify its ongoing development and version management. [#672](https://github.com/OpenAssetIO/OpenAssetIO/issues/672)

Improvements

- Added compatibility with Python 3.7. [660](https://github.com/OpenAssetIO/OpenAssetIO/issues/660)

Breaking changes

- Added `[[nodiscard]]` attribute to various `make` factory functions, may generate additional compiler warnings in your project.

- Removed predownload of test dependencies, meaning contributors must reuse their python environments in order to run tests offline. [629](https://github.com/OpenAssetIO/OpenAssetIO/issues/629)

- Changed location of python virtual environment created by
`openassetio-python-venv` CMake build target to be outside of the CMake install tree. This target is executed during test runs if `OPENASSETIO_ENABLE_PYTHON_TEST_VENV` is enabled. [629](https://github.com/OpenAssetIO/OpenAssetIO/issues/629)

- Changed `--install-folder` location of conan install in bootstrap scripts from `$CONAN_USER_HOME` to `$WORKSPACE/.conan`. Users who have been using the bootstrap scripts directly may need to update their toolchain CMake arguments.

New Features

- Added `simpleResolver.py` example host (under `resources/examples`), that provides a basic CLI to resolve Entity References for a supplied Trait Set.

- Added CMake option `OPENASSETIO_ENABLE_PYTHON_TEST_VENV`, allowing the user to configure whether a python virtual environment is automatically created during `ctest` execution, along with a new CMake preset `test-custom-python-env` that disables this option.

Improvements

- Added Python sources to the CMake install tree (rather than requiring a separate `pip install` for the pure Python component), effectively creating a complete bundle that can be used directly or packaged. [629](https://github.com/OpenAssetIO/OpenAssetIO/issues/629)

- Updated `setup.py` to build the Python extension module. Assuming CMake's `find_package` can locate dependencies, then `pip install .` is all that is needed to build and install OpenAssetIO into a Python environment. [630](https://github.com/OpenAssetIO/OpenAssetIO/issues/630)

- Added 'unstable' warning to docs to notify of python api that has not yet been updated for the C++ api, and is thus inherently unstable. [600](https://github.com/OpenAssetIO/OpenAssetIO/issues/600)

- Changed CMake configuration so that `openassetio-python-venv` target now automatically installs python dependencies of enabled components. [629](https://github.com/OpenAssetIO/OpenAssetIO/issues/629)

- Added convenience methods `debugApi`, `debug`, `info`, `progress`, `warning`, `error`, `critical` to `LoggerInterface` to log messages of the respective severity.

- Added `OPENASSETIO_CONAN_SKIP_CPYTHON` environment variable to prevent conan installing its own python version. This is to support workflows where the user is bringing their own python environment, and does not want python installations to conflict. [653](https://github.com/OpenAssetIO/OpenAssetIO/issues/653)

- Bleeding edge python wheels are now downloadable as artifacts from the `Build wheels` github actions workflow. [653](https://github.com/OpenAssetIO/OpenAssetIO/issues/653)

Breaking changes

- Added checks to the `test.manager.apiComplianceSuite` to ensure the correct handling of malformed references.

- Reordered `BatchElementError.ErrorCode` constants to allow grouping of entity-related errors. [587](https://github.com/OpenAssetIO/OpenAssetIO/issues/587)

- Migrated `Manager.preflight` and `Manager.register` to use the new callback based batch API. [587](https://github.com/OpenAssetIO/OpenAssetIO/issues/587)

- Renamed `apiComplianceSuite` fixtures to disambiguate their use:
- `a_malformed_reference` -> `an_invalid_reference`
- `a_malformed_entity_reference` -> `a_malformed_refrence`
[585](https://github.com/OpenAssetIO/OpenAssetIO/issues/585)

- Renamed `ResolveErrorCallback` to `BatchElementErrorCallback` for use more widely in callback based API functions. [588](https://github.com/OpenAssetIO/OpenAssetIO/issues/588)


New Features

- Added basic publishing support to the `BasicAssetLibrary` (BAL) example manager plugin. This allows rudimentary entity creation workflows to be explored. Initially, support is limited to the simple in-memory creation/update of entities, with verbatim store/recall of the supplied traits data. [585](https://github.com/OpenAssetIO/OpenAssetIO/issues/585)

- Added the `$OPENASSETIO_DEFAULT_CONFIG` mechanism, that allows the API to be bootstrapped from a simple TOML file referenced by this env var. Presently, this is exposed via the `ManagerFactory.createDefaultManagerForInterface` method, which reads the manager identifier/settings from this file and returns a suitably configured instance of that manager. [494](https://github.com/OpenAssetIO/OpenAssetIO/issues/494)


Improvements

- Added new `BatchElementError.ErrorCode` constants:
- `kMalformedEntityReference` When an entity reference is valid, but malformed for the calling context and target entity.
- `kEntityAccessError` When the supplied context's access is the specific cause of the error.
[587](https://github.com/OpenAssetIO/OpenAssetIO/issues/587)

- Added (protected) `ManagerInterface.createEntityReference` method to facilitate the creation of `EntityReference` values as required by a manager's implementation. [549](https://github.com/OpenAssetIO/OpenAssetIO/issues/549)

- Added `TraitsData.traitPropertyKeys` to return a set of the property keys for a given trait. [498](https://github.com/OpenAssetIO/OpenAssetIO/issues/498)

- Migrated the `preflight` and `register` `ManagerInterface` methods to C++. [588](https://github.com/OpenAssetIO/OpenAssetIO/issues/588)

- Migrated the `preflight` and `register` `Manager` methods to C++. [588](https://github.com/OpenAssetIO/OpenAssetIO/issues/588)

- Reformatted the Python codebase using [black](https://black.readthedocs.io/en/stable/), and added CI checks to enforce Python formatting going forward.

Bug fixes

- Fixed `Manager.resolve` success callback such that the trait data provided is compatible with C++ trait views. [605](https://github.com/OpenAssetIO/OpenAssetIO/pull/605)

- Fixed the `RetainPyArgs` Python binding helper to work with functions that take `shared_ptr`s by const reference, as well as by value. This affected the Python bindings of `createManagerForInterface`, which would allow the Python objects given to it to go out of scope and be destroyed, despite the associated C++ objects remaining alive. [620](https://github.com/OpenAssetIO/OpenAssetIO/pull/620)

Improvements

- Added boolean comparison based on content to `EntityReference` types.


Bug fixes

- Fixed calling `Manager.resolve` from C++, when the manager implementation is written in Python. [582](https://github.com/OpenAssetIO/OpenAssetIO/issues/582)