Skip to content

sideffects

tuprolog.solve.sideffects

Side effects: the changes primitives make to the state of solvers.

Primitives (predicates implemented in Python, see tuprolog.solve.primitive) never change the state of the solver running them directly: the state they see (an tuprolog.solve.ExecutionContext) is immutable. Instead, along with each response, they return side effects, i.e. descriptions of changes, which the solver applies in order. This is how, e.g., assertz/1 adds clauses to the dynamic knowledge base.

Each side effect changes one part of the state, either replacing it (reset) or adding to and removing from it:

  • knowledge bases: reset_static_kb, add_static_clauses, remove_static_clauses, and the same for the dynamic knowledge base;
  • flags: set_flags, reset_flags, clear_flags;
  • libraries: load_library, unload_libraries, update_library, add_libraries, reset_libraries;
  • operators: set_operators, reset_operators, remove_operators;
  • channels: open_input_channels, reset_input_channels, close_input_channels, and the same for output channels;
  • custom data (see tuprolog.solve.data): set_persistent_data, reset_persistent_data, and the same for durable and ephemeral data.

These functions create instances of the SideEffect subclasses of the same names (e.g. AddDynamicClauses); DEFAULT_SIDE_EFFECT_FACTORY and SideEffectsBuilder are 2P-Kt's own factories of them.

Examples:

A primitive remember/1 adding a fact seen(X) to the dynamic knowledge base:

>>> from tuprolog.core import fact, struct
>>> from tuprolog.solve.library import library
>>> from tuprolog.solve.primitive import primitive
>>> from tuprolog.solve.prolog import prolog_solver
>>> @primitive
... def remember(request):
...     seen = fact(struct("seen", request.arguments[0]))
...     yield request.reply_success(None, add_dynamic_clauses(seen))
>>> solver = prolog_solver(libraries=library("my.lib", primitives={"remember/1": remember}))
>>> solver.solve_once("remember(a), remember(b)").is_yes
True
>>> list(solver.query("seen(X)"))
[{'X': 'a'}, {'X': 'b'}]
See Also

SideEffect module-attribute

SideEffect = _sideffects.SideEffect

A change to the state of a solver, returned by a primitive along with a response.

The base class of all side effects, nested in it (e.g. SideEffect.AddDynamicClauses, also re-exported by tuprolog.solve.sideffects). Its method apply_to(context) returns the tuprolog.solve.ExecutionContext resulting from applying the side effect.

ResetStaticKb module-attribute

ResetStaticKb = SideEffect.ResetStaticKb

The side effect replacing the static knowledge base with clauses.

Created by reset_static_kb.

AddStaticClauses module-attribute

AddStaticClauses = SideEffect.AddStaticClauses

The side effect adding clauses to the static knowledge base, first if on_top.

Created by add_static_clauses.

RemoveStaticClauses module-attribute

RemoveStaticClauses = SideEffect.RemoveStaticClauses

The side effect removing clauses from the static knowledge base.

Created by remove_static_clauses.

ResetDynamicKb module-attribute

ResetDynamicKb = SideEffect.ResetDynamicKb

The side effect replacing the dynamic knowledge base with clauses.

Created by reset_dynamic_kb.

AddDynamicClauses module-attribute

AddDynamicClauses = SideEffect.AddDynamicClauses

The side effect adding clauses to the dynamic knowledge base, first if on_top.

Created by add_dynamic_clauses.

RemoveDynamicClauses module-attribute

RemoveDynamicClauses = SideEffect.RemoveDynamicClauses

The side effect removing clauses from the dynamic knowledge base.

Created by remove_dynamic_clauses.

SetFlags module-attribute

SetFlags = SideEffect.SetFlags

The side effect setting flags (a map from names to terms), keeping the other flags.

Created by set_flags.

ResetFlags module-attribute

ResetFlags = SideEffect.ResetFlags

The side effect replacing all the flags with flags.

Created by reset_flags.

ClearFlags module-attribute

ClearFlags = SideEffect.ClearFlags

The side effect removing the flags with the given names.

Created by clear_flags.

LoadLibrary module-attribute

LoadLibrary = SideEffect.LoadLibrary

The side effect loading library into the solver.

Created by load_library.

UnloadLibraries module-attribute

UnloadLibraries = SideEffect.UnloadLibraries

The side effect unloading the libraries with the given aliases.

Created by unload_libraries.

UpdateLibrary module-attribute

UpdateLibrary = SideEffect.UpdateLibrary

The side effect replacing the loaded library with the alias of library.

Created by update_library.

AddLibraries module-attribute

AddLibraries = SideEffect.AddLibraries

The side effect loading the libraries of a runtime into the solver.

Created by add_libraries.

ResetRuntime module-attribute

ResetRuntime = SideEffect.ResetRuntime

The side effect replacing all the loaded libraries with libraries.

