HSpy writer requires undocumented "package_info" key in the signal dictionary

[hakonanes]

Describe the bug

This is more of a question than a bug report.

rsciio.hspy.file_writer() requires a "package_info" key in the signal dictionary. This is not listed in the API docs. In HyperSpy's use of file_writer(), this dictionary field is populated by calling the utility function rsciio.utils.tools.get_object_package_info(). This function is not listed in Rosetta's public API, so I assume it is private.

Is the intention that a user or another package imports this private function and populates the "package_info" key when using the HSpy writer? Or shouldn't the writer be used by anyone else than HyperSpy?

Please correct me if I missed something here.

To Reproduce

kikuchipy 0.8.7 supports writing to HyperSpy's HSpy file format via a custom save() method. This works fine when calling the HSpy writer from HyperSpy 1.7.5 (internally in kikuchipy). In the effort to make kikuchipy compatible with HyperSpy 2.0 and start using RosettaSciIO 0.1, the need to populate the "package_info" dictionary field presented itself:

>>> from rsciio import hspy
>>> import kikuchipy as kp
>>> s = kp.data.nickel_ebsd_small()  # Extends HyperSpy's Signal2D class for EBSD
>>> hspy.file_writer("test.hspy", s._to_dictionary())  # Calls BaseSignal._to_dictionary()
Traceback (most recent call last):
  File "/home/hakon/miniconda3/envs/kp-dev/lib/python3.11/site-packages/IPython/core/interactiveshell.py", line 3548, in run_code
    exec(code_obj, self.user_global_ns, self.user_ns)
  File "<ipython-input-26-92e4bdbf6859>", line 1, in <module>
    hspy.file_writer("/home/hakon/test.hspy", s._to_dictionary())
  File "/home/hakon/miniconda3/envs/kp-dev/lib/python3.11/site-packages/rsciio/hspy/_api.py", line 271, in file_writer
    writer.write()
  File "/home/hakon/miniconda3/envs/kp-dev/lib/python3.11/site-packages/rsciio/_hierarchical.py", line 700, in write
    self.write_signal(self.signal, self.group, **self.kwds)
  File "/home/hakon/miniconda3/envs/kp-dev/lib/python3.11/site-packages/rsciio/_hierarchical.py", line 704, in write_signal
    group.attrs.update(signal["package_info"])
                       ~~~~~~^^^^^^^^^^^^^^^^
KeyError: 'package_info'

😮

The "package_info" field is populated in HyperSpy's io.save() function and not in BaseSignal._to_dictionary().

Expected behavior

To write the signal to file 😅

The "package_info" dictionary field is new to me (although I see it was introduced by @francisco-dlp July last year...).

Python environement:

• RosettaSciIO version: 0.1
• Python version: 3.11.6
• HyperSpy version: 1.7.5
• kikuchipy version: 0.9.dev0 (from Use RosettaSciIO and adapt to their IO plugin specification architecture pyxem/kikuchipy#651)

Additional context

None at the moment.

[ericpre]

This is specific to the hyperspy specification and I would say that this should be documented ("package_info" and rsciio.utils.tools.get_object_package_info), as well as saving other signals attributes, which are currently undocumented too.

[hakonanes]

Thank you for the quick reply. It's good to know that I can then import get_object_package_info() to mimick HyperSpy's approach.

I hope to find time to open a PR that starts on updating the specification documentation soon. Feel free to do it yourself, though.