access_url behaviour change to raise a deprecation rather than error

[bsipocz]

I think it should be considered to use deprecations for the change of behavior in access_url, keeping the old behavior of returning the first element from access_urls along with the warnings, rather than raising the exception straight away.

I milestone this issue is only relevant before the 1.4 release.

[msdemlei]

PR #341 addresses using access_url on a resource directly.

It also adds an access_url column in the result of get_summary.

However, we can't really bring back access_url to to_table -- that would require an access_url column in the query result, and there's no sane way to have that. I'm afraid the legacy behaviour was based on the wrong assumption that there is one access URL per resource, which is simply not true.

I note in passing that the use in the NAVO notebook (I've looked at UseCase_II) is purely informational, that is, it just shows the results for demonstration and does not use the access_url any more.

This kind of use is what get_summary is for. That, however, doesn't have ivoid (I don't think that's human-readable and hence I'd argue it doesn't belong there), though, so we'd have to ask the authors to change to:

uv_services.get_summary()[
    np.array(['GALEX' in u.short_name for u in uv_services])
    ]['short_name', 'access_url']

But frankly, get_summary() is there exactly for displaying a human-readable table, so I'd say they should use get_summary() directly. There is no filtering facility on RegistryResults yet. Do we want to support that? Or can we get away just saying "Well, run a new query with short_name ILIKE '%GALEX%'"?

[bsipocz]

We'll be changing the notebooks themselves and bump the version number to require pyvo 1.4, so I was mentioning them mostly as a demonstration that users may use the previous API in similar ways we did and thus end with errors.
Given the recent discussions about how to notify downstream users, or recognise their incompatibility ahead of a release, I felt this may be a situation we are actually in. We can easily do the changes (especially if we call it 2.0 rather than 1.4), and point out fixed for those who report failures, or give some warnings in the code. (And I totally agree that rephrasing the navo notebooks is certainly something we should do)

[bsipocz]

(The one minor issue with get_summary is that it's not available in prior versions (as far as I see). So while everything is indeed much nicer and logical with the refactor it's somewhat difficult to do come up with an example that works for all versions. Which may be OK, it was just something I felt better to be raised as a concern).

[tomdonaldson]

#341 doesn't address the fact that access_url is now missing in the output of to_table(), but it does help users deal with unexpected multi-value access_urls.

As far as I can tell, there was never any documentation guaranteeing the columns that would result from to_table(). It's certainly possible that some users empirically relied on the access_url column, but the suggested uses for these results keep the access_url hidden. I think the updated documentation is thorough and sufficient enough that no additional fixes should be needed for this issue.

[tomdonaldson]

Based on the discussion here and offline, I think we can proceed without raising deprecation regarding the access_url changes. After releasing v1.4, we can respond to issues if or when they arise.