Created by reset_libraries.

SetOperators module-attribute

SetOperators = SideEffect.SetOperators

The side effect adding operators, overriding those with the same symbol and notation.

Created by set_operators.

ResetOperators module-attribute

ResetOperators = SideEffect.ResetOperators

The side effect meant to replace all the operators with operators.

Created by reset_operators.

Note

In 2P-Kt 3.0, it adds operators to the existing ones instead, like SetOperators.

RemoveOperators module-attribute

RemoveOperators = SideEffect.RemoveOperators

The side effect removing operators.

Created by remove_operators.

OpenInputChannels module-attribute

OpenInputChannels = SideEffect.OpenInputChannels

The side effect adding input channels, by alias.

Created by open_input_channels.

ResetInputChannels module-attribute

ResetInputChannels = SideEffect.ResetInputChannels

The side effect replacing all the input channels.

Created by reset_input_channels.

CloseInputChannels module-attribute

CloseInputChannels = SideEffect.CloseInputChannels

The side effect closing and removing the input channels with the given names.

Created by close_input_channels.

OpenOutputChannels module-attribute

OpenOutputChannels = SideEffect.OpenOutputChannels

The side effect adding output channels, by alias.

Created by open_output_channels.

ResetOutputChannels module-attribute

ResetOutputChannels = SideEffect.ResetOutputChannels

The side effect replacing all the output channels.

Created by reset_output_channels.

CloseOutputChannels module-attribute

CloseOutputChannels = SideEffect.CloseOutputChannels

The side effect closing and removing the output channels with the given names.

Created by close_output_channels.

SetPersistentData module-attribute

SetPersistentData = SideEffect.SetPersistentData

The side effect adding data to the persistent custom data, or replacing it if reset.

Created by set_persistent_data.

SetDurableData module-attribute

SetDurableData = SideEffect.SetDurableData

The side effect adding data to the durable custom data, or replacing it if reset.

Created by set_durable_data.

SetEphemeralData module-attribute

SetEphemeralData = SideEffect.SetEphemeralData

The side effect adding data to the ephemeral custom data, or replacing it if reset.

Created by set_ephemeral_data.

SideEffectFactory module-attribute

SideEffectFactory = _sideffects.SideEffectFactory

2P-Kt's factory of side effects, with one method per side effect (e.g. add_dynamic_clauses).

The functions of tuprolog.solve.sideffects are a more Pythonic alternative.

DEFAULT_SIDE_EFFECT_FACTORY module-attribute

DEFAULT_SIDE_EFFECT_FACTORY = SideEffectFactory.getDefault()

2P-Kt's default SideEffectFactory.

SideEffectManager module-attribute

SideEffectManager = _sideffects.SideEffectManager

A manager of the changes primitives make to the flow of resolution, i.e. the effects of cuts.

Primitives may attach one to their responses, to make resolution behave as if a cut (!/0) had been executed, i.e. discarding pending alternatives.

SideEffectsBuilder module-attribute

SideEffectsBuilder = _sideffects.SideEffectsBuilder

2P-Kt's builder of lists of side effects: a SideEffectFactory collecting what it creates.

Its build() method returns the side effects created so far, in order.

reset_static_kb

reset_static_kb(
    *clauses: Clause | Iterable[Clause],
) -> ResetStaticKb

Creates the side effect replacing the static knowledge base with the given clauses.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()

Returns:

Type Description
ResetStaticKb

The ResetStaticKb side effect.

add_static_clauses

add_static_clauses(
    *clauses: Clause | Iterable[Clause],
    on_top: bool = False,
) -> AddStaticClauses

Creates the side effect adding clauses to the static knowledge base.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()
on_top bool

Whether to add them before the existing clauses, rather than after.

False

Returns:

Type Description
AddStaticClauses

The AddStaticClauses side effect.

remove_static_clauses

remove_static_clauses(
    *clauses: Clause | Iterable[Clause],
) -> RemoveStaticClauses

Creates the side effect removing clauses from the static knowledge base.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()

Returns:

Type Description
RemoveStaticClauses

The RemoveStaticClauses side effect.

reset_dynamic_kb

reset_dynamic_kb(
    *clauses: Clause | Iterable[Clause],
) -> ResetDynamicKb

Creates the side effect replacing the dynamic knowledge base with the given clauses.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()

Returns:

Type Description
ResetDynamicKb

The ResetDynamicKb side effect.

add_dynamic_clauses

add_dynamic_clauses(
    *clauses: Clause | Iterable[Clause],
    on_top: bool = False,
) -> AddDynamicClauses

Creates the side effect adding clauses to the dynamic knowledge base, as assertz/1 does.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()
on_top bool

Whether to add them before the existing clauses (as asserta/1 does), rather than after.

False

Returns:

Type Description
AddDynamicClauses

