scenic.syntax.translator

Translator turning Scenic programs into Scenario objects.

The top-level interface to Scenic is provided by two functions:

These output a Scenario object, from which scenes can be generated. See the documentation for Scenario for details.

When imported, this module hooks the Python import system so that Scenic modules can be imported using the import statement. This is primarily for the translator’s own use, but you could import Scenic modules from Python to inspect them. Because Scenic uses Python’s import system, the latter’s rules for finding modules apply, including the handling of packages.

Scenic is compiled in two main steps: translating the code into Python, and executing the resulting Python module to generate a Scenario object encoding the objects, distributions, etc. in the scenario. For details, see the function compileStream below.

Summary of Module Members

Functions

compileStream

Compile a stream of Scenic code and execute it in a namespace.

compileTranslatedTree

constructScenarioFrom

Build a Scenario object from an executed Scenic module.

executeCodeIn

Execute the final translated Python code in the given namespace.

findConstructorsIn

Find all constructors (Scenic classes) defined in a namespace.

functionForStatement

gatherBehaviorNamespacesFrom

Gather any global namespaces which could be referred to by behaviors.

nameForStatement

parseTranslatedSource

partitionByImports

Partition the tokens into blocks ending with import statements.

peek

scenarioFromFile

Compile a Scenic file into a Scenario.

scenarioFromStream

Compile a stream of Scenic code into a Scenario.

scenarioFromString

Compile a string of Scenic code into a Scenario.

storeScenarioStateIn

Post-process an executed Scenic module, extracting state from the veneer.

topLevelNamespace

Creates an environment like that of a Python script being run directly.

translateParseTree

Modify the Python AST to produce the desired Scenic semantics.

Classes

ASTSurgeon

AttributeFinder

Utility class for finding all referenced attributes of a given name.

Constructor

InfixOp

LocalFinder

Utility class for finding all local variables of a code block.

ModifierInfo

Peekable

Utility class to allow iterator lookahead.

ScenicLoader

ScenicMetaFinder

TokenTranslator

Translates a Scenic token stream into valid Python syntax.

Member Details

scenarioFromString(string, params={}, model=None, scenario=None, filename='<string>', cacheImports=False)[source]

Compile a string of Scenic code into a Scenario.

The optional filename is used for error messages.

scenarioFromFile(path, params={}, model=None, scenario=None, cacheImports=False)[source]

Compile a Scenic file into a Scenario.

Parameters
  • path (str) – path to a Scenic file

  • params (dict) – global parameters to override

  • model (str) – Scenic module to use as world model

  • scenario (str) – if there are multiple scenarios in the file, which one to use

  • cacheImports (bool) – Whether to cache any imported Scenic modules. The default behavior is to not do this, so that subsequent attempts to import such modules will cause them to be recompiled. If it is safe to cache Scenic modules across multiple compilations, set this argument to True. Then importing a Scenic module will have the same behavior as importing a Python module.

Returns

A Scenario object representing the Scenic scenario.

scenarioFromStream(stream, params={}, model=None, scenario=None, filename='<stream>', path=None, cacheImports=False)[source]

Compile a stream of Scenic code into a Scenario.

topLevelNamespace(path=None)[source]

Creates an environment like that of a Python script being run directly.

Specifically, __name__ is ‘__main__’, __file__ is the path used to invoke the script (not necessarily its absolute path), and the parent directory is added to the path so that ‘import blobbo’ will import blobbo from that directory if it exists there.

compileStream(stream, namespace, params={}, model=None, filename='<stream>')[source]

Compile a stream of Scenic code and execute it in a namespace.

The compilation procedure consists of the following main steps:

  1. Tokenize the input using the Python tokenizer.

  2. Partition the tokens into blocks separated by import statements. This is done by the partitionByImports function.

  3. Translate Scenic constructions into valid Python syntax. This is done by the TokenTranslator.

  4. Parse the resulting Python code into an AST using the Python parser.

  5. Modify the AST to achieve the desired semantics for Scenic. This is done by the translateParseTree function.

  6. Compile and execute the modified AST.

  7. After executing all blocks, extract the global state (e.g. objects). This is done by the storeScenarioStateIn function.

class Constructor(name, bases)

Bases: tuple

_asdict()

Return a new dict which maps field names to their values.

classmethod _make(iterable)

Make a new Constructor object from a sequence or iterable

_replace(**kwds)

Return a new Constructor object replacing specified fields with new values

bases

Alias for field number 1

name

Alias for field number 0

class ModifierInfo(name, terminators, contexts)[source]

Bases: tuple

Parameters
  • name (str) –

  • terminators (Tuple[str]) –

  • contexts (Optional[Tuple[str]]) –

name: str

Alias for field number 0

terminators: Tuple[str]

Alias for field number 1

contexts: Optional[Tuple[str]]

Alias for field number 2

_asdict()

Return a new dict which maps field names to their values.

classmethod _make(iterable)

Make a new ModifierInfo object from a sequence or iterable

_replace(**kwds)

Return a new ModifierInfo object replacing specified fields with new values

class InfixOp(syntax, implementation, arity, token, node, contexts)[source]

Bases: tuple

Parameters
  • syntax (str) –

  • implementation (Optional[str]) –

  • arity (int) –

  • token (Tuple[int, str]) –

  • node (_ast.AST) –

  • contexts (Optional[Tuple[str]]) –

syntax: str

Alias for field number 0

implementation: Optional[str]

Alias for field number 1

arity: int

Alias for field number 2

token: Tuple[int, str]

Alias for field number 3

node: _ast.AST

Alias for field number 4

contexts: Optional[Tuple[str]]

Alias for field number 5

_asdict()

Return a new dict which maps field names to their values.

classmethod _make(iterable)

Make a new InfixOp object from a sequence or iterable

_replace(**kwds)

Return a new InfixOp object replacing specified fields with new values

partitionByImports(tokens)[source]

Partition the tokens into blocks ending with import statements.

We avoid splitting top-level try-except statements, to allow the pattern of trying to import an optional module and catching an ImportError. If someone tries to define objects inside such a statement, woe unto them.

findConstructorsIn(namespace)[source]

Find all constructors (Scenic classes) defined in a namespace.

class Peekable(gen)[source]

Utility class to allow iterator lookahead.

class TokenTranslator(constructors=(), filename='<unknown>')[source]

Translates a Scenic token stream into valid Python syntax.

This is a stateful process because constructor (Scenic class) definitions change the way subsequent code is parsed.

translate(tokens)[source]

Do the actual translation of the token stream.

class AttributeFinder(target)[source]

Bases: ast.NodeVisitor

Utility class for finding all referenced attributes of a given name.

class LocalFinder[source]

Bases: ast.NodeVisitor

Utility class for finding all local variables of a code block.

translateParseTree(tree, constructors, filename)[source]

Modify the Python AST to produce the desired Scenic semantics.

executeCodeIn(code, namespace)[source]

Execute the final translated Python code in the given namespace.

storeScenarioStateIn(namespace, requirementSyntax)[source]

Post-process an executed Scenic module, extracting state from the veneer.

gatherBehaviorNamespacesFrom(behaviors)[source]

Gather any global namespaces which could be referred to by behaviors.

We’ll need to rebind any sampled values in them at runtime.

constructScenarioFrom(namespace, scenarioName=None)[source]

Build a Scenario object from an executed Scenic module.