ForceField sources allows strings but description doesn't seem mention it.

[IAlibay]

Overview

Looking at the definition for sources, my understanding is that the docstring always seems to indicate that a file or file-like object is required. This can be seen in either in __init__:

openff-toolkit/openff/toolkit/typing/engines/smirnoff/forcefield.py

Lines 241 to 248 in 9934858

	A list of files defining the SMIRNOFF force field to be loaded.
	Currently, only `the SMIRNOFF XML format <https://openforcefield.github.io/standards/standards/smirnoff/>`_
	is supported. Each entry may be an absolute file path, a path relative to the current working directory, a
	path relative to this module's data subdirectory (for built in force fields), or an open file-like object
	with a ``read()`` method from which the force field XML data can be loaded. If multiple files are
	specified, any top-level tags that are repeated will be merged if they are compatible, with files appearing
	later in the sequence resulting in parameters that have higher precedence. Support for multiple files is
	primarily intended to allow solvent parameters to be specified by listing them last in the sequence.

or in parse_sources:

openff-toolkit/openff/toolkit/typing/engines/smirnoff/forcefield.py

Lines 772 to 779 in 9934858

	An iterable of files defining the SMIRNOFF force field to be loaded.
	Currently, only `the SMIRNOFF XML format <https://openforcefield.github.io/standards/standards/smirnoff/>`_
	is supported. Each entry may be an absolute file path, a path relative to the current working directory, a
	path relative to this module's data subdirectory (for built in force fields), or an open file-like object
	with a ``read()`` method from which the force field XML data can be loaded. If multiple files are
	specified, any top-level tags that are repeated will be merged if they are compatible, with files appearing
	later in the sequence resulting in parameters that have higher precedence. Support for multiple files is
	primarily intended to allow solvent parameters to be specified by listing them last in the sequence.

or in parse_smirnoff_from_source:

openff-toolkit/openff/toolkit/typing/engines/smirnoff/forcefield.py

Lines 985 to 989 in 9934858

	File defining the SMIRNOFF force field to be loaded Currently, only `the SMIRNOFF XML format
	<https://openforcefield.github.io/standards/standards/smirnoff/>`_ is supported. The file may be an
	absolute file path, a path relative to the current working directory, a path relative to this module's data
	subdirectory (for built in force fields), or an open file-like object with a ``read()`` method from which
	the force field XML data can be loaded.

However, looking a bit further below, it looks like we can indeed parse an FFXML as a string directly:

openff-toolkit/openff/toolkit/typing/engines/smirnoff/forcefield.py

Line 1038 in 9934858

smirnoff_data = parameter_io_handler.parse_string(source)

The question

Is this intended? Is string parsing officially supported but the docstring is out of date, or is this something that is more private API-esque?

The use case

I want to be able to allow folks to define OFFXML strings when creating an OpenFE FF settings object and not having to wrap it into a file-like object after the fact would make life a lot easier.

[mattwthompson]

As a passer-by, that docstring could use a heavy dose of whitespace 😅

Is this intended?

Hard to ascribe intent, but this is something that's been in the API/functionality since the beginning and is heavily baked into the test suite (look at several hundred lines in openff/toolkit/_tests/test_forcefield.py). I can't imagine it going away soon

[j-wags]

Yeah, at this point I think the docstring is wrong. I consider the ability of this methods to load OFFXML strings to be de facto in the public API so in my mind this a stable feature with deficient documentation. Feel free to continue using it this way.