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, '=',
  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)=',
  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)=',
  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)
apache_beam.utils.annotations.annotate(label, since, current, extra_message)[source]

Decorates a function 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.
Returns:

The decorator for the function.