docs build - fix for automodapi

[zacharyburnett]

apply fix from #155 (comment) for docs build issue in Python > 3.8

[zacharyburnett]

It looks like the build fails with
https://readthedocs.org/projects/roman-datamodels/builds/20154238/

TypeError: <lambda>() got an unexpected keyword argument 'onlylocals'

[codecov]

Codecov Report

Patch and project coverage have no change.

Comparison is base (5087ffe) 96.73% compared to head (b004f7a) 96.73%.

❗ Current head b004f7a differs from pull request most recent head 72bb963. Consider uploading reports for the commit 72bb963 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #156   +/-   ##
=======================================
  Coverage   96.73%   96.73%           
=======================================
  Files           9        9           
  Lines        1101     1101           
=======================================
  Hits         1065     1065           
  Misses         36       36           

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[nden]

It looks like the behavior has changed with Python 3.9. The issue and a proposed updated solution is documented here.

[ddavis-stsci]

Looks OK to me, hopefully they will update the astropy/sphinx code so we can remove the patch at some point.

[nden]

The failure is unrelated.

[WilliamJamieson]

I do not like this fix considering its only needed to fix some type hints.

[nden]

@WilliamJamieson Do you have a better suggestion?

[WilliamJamieson]

Short answer is fix stuserdict.py, which is what is causing the issue. This can be done in several ways (note these are not mutually exclusive improvements):

1. Define an __all__ = ["STUserDict"] in stuserdict.py. Per pep-8:

To better support introspection, modules should explicitly declare the names in their public API using the __all__ attribute. Setting __all__ to an empty list indicates that the module has no public API.

So __all__ should be defined anyways

2. The issue is it attempting to generate documents for Any and Iterator which are used purely as type annotations. This is because they are imported as no private things in the namespace there. As they are purely type annotations changing:

   roman_datamodels/src/roman_datamodels/stuserdict.py

   Line 1 in 52b5451

   from typing import Any, Iterator

   to

from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from typing import Any, Iterator
from typing import Any, Iterator

Allows for the type-hints to say, but they will only be imported if type checking via the annotations is used.

3. Remove the type hints all together. No where else in roman_datamodels are there type hints.

The either options 1 and 2 or 1 and 3 would be the best way to deal with the issue.

Note, STUserDict seems redundant and should be removed. It is only a base class for stnode.DNode, which overloads much of its interface anyways. Moreover, STUserDict appears to be a copy-paste from the CPython standard library's UserDict (from 3.8/3.9) where .data has been replaced by ._data. Instead it would be simpler to simply have DNode subclass collections.abc.MutableMapping directly. However, this type of change is outside the scope of this bugfix.