crandas.script

Functionalities to record scripts.

The user can package a crandas script by first executing crandas.script.record(path=filename). Then, every query that is executed will be recorded in a script. This does not modify the output: the user still needs to be able to execute the queries, e.g. by being connected to a test environment, or by setting session.dry_run = True.

After executing all their queries, the user can run crandas.script.end(), which will package the script into a json-formatted file. The session.analyst_key is included into the file. This file can be sent to the approvers to be signed off.

After receiving the signed query file from the approvers, it can be loaded using crandas.script.load(filename). Now the user, possibly being connected to a different engine server that requires authorization, can execute the same script as they executed when recording the script. Note that exactly the same queries have to be executed as before, in the same order.

`allow_errors(session=None)`

Context manager for allowing a script to continue in case of errors

Normally, if a script is run in linear mode (see [Script][crandas.script.Script] ), and an error occurs any point during the script, then the script cannot be executed further. By running crandas commands in an allow_errors block, this behaviour is overridden for the commands in this block. In order to do this, the function must be in an allow_errors block both in during recording and execution.

Example usage:

cdf = cd.get_table("people")

# Analysis on people > 65
with cd.script.allow_errors():
    print(cdf.filter(cdf["age"]>65, threshold=10).describe())

# Analysis on people <= 65, allowed regardless of whether or
# not the previous analysis succeeded
with cd.script.allow_errors():
    print(cdf.filter(cdf["age"]<=65, threshold=10).describe())

`current_script(session=None)`

Returns the currently recording/loaded script.

`end(*, session=None)`

Denote the end of a script.

See [Script.end][crandas.script.Script.end].

`is_executing(session=None)`

Check if a script is being executed

PARAMETER	DESCRIPTION
`session`	Session in which to check; if not given, `crandas.base.session` is used TYPE: `Session(optional)` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	`True` if the session has an active script and this script is being executed

`is_recording(session=None)`

Check if a script is being recorded

PARAMETER	DESCRIPTION
`session`	Session in which to check; if not given, `crandas.base.session` is used TYPE: `Session(optional)` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	`True` if the session has an active script and this script is being recorded

`load(path, *, session=None)`

Load a script from a file for execution.

PARAMETER	DESCRIPTION
`path`	File name of script to load TYPE: `str`

`record(*, path=None, name=None, map_dummy_handles=True, analyst_key=None, session=None, include_python_script=None, include_full_script=None, include_outputs=None, linear=True)`

Start recording a new script.

Use this command before running a sequence of crandas commands. Afterwards, use end to save the script to a file (or reset to reset the script without saving). The script can subsequently be authorized by approvers. When the approved script is received, use load to load it, and then you may execute the exact same sequence of commands, in the same order, as you did when recording the script.

PARAMETER	DESCRIPTION
`path`	The path to save the script to, or a file-like object (such as the result of a call to `open`). TYPE: `str \| Path \| file-like object` DEFAULT: `None`
`name`	A name to attach to the script TYPE: `str(optional)` DEFAULT: `None`
`map_dummy_handles`	Unless the user sets this to False, this causes all hexadecimal table handles that are used during recording to map to the table name `dummy_name(handle)`. To upload tables with this name, save an object with the `dummy_for` argument, e.g., `crandas.upload_pandas_dataframe(df).save(dummy_for="<handle>")`. TYPE: `bool` DEFAULT: `True`
`analyst_key`	A script will generally include the analyst_key of the user that created the script. The user may specify a signing or verification key to include, either as a key object, or a path to load the key from disk. Alternatively, if True (the default), the current `crandas.base.session` analyst_key will be used. If False, no analyst key will be included in the script. TYPE: `VerifyKey \| SigningKey \| str \| Path \| False \| True(default)` DEFAULT: `None`
`include_python_script`	Automatically include the recorded Python script used for the analysis in the .recording file. TYPE: `bool` DEFAULT: True, the default is configurable by `config.settings.include_python_script`, see [`crandas.config`][crandas.config]
`include_full_script`	When `include_full_script` is True, include the full python script. When False, only include the analysis part of the recorded script, consisting of `script.record()` up to `script.end()`. TYPE: `bool` DEFAULT: False, the default is configurable by `config.settings.include_full_script`, see [`crandas.config`][crandas.config]
`include_outputs`	Include the outputs revealed by the recorded script on the design data. Similar outputs are revealed when the approved script is executed on production data. When `include_python_script` is False, no positional information about the outputs can be provided. TYPE: `bool` DEFAULT: True, the default is configurable by `config.settings.include_outputs`, see [`crandas.config`][crandas.config]
`linear`	Record the script in linear mode. Scripts recorded in this mode need to be executed in the same order as they were recorded, without skipping steps and without raising errors. The latter condition can be relaxed by using crandas.script.allow_errors. TYPE: `bool` DEFAULT: `True`

`reset(session=None)`

Reset the current script execution or recording (without saving the recording to file)

`save(target=None, analyst_key=None, *, session=None)`

Deprecated

Use [Script.end][crandas.script.Script.end] instead. Save the recorded script to a file.

See [Script.save][crandas.script.Script.save].

`stepless()`

Context manager to facilitate stepless recording/execution. See [crandas.script.Script][] for details on stepless queries.