Add a feature to instantiate a `Resource` from a YML doc

[davemfish]

A public function like geometamaker.load(yaml_filepath) would be useful. The key is that the caller does not know the type of resource that it's loading, so it would need to read that from the YAML before instantiating the resource. That's the difference between this new function and the class method BaseResource.load, which already exists.

We have this function implemented in natcap.invest.reports.raster_utils, but think it makes sense to have this functionality in geometamaker instead.

def geometamaker_load(filepath):
    with open(filepath, 'r', encoding='utf-8') as file:
        yaml_string = file.read()
        yaml_dict = yaml.safe_load(yaml_string)
        if not yaml_dict or ('metadata_version' not in yaml_dict
                             and 'geometamaker_version' not in yaml_dict):
            message = (f'{filepath} exists but is not compatible with '
                       f'geometamaker.')
            raise ValueError(message)

    return geometamaker.geometamaker.RESOURCE_MODELS[yaml_dict['type']](**yaml_dict)

Also see BaseResource.load for how we try to load older versions of metadata models and migrate them to the current models, if possible. And consider whether the API should include this new function and this class method, or whether they should be consolidated.

[davemfish]

Whenever geometamaker reads one of its own YML files, it may need to open the file with encoding='utf-8' because that is always the encoding it uses when writing those docs.

[davemfish]

I'm on the fence about adding this feature. It is sometimes useful to quickly open an existing YML doc and get an attribute value. But initializing a Resource without going through the normal describe pathway means it would be possible for the metadata to become out of sync with the data.

Every time describe is called (even when a YML doc already exists) it reads properties intrinsic to the dataset (e.g. field names, raster sizes, CRS, etc) and updates the metadata accordingly. Bypassing that using a geometamaker.load() function means a Resource can be initialized from an existing YML without checking if those metadata properties still match the actual dataset.

Loading the YML directly saves time, but in most cases it's safer to call describe, even when you know a YML doc already exists. Users who are concerned about performance can write their own load function (example above). Another option is to add this feature as geometamaker._load(), to keep it somewhat hidden.

[claire-simpson]

I'm somewhat in favor of adding this feature. (1) I think calling describe to load the metadata is slightly unintuitive and I have to remind myself that is the primary way to achieve the same outcome as reading in the yaml, and (2) calling describe will update some of the attributes that maybe you don't want to update (admittedly my use case for this is a bit niche, but when creating sample data recently, I didn't want path and sources to get updated with the current filepath). Maybe keeping it hidden is the way to go, or just logging a warning when its called to say that "describing the metadata is the preferred way of reading metadata to ensure that the metadata is current" or something?

[davemfish]

(2) calling describe will update some of the attributes that maybe you don't want to update (admittedly my use case for this is a bit niche, but when creating sample data recently, I didn't want path and sources to get updated with the current filepath).

That's definitely by design, though the assumption is that you do want to update those attributes because they have become out of sync with the actual data. But I understand your use-case also.

(1) I think calling describe to load the metadata is slightly unintuitive and I have to remind myself that is the primary way to achieve the same outcome as reading in the yaml,

Yes, the fact that it is unintuitive is a problem. I'd rather make this more intuitive than giving an alternate way that could be easily misused, but I'm not sure how to do that.

I think we'll plan to add this feature, but not in the 0.3.0 milestone in the interest of staying on track for that release date.

[emlys]

I think I'm in favor of this. Being able to load from a yaml file (without needing any prior knowledge of the contents) seems like a very reasonable feature I'd expect in a library that produces yaml. I see what you mean about losing the link to the underlying dataset without calling describe, but I agree with @claire-simpson that describe is not the most intuitive way to load metadata. Really, there is never a guarantee that the metadata in a Resource is in sync with the underlying dataset - it could theoretically be modified by another process and become out-of-sync right after describe is called. So I think we should accept that they are separate entities, and the user is responsible for ensuring that the metadata is regenerated if the data could have changed.