Of required and optional dependencies #10342

Description

As astropy grows over the years, we now have different kinds of dependencies:

• Absolutely required and documented as such: numpy
• Required for certain jobs, e.g., building docs and testing.
• Declared optional but really required for some subpackages, such as but not limited to:
  • matplotlib for visualization.wcsaxes
  • asdf for io.misc.asdf (this one is even cyclic, i.e., we also depend on it for schemas version or something)
  • PyYAML for io.misc.yaml and maybe even io.fits (see Table.read on FITS file triggers PyYAML import #7783)
• Truly optional, i.e., there is a fallback alternative if the dependency is missing -- Do we really have this? Need to double check.

All the dependencies are declared in the installation page but unfortunately this page is purely informational and does not enforce anything code-wise; i.e., it will not automatically downloads asdf for you if you use astropy.io.misc.asdf. (But do we even want that?)

The complexity of these dependencies occasionally cause problems when they are missing or incompatible, resulting in but not limited to:

• Unable to use part of the code directly.
• Unable to use code in downstream package that uses our affected code.
• Unable to test the code effectively, causing bugs to slip through during development process. (Either forget to test with or without the dependency.)
• Version limitations for optional dependencies are ignored #12121

Some workaround to make the dependency optional also caused performance issue; e.g., #10302 .

Things we could do to improve the situation

• Import-only test job as discussed in Add an import-only test matrix entry #7939 . Such a job will ensure things like, but not limited to:
  • pytest not required at runtime.
  • Optional dependencies don't cross-pollinate; e.g., io.fits would work even if PyYAML is not present, or visualization.wcsaxes is not affected by the presence or lack of asdf.
  • Importing astropy without any optional dependencies will not cause ImportError.
  • Defining special cases where ImportError is acceptable; e.g., io.misc.asdf can throw ImportError if asdf is not installed.
    • However, will this accidentally let real problems through?
    • Can we overload __doctest_requires__ for this purpose or is subpackage conftest.py incantation sufficient?
    • Perhaps even a new __doctest_subpackage_requires__ directive in pytest-doctestplus to avoid recursion into a subpackage.
• Skip test collection in setup_package.py to avoid problem with requiring extension-helpers; e.g. Tests should collect without optional dependencies #10246 .
• Do not use pytest.importorskip in non-test code; e.g., Speed up wcsaxes import by avoiding unnecessary pytest import #10302 vs TST: Globally ignore import error during test collection for doctest #10325.
• Avoid try ... except ... imports in subpackage; e.g., io.misc.asdf should always assume asdf is importable.
• Parse __init__.py with AST rather than importing them? (This idea was given with a 😉)

What else?

Other related issues/PRs not mentioned above

• MNT: Make asdf import truly optional in io.misc.asdf #10260 (deemed impractical and was rejected)
• Why is this not part of pytest? scientific-python/pytest-doctestplus#100
• add doctest_ignore_import_errors_modules scientific-python/pytest-doctestplus#110

Disclaimer

The information here is put together from multiple discussions with many people. Feel free to comment/edit if I missed something.