The AddDynamicClauses side effect.

Examples:

>>> from tuprolog.core import atom, fact
>>> add_dynamic_clauses(fact(atom("a")), on_top=True)
AddDynamicClauses(clauses=[a :- true], onTop=true)

remove_dynamic_clauses

remove_dynamic_clauses(
    *clauses: Clause | Iterable[Clause],
) -> RemoveDynamicClauses

Creates the side effect removing clauses from the dynamic knowledge base.

Parameters:

Name Type Description Default
*clauses Clause | Iterable[Clause]

The clauses (tuprolog.core.Clause), as varargs or as a single iterable.

()

Returns:

Type Description
RemoveDynamicClauses

The RemoveDynamicClauses side effect.

set_flags

set_flags(
    flags: Mapping[str, Term] = {}, **kwargs: Term
) -> SetFlags

Creates the side effect setting flags, keeping the other ones.

Parameters:

Name Type Description Default
flags Mapping[str, Term]

The flags' values (terms), by name.

{}
**kwargs Term

More flags' values, by name.

{}

Returns:

Type Description
SetFlags

The SetFlags side effect.

Examples:

>>> from tuprolog.core import atom
>>> set_flags(unknown=atom("fail"))
SetFlags(flags={unknown=fail})

reset_flags

reset_flags(
    flags: Mapping[str, Term] = {}, **kwargs: Term
) -> ResetFlags

Creates the side effect replacing all the flags with the given ones.

Parameters:

Name Type Description Default
flags Mapping[str, Term]

The flags' values (terms), by name.

{}
**kwargs Term

More flags' values, by name.

{}

Returns:

Type Description
ResetFlags

The ResetFlags side effect.

clear_flags

clear_flags(*flag_names: str) -> ClearFlags

Creates the side effect removing the flags with the given names.

Parameters:

Name Type Description Default
*flag_names str

The names of the flags.

()

Returns:

Type Description
ClearFlags

The ClearFlags side effect.

Examples:

>>> clear_flags("my_flag", "other_flag")
ClearFlags(names=[my_flag, other_flag])

load_library

load_library(alias: str, library: Library) -> LoadLibrary

Creates the side effect loading a library, under the given alias.

Parameters:

Name Type Description Default
alias str

The alias of the library, e.g. my.lib.

required
library Library

The library (see tuprolog.solve.library).

required

Returns:

Type Description
LoadLibrary

The LoadLibrary side effect.

unload_libraries

unload_libraries(*aliases: str) -> UnloadLibraries

Creates the side effect unloading the libraries with the given aliases.

Parameters:

Name Type Description Default
*aliases str

The aliases of the libraries, as varargs or as a single iterable.

()

Returns:

Type Description
UnloadLibraries

The UnloadLibraries side effect.

update_library

update_library(
    alias: str, library: Library
) -> UpdateLibrary

Creates the side effect replacing the loaded library with the given alias.

Parameters:

Name Type Description Default
alias str

The alias of the library to replace.

required
library Library

The new library, loaded under alias.

required

Returns:

Type Description
UpdateLibrary

The UpdateLibrary side effect.

add_libraries

add_libraries(*libraries: Library) -> AddLibraries

Creates the side effect loading the given libraries.

Parameters:

Name Type Description Default
*libraries Library

The libraries (see tuprolog.solve.library).

()

Returns:

Type Description
AddLibraries

The AddLibraries side effect.

reset_libraries

reset_libraries(*libraries: Library) -> ResetRuntime

Creates the side effect replacing all the loaded libraries with the given ones.

Parameters:

Name Type Description Default
*libraries Library

The libraries (see tuprolog.solve.library).

()

Returns:

Type Description
ResetRuntime

The ResetRuntime side effect.

set_operators

set_operators(
    *operators: Operator | Iterable[Operator],
) -> SetOperators

Creates the side effect adding operators, as op/3 does.

Parameters:

Name Type Description Default
*operators Operator | Iterable[Operator]

The operators (tuprolog.core.operators.Operator), as varargs or as a single iterable.

()

Returns:

Type Description
SetOperators

The SetOperators side effect.

reset_operators

reset_operators(
    *operators: Operator | Iterable[Operator],
) -> ResetOperators

Creates the side effect meant to replace all the operators with the given ones.

Parameters:

Name Type Description Default
*operators Operator | Iterable[Operator]

The operators (tuprolog.core.operators.Operator), as varargs or as a single iterable.

()

Returns:

Type Description
ResetOperators

The ResetOperators side effect.

Note

In 2P-Kt 3.0, the side effect adds the operators to the existing ones instead.

remove_operators

remove_operators(
    *operators: Operator | Iterable[Operator],
) -> RemoveOperators

Creates the side effect removing operators.

Parameters:

Name Type Description Default
*operators Operator | Iterable[Operator]

