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):
  • 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

    • 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.

coerceToBehavior

coerceToFloat

coerceToHeading

coerceToVector

evaluateRequiringEqualTypes

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

isA

Does this evaluate to a member of the given Scenic type?

toHeading

Convert something to a heading, 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.

unifyingType

Most specific type unifying the given types.

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, /)[source]

Bases: float

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

underlyingType(thing)[source]

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

isA(thing, ty)[source]

Does this evaluate to a member of the given Scenic type?

unifyingType(opts)[source]

Most specific type unifying the given types.

canCoerceType(typeA, typeB)[source]

Can values of typeA be coerced into typeB?

canCoerce(thing, ty)[source]

Can this value be coerced into the given type?

coerce(thing, ty, error='wrong type')[source]

Coerce something into the given type.

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

exception CoercionFailure[source]

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(*args, **kwargs)[source]

Bases: scenic.core.distributions.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)[source]

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

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

toTypes(thing, types, typeError='wrong type')[source]

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

RuntimeParseError – 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')[source]

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')[source]

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

See toTypes for details.

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

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

See toTypes for details.

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

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

See toTypes for details.

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

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

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

class TypeChecker(*args, _internal=False, **kwargs)[source]

Bases: scenic.core.lazy_eval.DelayedArgument

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

class TypeEqualityChecker(*args, _internal=False, **kwargs)[source]

Bases: scenic.core.lazy_eval.DelayedArgument

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