confusing tutorial / api description about model.add_readers_from_file

[jerabaul29]

From https://opendrift.github.io/tutorial.html:

add_readers_from_file(<file_with_lines of_reader_filenames/URLs>)

and there is not much more information available in the api description:

https://opendrift.github.io/autoapi/opendrift/models/basemodel/index.html#opendrift.models.basemodel.OpenDriftSimulation.add_readers_from_file

But:

[ins] In [5]: o.add_readers_from_file("https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be")
---------------------------------------------------------------------------
FileNotFoundError                         Traceback (most recent call last)
Cell In[5], line 1
----> 1 o.add_readers_from_file("https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be")

File ~/miniconda3/envs/harvest/lib/python3.11/site-packages/opendrift/models/basemodel.py:978, in OpenDriftSimulation.add_readers_from_file(self, filename, timeout, lazy)
    977 def add_readers_from_file(self, filename, timeout=10, lazy=True):
--> 978     fp = open(filename, 'r')
    979     sources = fp.readlines()
    980     sources = [line.strip() for line in sources if line[0] != '#']

FileNotFoundError: [Errno 2] No such file or directory: 'https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be'

[ins] In [6]: o.add_readers_from_list("https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be")
11:13:14 DEBUG   opendrift.readers.reader_lazy:32: Delaying initialisation of LazyReader: https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be
11:13:14 DEBUG   opendrift.models.basemodel:942: Added reader LazyReader: https://thredds.met.no/thredds/dodsC/sea/norkyst800m/1h/aggregate_be

So the add_readers_from_file seem to accept only local files, not "opendap url files" if I understand correctly? Could the tutorial be updated to:

add_readers_from_file(<file_with_lines of_reader_filenames>)

If I am misunderstanding something, apologies - but may be useful to clarify a bit :) .

Also, any reason for providing add_readers_from_file when add_readers_from_list seems to be a drop in replacement with more built in capabilities? :)

[knutfrode]

Yes, documentation is totally lacking here, but add_readers_from_file is supposed to take in a plain text file (from local disk) where each line is either a filename or a thredds URL to datasets. Thus its implementation is very basic:

    def add_readers_from_file(self, filename, timeout=10, lazy=True):
        fp = open(filename, 'r')
        sources = fp.readlines()
        sources = [line.strip() for line in sources if line[0] != '#']
        self.add_readers_from_list(sources, timeout, lazy=lazy)

Documentation should be added, but anyway we might need to do an update, as it might generally be necessry to provide additional information to a single URL/filename, e.g. specifying which variable names to be used in cases where several variables have the same standard_name (e.g. commonly for wind, which can be at several levels, e.g. surface, tropopause....)
Thus we are considering that a file could be e.g. yml or json, but also accepting plain text files as presently.