More Information for JWST Users

The documentation hosted here focuses primarily on calibration software implementation and use.

For more user-focused information on JWST instruments and calibration methods, please see the JWST science calibration pipeline pages hosted on JDox.

More information on the latest build in use for data processing operations is also available on JDox.

Versioning Scheme

Note

This section addresses the release version to PyPI. It is not to be confused with the DMS quarterly build version, which has a different numbering scheme (see software vs. DMS builds).

The jwst package does not follow strict semantic versioning, in that a “minor” version bump may also contain non-backward compatible changes. However, a “patch” release will strive to contain only bug fixes.

API: Public vs Private

As per Python convention, any API name that starts with underscore (e.g., _my_private_function) is considered private. Any API not officially documented (i.e., you only found it after some extensive code-diving) is also considered private.

However, contrary to common practice, the jwst package also considers what would normally be public API (i.e., no leading underscore and fully documented) to be private unless stated as follows. Any API not listed below, even if fully documented, could be removed or changed without notice.

These are the only software interfaces that jwst considers public API and thus follow API Deprecation Policy:

  • Calibration step classes (e.g., Spec2Pipeline, JumpStep, AmiNormalizeStep)

  • Command-line interface for calibration steps (e.g., strun calwebb_image3)

  • Data models (e.g., removal of a WCS transform converter causing I/O incompatibility)

API Deprecation Policy

Note

This section only covers API changes that are not backward-compatible. Adding a new API is usually backward compatible and thus not covered here.

Occasionally, there is a need to modify or remove a given API (e.g., introduction of new algorithm or instrumentation changes). For public API (see API: Public vs Private), when such a breaking change happens, if possible, jwst would first deprecate the item being removed or renamed; this could be a input keyword, step configuration, function, class, etc.

A deprecated item would emit a DeprecationWarning via the Python warnings system (and also to the log, where appropriate). Ideally, the deprecation warning would provide at least the following information:

  • which jwst version first deprecated it, and

  • alternative or replacement, if available.

Deprecation usually cannot happen in a “patch” release (see Versioning Scheme) unless it somehow addresses critical security vulnerability or mission needs. All deprecations would be stated clearly in the API documentation and the release change log.

The deprecation period starts the moment it is first released. Ideally, it would last at least two “minor” releases, or longer if the item is high-impact. After the period elapses, then this deprecated item would be removed completely in the following “minor” release.

Impacted users (e.g., scientists or notebook maintainers) should switch away from the deprecated API early in its deprecation period, to give yourselves ample time to address downstream changes. If you think you are unable to perform this switch within the deprecation period, you could either pin to a maximum version of jwst before the API removal, or contact jwst developers to request an extension of the deprecation period. Any extension request must have sufficient justification on why it is worth the extra maintenance burden to do so.