example on main page has an incorrect statement

[schaefer01]

Thank you for taking the time to report a bug! Your support is essential for the maintenance of this project. Please fill out the following fields to ease bug hunting and resolving this issue as soon as possible:

On the page URL: https://github.com/pytransitions/transitions?tab=readme-ov-file#diagrams

in the section that begins "Let's try again."

The example statement shows: lump.trigger('ionize') as this raises an exception

The correct example statement should be: lump.ionize()

[aleneum]

Hello @schaefer01,

lump.trigger should work since transitions adds a trigger method to each model that can be used to trigger events by name. So lump.trigger('ionize') should do the same as lump.ionize().

Could you provide a minimal reproducible example where this does not work?

Here is an example that shows how it can be used:

from transitions import Machine


class Matter(object):
    pass


lump = Matter()

states = ["solid", "liquid", "gas", "plasma"]

transitions = [
    {"trigger": "melt", "source": "solid", "dest": "liquid"},
    {"trigger": "evaporate", "source": "liquid", "dest": "gas"},
    {"trigger": "sublimate", "source": "solid", "dest": "gas"},
    {"trigger": "ionize", "source": "gas", "dest": "plasma"},
]

machine = Machine(model=lump, states=states, transitions=transitions, initial="gas")
lump.trigger("ionize")
assert lump.is_plasma()

[schaefer01]

I will add the exception today. My organization's plans for this tool are to use transitions as a state machine triggering processes running an atmospheric science radar that many scientists depend on.

rps@C02D81GJMD6W ~ % python3
Python 3.11.6 (v3.11.6:8b6ee5ba3b, Oct 2 2023, 11:18:21) [Clang 13.0.0 (clang-1300.0.29.30)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

class Matter(object):
... pass
...
lump = Matter()
from transitions import Machine
machine = Machine(model=lump, states=['solid', 'liquid', 'gas', 'plasma'], initial='solid')
lump.state
'solid'
states=['solid', 'liquid', 'gas', 'plasma']
transitions = [
... { 'trigger': 'melt', 'source': 'solid', 'dest': 'liquid' },
... { 'trigger': 'evaporate', 'source': 'liquid', 'dest': 'gas' },
... { 'trigger': 'sublimate', 'source': 'solid', 'dest': 'gas' },
... { 'trigger': 'ionize', 'source': 'gas', 'dest': 'plasma' }
... ]
machine = Machine(lump, states=states, transitions=transitions, initial='liquid')

lump.evaporate()
True
lump.state
'gas'
lump.trigger('ionize')
Traceback (most recent call last):
File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/transitions/core.py", line 942, in _get_trigger
event = self.events[trigger_name]
~~~~~~~~~~~^^^^^^^^^^^^^^
KeyError: 'ionize'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File "", line 1, in
File "/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/transitions/core.py", line 948, in _get_trigger
raise AttributeError("Do not know event named '%s'." % trigger_name)
AttributeError: Do not know event named 'ionize'.

[aleneum]

Thank you,

the problem here is that you pass lump twice to a Machine constructor. There is a lot happening under the hood here. When you pass a model (lump) to a machine, it will get decorated with convenience functions such as 'evaporate', 'ionize', etc. and 'trigger' as well. transitions does this decoration defensively which means that it checks first whether a method or variable is already defined on that object.

When you do machine = Machine(model=lump, states=['solid', 'liquid', 'gas', 'plasma'], initial='solid'), lump will get decorated with a trigger method referencing this machine. Note that this machine does not have any transitions defined. When you use the same object in machine = Machine(lump, states=states, transitions=transitions, initial='liquid') you will create another machine which will decorate 'lump' with methods such as 'ionize' since they are not yet defined on lump. However, lump.trigger is defined already and is refering to the first machine which does not have any events/transitions defined. So calling lump.trigger('ionize') will fail.

I hope this example makes this a bit more obvious.

import logging

from transitions import Machine


class Matter(object):
    pass


logging.basicConfig()

lump = Matter()

machine = Machine(
    model=lump, states=["solid", "liquid", "gas", "plasma"], initial="solid"
)
# add a unique transition on machine A
machine.add_transition("gasify", "*", "gas")
assert lump.state == "solid"
ref = lump.trigger 
try:
    # this is not (yet) defined
    lump.evaporate()
    assert False
except AttributeError:
    pass

states = ["solid", "liquid", "gas", "plasma"]
transitions = [
    {"trigger": "melt", "source": "solid", "dest": "liquid"},
    {"trigger": "evaporate", "source": "liquid", "dest": "gas"},
    {"trigger": "sublimate", "source": "solid", "dest": "gas"},
    {"trigger": "ionize", "source": "gas", "dest": "plasma"},
]


machine = Machine(lump, states=states, transitions=transitions, initial="liquid")  # this will trigger logging warnings
assert lump.evaporate()
assert ref == lump.trigger  # <-- this has not changed
assert lump.trigger("gasify")  # <-- this   
assert lump.is_gas()

Furthermore, if you use a logger as shown in this example, transitions will provide better feedback about configuration issues. This example will cause this log:

WARNING:transitions.core:Skip binding of 'trigger' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'may_trigger' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'to_solid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'may_to_solid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'to_liquid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'may_to_liquid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'to_gas' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'may_to_gas' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'to_plasma' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'may_to_plasma' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'is_solid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'is_liquid' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'is_gas' to model due to model override policy.
WARNING:transitions.core:Skip binding of 'is_plasma' to model due to model override policy.

[schaefer01]

Thank you.
I had no idea.