Document "magic" behavior of filepath and other attributes

[astrojuanlu]

Description

https://linen-slack.kedro.org/t/12920230/hi-all-the-other-day-i-was-making-a-custom-dataset-for-the-h#4537cfc5-4656-4b9f-9330-e199d48ac8fa

Hi All,
The other day i was making a custom dataset for the Huggingface AudioFolder dataset, which takes a folder as an argument. As such, i gave it the parameter data_dir as input, instead of filepath, it took me roughly an hour of debugging to figure out why i loading the dataset was now dependant on the current working directory, and just wouldn't load if i gave it a relative path (data/01_raw/..) instead of workspace/project_name/data/01_raw/….
Anyway, the issue was that filepath has a (buried) custom resolver in AbstractDataSet baseclass.

Indeed, Kedro has a hardcoded list of special properties of datasets that get special treatment:

kedro/kedro/framework/context/context.py

Lines 91 to 92 in 16dd1df

	# only check a few conf keys that are known to specify a path string as value
	conf_keys_with_filepath = ("filename", "filepath", "path")

As noted by @noklam in #2819 (comment), this does not happen when one uses the DataCatalog as a standalone library component.

Context

Possible Implementation

Possible Alternatives

An alternative is to remove this behavior or make it configurable. This will probably come up as one of the work items of #2819. In the meantime though, we should document it somewhere.

[noklam]

I think this need to be included in the documentation. This is part of the artifact of CustomDataSet is bind with an implicit contract (by convention, rather than fixed interface).

Note for this example, it will be hard to figure out all possible "file" attribute if we allowed any kind of keywords. It is not a bad thing.

Maybe the alternative is having a generic way of handling path, or may need to move these logic around to have consistent behavior across framework and library?

[stichbury]

Thanks for this. Let me know when/where this should go but I will discount including it in the current round of updates to the data catalog docs in #2888 🙏