apache_beam.utils.annotations module

Deprecated and experimental annotations.

Experimental: Signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release. Note that the presence of this annotation implies nothing about the quality or performance of the API in question, only the fact that the API or behavior may change in any way.

Deprecated: Signifies that users are discouraged from using a public API typically because a better alternative exists, and the current form might be removed in a future version.

Usage: For internal use only; no backwards-compatibility guarantees.

Annotations come in two flavors: deprecated and experimental

The ‘deprecated’ annotation requires a ‘since” parameter to specify what version deprecated it. Both ‘deprecated’ and ‘experimental’ annotations can specify the current recommended version to use by means of a ‘current’ parameter.

The following example illustrates how to annotate coexisting versions of the same function ‘multiply’.:

def multiply(arg1, arg2):
  print(arg1, '*', arg2, '=', end=' ')
  return arg1*arg2

# This annotation marks ‘old_multiply’ as deprecated since ‘v.1’ and suggests # using ‘multiply’ instead.:

@deprecated(since='v.1', current='multiply')
def old_multiply(arg1, arg2):
  result = 0
  for i in xrange(arg1):
      result += arg2
  print(arg1, '*', arg2, '(the old way)=', end=' ')
  return result

# This annotation marks ‘exp_multiply’ as experimental and suggests # using ‘multiply’ instead.:

@experimental(since='v.1', current='multiply')
def exp_multiply(arg1, arg2):
  print(arg1, '*', arg2, '(the experimental way)=', end=' ')
  return (arg1*arg2)*(arg1/arg2)*(arg2/arg1)

# If a custom message is needed, on both annotations types the # arg custom_message can be used.:

@experimental(since='v.1', current='multiply'
              custom_message='Experimental since %since%
                              Please use %current% insted.')
def exp_multiply(arg1, arg2):
  print(arg1, '*', arg2, '(the experimental way)=', end=' ')
  return (arg1*arg2)*(arg1/arg2)*(arg2/arg1)

# Set a warning filter to control how often warnings are produced.:

warnings.simplefilter("always")
print(multiply(5, 6))
print(old_multiply(5,6))
print(exp_multiply(5,6))

exception apache_beam.utils.annotations.BeamDeprecationWarning

Bases: exceptions.DeprecationWarning

Beam-specific deprecation warnings.

apache_beam.utils.annotations.annotate(label, since, current, extra_message, custom_message=None)

Decorates an API with a deprecated or experimental annotation.

Parameters:

• label – the kind of annotation (‘deprecated’ or ‘experimental’).
• since – the version that causes the annotation.
• current – the suggested replacement function.
• extra_message – an optional additional message.
• custom_message – if the default message does not suffice, the message can be changed using this argument. A string whit replacement tokens. A replecement string is were the previus args will be located on the custom message. The following replacement strings can be used: %name% -> API.__name__ %since% -> since (Mandatory for the decapreted annotation) %current% -> current %extra% -> extra_message

Returns:

The decorator for the API.