使用 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 无法预测到这一点。恕我直言，这是工作方式的最大缺点transitions（但同样，在处理动态状态机或在运行时创建/接收的状态机时，这也是它的优势，但那是另一回事）

如果您使用具有代码完成功能的交互式 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! 

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

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

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 没有考虑用于代码完成的文档字符串中的属性（有关更多详细信息，请参阅此讨论）。我们需要使用另一种方法。我们可以创建所谓的pyi文件来为 PyCharm 提供提示。这些文件的名称与其.py对应文件的名称相同，但仅用于 IDE 和其他工具，不得导入（请参阅此帖子）。让我们创建一个名为的文件sandbox.pyi

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]

现在让我们创建实际的代码文件sandbox.py（我没有将我的 Playground 文件命名为“test”，因为这总是让 pytest 感到震惊......）

# sandbox.pyi

class Model:
    evaporate = None  # type: callable

这样您就可以完成代码transitions并正确装饰模型。缺点是您需要担心另一个文件可能会使您的项目混乱。

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

# 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 

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

转换的问题跟踪器中已经讨论了类似的问题（参见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

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