Python config/library API

[lpapp-foundry]

What

Allow users to configure the BAL library using a Python API to simplify the recreation of known states as part of automated testing.

Why

Presently, BAL can only be configured using a JSON library file. This causes several problems with the authoring of automated tests within host integrations:

• It is difficult to single-source inputs and expected, values without authoring the JSON file in the test case and re-initializing the manager.
• It requires additional side-car data files to accompany the tests which may not be desirable.

Notes

• JSON should still be supported for other uses of BAL.
• Workflows need careful consideration, including:
  • Run-time manipulation of BAL in a test case.
  • Drop-in replacement for the JSON file via declarative Python.
  • Authoring of JSON at scale via Python.
  • Can we leverage traitgen classes as part of this?

Acceptance Criteria

• BAL has an additional settings key called "library_json", which contains the serialized database.
• The JSON is returned from settings() and can be set through initialize()
• Implicit interpolation variables, e.g. ${bal_library_dir} etc, are not provided. If required then they must be passed as any other user-configured "variables" entry in the library.
• If provided,"library_json" takes precedence over "library_path".
• A blank "library_json" reverts the library to the library stored at "library_path", if available.

[foundrytom]

A suggested sketch of one way this could be used:

@pytest.fixture
def bal() -> Bal:
    return Bal.instance()

def test_when_evaluated_then_location_is_urldecoded_and_path_extracted(read, bal: Bal):
  
    resolved_value = "file:///a/path%20with%20spaces/some.%23%23%23%23.ext"
    expected_value = "/a/path with spaces/some.####.ext"

    with bal.scoped_entities() as library:

        entity = library
            .add_entity("aComplexPath")
            .locatable_content(resolved_value)

        read["file"].setValue(entity.reference)
        assert read['file'].getEvaluatedValue() == expected_value

[feltech]

There is a simpler half-way-house to consider, whereby we add some mechanism within BAL to be able to alter its in-memory JSON database at runtime as a JSON document (as opposed to an imperative API).

[feltech]

Riffing off past me... the settings dict could contain a serialised JSON database, as an alternative to a path to a JSON file.

This means the host could get the current state of the database (as serialised JSON) from settings(). The host could then mutate, re-serialise, and re-initialize(...) with the updated database.

Pros:

• (Probably) trivial to implement.
• No need to import/expose BAL internals.
• Works in C++ too since its using the existing OpenAssetIO bindings.
• Allows BAL database to be defined as a string value in an OpenAssetIO .toml config file, rather than in a separate file.

Cons:

• Serialisation/deserialsation to/from JSON. The JSON has to be serialized/deserialised since InfoDictionary is a subset of JSON functionality (e.g no nested objects).
• C++ standard library cannot natively parse JSON.
• Need to rethink ${bal_library_dir} -type variable interpolation.

[feltech]

Expanded acceptance criteria based on findings during implementation.