Implement a format representation sequence path function for Loaders

[BigRoy]

Is your feature request related to a problem? Please describe.

Many loader plug-ins involved quite some code on finding the right file or file pattern for a sequence. They are trying to construct patterns like:

/path/to/publish/v001/filename.####.exr
/path/to/publish/v001/filename.$F4.exr
/path/to/publish/v001/filename.%04d.exr
/path/to/publish/v001/filename.<f>.exr
/path/to/publish/v001/filename.<udim>.exr
/path/to/publish/v001/filename.<udim>.<f>.exr

These currently all appear to be implemented over and over again, and also appear to parse this data from the filename itself even though most of these frames or udims or alike is information that was available at the time of publish.

Some examples

• Replacing part of the filename in the Nuke image loader - this would already fail if the subset was called imageMain20 and we're loading frame 20, it would also replace the 20 of the subset name to
• Houdini image loader, listing files in the publish folder and going from there
• Houdini bgeo loader loading a sequence and always expecting the dot in front of the frame number even though I believe that's customizable to be another frame separator in OpenPype and something similar for Houdini's VDB Loader
• Fusion image sequence loader listing folder's contents
• Maya ass loader listing publish contents using os.listdir and then clique.assemble
• Maya VDB loader to V-Ray trying to parse path from listing folder
• Maya Yeti Cache finding fur sequences

A lot of these implementations have many points of failures. E.g. most of the os.listdir usages don't even check whether the result is a file and has the right extension - it might just pick up any other file in that folder instead. But the essence of what they are trying to do is mostly the same, and its detecting and formatting the following:

• Do the files exist?
• Are they a sequence of files or a single file?
• What kind of tokens are in the filename?
• And then last format the path so the token is the way we need for our loader, e.g. changing frame in #### or <f> or $F4 etc.

Describe the solution you'd like

I'd like a single recommended (and documented) approach on how a loader should retrieve the files of the publish and preferably even expose get_representation_sequence or format_representation_path or something along those lines that would make this loading logic of sequences in a certain way easily manageable for the developer implementing a Loader plugin.

The tricky bit is if the function itself formats the path like e.g. /path/to/publish/v001/filename.%04d.exr that would make it non-trivial for the loader plugin developer to detect whether the files exist on disk or not. So we might need to consider also returning the full paths easily.

Describe alternatives you've considered

The alternative is to pick one of the different implementations found in the codebase and use one, but they don't seem foolproof and generally result in many lines of code extra to maintain in a loader.

Additional context

There is an existing get_representation_path function which I believe returns the first filepath of the representation.

[cuID:OP-4791]

[BigRoy]

A form of this was implemented with ynput/OpenPype#4313 - the template would be used to generate the path with the tokens in it. However, there are edge cases which will still be problematic then, e.g. publishes made using {originalBasename} could not be formatted like that with the tokens and the frame or udim tiles in those I believe would also not be detected correctly?

[BigRoy]

This is still relevant - but may be superseded by some openassetio logic being worked on by @antirotor

[dee-ynput]

This is still relevant - but may be superseded by some openassetio logic being worked on by @antirotor

Indeed. I have mentionned it in 🚀 Representation Schemas. I'll mark this as blocked in backlog now, to avoid picking it on its own.