scenic.syntax.translator

Translator turning Scenic programs into Scenario objects.

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

scenarioFromString – compile a string of Scenic code;
scenarioFromFile – compile a Scenic file.

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 in order to implement the import statement. This is only for the compiler’s own use: it is not allowed to import a Scenic module from Python, and attempting to do so will fail with a ModuleNotFoundError.

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

`astToSource`
`compileStream`	Compile a stream of Scenic code and execute it in a namespace.
`compileTranslatedTree`
`constructScenarioFrom`	Build a Scenario object from an executed Scenic module.
`dump`
`executeCodeIn`	Execute the final translated Python code in the given namespace.
`gatherBehaviorNamespacesFrom`	Gather any global namespaces which could be referred to by behaviors.
`purgeModulesUnsafeToCache`	Uncache loaded modules which should not be kept after compilation.
`scenarioFromFile`	Compile a Scenic file into a `Scenario`.
`scenarioFromString`	Compile a string of Scenic code into a `Scenario`.
`scenic_path_hook`
`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.

Classes

`CompileOptions`	Internal class for capturing options used when compiling a scenario.
`ScenicFileFinder`
`ScenicLoader`

Member Details

class CompileOptions(mode2D=False, modelOverride=None, paramOverrides=<factory>, scenario=None)[source]

Internal class for capturing options used when compiling a scenario.

Parameters:

mode2D (bool) –
modelOverride (Optional[str]) –
paramOverrides (dict) –
scenario (Optional[str]) –

mode2D: bool = False: Whether or not the scenario uses 2D Compatibility Mode.

modelOverride: Optional[str] = None: Overridden world model, if any.

paramOverrides: dict: Overridden global parameters.

scenario: Optional[str] = None: Selected modular scenario, if any.

property hash: Deterministic hash saved in serialized scenes to catch option mismatches.

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

Compile a string of Scenic code into a Scenario.

The optional filename is used for error messages. Other arguments are as in scenarioFromFile.

scenarioFromFile(path, params={}, model=None, scenario=None, *, mode2D=False, **kwargs)[source]

Compile a Scenic file into a Scenario.

Parameters:

path (str) – Path to a Scenic file.
params (dict) – Global parameters to override, as a dictionary mapping parameter names to their desired values.
model (str) – Scenic module to use as world model.
scenario (str) – If there are multiple modular scenarios in the file, which one to compile; if not specified, a scenario called ‘Main’ is used if it exists.
mode2D (bool) – Whether to compile this scenario in 2D Compatibility Mode.

Returns:

A Scenario object representing the Scenic scenario.

Note for Scenic developers: this function accepts additional keyword arguments which are intended for internal use and debugging only. See _scenarioFromStream for details.

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.

purgeModulesUnsafeToCache(oldModules)[source]

Uncache loaded modules which should not be kept after compilation.

Keeping Scenic modules in sys.modules after compilation will cause subsequent attempts at compiling the same module to reuse the compiled scenario: this is usually not what is desired, since compilation can depend on external state (in particular overridden global parameters, used e.g. to specify the map for driving domain scenarios).

Parameters:: oldModules – List of names of modules loaded before compilation. These will be skipped.

compileStream(stream, namespace, compileOptions, filename)[source]

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

The compilation procedure consists of the following main steps:

Parse the Scenic code into a Scenic AST using the parser generated by pegen from scenic.gram.

Compile the Scenic AST into a Python AST with the desired semantics. This is done by the compiler, scenic.syntax.compiler.

Compile and execute the Python AST.

Extract the global state (e.g. objects). This is done by the storeScenarioStateIn function.

executeCodeIn(code, namespace)[source]: Execute the final translated Python code in the given namespace.

storeScenarioStateIn(namespace, requirementSyntax, astHash, options)[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.

_scenarioFromStream(stream, compileOptions, filename, *, scenario=None, path=None, _cacheImports=False)[source]

Compile a stream of Scenic code into a Scenario.

This method is not meant to be called directly by users of Scenic. Use the top-level functions scenarioFromFile and scenarioFromString instead.

These functions also accept the following keyword arguments, which are intended for internal use and debugging only. They should be considered unstable and are subject to modification or removal at any time.

Parameters:: _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. See purgeModulesUnsafeToCache for a more detailed discussion of the internals behind this.