Metadata Viewer: API to return dict, not list

[pllim]

Description

This pull request is to address the request, "File metadata extracted from the API is hard to parse. Maybe a dictionary is better?"

I avoided changing metadata itself because that would mean messing with the front-end stuff that already works. Also might be subtly confusing because the same attribute now returns something different. Maybe best to have a clean break using a different attribute name.

Change log entry

• Is a change log needed? If yes, is it added to CHANGES.rst? If you want to avoid merge conflicts,
  list the proposed change log here for review and add to CHANGES.rst before merge. If no, maintainer
  should add a no-changelog-entry-needed label.

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Are two approvals required? Branch protection rule does not check for the second approval. If a second approval is not necessary, please apply the trivial label.
• Do the proposed changes actually accomplish desired goals? Also manually run the affected example notebooks, if necessary.
• Do the proposed changes follow the STScI Style Guides?
• Are tests added/updated as required? If so, do they follow the STScI Style Guides?
• Are docs added/updated as required? If so, do they follow the STScI Style Guides?
• Did the CI pass? If not, are the failures related?
• Is a milestone set? Set this to bugfix milestone if this is a bug fix and needs to be released ASAP; otherwise, set this to the next major release milestone. Bugfix milestone also needs an accompanying backport label.
• After merge, any internal documentations need updating (e.g., JIRA, Innerspace)? 🐱

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.80%. Comparing base (1408806) to head (5c733fc).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3292   +/-   ##
=======================================
  Coverage   88.80%   88.80%           
=======================================
  Files         125      125           
  Lines       19011    19016    +5     
=======================================
+ Hits        16883    16888    +5     
  Misses       2128     2128           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[camipacifici]

Much easier to use now, thank you!
I had the same question as Kyle about meta vs metadata. I do not have strong opinions since I doubt it was widely used. I am ok with meta if metadata can be deprecated, but I let you all decide.
Is it possible to carry also the description of the keyword like it was before? Example in screenshot.

[pllim]

During 2024-11-15 tag-up, it was agreed to deprecate metadata as public API.

carry also the description

@camipacifici , this was also discussed at tag-up but unclear if this will be confusing to users or not. Description is only applicable when it comes from FITS header (but even then, not always there). In astropy.io.fits.Header, such things are represented by key: (value, descrip) combo but a user that is not familiar with that convention might not understand why the key gives back a tuple.

@kecnry suggested a nested dictionary. But will a nested dictionary be confusing too? Also a nested dictionary cannot be roundtripped back into a FITS Header easily.

[kecnry]

nested dictionary could look something like:

{'ACT_ID': {'description': 'Activity identifier', 'value': 1},
 'ASPERNAME': {'description': 'PRD science aperture used': 'value': 'NRS_FULL_MSA'}
...
}

[rosteen]

Also a nested dictionary cannot be roundtripped back into a FITS Header easily.

Is there somewhere in the code that we do this in Jdaviz that would be made more complicated, or are you talking about a user who might want to put the metadata returned by this back into a Header?

[camipacifici]

@pllim I think users are very familiar with what astropy.io.fits gives and the description (if available) is returned. I would try to stay closed to that format. The combo is fine.

[pllim]

are you talking about a user who might want to put the metadata returned by this back into a Header?

Yes, there is always a chance a user did a cube smooth or whatever and then wants to write their own FITS file back out and then want to stuff in header from original cube.

[pllim]

Okay, looks like I give fits.Header too much credit. This works if d is a simple key-value pair.

fits.Header({"a": 1})

This does not work.

fits.Header({"a": (1, "aaa")})

But if you do it keyword by keyword, this works.

hdr = fits.Header()
hdr["a"] = (1, "aaa")

So I guess simple full roundtrip is quite impossible. Just a matter of how much code you want user to write, like this.

for key, val in meta.items():
    hdr[key] = val

Or like this.

for key, val in meta.items():
    hdr[key] = (val["value"], val.get("description", ""))

Any preference?

[rosteen]

I'm in favor of the nested dictionary approach, I think that's the clearest thing to return. We could always provide a meta_as_header method in the API to do the fiddly bits of packing it back up in a FITS header (as a follow up, I don't think that would need to go in this PR).

[pllim]

I don't think this is correct but I cannot find a good example of deprecating just an attribute that is also traitlet. Just so we're clear, we are never going to delete this, just retiring it from public API. Maybe @kecnry can tell me how when he returns next week.