The operators (tuprolog.core.operators.Operator), as varargs or as a single iterable.

()

Returns:

Type Description
RemoveOperators

The RemoveOperators side effect.

open_input_channels

open_input_channels(
    channels: Mapping[str, InputChannel] = {},
    **kwargs: InputChannel,
) -> OpenInputChannels

Creates the side effect adding input channels.

Parameters:

Name Type Description Default
channels Mapping[str, InputChannel]

The input channels (tuprolog.solve.channel.InputChannel), by alias.

{}
**kwargs InputChannel

More input channels, by alias.

{}

Returns:

Type Description
OpenInputChannels

The OpenInputChannels side effect.

reset_input_channels

reset_input_channels(
    channels: Mapping[str, InputChannel] = {},
    **kwargs: InputChannel,
) -> ResetInputChannels

Creates the side effect replacing all the input channels with the given ones.

Parameters:

Name Type Description Default
channels Mapping[str, InputChannel]

The input channels (tuprolog.solve.channel.InputChannel), by alias.

{}
**kwargs InputChannel

More input channels, by alias.

{}

Returns:

Type Description
ResetInputChannels

The ResetInputChannels side effect.

close_input_channels

close_input_channels(
    *names: str | Iterable[str],
) -> CloseInputChannels

Creates the side effect closing and removing the input channels with the given aliases.

Parameters:

Name Type Description Default
*names str | Iterable[str]

The aliases of the channels, as varargs or as a single iterable.

()

Returns:

Type Description
CloseInputChannels

The CloseInputChannels side effect.

open_output_channels

open_output_channels(
    channels: Mapping[str, OutputChannel] = {},
    **kwargs: OutputChannel,
) -> OpenOutputChannels

Creates the side effect adding output channels.

Parameters:

Name Type Description Default
channels Mapping[str, OutputChannel]

The output channels (tuprolog.solve.channel.OutputChannel), by alias.

{}
**kwargs OutputChannel

More output channels, by alias.

{}

Returns:

Type Description
OpenOutputChannels

The OpenOutputChannels side effect.

reset_output_channels

reset_output_channels(
    channels: Mapping[str, OutputChannel] = {},
    **kwargs: OutputChannel,
) -> ResetOutputChannels

Creates the side effect replacing all the output channels with the given ones.

Parameters:

Name Type Description Default
channels Mapping[str, OutputChannel]

The output channels (tuprolog.solve.channel.OutputChannel), by alias.

{}
**kwargs OutputChannel

More output channels, by alias.

{}

Returns:

Type Description
ResetOutputChannels

The ResetOutputChannels side effect.

close_output_channels

close_output_channels(
    *names: str | Iterable[str],
) -> CloseOutputChannels

Creates the side effect closing and removing the output channels with the given aliases.

Parameters:

Name Type Description Default
*names str | Iterable[str]

The aliases of the channels, as varargs or as a single iterable.

()

Returns:

Type Description
CloseOutputChannels

The CloseOutputChannels side effect.

set_persistent_data

set_persistent_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetPersistentData

Creates the side effect adding values to the persistent custom data.

The persistent custom data lives as long as the solver (see tuprolog.solve.data); the given values replace those with the same keys.

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetPersistentData

The SetPersistentData side effect.

reset_persistent_data

reset_persistent_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetPersistentData

Creates the side effect replacing the persistent custom data with the given values.

The persistent custom data lives as long as the solver (see tuprolog.solve.data).

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetPersistentData

The SetPersistentData side effect.

Examples:

>>> reset_persistent_data(counter=0)
SetPersistentData(data={counter=0}, reset=true)

set_durable_data

set_durable_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetDurableData

Creates the side effect adding values to the durable custom data.

The durable custom data lives during a query (see tuprolog.solve.data); the given values replace those with the same keys.

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetDurableData

The SetDurableData side effect.

reset_durable_data

reset_durable_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetDurableData

Creates the side effect replacing the durable custom data with the given values.

The durable custom data lives during a query (see tuprolog.solve.data).

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetDurableData

The SetDurableData side effect.

set_ephemeral_data

set_ephemeral_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetEphemeralData

Creates the side effect adding values to the ephemeral custom data.

The ephemeral custom data is the first to be discarded (see tuprolog.solve.data); the given values replace those with the same keys.

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetEphemeralData

The SetEphemeralData side effect.

reset_ephemeral_data

reset_ephemeral_data(
    data: Mapping[str, Any] = {}, **kwargs: Any
) -> SetEphemeralData

Creates the side effect replacing the ephemeral custom data with the given values.

The ephemeral custom data is the first to be discarded (see tuprolog.solve.data).

Parameters:

Name Type Description Default
data Mapping[str, Any]

The values, by key.

{}
**kwargs Any

More values, by key.

{}

Returns:

Type Description
SetEphemeralData

The SetEphemeralData side effect.