job outputs: support single file vs multiple file results better

[soxofaan]

The current client has some assumptions here and there that a job has a single result, e.g.

openeo-python-client/openeo/rest/job.py

Lines 78 to 85 in cb717a0

	def download_results(self, target: Union[str, pathlib.Path]) -> pathlib.Path:
	""" Download job results."""
	results_url = "/jobs/{}/results".format(self.job_id)
	r = self.connection.get(results_url, expected_status=200)
	links = r.json()["links"]
	if len(links) != 1:
	# TODO handle download of multiple files?
	raise OpenEoClientException("Expected 1 result file to download, but got {c}".format(c=len(links)))

openeo-python-client/openeo/rest/datacube.py

Lines 838 to 840 in cb717a0

	def execute_batch(
	self,
	outputfile: Union[str, pathlib.Path], out_format: str = None,

We should find something to also support download a multi-file result set without complicating the client API too much

[soxofaan]

in #128 we already made the difference more explicit in the RESTJob class:

• RESTJob.download_result("file.tiff") to download a single file (fails when result has multiple files)
• RESTJob.download_results("folder") to download all files from a result to a folder

Also did some finetuning to make it easier for user to do either of these directly from datacube (which only has single file support in execute_batch() at the moment):

• cube.send_job().start_and_wait().download_result("file.tiff")
• cube.send_job().start_and_wait().download_results("folder")

[soxofaan]

under EP-3739 I added JobResults and ResultAsset classes to make clear distinction between the job results (GET /job/{job_id}/results and the individual assets in these results. This gives more flexibility to the end user to do what's best for them.

Initial documentation: https://open-eo.github.io/openeo-python-client/batch_jobs.html#download-batch-job-results

recommended flow:

results = job.get_results()
results.download_files("path/to/folder")

if user knows there is just one asset in result:

results.download_file("path/to/result.tiff")

[soxofaan]

ResultAsset also supports load_json and load_bytes to get result directly in memory and skip download to file.
It should be straightforward to also provide something like load_numpy_array (from geotiff or netcdf asset)

[soxofaan]

I think we can close this ticket now