python - 使用 Pytransitions 时没有关于触发器的建议

Question

尝试按照此处提供的示例使用 transitions 包 https://github.com/pytransitions/transitions

由于某种原因，下面显示的两种方法都没有为注册的 evaporate() 触发器提供输入建议(至少在适用于 Windows x64 的 PyCharm 2019.1.2 中)

同时，这些触发器仍然可以使用。

如何才能在我键入时建议这些触发器？

class Matter(Machine):
    def say_hello(self): print("hello, new state!")
    def say_goodbye(self): print("goodbye, old state!")

    def __init__(self):
        states = ['solid', 'liquid', 'gas']
        Machine.__init__(self, states=states, initial='liquid')
        self.add_transition('melt', 'solid', 'liquid')

testmatter= Matter()
testmatter.add_transition('evaporate', 'liquid', 'gas')
testmatter.evaporate()
Out: True

testmatter.get_model_state(testmatter)
Out: <State('gas')@14748976>

class Matter2():
    pass
testmatter2 = Matter2()
machine  = Machine(model=testmatter2, states=['solid', 'liquid', 'gas', 'plasma'], initial='liquid')
machine.add_transition('evaporate', 'liquid', 'gas')

testmatter2.evaporate()
Out: True

Answer 1

transitions 在运行时将触发器添加到模型 (Matter) 实例。在初始化代码实际执行之前，IDE 无法预测这一点。恕我直言，这是转换工作方式的最大缺点(但恕我直言，在处理动态状态机或在运行时创建/接收的状态机时，这也是它的优势，但那是另一个故事了)

如果您使用具有代码完成功能的交互式 shell (ipython)，您将看到 evaporate (基于对模型的 __dir__ 调用)将建议:

from transitions import Machine

class Model:
    pass

model = Model()
>>> model.e  # TAB -> nothing

# model will be decorated during machine initialization
machine = Machine(model, states=['A', 'B'], 
                  transitions=[['evaporate', 'A', 'B']], initial='A')

>>> model.e  # TAB -> completion! 

但我认为这不是您计划的编码方式。那么我们该如何提示内省(introspection)呢？

最简单的解决方案:使用模型的文档字符串来宣布触发器。

from transitions import Machine

class Model:
    """My dynamically extended Model
    Attributes:
        evaporate(callable): dynamically added method
    """

model = Model()
# [1]
machine = Machine(model, states=['A', 'B'],
                  transitions=[['evaporate', 'A', 'B']], initial='A')
model.eva  # code completion! will also suggest 'evaporate' before it was added at [1]

这里的问题是 IDE 将依赖文档字符串的正确性。因此，当调用 docstring 方法(屏蔽为属性)evaparate 时，它始终会建议即使您稍后添加 evaporate。

使用 pyi 文件和 PEP484 (PyCharm 解决方法)

不幸的是，正如您正确指出的那样，PyCharm 不会考虑文档字符串中的属性来完成代码(有关更多详细信息，请参阅 this discussion)。我们需要使用另一种方法。我们可以创建所谓的 pyi 文件来为 PyCharm 提供提示。这些文件的名称与其对应的 .py 相同，但仅用于 IDE 和其他工具，不得导入(请参阅 this post )。让我们创建一个名为 sandbox.pyi

的文件

# sandbox.pyi

class Model:
    evaporate = None  # type: callable

现在让我们创建实际的代码文件 sandbox.py (我没有将我的 Playground 文件命名为“test”，因为这总是会吓到 pytest...)

# sandbox.py
from transitions import Machine

class Model:
    pass

## Having the type hints right here would enable code completion BUT
## would prevent transitions to decorate the model as it does not override 
## already defined model attributes and methods.
# class Model:
#     evaporate = None  # type: callable

model = Model()
# machine initialization
model.ev  # code completion 

这样您就可以完成代码并且转换将正确地装饰模型。缺点是您需要担心另一个文件，这可能会使您的项目变得困惑。

如果你想自动生成 pyi 文件，你可以看看 stubgen或扩展 Machine 为您生成模型的事件 stub 。

from transitions import Machine

class Model:
    pass


class PyiMachine(Machine):

    def generate_pyi(self, filename):
        with open(f'{filename}.pyi', 'w') as f:
            for model in self.models:
                f.write(f'class {model.__class__.__name__}:\n')
                for event in self.events:
                    f.write(f'    def {event}(self, *args, **kwargs) -> bool: pass\n')
                f.write('\n\n')


model = Model()
machine = PyiMachine(model, states=['A', 'B'],
                     transitions=[['evaporate', 'A', 'B']], initial='A')
machine.generate_pyi('sandbox')
# PyCharm can now correctly infer the type of success
success = model.evaporate()
model.to_A()  # A dynamically added method which is now visible thanks to the pyi file

替代方案:从文档字符串生成机器配置

类似的问题已经在转换问题跟踪器中讨论过(请参阅 https://github.com/pytransitions/transitions/issues/383 )。您还可以从模型的文档字符串生成机器配置:

import transitions
import inspect
import re


class DocMachine(transitions.Machine):
    """Parses states and transitions from model definitions"""

    # checks for 'attribute:value' pairs (including [arrays]) in docstrings
    re_pattern = re.compile(r"(\w+):\s*\[?([^\]\n]+)\]?")

    def __init__(self, model, *args, **kwargs):
        conf = {k: v for k, v in self.re_pattern.findall(model.__doc__, re.MULTILINE)}
        if 'states' not in kwargs:
            kwargs['states'] = [x.strip() for x in conf.get('states', []).split(',')]
        if 'initial' not in kwargs and 'initial' in conf:
            kwargs['initial'] = conf['initial'].strip()
        super(DocMachine, self).__init__(model, *args, **kwargs)
        for name, method in inspect.getmembers(model, predicate=inspect.ismethod):
            doc = method.__doc__ if method.__doc__ else ""
            conf = {k: v for k, v in self.re_pattern.findall(doc, re.MULTILINE)}
            # if docstring contains "source:" we assume it is a trigger definition
            if "source" not in conf:  
                continue
            else:
                conf['source'] = [s.strip() for s in conf['source'].split(', ')]
                conf['source'] = conf['source'][0] if len(conf['source']) == 1 else conf['source']
            if "dest" not in conf:
                conf['dest'] = None
            else:
                conf['dest'] = conf['dest'].strip()
            self.add_transition(trigger=name, **conf)

    # override safeguard which usually prevents accidental overrides
    def _checked_assignment(self, model, name, func):
        setattr(model, name, func)


class Model:
    """A state machine model
    states: [A, B]
    initial: A
    """

    def go(self):
        """processes information
        source: A
        dest: B
        conditions: always_true
        """

    def cycle(self):
        """an internal transition which will not exit the current state
        source: *
        """

    def always_true(self):
        """returns True... always"""
        return True

    def on_exit_B(self):  # no docstring
        raise RuntimeError("We left B. This should not happen!")


m = Model()
machine = DocMachine(m)
assert m.is_A()
m.go()
assert m.is_B()
m.cycle()
try:
    m.go()  # this will raise a MachineError since go is not defined for state B
    assert False
except transitions.MachineError:
    pass

这是一个非常简单的文档字符串到机器配置解析器，它不处理可能成为文档字符串一部分的所有可能性。它假设文档字符串包含 ("source: ") 的每个方法都应该是触发器。然而，它也解决了文档问题。使用这样的机器将确保至少存在所开发机器的一些文档。