lod.basics module

Defines basic objects that are used by LOD scenarios.

(This file is used both on the server, and in several external applications, for consistency. As a result, some classes and/or methods may not be relevant for your purposes.)

class lod.basics.Identifier(object_id, type, preliminary=None, name=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

A token by which objects of different types can be compared. All the objects in this file have a field like this. Identifiers can be compared using equality comparisons like == and can be used as hash keys. Corresponds to this.

id = None

An ID that uniquely identifies the object together with the type. For Rules, Programs and Symbols, this uniquely identifies the object globally. For the other objects, it identifies them only within the current ExecutionEnvironment / Scenario.

type = None

Used together with the ID.

preliminary = None

If this is not None, this Identifier belongs to a newly created object that has not been confirmed by the server, yet.

name = None

Used as an additional means of identifying an object. If both ID and name are given, the ID takes precedence. In the case of Rules and Programs, this name includes the version as well, like so: base_name#version

to_json()

Gives a JSON-like dictionary representation of this identifier. Counterpart to parse_identifier().

get_program_name_and_version_separately()

If this Identifier refers to a program and has a name, splits the name into the base name and the version and returns a tuple of both.

lod.basics.parse_identifier(dictionary)

Creates an Identifier from a JSON-like dictionary structure. Counterpart to Identifier.to_json(). Raises an InvalidParamsException if the format is incorrect.

lod.basics.create_preliminary_identifier(type, name=None)

Creates a preliminary Identifier, for use by output objects. The Identifier has its field ‘preliminary’ set to a constant defined by configure_name_for_source_of_preliminary_identifiers().

class lod.basics.Program(identifier, creator_id, name, version, is_release_version, description, required_external_domains, docker_image_name, rating_numerator, rating_count)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a Program.

identifier = None

The Identifier of this object.

creator_id = None

The ID of the developer who uploaded this Program

name = None
version = None
is_release_version = None
description = None
required_external_domains = None
docker_image_name = None
to_json()

Creates a JSON-like dictionary structure from this object. Counterpart to parse_program().

lod.basics.parse_program(dictionary)

Creates a Program from a JSON-like dictionary structure. Counterpart to Program.to_json().

class lod.basics.Symbol(identifier, name, description, private=False, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a Symbol.

identifier = None

The Identifier of this object.

name = None
description = None
private = None
creator_id = None

The ID of the developer who defined this Symbol

to_json()

Creates a JSON-like dictionary structure from this object. Counterpart to parse_symbol().

lod.basics.parse_symbol(dictionary)

Creates a Symbol from a JSON-like dictionary structure Counterpart to Symbol.to_json().

class lod.basics.Rule(identifier, creator_id, name, description, dependencies, threshold, trigger, actions, existing_variables, rating_numerator, rating_count)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a Rule.

identifier = None

The Identifier of this object.

creator_id = None

The ID of the developer who uploaded this Rule

name = None
description = None
dependencies = None
threshold = None
trigger = None
actions = None
existing_variables = None
to_json()

Returns a JSON-like representation of the Rule object. Counterpart to parse_rule().

lod.basics.parse_rule(dictionary)

Creates a Rule from a JSON-like dictionary structure. Counterpart to Rule.to_json().

class lod.basics.FileObject(identifier, file_name, creation_step, creation_index, creation_trigger=None, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a File. This does not contain the actual content of the file, it just describes the file.

identifier = None

The Identifier of this object.

file_name = None
creation_step = None

This is set by the server; values provided by the user are ignored

creation_index = None

This is set by the server; values provided by the user are ignored

creation_trigger = None

This is set by the server; values provided by the user are ignored

creator_id = None

This is set by the server; values provided by the user are ignored

to_json()

Gives a JSON-like dictionary representation of this FileObject that can be parsed as a new FileObject. Counterpart to parse_file_object().

lod.basics.parse_file_object(dictionary)

Creates a FileObject from a JSON-like dictionary structure. Counterpart to FileObject.to_json().

class lod.basics.Tag(own_identifier, arguments, symbol_name=None, comment=None, weight=None, creation_trigger=None, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a Tag. A Tag consists of a Symbol, stored here as a string, and one Identifier for each of its arguments. It also has an Identifier of its own. Optionally, it may also have a comment and a weight.

identifier = None

The Identifier of this object.

symbol_name = None
argument_identifiers = None
comment = None
weight = None
creation_trigger = None

This is set by the server; values provided by the user are ignored

creator_id = None

This is set by the server; values provided by the user are ignored

get_argument(index)

Returns the argument at the specified position.

get_arguments()

Returns all the arguments of this Tag in a list.

to_json()

Gives a JSON-like dictionary representation of this Tag. Counterpart to parse_tag().

lod.basics.parse_tag(dictionary)

Creates a Tag from a JSON-like dictionary structure. Counterpart to Tag.to_json().

class lod.basics.TagBuilder

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

A class that uses method-chaining to create a Tag.

symbol(sym)

Sets the symbol of the Tag. The symbol can be specified either as a string, a Symbol object or an Identifier.

arguments(*arguments)

Sets the arguments of the Tag. The arguments of a Tag must be specified either as Identifiers or as objects with an Identifier as a field.

comment(comment)

Sets the comment of the Tag.

weight(weight)

Sets the weight of the Tag.

to_json()

Gives a JSON-like dictionary representation of the constructed Tag.

class lod.basics.Message(identifier, message_components, visibility, creation_trigger=None, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents a Message.

identifier = None

The Identifier of this object.

message_components = None
visibility = None
creation_trigger = None

This is set by the server; values provided by the user are ignored

creator_id = None

This is set by the server; values provided by the user are ignored

to_json()

Gives a JSON-like dictionary representation of this Message that can be parsed as a new Message. Counterpart to parse_message().

lod.basics.parse_message(dictionary)

Creates a Message from a JSON-like dictionary structure Counterpart to Message.to_json().

class lod.basics.MessageBuilder(identifier=None, callback=None)

Bases: lod.basics.Message

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

A class that uses method-chaining to create a Message to the user.

add_message_component(message_component_dict)

Adds a message_component of any type by providing its dictionary representation directly. Correctness will only be verified by the server when the program has finished running, so be careful when using this.

add_text(message_text)

Adds a message_component of type ‘text’.

add_image(path_to_image_file, file_type, *args, **kwargs)

Displays an Image by turning it into HTML and displaying a message_component of type ‘html’.

add_html(html_code, external_domains=None, scenario_history=None, scenario_history_title=None, scenario_history_description=None)

Adds a message_component of type ‘html’.

add_plot(data, options=None)

Adds a message_component of type ‘plot’.

add_downloadable_file(button_text, file_to_download, scenario_history=None, scenario_history_title=None, scenario_history_description=None)

Adds a message_component of type ‘downloadable_file’.

add_request_for_rating(target, event=None, scenario_history=None, scenario_history_title=None, scenario_history_description=None)

Adds a message_component of type ‘request_for_rating’.

When adding a feedback request in this way, the event may be set to None. If it is, it defaults to the currently executed event when the server parses it.

The target and event of a feedback_request must be given as an Identifier or as an object with an ‘identifier’ field.

add_request_for_feedback(target, event=None, scenario_history=None, scenario_history_title=None, scenario_history_description=None)

Adds a message_component of type ‘request_for_feedback’.

When adding a feedback request in this way, the event may be set to None. If it is, it defaults to the currently executed event when the server parses it.

The target and event of a feedback_request must be given as an Identifier or as an object with an ‘identifier’ field.

add_email_contact_form(subject, body, scenario_history=None, scenario_history_title=None, scenario_history_description=None)

Adds a message_component of type ‘email_contact’.

set_visibility(visibility)

Sets the visibility to one of ‘all’, ‘developers’, or ‘hidden’.

finish()

Call this to finish building this Message.

class lod.basics.Event(identifier, type, args, priority=False, triggering_step=None, creation_trigger=None, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents an Event.

identifier = None

The Identifier of this object.

type = None
args = None
priority = None
triggering_step = None

This is set by the server; values provided by the user are ignored when this gets parsed by the server

creation_trigger = None

This is set by the server; values provided by the user are ignored

creator_id = None

This is set by the server; values provided by the user are ignored

set_priority(priority=True)

Mark the event as a priority. Priority events are executed before any others.

to_json()

Gives a JSON-like dictionary representation of this Event. Counterpart to parse_event().

lod.basics.parse_event(dictionary)

Creates an Event from a JSON-like dictionary structure Counterpart to Event.to_json().

class lod.basics.ProgramExecutionRequest

Bases: lod.basics.Event

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

A class that uses method-chaining to create an Event to execute a Program.

program(program_identifier)

Sets the program to execute. The program may be identified as an Identifier, as a String displaying the name of the program (in which case the latest version is picked), as a String of <name>#<version> (which identifies the version directly), or as an integer that is the program’s ID (which is unambiguous and includes the version)

argument(arg_name, object_or_identifier)

Sets a single argument of the Program. The argument’s name must be a string and the object must be a FileObject or an Identifier of same.

argument_list(arg_name, object_or_identifier_list)

Sets a single argument of the Program. The argument’s name must be a string and the object must be a FileObject or an Identifier of same.

arguments(**kwargs)

Sets multiple arguments or argument lists at once. The kwarg names become the variable names, and the kwarg values the variable values.

class lod.basics.Option(identifier, name, description, trigger, display, actions, existing_variables, creation_trigger=None, creator_id=None)

Bases: object

(Contributors should not create these objects directly. Use the functions in the file lod.py instead.)

Represents an Option.

identifier = None

The Identifier of this object.

name = None
description = None
trigger = None
display = None
actions = None
existing_variables = None
creation_trigger = None

This is set by the server; values provided by the user are ignored

creator_id = None

This is set by the server; values provided by the user are ignored

to_json()

Gives a JSON-like dictionary representation of this Option. Counterpart to parse_option().

lod.basics.parse_option(dictionary)

Creates an Option from a JSON-like dictionary structure Counterpart to Option.to_json().

lod.basics.parse_object_according_to_type(type, dictionary)

Helper function. Calls one of the other parse_x() functions, depending on the provided type.

lod.basics.parse_object_manager(dictionary)

Creates an ObjectManager from a JSON-like dictionary structure Counterpart to ObjectManager.to_json().

class lod.basics.FeedbackRequest(id, feedback_type, creation_trigger, target_identifier, event_identifier, execution_environment_id)

Bases: object

Represents a Feedback Request.

to_json()

Gives a JSON-like dictionary representation of this FeedbackRequest. Counterpart to parse_feedback_request().

lod.basics.parse_feedback_request(dictionary)

Creates a FeedbackRequest from a JSON-like dictionary structure Counterpart to FeedbackRequest.to_json().

class lod.basics.ObjectManager(execution_environment_id)

A manager to keep track of all of the objects in use in a scenario, as well as the relations between them. This acts as a single source-of-truth for all objects in use by an active scenario. It keeps a history of when each object was added as well.

It is also used to make communicating and synchronizing knowledge between server and local executions easier because this object has a JSON-like representation.

When using the ObjectManager locally in your own programs, it is only useful for looking up the history of what has already happened in this scenario. On the server, it is also used for making changes. However, any changes made to a local ObjectManager are discarded by the server, so you shouldn’t change anything directly. Instead, use the module lod.lod for making changes.

identifier_exists(identifier)

Returns whether or not a given Identifier is already registered.

get_object_for_identifier(identifier)

Returns the object corresponding to an Identifier, if it has been registered. If the identifier is a preliminary one, uses the corresponding real one instead, if it exists.

get_step_number_of_addition(object_or_identifier)

Returns the number of the step at which an object has first been registered or created.

get_symbol_from_name(symbol_name)

Takes the name of a symbol as a string and returns the corresponding Symbol object if it has been loaded yet. If it has not been loaded yet, raises an exception.

find_latest_tag(*args, **kwargs)

Returns the latest Tag matching the specified conditions, or None if none exist. Uses ObjectManager.check_tag_conditions() to check conditions.

get_tags(*args, **kwargs)

Returns a list of all Tags matching the specified conditions. Uses ObjectManager.check_tag_conditions() to check conditions.

check_tag_conditions(candidate_tag_or_identifier, symbol_name, min_weight=None, max_weight=None, comment=None, step=None, arguments=[], nullified=False)

Checks if a given Tag matches all conditions specified here. Returns True if it does, otherwise False.

  • symbol_name : The Tag’s symbol must match the given string.
  • comment : The Tag’s comment must match the given string exactly.
  • min_weight and max_weight : boundaries for the weight.
  • step : The Tag was created in the specified step (given as a number).
  • arguments : A list of arguments. None values are skipped. For each not-None value in this list, the Tag must have that object as an argument at that position. The objects may be given as objects or as their Identifier.
  • nullified : If None, this is ignored. Otherwise the Tag only matches if either this argument is True and the Tag is nullified, or this argument is False and the Tag is not nullified.
get_tag_arguments(tag)

Returns a list of the Arguments of a given Tag. The Tag may be given either as a Tag object or as an Identifier of a Tag.

get_tag_backreferences(obj_or_identifier)

Returns an ordered list of all Tags that have the given object as an argument. The object may be given either as an object or as that object’s Identifier.

get_all_objects(object_type=None, step_of_creation=None)

Return a list of Objects stored in this ObjectManager. Can be filtered by type, and by the number of the step in which the object was created.

get_current_step()

Returns the current step, as an integer.

get_current_event()

Based on the current_step and the ordered_list_of_event_identifiers, return the current Event. If the queue of events has been exceeded, returns None.

get_creator(obj_or_identifier, get_event_only=False)

Gets the Rule, Option, Program or Event that is responsible for creating an object. This is based on the Event of the step in which the object was added. If the Event is of type ‘execute_rule’, ‘execute_option’, or ‘execute_program’, returns the corresponding object, otherwise returns the event itself.

is_nullified(obj_or_identifier)

Returns True if the target object has a !nullify Tag on it, otherwise returns False.

is_reserved(obj_or_identifier, reserve_tag_symbol=None)

Checks an object to find out if there is a reserve_ Tag targeting it in its first position. reserve_ Tags with !nullify on them don’t count. Optionally, you can specify a particular reserve_ Tag instead of any arbitrary one.

rule_or_option_is_deactivated(rule_or_option_identifier)

Checks a Rule or Option to find out if it is marked with a non-nullified !deactivate_rule_or_option. Can raise an InvalidParamsException if the object is not a Rule or Option.

requirement_is_provided(requirement_tag_or_identifier)

Checks a require_ Tag to find out if the requirement is provided, using the !provide Tag. !provide Tags with !nullify on them don’t count. Can raise an InvalidParamsException.

task_is_finished(task_tag_or_identifier)

Checks a task_ Tag to find out if the task is finished. Looks at all require_ Tags of the task_ Tag. If they are all marked with !provide, the task is considered finished. Note that !nullify Tags can nullify both the require_ Tags and the !provide Tags. Can raise an InvalidParamsException.

get_signal_strengths()

returns a list of signals and their strengths, for the purpose of determining which Rules to load from the server and in what order to test the rules for matching arguments. The output has the format [(target_symbol_name, target_comment, target_weight_multiplier), …]

get_options_with_confidence_levels()

Returns a list of Options that could potentially be executed, along with their confidence levels. The output has the format [(option, confidence), …]

to_json()

Gives a JSON-like dictionary representation of this ObjectManager that can be parsed as a new ObjectManager. Counterpart to parse_object_manager().