apache_beam.utils.annotations module

Deprecated annotations.

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

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

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

exception apache_beam.utils.annotations.BeamDeprecationWarning

Bases: 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.

apache_beam.utils.annotations.deprecated(*, label='deprecated', since, current=None, extra_message=None, 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.