pyomo.common.deprecation

This module provides utilities for deprecating functionality.

deprecated([msg, logger, version, remove_in]) Decorator to indicate that a function, method or class is deprecated.
deprecation_warning(msg[, logger, version, ...]) Standardized formatter for deprecation warnings
relocated_module_attribute(local, target, ...) Provide a deprecation path for moved / renamed module attributes
RenamedClass(name, bases, classdict, *args, ...) Metaclass to provide a deprecation path for renamed classes
pyomo.common.deprecation.in_testing_environment()[source]

Return True if we are currently running in a “testing” environment

This currently includes if nose, nose2, pytest, or Sphinx are running (imported).

pyomo.common.deprecation.deprecation_warning(msg, logger=None, version=None, remove_in=None, calling_frame=None)[source]

Standardized formatter for deprecation warnings

This is a standardized routine for formatting deprecation warnings so that things look consistent and “nice”.

Parameters:
  • msg (str) – the deprecation message to format
  • logger (str) – the logger to use for emitting the warning (default: the calling pyomo package, or “pyomo”)
  • version (str) – [required] the version in which the decorated object was deprecated. General practice is to set version to ‘’ or ‘TBD’ during development and update it to the actual release as part of the release process.
  • remove_in (str) – the version in which the decorated object will be removed from the code.
  • calling_frame (frame) – the original frame context that triggered the deprecation warning.
pyomo.common.deprecation.deprecated(msg=None, logger=None, version=None, remove_in=None)[source]

Decorator to indicate that a function, method or class is deprecated.

This decorator will cause a warning to be logged when the wrapped function or method is called, or when the deprecated class is constructed. This decorator also updates the target object’s docstring to indicate that it is deprecated.

Parameters:
  • msg (str) – a custom deprecation message (default: “This {function|class} has been deprecated and may be removed in a future release.”)
  • logger (str) – the logger to use for emitting the warning (default: the calling pyomo package, or “pyomo”)
  • version (str) – [required] the version in which the decorated object was deprecated. General practice is to set version to ‘’ or ‘TBD’ during development and update it to the actual release as part of the release process.
  • remove_in (str) – the version in which the decorated object will be removed from the code.
pyomo.common.deprecation.relocated_module_attribute(local, target, version, remove_in=None)[source]

Provide a deprecation path for moved / renamed module attributes

This function declares that a local module attribute has been moved to another location. For Python 3.7+, it leverages a module.__getattr__ method to manage the deferred import of the object from the new location (on request), as well as emitting the deprecation warning.

It contains backports of the __getattr__ functionality for earlier versions of Python (although the implementation for 3.5+ is more efficient that the implementation for 2.7+)

Parameters:
  • local (str) – The original (local) name of the relocated attribute
  • target (str) – The new absolute import name of the relocated attribute
  • version (str) – The Pyomo version when this move was released (passed to deprecation_warning)
  • remove_in (str) – The Pyomo version when this deprecation path will be removed (passed to deprecation_warning)
class pyomo.common.deprecation.RenamedClass(name, bases, classdict, *args, **kwargs)[source]

Metaclass to provide a deprecation path for renamed classes

This metaclass provides a mechanism for renaming old classes while still preserving isinstance / issubclass relationships.

Example

>>> from pyomo.common.deprecation import RenamedClass
>>> class NewClass(object):
...     pass
>>> class OldClass(metaclass=RenamedClass):
...     __renamed__new_class__ = NewClass
...     __renamed__version__ = '6.0'

Deriving from the old class generates a warning:

>>> class DerivedOldClass(OldClass):
...     pass
WARNING: DEPRECATED: Declaring class 'DerivedOldClass' derived from
    'OldClass'. The class 'OldClass' has been renamed to 'NewClass'.
    (deprecated in 6.0) ...

As does instantiating the old class:

>>> old = OldClass()
WARNING: DEPRECATED: Instantiating class 'OldClass'.  The class
    'OldClass' has been renamed to 'NewClass'.  (deprecated in 6.0) ...

Finally, isinstance and issubclass still work, for example:

>>> isinstance(old, NewClass)
True
>>> class NewSubclass(NewClass):
...     pass
>>> new = NewSubclass()
>>> isinstance(new, OldClass)
WARNING: DEPRECATED: Checking type relative to 'OldClass'.  The class
    'OldClass' has been renamed to 'NewClass'.  (deprecated in 6.0) ...
True