apache_beam.typehints.decorators module

Type hinting decorators allowing static or runtime type-checking for the SDK.

This module defines decorators which utilize the type-hints defined in ‘type_hints.py’ to allow annotation of the types of function arguments and return values.

Type-hints for functions are annotated using two separate decorators. One is for type-hinting the types of function arguments, the other for type-hinting the function return value. Type-hints can either be specified in the form of positional arguments:

@with_input_types(int, int)
def add(a, b):
  return a + b

Keyword arguments:

@with_input_types(a=int, b=int)
def add(a, b):
  return a + b

Or even a mix of both:

@with_input_types(int, b=int)
def add(a, b):
  return a + b

Example usage for type-hinting arguments only:

@with_input_types(s=str)
def to_lower(a):
  return a.lower()

Example usage for type-hinting return values only:

@with_output_types(Tuple[int, bool])
def compress_point(ec_point):
  return ec_point.x, ec_point.y < 0

Example usage for type-hinting both arguments and return values:

@with_input_types(a=int)
@with_output_types(str)
def int_to_str(a):
  return str(a)

The valid type-hint for such as function looks like the following:

@with_input_types(a=int, b=int)
def foo((a, b)):
  ...

Notice that we hint the type of each unpacked argument independently, rather than hinting the type of the tuple as a whole (Tuple[int, int]).

Optionally, type-hints can be type-checked at runtime. To toggle this behavior this module defines two functions: ‘enable_run_time_type_checking’ and ‘disable_run_time_type_checking’. NOTE: for this toggle behavior to work properly it must appear at the top of the module where all functions are defined, or before importing a module containing type-hinted functions.

apache_beam.typehints.decorators.no_annotations(fn)

Decorator that prevents Beam from using type hint annotations on a callable.

apache_beam.typehints.decorators.disable_type_annotations()

Prevent Beam from using type hint annotations to determine input and output types of transforms.

This setting applies globally.

class apache_beam.typehints.decorators.WithTypeHints(*unused_args, **unused_kwargs)

Bases: object

A mixin class that provides the ability to set and retrieve type hints.

get_type_hints()

Gets and/or initializes type hints for this object.

If type hints have not been set, attempts to initialize type hints in this order: - Using self.default_type_hints(). - Using self.__class__ type hints.

default_type_hints()

with_input_types(*arg_hints, **kwarg_hints)

with_output_types(*arg_hints, **kwarg_hints)

exception apache_beam.typehints.decorators.TypeCheckError

Bases: Exception

apache_beam.typehints.decorators.with_input_types(*positional_hints, **keyword_hints)

A decorator that type-checks defined type-hints with passed func arguments.

All type-hinted arguments can be specified using positional arguments, keyword arguments, or a mix of both. Additionaly, all function arguments must be type-hinted in totality if even one parameter is type-hinted.

Once fully decorated, if the arguments passed to the resulting function violate the type-hint constraints defined, a TypeCheckError detailing the error will be raised.

To be used as:

from apache_beam.typehints import with_input_types

@with_input_types(str)
def upper(s):
  return s.upper()

Or:

from apache_beam.typehints import with_input_types
from apache_beam.typehints import List
from apache_beam.typehints import Tuple

@with_input_types(ls=List[Tuple[int, int]])
def increment(ls):
  [(i + 1, j + 1) for (i,j) in ls]

Parameters:

• *positional_hints – Positional type-hints having identical order as the function’s formal arguments. Values for this argument must either be a built-in Python type or an instance of a TypeConstraint created by ‘indexing’ a CompositeTypeHint instance with a type parameter.
• **keyword_hints – Keyword arguments mirroring the names of the parameters to the decorated functions. The value of each keyword argument must either be one of the allowed built-in Python types, a custom class, or an instance of a TypeConstraint created by ‘indexing’ a CompositeTypeHint instance with a type parameter.

Raises:

• ValueError – If not all function arguments have corresponding type-hints specified. Or if the inner wrapper function isn’t passed a function object.
• TypeCheckError – If the any of the passed type-hint constraints are not a type or TypeConstraint instance.

Returns:

The original function decorated such that it enforces type-hint constraints for all received function arguments.

apache_beam.typehints.decorators.with_output_types(*return_type_hint, **kwargs)

A decorator that type-checks defined type-hints for return values(s).

This decorator will type-check the return value(s) of the decorated function.

Only a single type-hint is accepted to specify the return type of the return value. If the function to be decorated has multiple return values, then one should use: Tuple[type_1, type_2] to annotate the types of the return values.

If the ultimate return value for the function violates the specified type-hint a TypeCheckError will be raised detailing the type-constraint violation.

This decorator is intended to be used like:

from apache_beam.typehints import with_output_types
from apache_beam.typehints import Set

class Coordinate(object):
  def __init__(self, x, y):
    self.x = x
    self.y = y

@with_output_types(Set[Coordinate])
def parse_ints(ints):
  return {Coordinate(i, i) for i in ints}

Or with a simple type-hint:

from apache_beam.typehints import with_output_types

@with_output_types(bool)
def negate(p):
  return not p if p else p

Parameters:

• *return_type_hint – A type-hint specifying the proper return type of the function. This argument should either be a built-in Python type or an instance of a TypeConstraint created by ‘indexing’ a CompositeTypeHint.
• **kwargs – Not used.

Raises:

• ValueError – If any kwarg parameters are passed in, or the length of return_type_hint is greater than 1. Or if the inner wrapper function isn’t passed a function object.
• TypeCheckError – If the return_type_hint object is in invalid type-hint.

Returns:

The original function decorated such that it enforces type-hint constraints for all return values.