scenic.core.type_support

Support for checking Scenic types.

This module provides a system for checking that values passed to Scenic operators and functions have the expected types. The top-level function toTypes and its specializations toType, toVector, toScalar, etc. can also coerce closely-related types into the desired type in some cases. For lazily-evaluated values (random values and delayed arguments of specifiers), it may not be possible to determine the type at object creation time: in such cases these functions return a lazily-evaluated object that performs the type check either during specifier resolution or sampling as needed.

In general, the only objects which are coercible to a type T are instances of that type, together with Distribution objects whose _valueType is a type coercible to T (and therefore whose sampled value can be coerced to T). However, we also have the following exceptional rules:

• Coercible to a scalar (type float):

  • Instances of numbers.Real (coerced by calling float on them); this includes NumPy types such as numpy.single

• Coercible to a heading (type Heading):

  • Anything coercible to a scalar

  • Any type with a toHeading method (including OrientedPoint)

• Coercible to a vector (type Vector):

  • Tuples and lists of length 2 or 3

  • Any type with a toVector method (including Point)

• Coercible to a Behavior:

  • Subclasses of Behavior (coerced by calling them with no arguments)

  • None (considered to have type Behavior for convenience)

Summary of Module Members

Functions

canCoerce	Can this value be coerced into the given type?
canCoerceType	Can values of typeA be coerced into typeB?
coerce	Coerce something into the given type.
coerceToAny	Coerce something into any of the given types, raising an error if impossible.
coerceToFloat
coerceToHeading
evaluateRequiringEqualTypes	Evaluate the func, assuming thingA and thingB have the same type.
isA	Is this guaranteed to evaluate to a member of the given Scenic type?
is_typing_generic	Whether this is a pre-3.9 generic type from the typing module.
toHeading	Convert something to a heading, raising an error if impossible.
toOrientation	Convert something to an orientation, raising an error if impossible.
toScalar	Convert something to a scalar, raising an error if impossible.
toType	Convert something to a given type, raising an error if impossible.
toTypes	Convert something to any of the given types, raising an error if impossible.
toVector	Convert something to a vector, raising an error if impossible.
underlyingType	What type this value ultimately evaluates to, if we can tell.
unifierOfTypes	Most specific type unifying the given types.
unifyingType	Most specific type unifying the given values.

Classes

Heading	Dummy class used as a target for type coercions to headings.
TypeChecker	Checks that a given lazy value has one of a given list of types.
TypeEqualityChecker	Evaluates a function after checking that two lazy values have the same type.
TypecheckedDistribution	Distribution which typechecks its value at sampling time.

Exceptions

CoercionFailure

Raised by coercion functions when coercion is impossible.

Member Details

class Heading(x=0, /)

Bases: float

Dummy class used as a target for type coercions to headings.

underlyingType(thing)

What type this value ultimately evaluates to, if we can tell.

isA(thing, ty)

Is this guaranteed to evaluate to a member of the given Scenic type?

unifyingType(opts)

Most specific type unifying the given values.

unifierOfTypes(types)

Most specific type unifying the given types.

canCoerceType(typeA, typeB)

Can values of typeA be coerced into typeB?

canCoerce(thing, ty, exact=False)

Can this value be coerced into the given type?

coerce(thing, ty, error='wrong type')

Coerce something into the given type.

Used internally by toType, etc.; this function should not otherwise be called directly.

exception CoercionFailure

Bases: Exception

Raised by coercion functions when coercion is impossible.

Only used internally; will be converted to a parse error for reporting to the user.

class TypecheckedDistribution(dist, ty, errorMessage, coercer=None)

Bases: Distribution

Distribution which typechecks its value at sampling time.

Only for internal use by the typechecking system; introduced by coerce when it is unable to guarantee that a random value will have the correct type after sampling. Note that the type check is not a purely passive operation, and may actually transform the sampled value according to the coercion rules above (e.g. a sampled Point will be converted to a Vector in a context which expects the latter).

coerceToAny(thing, types, error)

Coerce something into any of the given types, raising an error if impossible.

Only for internal use by the typechecking system; called from toTypes.

Raises:

TypeError – if it is impossible to coerce the value into any of the types.

toTypes(thing, types, typeError='wrong type')

Convert something to any of the given types, raising an error if impossible.

Types are tried in the order they are given: the first one compatible with the given value is used. Coercions of closely-related types may take place as described in the module documentation above.

If the given value requires lazy evaluation, this function returns a TypeChecker object that performs the type conversion after specifier resolution.

Parameters:

• thing – Value to convert.

• types – Sequence of one or more destination types.

• typeError (str) – Message included in exception raised on failure.

Raises:

TypeError – if the given value is not one of the given types and cannot be converted to any of them.

toType(thing, ty, typeError='wrong type')

Convert something to a given type, raising an error if impossible.

Equivalent to toTypes with a single destination type.

toScalar(thing, typeError='non-scalar in scalar context')

Convert something to a scalar, raising an error if impossible.

See toTypes for details.

toHeading(thing, typeError='non-heading in heading context')

Convert something to a heading, raising an error if impossible.

See toTypes for details.

toOrientation(thing, typeError='non-orientation in orientation context')

Convert something to an orientation, raising an error if impossible.

See toTypes for details.

toVector(thing, typeError='non-vector in vector context')

Convert something to a vector, raising an error if impossible.

See toTypes for details.

evaluateRequiringEqualTypes(func, thingA, thingB, typeError='type mismatch')

Evaluate the func, assuming thingA and thingB have the same type.

If func produces a lazy value, it should not have any required properties beyond those of thingA and thingB.

Raises:

TypeError – if thingA and thingB do not have the same type.

class TypeChecker(*args, _internal=False, **kwargs)

Bases: DelayedArgument

Checks that a given lazy value has one of a given list of types.

class TypeEqualityChecker(*args, _internal=False, **kwargs)

Bases: DelayedArgument

Evaluates a function after checking that two lazy values have the same type.

is_typing_generic(tp)

Whether this is a pre-3.9 generic type from the typing module.