synthesizer.synth_warnings

A module containing warnings and deprecation utilities.

This module contains functions and decorators for issuing warnings to the end user.

Example usage:

deprecation("x will have to be a unyt_array in future versions.")

@deprecated()
def old_function():
    pass

@deprecated("will be removed in v2.0")
def old_function():
    pass

warn("This is a warning message.")

Functions

synthesizer.synth_warnings.deprecated(message=None, category=<class 'FutureWarning'>)[source]

Decorate a function to mark it as deprecated.

This decorator will issue a warning to the end user when the function is called. The message and category can be optionally specified, if not a default message will be used and FutureWarning will be issued (which will by default warn the end user unless explicitly silenced).

Parameters:

  • message (str) – The message to be displayed to the end user. If None a default message will be used.

  • category (Warning) – The warning category to use. FutureWarning by default.

synthesizer.synth_warnings.deprecation(message, category=<class 'FutureWarning'>)[source]

Issue a deprecation warning to the end user.

A message must be specified, and a category can be optionally specified. FutureWarning will, by default, warn the end user, DeprecationWarning will only warn when the user has set the PYTHONWARNINGS environment variable, and PendingDeprecationWarning can be used for far future deprecations.

Parameters:

  • message (str) – The message to be displayed to the end user.

  • category (Warning) – The warning category to use. FutureWarning by default.

synthesizer.synth_warnings.warn(message, category=<class 'RuntimeWarning'>, stacklevel=None)[source]

Issue a warning to the end user with proper text wrapping.

A message must be specified, and a category can be optionally specified. RuntimeWarning will, by default, warn the end user, and can be silenced by setting the PYTHONWARNINGS environment variable.

This function automatically determines the appropriate stack level to point to user code rather than library internals. The message will be wrapped to fit the terminal width for better readability, accounting for the warning prefix that gets added by the warnings system.

Parameters:

  • message (str) – The message to be displayed to the end user.

  • category (Warning) – The warning category to use. RuntimeWarning by default.

  • stacklevel (int, optional) – The number of stack levels to skip when displaying the warning. If None (default), automatically determines the appropriate level to point to user code.