Ausgabe der neuen DB Einträge

venv/lib/python3.9/site-packages/automat/__init__.py

@@ -0,0 +1,8 @@
+# -*- test-case-name: automat -*-
+from ._methodical import MethodicalMachine
+from ._core import NoTransition
+
+__all__ = [
+    'MethodicalMachine',
+    'NoTransition',
+]

venv/lib/python3.9/site-packages/automat/_core.py

@@ -0,0 +1,165 @@
+# -*- test-case-name: automat._test.test_core -*-
+
+"""
+A core state-machine abstraction.
+
+Perhaps something that could be replaced with or integrated into machinist.
+"""
+
+from itertools import chain
+
+_NO_STATE = "<no state>"
+
+
+class NoTransition(Exception):
+    """
+    A finite state machine in C{state} has no transition for C{symbol}.
+
+    @param state: the finite state machine's state at the time of the
+        illegal transition.
+
+    @param symbol: the input symbol for which no transition exists.
+    """
+
+    def __init__(self, state, symbol):
+        self.state = state
+        self.symbol = symbol
+        super(Exception, self).__init__(
+            "no transition for {} in {}".format(symbol, state)
+        )
+
+
+class Automaton(object):
+    """
+    A declaration of a finite state machine.
+
+    Note that this is not the machine itself; it is immutable.
+    """
+
+    def __init__(self):
+        """
+        Initialize the set of transitions and the initial state.
+        """
+        self._initialState = _NO_STATE
+        self._transitions = set()
+
+
+    @property
+    def initialState(self):
+        """
+        Return this automaton's initial state.
+        """
+        return self._initialState
+
+
+    @initialState.setter
+    def initialState(self, state):
+        """
+        Set this automaton's initial state.  Raises a ValueError if
+        this automaton already has an initial state.
+        """
+
+        if self._initialState is not _NO_STATE:
+            raise ValueError(
+                "initial state already set to {}".format(self._initialState))
+
+        self._initialState = state
+
+
+    def addTransition(self, inState, inputSymbol, outState, outputSymbols):
+        """
+        Add the given transition to the outputSymbol. Raise ValueError if
+        there is already a transition with the same inState and inputSymbol.
+        """
+        # keeping self._transitions in a flat list makes addTransition
+        # O(n^2), but state machines don't tend to have hundreds of
+        # transitions.
+        for (anInState, anInputSymbol, anOutState, _) in self._transitions:
+            if (anInState == inState and anInputSymbol == inputSymbol):
+                raise ValueError(
+                    "already have transition from {} via {}".format(inState, inputSymbol))
+        self._transitions.add(
+            (inState, inputSymbol, outState, tuple(outputSymbols))
+        )
+
+
+    def allTransitions(self):
+        """
+        All transitions.
+        """
+        return frozenset(self._transitions)
+
+
+    def inputAlphabet(self):
+        """
+        The full set of symbols acceptable to this automaton.
+        """
+        return {inputSymbol for (inState, inputSymbol, outState,
+                                 outputSymbol) in self._transitions}
+
+
+    def outputAlphabet(self):
+        """
+        The full set of symbols which can be produced by this automaton.
+        """
+        return set(
+            chain.from_iterable(
+                outputSymbols for
+                (inState, inputSymbol, outState, outputSymbols)
+                in self._transitions
+            )
+        )
+
+
+    def states(self):
+        """
+        All valid states; "Q" in the mathematical description of a state
+        machine.
+        """
+        return frozenset(
+            chain.from_iterable(
+                (inState, outState)
+                for
+                (inState, inputSymbol, outState, outputSymbol)
+                in self._transitions
+            )
+        )
+
+
+    def outputForInput(self, inState, inputSymbol):
+        """
+        A 2-tuple of (outState, outputSymbols) for inputSymbol.
+        """
+        for (anInState, anInputSymbol,
+             outState, outputSymbols) in self._transitions:
+            if (inState, inputSymbol) == (anInState, anInputSymbol):
+                return (outState, list(outputSymbols))
+        raise NoTransition(state=inState, symbol=inputSymbol)
+
+
+class Transitioner(object):
+    """
+    The combination of a current state and an L{Automaton}.
+    """
+
+    def __init__(self, automaton, initialState):
+        self._automaton = automaton
+        self._state = initialState
+        self._tracer = None
+
+    def setTrace(self, tracer):
+        self._tracer = tracer
+
+    def transition(self, inputSymbol):
+        """
+        Transition between states, returning any outputs.
+        """
+        outState, outputSymbols = self._automaton.outputForInput(self._state,
+                                                                 inputSymbol)
+        outTracer = None
+        if self._tracer:
+            outTracer = self._tracer(self._state._name(),
+                                     inputSymbol._name(),
+                                     outState._name())
+        self._state = outState
+        return (outputSymbols, outTracer)

venv/lib/python3.9/site-packages/automat/_discover.py

@@ -0,0 +1,144 @@
+import collections
+import inspect
+from automat import MethodicalMachine
+from twisted.python.modules import PythonModule, getModule
+
+
+def isOriginalLocation(attr):
+    """
+    Attempt to discover if this appearance of a PythonAttribute
+    representing a class refers to the module where that class was
+    defined.
+    """
+    sourceModule = inspect.getmodule(attr.load())
+    if sourceModule is None:
+        return False
+
+    currentModule = attr
+    while not isinstance(currentModule, PythonModule):
+        currentModule = currentModule.onObject
+
+    return currentModule.name == sourceModule.__name__
+
+
+def findMachinesViaWrapper(within):
+    """
+    Recursively yield L{MethodicalMachine}s and their FQPNs within a
+    L{PythonModule} or a L{twisted.python.modules.PythonAttribute}
+    wrapper object.
+
+    Note that L{PythonModule}s may refer to packages, as well.
+
+    The discovery heuristic considers L{MethodicalMachine} instances
+    that are module-level attributes or class-level attributes
+    accessible from module scope.  Machines inside nested classes will
+    be discovered, but those returned from functions or methods will not be.
+
+    @type within: L{PythonModule} or L{twisted.python.modules.PythonAttribute}
+    @param within: Where to start the search.
+
+    @return: a generator which yields FQPN, L{MethodicalMachine} pairs.
+    """
+    queue = collections.deque([within])
+    visited = set()
+
+    while queue:
+        attr = queue.pop()
+        value = attr.load()
+
+        if isinstance(value, MethodicalMachine) and value not in visited:
+            visited.add(value)
+            yield attr.name, value
+        elif (inspect.isclass(value) and isOriginalLocation(attr) and
+              value not in visited):
+            visited.add(value)
+            queue.extendleft(attr.iterAttributes())
+        elif isinstance(attr, PythonModule) and value not in visited:
+            visited.add(value)
+            queue.extendleft(attr.iterAttributes())
+            queue.extendleft(attr.iterModules())
+
+
+class InvalidFQPN(Exception):
+    """
+    The given FQPN was not a dot-separated list of Python objects.
+    """
+
+
+class NoModule(InvalidFQPN):
+    """
+    A prefix of the FQPN was not an importable module or package.
+    """
+
+
+class NoObject(InvalidFQPN):
+    """
+    A suffix of the FQPN was not an accessible object
+    """
+
+
+def wrapFQPN(fqpn):
+    """
+    Given an FQPN, retrieve the object via the global Python module
+    namespace and wrap it with a L{PythonModule} or a
+    L{twisted.python.modules.PythonAttribute}.
+    """
+    # largely cribbed from t.p.reflect.namedAny
+
+    if not fqpn:
+        raise InvalidFQPN("FQPN was empty")
+
+    components = collections.deque(fqpn.split('.'))
+
+    if '' in components:
+        raise InvalidFQPN(
+            "name must be a string giving a '.'-separated list of Python "
+            "identifiers, not %r" % (fqpn,))
+
+    component = components.popleft()
+    try:
+        module = getModule(component)
+    except KeyError:
+        raise NoModule(component)
+
+    # find the bottom-most module
+    while components:
+        component = components.popleft()
+        try:
+            module = module[component]
+        except KeyError:
+            components.appendleft(component)
+            break
+        else:
+            module.load()
+    else:
+        return module
+
+    # find the bottom-most attribute
+    attribute = module
+    for component in components:
+        try:
+            attribute = next(child for child in attribute.iterAttributes()
+                             if child.name.rsplit('.', 1)[-1] == component)
+        except StopIteration:
+            raise NoObject('{}.{}'.format(attribute.name, component))
+
+    return attribute
+
+
+def findMachines(fqpn):
+    """
+    Recursively yield L{MethodicalMachine}s and their FQPNs in and
+    under the a Python object specified by an FQPN.
+
+    The discovery heuristic considers L{MethodicalMachine} instances
+    that are module-level attributes or class-level attributes
+    accessible from module scope.  Machines inside nested classes will
+    be discovered, but those returned from functions or methods will not be.
+
+    @type within: an FQPN
+    @param within: Where to start the search.
+
+    @return: a generator which yields FQPN, L{MethodicalMachine} pairs.
+    """
+    return findMachinesViaWrapper(wrapFQPN(fqpn))

venv/lib/python3.9/site-packages/automat/_introspection.py

@@ -0,0 +1,45 @@
+"""
+Python introspection helpers.
+"""
+
+from types import CodeType as code, FunctionType as function
+
+
+def copycode(template, changes):
+    names = [
+        "argcount", "nlocals", "stacksize", "flags", "code", "consts",
+        "names", "varnames", "filename", "name", "firstlineno", "lnotab",
+        "freevars", "cellvars"
+    ]
+    if hasattr(code, "co_kwonlyargcount"):
+        names.insert(1, "kwonlyargcount")
+    if hasattr(code, "co_posonlyargcount"):
+        # PEP 570 added "positional only arguments"
+        names.insert(1, "posonlyargcount")
+    values = [
+        changes.get(name, getattr(template, "co_" + name))
+        for name in names
+    ]
+    return code(*values)
+
+
+
+def copyfunction(template, funcchanges, codechanges):
+    names = [
+        "globals", "name", "defaults", "closure",
+    ]
+    values = [
+        funcchanges.get(name, getattr(template, "__" + name + "__"))
+        for name in names
+    ]
+    return function(copycode(template.__code__, codechanges), *values)
+
+
+def preserveName(f):
+    """
+    Preserve the name of the given function on the decorated function.
+    """
+    def decorator(decorated):
+        return copyfunction(decorated,
+                            dict(name=f.__name__), dict(name=f.__name__))
+    return decorator

venv/lib/python3.9/site-packages/automat/_methodical.py

@@ -0,0 +1,474 @@
+# -*- test-case-name: automat._test.test_methodical -*-
+
+import collections
+from functools import wraps
+from itertools import count
+
+try:
+    # Python 3
+    from inspect import getfullargspec as getArgsSpec
+except ImportError:
+    # Python 2
+    from inspect import getargspec as getArgsSpec
+
+import attr
+import six
+
+from ._core import Transitioner, Automaton
+from ._introspection import preserveName
+
+
+ArgSpec = collections.namedtuple('ArgSpec', ['args', 'varargs', 'varkw',
+                                             'defaults', 'kwonlyargs',
+                                             'kwonlydefaults', 'annotations'])
+
+
+def _getArgSpec(func):
+    """
+    Normalize inspect.ArgSpec across python versions
+    and convert mutable attributes to immutable types.
+
+    :param Callable func: A function.
+    :return: The function's ArgSpec.
+    :rtype: ArgSpec
+    """
+    spec = getArgsSpec(func)
+    return ArgSpec(
+        args=tuple(spec.args),
+        varargs=spec.varargs,
+        varkw=spec.varkw if six.PY3 else spec.keywords,
+        defaults=spec.defaults if spec.defaults else (),
+        kwonlyargs=tuple(spec.kwonlyargs) if six.PY3 else (),
+        kwonlydefaults=(
+            tuple(spec.kwonlydefaults.items())
+            if spec.kwonlydefaults else ()
+        ) if six.PY3 else (),
+        annotations=tuple(spec.annotations.items()) if six.PY3 else (),
+    )
+
+
+def _getArgNames(spec):
+    """
+    Get the name of all arguments defined in a function signature.
+
+    The name of * and ** arguments is normalized to "*args" and "**kwargs".
+
+    :param ArgSpec spec: A function to interrogate for a signature.
+    :return: The set of all argument names in `func`s signature.
+    :rtype: Set[str]
+    """
+    return set(
+        spec.args
+        + spec.kwonlyargs
+        + (('*args',) if spec.varargs else ())
+        + (('**kwargs',) if spec.varkw else ())
+        + spec.annotations
+    )
+
+
+def _keywords_only(f):
+    """
+    Decorate a function so all its arguments must be passed by keyword.
+
+    A useful utility for decorators that take arguments so that they don't
+    accidentally get passed the thing they're decorating as their first
+    argument.
+
+    Only works for methods right now.
+    """
+    @wraps(f)
+    def g(self, **kw):
+        return f(self, **kw)
+    return g
+
+
+@attr.s(frozen=True)
+class MethodicalState(object):
+    """
+    A state for a L{MethodicalMachine}.
+    """
+    machine = attr.ib(repr=False)
+    method = attr.ib()
+    serialized = attr.ib(repr=False)
+
+    def upon(self, input, enter, outputs, collector=list):
+        """
+        Declare a state transition within the :class:`automat.MethodicalMachine`
+        associated with this :class:`automat.MethodicalState`:
+        upon the receipt of the `input`, enter the `state`,
+        emitting each output in `outputs`.
+
+        :param MethodicalInput input: The input triggering a state transition.
+        :param MethodicalState enter: The resulting state.
+        :param Iterable[MethodicalOutput] outputs: The outputs to be triggered
+            as a result of the declared state transition.
+        :param Callable collector: The function to be used when collecting
+            output return values.
+
+        :raises TypeError: if any of the `outputs` signatures do not match
+            the `inputs` signature.
+        :raises ValueError: if the state transition from `self` via `input`
+            has already been defined.
+        """
+        inputArgs = _getArgNames(input.argSpec)
+        for output in outputs:
+            outputArgs = _getArgNames(output.argSpec)
+            if not outputArgs.issubset(inputArgs):
+                raise TypeError(
+                    "method {input} signature {inputSignature} "
+                    "does not match output {output} "
+                    "signature {outputSignature}".format(
+                        input=input.method.__name__,
+                        output=output.method.__name__,
+                        inputSignature=getArgsSpec(input.method),
+                        outputSignature=getArgsSpec(output.method),
+                ))
+        self.machine._oneTransition(self, input, enter, outputs, collector)
+
+    def _name(self):
+        return self.method.__name__
+
+
+def _transitionerFromInstance(oself, symbol, automaton):
+    """
+    Get a L{Transitioner}
+    """
+    transitioner = getattr(oself, symbol, None)
+    if transitioner is None:
+        transitioner = Transitioner(
+            automaton,
+            automaton.initialState,
+        )
+        setattr(oself, symbol, transitioner)
+    return transitioner
+
+
+def _empty():
+    pass
+
+def _docstring():
+    """docstring"""
+
+def assertNoCode(inst, attribute, f):
+    # The function body must be empty, i.e. "pass" or "return None", which
+    # both yield the same bytecode: LOAD_CONST (None), RETURN_VALUE. We also
+    # accept functions with only a docstring, which yields slightly different
+    # bytecode, because the "None" is put in a different constant slot.
+
+    # Unfortunately, this does not catch function bodies that return a
+    # constant value, e.g. "return 1", because their code is identical to a
+    # "return None". They differ in the contents of their constant table, but
+    # checking that would require us to parse the bytecode, find the index
+    # being returned, then making sure the table has a None at that index.
+
+    if f.__code__.co_code not in (_empty.__code__.co_code,
+                                  _docstring.__code__.co_code):
+        raise ValueError("function body must be empty")
+
+
+def _filterArgs(args, kwargs, inputSpec, outputSpec):
+    """
+    Filter out arguments that were passed to input that output won't accept.
+
+    :param tuple args: The *args that input received.
+    :param dict kwargs: The **kwargs that input received.
+    :param ArgSpec inputSpec: The input's arg spec.
+    :param ArgSpec outputSpec: The output's arg spec.
+    :return: The args and kwargs that output will accept.
+    :rtype: Tuple[tuple, dict]
+    """
+    named_args = tuple(zip(inputSpec.args[1:], args))
+    if outputSpec.varargs:
+        # Only return all args if the output accepts *args.
+        return_args = args
+    else:
+        # Filter out arguments that don't appear
+        # in the output's method signature.
+        return_args = [v for n, v in named_args if n in outputSpec.args]
+
+    # Get any of input's default arguments that were not passed.
+    passed_arg_names = tuple(kwargs)
+    for name, value in named_args:
+        passed_arg_names += (name, value)
+    defaults = zip(inputSpec.args[::-1], inputSpec.defaults[::-1])
+    full_kwargs = {n: v for n, v in defaults if n not in passed_arg_names}
+    full_kwargs.update(kwargs)
+
+    if outputSpec.varkw:
+        # Only pass all kwargs if the output method accepts **kwargs.
+        return_kwargs = full_kwargs
+    else:
+        # Filter out names that the output method does not accept.
+        all_accepted_names = outputSpec.args[1:] + outputSpec.kwonlyargs
+        return_kwargs = {n: v for n, v in full_kwargs.items()
+                         if n in all_accepted_names}
+
+    return return_args, return_kwargs
+
+
+@attr.s(eq=False, hash=False)
+class MethodicalInput(object):
+    """
+    An input for a L{MethodicalMachine}.
+    """
+    automaton = attr.ib(repr=False)
+    method = attr.ib(validator=assertNoCode)
+    symbol = attr.ib(repr=False)
+    collectors = attr.ib(default=attr.Factory(dict), repr=False)
+    argSpec = attr.ib(init=False, repr=False)
+
+    @argSpec.default
+    def _buildArgSpec(self):
+        return _getArgSpec(self.method)
+
+    def __get__(self, oself, type=None):
+        """
+        Return a function that takes no arguments and returns values returned
+        by output functions produced by the given L{MethodicalInput} in
+        C{oself}'s current state.
+        """
+        transitioner = _transitionerFromInstance(oself, self.symbol,
+                                                 self.automaton)
+        @preserveName(self.method)
+        @wraps(self.method)
+        def doInput(*args, **kwargs):
+            self.method(oself, *args, **kwargs)
+            previousState = transitioner._state
+            (outputs, outTracer) = transitioner.transition(self)
+            collector = self.collectors[previousState]
+            values = []
+            for output in outputs:
+                if outTracer:
+                    outTracer(output._name())
+                a, k = _filterArgs(args, kwargs, self.argSpec, output.argSpec)
+                value = output(oself, *a, **k)
+                values.append(value)
+            return collector(values)
+        return doInput
+
+    def _name(self):
+        return self.method.__name__
+
+
+@attr.s(frozen=True)
+class MethodicalOutput(object):
+    """
+    An output for a L{MethodicalMachine}.
+    """
+    machine = attr.ib(repr=False)
+    method = attr.ib()
+    argSpec = attr.ib(init=False, repr=False)
+
+    @argSpec.default
+    def _buildArgSpec(self):
+        return _getArgSpec(self.method)
+
+    def __get__(self, oself, type=None):
+        """
+        Outputs are private, so raise an exception when we attempt to get one.
+        """
+        raise AttributeError(
+            "{cls}.{method} is a state-machine output method; "
+            "to produce this output, call an input method instead.".format(
+                cls=type.__name__,
+                method=self.method.__name__
+            )
+        )
+
+
+    def __call__(self, oself, *args, **kwargs):
+        """
+        Call the underlying method.
+        """
+        return self.method(oself, *args, **kwargs)
+
+    def _name(self):
+        return self.method.__name__
+
+@attr.s(eq=False, hash=False)
+class MethodicalTracer(object):
+    automaton = attr.ib(repr=False)
+    symbol = attr.ib(repr=False)
+
+
+    def __get__(self, oself, type=None):
+        transitioner = _transitionerFromInstance(oself, self.symbol,
+                                                 self.automaton)
+        def setTrace(tracer):
+            transitioner.setTrace(tracer)
+        return setTrace
+
+
+
+counter = count()
+def gensym():
+    """
+    Create a unique Python identifier.
+    """
+    return "_symbol_" + str(next(counter))
+
+
+
+class MethodicalMachine(object):
+    """
+    A :class:`MethodicalMachine` is an interface to an `Automaton`
+    that uses methods on a class.
+    """
+
+    def __init__(self):
+        self._automaton = Automaton()
+        self._reducers = {}
+        self._symbol = gensym()
+
+
+    def __get__(self, oself, type=None):
+        """
+        L{MethodicalMachine} is an implementation detail for setting up
+        class-level state; applications should never need to access it on an
+        instance.
+        """
+        if oself is not None:
+            raise AttributeError(
+                "MethodicalMachine is an implementation detail.")
+        return self
+
+
+    @_keywords_only
+    def state(self, initial=False, terminal=False,
+              serialized=None):
+        """
+        Declare a state, possibly an initial state or a terminal state.
+
+        This is a decorator for methods, but it will modify the method so as
+        not to be callable any more.
+
+        :param bool initial: is this state the initial state?
+            Only one state on this :class:`automat.MethodicalMachine`
+            may be an initial state; more than one is an error.
+
+        :param bool terminal: Is this state a terminal state?
+            i.e. a state that the machine can end up in?
+            (This is purely informational at this point.)
+
+        :param Hashable serialized: a serializable value
+            to be used to represent this state to external systems.
+            This value should be hashable;
+            :py:func:`unicode` is a good type to use.
+        """
+        def decorator(stateMethod):
+            state = MethodicalState(machine=self,
+                                    method=stateMethod,
+                                    serialized=serialized)
+            if initial:
+                self._automaton.initialState = state
+            return state
+        return decorator
+
+
+    @_keywords_only
+    def input(self):
+        """
+        Declare an input.
+
+        This is a decorator for methods.
+        """
+        def decorator(inputMethod):
+            return MethodicalInput(automaton=self._automaton,
+                                   method=inputMethod,
+                                   symbol=self._symbol)
+        return decorator
+
+
+    @_keywords_only
+    def output(self):
+        """
+        Declare an output.
+
+        This is a decorator for methods.
+
+        This method will be called when the state machine transitions to this
+        state as specified in the decorated `output` method.
+        """
+        def decorator(outputMethod):
+            return MethodicalOutput(machine=self, method=outputMethod)
+        return decorator
+
+
+    def _oneTransition(self, startState, inputToken, endState, outputTokens,
+                       collector):
+        """
+        See L{MethodicalState.upon}.
+        """
+        # FIXME: tests for all of this (some of it is wrong)
+        # if not isinstance(startState, MethodicalState):
+        #     raise NotImplementedError("start state {} isn't a state"
+        #                               .format(startState))
+        # if not isinstance(inputToken, MethodicalInput):
+        #     raise NotImplementedError("start state {} isn't an input"
+        #                               .format(inputToken))
+        # if not isinstance(endState, MethodicalState):
+        #     raise NotImplementedError("end state {} isn't a state"
+        #                               .format(startState))
+        # for output in outputTokens:
+        #     if not isinstance(endState, MethodicalState):
+        #         raise NotImplementedError("output state {} isn't a state"
+        #                                   .format(endState))
+        self._automaton.addTransition(startState, inputToken, endState,
+                                      tuple(outputTokens))
+        inputToken.collectors[startState] = collector
+
+
+    @_keywords_only
+    def serializer(self):
+        """
+
+        """
+        def decorator(decoratee):
+            @wraps(decoratee)
+            def serialize(oself):
+                transitioner = _transitionerFromInstance(oself, self._symbol,
+                                                         self._automaton)
+                return decoratee(oself, transitioner._state.serialized)
+            return serialize
+        return decorator
+
+    @_keywords_only
+    def unserializer(self):
+        """
+
+        """
+        def decorator(decoratee):
+            @wraps(decoratee)
+            def unserialize(oself, *args, **kwargs):
+                state = decoratee(oself, *args, **kwargs)
+                mapping = {}
+                for eachState in self._automaton.states():
+                    mapping[eachState.serialized] = eachState
+                transitioner = _transitionerFromInstance(
+                    oself, self._symbol, self._automaton)
+                transitioner._state = mapping[state]
+                return None # it's on purpose
+            return unserialize
+        return decorator
+
+    @property
+    def _setTrace(self):
+        return MethodicalTracer(self._automaton, self._symbol)
+
+    def asDigraph(self):
+        """
+        Generate a L{graphviz.Digraph} that represents this machine's
+        states and transitions.
+
+        @return: L{graphviz.Digraph} object; for more information, please
+            see the documentation for
+            U{graphviz<https://graphviz.readthedocs.io/>}
+
+        """
+        from ._visualize import makeDigraph
+        return makeDigraph(
+            self._automaton,
+            stateAsString=lambda state: state.method.__name__,
+            inputAsString=lambda input: input.method.__name__,
+            outputAsString=lambda output: output.method.__name__,
+        )

venv/lib/python3.9/site-packages/automat/_test/test_core.py

@@ -0,0 +1,86 @@
+
+from .._core import Automaton, NoTransition
+
+from unittest import TestCase
+
+class CoreTests(TestCase):
+    """
+    Tests for Automat's (currently private, implementation detail) core.
+    """
+
+    def test_NoTransition(self):
+        """
+        A L{NoTransition} exception describes the state and input symbol
+        that caused it.
+        """
+        # NoTransition requires two arguments
+        with self.assertRaises(TypeError):
+            NoTransition()
+
+        state = "current-state"
+        symbol = "transitionless-symbol"
+        noTransitionException = NoTransition(state=state, symbol=symbol)
+
+        self.assertIs(noTransitionException.symbol, symbol)
+
+        self.assertIn(state, str(noTransitionException))
+        self.assertIn(symbol, str(noTransitionException))
+
+
+    def test_noOutputForInput(self):
+        """
+        L{Automaton.outputForInput} raises L{NoTransition} if no
+        transition for that input is defined.
+        """
+        a = Automaton()
+        self.assertRaises(NoTransition, a.outputForInput,
+                          "no-state", "no-symbol")
+
+
+    def test_oneTransition(self):
+        """
+        L{Automaton.addTransition} adds its input symbol to
+        L{Automaton.inputAlphabet}, all its outputs to
+        L{Automaton.outputAlphabet}, and causes L{Automaton.outputForInput} to
+        start returning the new state and output symbols.
+        """
+        a = Automaton()
+        a.addTransition("beginning", "begin", "ending", ["end"])
+        self.assertEqual(a.inputAlphabet(), {"begin"})
+        self.assertEqual(a.outputAlphabet(), {"end"})
+        self.assertEqual(a.outputForInput("beginning", "begin"),
+                         ("ending", ["end"]))
+        self.assertEqual(a.states(), {"beginning", "ending"})
+
+
+    def test_oneTransition_nonIterableOutputs(self):
+        """
+        L{Automaton.addTransition} raises a TypeError when given outputs
+        that aren't iterable and doesn't add any transitions.
+        """
+        a = Automaton()
+        nonIterableOutputs = 1
+        self.assertRaises(
+            TypeError,
+            a.addTransition,
+            "fromState", "viaSymbol", "toState", nonIterableOutputs)
+        self.assertFalse(a.inputAlphabet())
+        self.assertFalse(a.outputAlphabet())
+        self.assertFalse(a.states())
+        self.assertFalse(a.allTransitions())
+
+
+    def test_initialState(self):
+        """
+        L{Automaton.initialState} is a descriptor that sets the initial
+        state if it's not yet set, and raises L{ValueError} if it is.
+
+        """
+        a = Automaton()
+        a.initialState = "a state"
+        self.assertEqual(a.initialState, "a state")
+        with self.assertRaises(ValueError):
+            a.initialState = "another state"
+
+
+# FIXME: addTransition for transition that's been added before

venv/lib/python3.9/site-packages/automat/_test/test_discover.py

@@ -0,0 +1,609 @@
+import operator
+import os
+import shutil
+import sys
+import textwrap
+import tempfile
+from unittest import skipIf, TestCase
+
+import six
+
+
+def isTwistedInstalled():
+    try:
+        __import__('twisted')
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+class _WritesPythonModules(TestCase):
+    """
+    A helper that enables generating Python module test fixtures.
+    """
+
+    def setUp(self):
+        super(_WritesPythonModules, self).setUp()
+
+        from twisted.python.modules import getModule, PythonPath
+        from twisted.python.filepath import FilePath
+
+        self.getModule = getModule
+        self.PythonPath = PythonPath
+        self.FilePath = FilePath
+
+        self.originalSysModules = set(sys.modules.keys())
+        self.savedSysPath = sys.path[:]
+
+        self.pathDir = tempfile.mkdtemp()
+        self.makeImportable(self.pathDir)
+
+    def tearDown(self):
+        super(_WritesPythonModules, self).tearDown()
+
+        sys.path[:] = self.savedSysPath
+        modulesToDelete = six.viewkeys(sys.modules) - self.originalSysModules
+        for module in modulesToDelete:
+            del sys.modules[module]
+
+        shutil.rmtree(self.pathDir)
+
+    def makeImportable(self, path):
+        sys.path.append(path)
+
+    def writeSourceInto(self, source, path, moduleName):
+        directory = self.FilePath(path)
+
+        module = directory.child(moduleName)
+        # FilePath always opens a file in binary mode - but that will
+        # break on Python 3
+        with open(module.path, 'w') as f:
+            f.write(textwrap.dedent(source))
+
+        return self.PythonPath([directory.path])
+
+    def makeModule(self, source, path, moduleName):
+        pythonModuleName, _ = os.path.splitext(moduleName)
+        return self.writeSourceInto(source, path, moduleName)[pythonModuleName]
+
+    def attributesAsDict(self, hasIterAttributes):
+        return {attr.name: attr for attr in hasIterAttributes.iterAttributes()}
+
+    def loadModuleAsDict(self, module):
+        module.load()
+        return self.attributesAsDict(module)
+
+    def makeModuleAsDict(self, source, path, name):
+        return self.loadModuleAsDict(self.makeModule(source, path, name))
+
+
+@skipIf(not isTwistedInstalled(), "Twisted is not installed.")
+class OriginalLocationTests(_WritesPythonModules):
+    """
+    Tests that L{isOriginalLocation} detects when a
+    L{PythonAttribute}'s FQPN refers to an object inside the module
+    where it was defined.
+
+    For example: A L{twisted.python.modules.PythonAttribute} with a
+    name of 'foo.bar' that refers to a 'bar' object defined in module
+    'baz' does *not* refer to bar's original location, while a
+    L{PythonAttribute} with a name of 'baz.bar' does.
+
+    """
+    def setUp(self):
+        super(OriginalLocationTests, self).setUp()
+        from .._discover import isOriginalLocation
+        self.isOriginalLocation = isOriginalLocation
+
+    def test_failsWithNoModule(self):
+        """
+        L{isOriginalLocation} returns False when the attribute refers to an
+        object whose source module cannot be determined.
+        """
+        source = """\
+        class Fake(object):
+            pass
+        hasEmptyModule = Fake()
+        hasEmptyModule.__module__ = None
+        """
+
+        moduleDict = self.makeModuleAsDict(source,
+                                           self.pathDir,
+                                           'empty_module_attr.py')
+
+        self.assertFalse(self.isOriginalLocation(
+            moduleDict['empty_module_attr.hasEmptyModule']))
+
+    def test_failsWithDifferentModule(self):
+        """
+        L{isOriginalLocation} returns False when the attribute refers to
+        an object outside of the module where that object was defined.
+        """
+        originalSource = """\
+        class ImportThisClass(object):
+            pass
+        importThisObject = ImportThisClass()
+        importThisNestingObject = ImportThisClass()
+        importThisNestingObject.nestedObject = ImportThisClass()
+        """
+
+        importingSource = """\
+        from original import (ImportThisClass,
+                              importThisObject,
+                              importThisNestingObject)
+        """
+
+        self.makeModule(originalSource, self.pathDir, 'original.py')
+        importingDict = self.makeModuleAsDict(importingSource,
+                                              self.pathDir,
+                                              'importing.py')
+        self.assertFalse(
+            self.isOriginalLocation(
+                importingDict['importing.ImportThisClass']))
+        self.assertFalse(
+            self.isOriginalLocation(
+                importingDict['importing.importThisObject']))
+
+        nestingObject = importingDict['importing.importThisNestingObject']
+        nestingObjectDict = self.attributesAsDict(nestingObject)
+        nestedObject = nestingObjectDict[
+            'importing.importThisNestingObject.nestedObject']
+
+        self.assertFalse(self.isOriginalLocation(nestedObject))
+
+    def test_succeedsWithSameModule(self):
+        """
+        L{isOriginalLocation} returns True when the attribute refers to an
+        object inside the module where that object was defined.
+        """
+        mSource = textwrap.dedent("""
+        class ThisClassWasDefinedHere(object):
+            pass
+        anObject = ThisClassWasDefinedHere()
+        aNestingObject = ThisClassWasDefinedHere()
+        aNestingObject.nestedObject = ThisClassWasDefinedHere()
+        """)
+        mDict = self.makeModuleAsDict(mSource, self.pathDir, 'm.py')
+        self.assertTrue(self.isOriginalLocation(
+            mDict['m.ThisClassWasDefinedHere']))
+        self.assertTrue(self.isOriginalLocation(mDict['m.aNestingObject']))
+
+        nestingObject = mDict['m.aNestingObject']
+        nestingObjectDict = self.attributesAsDict(nestingObject)
+        nestedObject = nestingObjectDict['m.aNestingObject.nestedObject']
+
+        self.assertTrue(self.isOriginalLocation(nestedObject))
+
+
+@skipIf(not isTwistedInstalled(), "Twisted is not installed.")
+class FindMachinesViaWrapperTests(_WritesPythonModules):
+    """
+    L{findMachinesViaWrapper} recursively yields FQPN,
+    L{MethodicalMachine} pairs in and under a given
+    L{twisted.python.modules.PythonModule} or
+    L{twisted.python.modules.PythonAttribute}.
+    """
+    TEST_MODULE_SOURCE = """
+    from automat import MethodicalMachine
+
+
+    class PythonClass(object):
+        _classMachine = MethodicalMachine()
+
+        class NestedClass(object):
+            _nestedClassMachine = MethodicalMachine()
+
+        ignoredAttribute = "I am ignored."
+
+        def ignoredMethod(self):
+            "I am also ignored."
+
+    rootLevelMachine = MethodicalMachine()
+    ignoredPythonObject = PythonClass()
+    anotherIgnoredPythonObject = "I am ignored."
+    """
+
+    def setUp(self):
+        super(FindMachinesViaWrapperTests, self).setUp()
+        from .._discover import findMachinesViaWrapper
+        self.findMachinesViaWrapper = findMachinesViaWrapper
+
+    def test_yieldsMachine(self):
+        """
+        When given a L{twisted.python.modules.PythonAttribute} that refers
+        directly to a L{MethodicalMachine}, L{findMachinesViaWrapper}
+        yields that machine and its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        rootMachine = MethodicalMachine()
+        """
+
+        moduleDict = self.makeModuleAsDict(source, self.pathDir, 'root.py')
+        rootMachine = moduleDict['root.rootMachine']
+        self.assertIn(('root.rootMachine', rootMachine.load()),
+                      list(self.findMachinesViaWrapper(rootMachine)))
+
+    def test_yieldsMachineInClass(self):
+        """
+        When given a L{twisted.python.modules.PythonAttribute} that refers
+        to a class that contains a L{MethodicalMachine} as a class
+        variable, L{findMachinesViaWrapper} yields that machine and
+        its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        class PythonClass(object):
+            _classMachine = MethodicalMachine()
+        """
+        moduleDict = self.makeModuleAsDict(source, self.pathDir, 'clsmod.py')
+        PythonClass = moduleDict['clsmod.PythonClass']
+        self.assertIn(('clsmod.PythonClass._classMachine',
+                       PythonClass.load()._classMachine),
+                      list(self.findMachinesViaWrapper(PythonClass)))
+
+    def test_yieldsMachineInNestedClass(self):
+        """
+        When given a L{twisted.python.modules.PythonAttribute} that refers
+        to a nested class that contains a L{MethodicalMachine} as a
+        class variable, L{findMachinesViaWrapper} yields that machine
+        and its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        class PythonClass(object):
+            class NestedClass(object):
+                _classMachine = MethodicalMachine()
+        """
+        moduleDict = self.makeModuleAsDict(source,
+                                           self.pathDir,
+                                           'nestedcls.py')
+
+        PythonClass = moduleDict['nestedcls.PythonClass']
+        self.assertIn(('nestedcls.PythonClass.NestedClass._classMachine',
+                       PythonClass.load().NestedClass._classMachine),
+                      list(self.findMachinesViaWrapper(PythonClass)))
+
+    def test_yieldsMachineInModule(self):
+        """
+        When given a L{twisted.python.modules.PythonModule} that refers to
+        a module that contains a L{MethodicalMachine},
+        L{findMachinesViaWrapper} yields that machine and its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        rootMachine = MethodicalMachine()
+        """
+        module = self.makeModule(source, self.pathDir, 'root.py')
+        rootMachine = self.loadModuleAsDict(module)['root.rootMachine'].load()
+        self.assertIn(('root.rootMachine', rootMachine),
+                      list(self.findMachinesViaWrapper(module)))
+
+    def test_yieldsMachineInClassInModule(self):
+        """
+        When given a L{twisted.python.modules.PythonModule} that refers to
+        the original module of a class containing a
+        L{MethodicalMachine}, L{findMachinesViaWrapper} yields that
+        machine and its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        class PythonClass(object):
+            _classMachine = MethodicalMachine()
+        """
+        module = self.makeModule(source, self.pathDir, 'clsmod.py')
+        PythonClass = self.loadModuleAsDict(
+            module)['clsmod.PythonClass'].load()
+        self.assertIn(('clsmod.PythonClass._classMachine',
+                       PythonClass._classMachine),
+                      list(self.findMachinesViaWrapper(module)))
+
+    def test_yieldsMachineInNestedClassInModule(self):
+        """
+        When given a L{twisted.python.modules.PythonModule} that refers to
+        the original module of a nested class containing a
+        L{MethodicalMachine}, L{findMachinesViaWrapper} yields that
+        machine and its FQPN.
+        """
+        source = """\
+        from automat import MethodicalMachine
+
+        class PythonClass(object):
+            class NestedClass(object):
+                _classMachine = MethodicalMachine()
+        """
+        module = self.makeModule(source, self.pathDir, 'nestedcls.py')
+        PythonClass = self.loadModuleAsDict(
+            module)['nestedcls.PythonClass'].load()
+
+        self.assertIn(('nestedcls.PythonClass.NestedClass._classMachine',
+                       PythonClass.NestedClass._classMachine),
+                      list(self.findMachinesViaWrapper(module)))
+
+    def test_ignoresImportedClass(self):
+        """
+        When given a L{twisted.python.modules.PythonAttribute} that refers
+        to a class imported from another module, any
+        L{MethodicalMachine}s on that class are ignored.
+
+        This behavior ensures that a machine is only discovered on a
+        class when visiting the module where that class was defined.
+        """
+        originalSource = """
+        from automat import MethodicalMachine
+
+        class PythonClass(object):
+            _classMachine = MethodicalMachine()
+        """
+
+        importingSource = """
+        from original import PythonClass
+        """
+
+        self.makeModule(originalSource, self.pathDir, 'original.py')
+        importingModule = self.makeModule(importingSource,
+                                          self.pathDir,
+                                          'importing.py')
+
+        self.assertFalse(list(self.findMachinesViaWrapper(importingModule)))
+
+    def test_descendsIntoPackages(self):
+        """
+        L{findMachinesViaWrapper} descends into packages to discover
+        machines.
+        """
+        pythonPath = self.PythonPath([self.pathDir])
+        package = self.FilePath(self.pathDir).child("test_package")
+        package.makedirs()
+        package.child('__init__.py').touch()
+
+        source = """
+        from automat import MethodicalMachine
+
+
+        class PythonClass(object):
+            _classMachine = MethodicalMachine()
+
+
+        rootMachine = MethodicalMachine()
+        """
+        self.makeModule(source, package.path, 'module.py')
+
+        test_package = pythonPath['test_package']
+        machines = sorted(self.findMachinesViaWrapper(test_package),
+                          key=operator.itemgetter(0))
+
+        moduleDict = self.loadModuleAsDict(test_package['module'])
+        rootMachine = moduleDict['test_package.module.rootMachine'].load()
+        PythonClass = moduleDict['test_package.module.PythonClass'].load()
+
+        expectedMachines = sorted(
+            [('test_package.module.rootMachine',
+              rootMachine),
+             ('test_package.module.PythonClass._classMachine',
+              PythonClass._classMachine)], key=operator.itemgetter(0))
+
+        self.assertEqual(expectedMachines, machines)
+
+    def test_infiniteLoop(self):
+        """
+        L{findMachinesViaWrapper} ignores infinite loops.
+
+        Note this test can't fail - it can only run forever!
+        """
+        source = """
+        class InfiniteLoop(object):
+            pass
+
+        InfiniteLoop.loop = InfiniteLoop
+        """
+        module = self.makeModule(source, self.pathDir, 'loop.py')
+        self.assertFalse(list(self.findMachinesViaWrapper(module)))
+
+
+@skipIf(not isTwistedInstalled(), "Twisted is not installed.")
+class WrapFQPNTests(TestCase):
+    """
+    Tests that ensure L{wrapFQPN} loads the
+    L{twisted.python.modules.PythonModule} or
+    L{twisted.python.modules.PythonAttribute} for a given FQPN.
+    """
+
+    def setUp(self):
+        from twisted.python.modules import PythonModule, PythonAttribute
+        from .._discover import wrapFQPN, InvalidFQPN, NoModule, NoObject
+
+        self.PythonModule = PythonModule
+        self.PythonAttribute = PythonAttribute
+        self.wrapFQPN = wrapFQPN
+        self.InvalidFQPN = InvalidFQPN
+        self.NoModule = NoModule
+        self.NoObject = NoObject
+
+    def assertModuleWrapperRefersTo(self, moduleWrapper, module):
+        """
+        Assert that a L{twisted.python.modules.PythonModule} refers to a
+        particular Python module.
+        """
+        self.assertIsInstance(moduleWrapper, self.PythonModule)
+        self.assertEqual(moduleWrapper.name, module.__name__)
+        self.assertIs(moduleWrapper.load(), module)
+
+    def assertAttributeWrapperRefersTo(self, attributeWrapper, fqpn, obj):
+        """
+        Assert that a L{twisted.python.modules.PythonAttribute} refers to a
+        particular Python object.
+        """
+        self.assertIsInstance(attributeWrapper, self.PythonAttribute)
+        self.assertEqual(attributeWrapper.name, fqpn)
+        self.assertIs(attributeWrapper.load(), obj)
+
+    def test_failsWithEmptyFQPN(self):
+        """
+        L{wrapFQPN} raises L{InvalidFQPN} when given an empty string.
+        """
+        with self.assertRaises(self.InvalidFQPN):
+            self.wrapFQPN('')
+
+    def test_failsWithBadDotting(self):
+        """"
+        L{wrapFQPN} raises L{InvalidFQPN} when given a badly-dotted
+        FQPN.  (e.g., x..y).
+        """
+        for bad in ('.fails', 'fails.', 'this..fails'):
+            with self.assertRaises(self.InvalidFQPN):
+                self.wrapFQPN(bad)
+
+    def test_singleModule(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonModule}
+        referring to the single module a dotless FQPN describes.
+        """
+        import os
+
+        moduleWrapper = self.wrapFQPN('os')
+
+        self.assertIsInstance(moduleWrapper, self.PythonModule)
+        self.assertIs(moduleWrapper.load(), os)
+
+    def test_failsWithMissingSingleModuleOrPackage(self):
+        """
+        L{wrapFQPN} raises L{NoModule} when given a dotless FQPN that does
+        not refer to a module or package.
+        """
+        with self.assertRaises(self.NoModule):
+            self.wrapFQPN("this is not an acceptable name!")
+
+    def test_singlePackage(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonModule}
+        referring to the single package a dotless FQPN describes.
+        """
+        import xml
+        self.assertModuleWrapperRefersTo(self.wrapFQPN('xml'), xml)
+
+    def test_multiplePackages(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonModule}
+        referring to the deepest package described by dotted FQPN.
+        """
+        import xml.etree
+        self.assertModuleWrapperRefersTo(self.wrapFQPN('xml.etree'), xml.etree)
+
+    def test_multiplePackagesFinalModule(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonModule}
+        referring to the deepest module described by dotted FQPN.
+        """
+        import xml.etree.ElementTree
+        self.assertModuleWrapperRefersTo(
+            self.wrapFQPN('xml.etree.ElementTree'), xml.etree.ElementTree)
+
+    def test_singleModuleObject(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonAttribute}
+        referring to the deepest object an FQPN names, traversing one module.
+        """
+        import os
+        self.assertAttributeWrapperRefersTo(
+            self.wrapFQPN('os.path'), 'os.path', os.path)
+
+    def test_multiplePackagesObject(self):
+        """
+        L{wrapFQPN} returns a L{twisted.python.modules.PythonAttribute}
+        referring to the deepest object described by an FQPN,
+        descending through several packages.
+        """
+        import xml.etree.ElementTree
+        import automat
+
+        for fqpn, obj in [('xml.etree.ElementTree.fromstring',
+                           xml.etree.ElementTree.fromstring),
+                          ('automat.MethodicalMachine.__doc__',
+                           automat.MethodicalMachine.__doc__)]:
+            self.assertAttributeWrapperRefersTo(
+                self.wrapFQPN(fqpn), fqpn, obj)
+
+    def test_failsWithMultiplePackagesMissingModuleOrPackage(self):
+        """
+        L{wrapFQPN} raises L{NoObject} when given an FQPN that contains a
+        missing attribute, module, or package.
+        """
+        for bad in ('xml.etree.nope!',
+                    'xml.etree.nope!.but.the.rest.is.believable'):
+            with self.assertRaises(self.NoObject):
+                self.wrapFQPN(bad)
+
+
+@skipIf(not isTwistedInstalled(), "Twisted is not installed.")
+class FindMachinesIntegrationTests(_WritesPythonModules):
+    """
+    Integration tests to check that L{findMachines} yields all
+    machines discoverable at or below an FQPN.
+    """
+
+    SOURCE = """
+    from automat import MethodicalMachine
+
+    class PythonClass(object):
+        _machine = MethodicalMachine()
+        ignored = "i am ignored"
+
+    rootLevel = MethodicalMachine()
+
+    ignored = "i am ignored"
+    """
+
+    def setUp(self):
+        super(FindMachinesIntegrationTests, self).setUp()
+        from .._discover import findMachines
+
+        self.findMachines = findMachines
+
+        packageDir = self.FilePath(self.pathDir).child("test_package")
+        packageDir.makedirs()
+        self.pythonPath = self.PythonPath([self.pathDir])
+        self.writeSourceInto(self.SOURCE, packageDir.path, '__init__.py')
+
+        subPackageDir = packageDir.child('subpackage')
+        subPackageDir.makedirs()
+        subPackageDir.child('__init__.py').touch()
+
+        self.makeModule(self.SOURCE, subPackageDir.path, 'module.py')
+
+        self.packageDict = self.loadModuleAsDict(
+            self.pythonPath['test_package'])
+        self.moduleDict = self.loadModuleAsDict(
+            self.pythonPath['test_package']['subpackage']['module'])
+
+    def test_discoverAll(self):
+        """
+        Given a top-level package FQPN, L{findMachines} discovers all
+        L{MethodicalMachine} instances in and below it.
+        """
+        machines = sorted(self.findMachines('test_package'),
+                          key=operator.itemgetter(0))
+
+        tpRootLevel = self.packageDict['test_package.rootLevel'].load()
+        tpPythonClass = self.packageDict['test_package.PythonClass'].load()
+
+        mRLAttr = self.moduleDict['test_package.subpackage.module.rootLevel']
+        mRootLevel = mRLAttr.load()
+        mPCAttr = self.moduleDict['test_package.subpackage.module.PythonClass']
+        mPythonClass = mPCAttr.load()
+
+        expectedMachines = sorted(
+            [('test_package.rootLevel', tpRootLevel),
+             ('test_package.PythonClass._machine', tpPythonClass._machine),
+             ('test_package.subpackage.module.rootLevel', mRootLevel),
+             ('test_package.subpackage.module.PythonClass._machine',
+              mPythonClass._machine)],
+            key=operator.itemgetter(0))
+
+        self.assertEqual(expectedMachines, machines)

venv/lib/python3.9/site-packages/automat/_test/test_methodical.py

@@ -0,0 +1,587 @@
+
+"""
+Tests for the public interface of Automat.
+"""
+
+from functools import reduce
+from unittest import TestCase
+
+from automat._methodical import ArgSpec, _getArgNames, _getArgSpec, _filterArgs
+from .. import MethodicalMachine, NoTransition
+from .. import _methodical
+
+
+class MethodicalTests(TestCase):
+    """
+    Tests for L{MethodicalMachine}.
+    """
+
+    def test_oneTransition(self):
+        """
+        L{MethodicalMachine} provides a way for you to declare a state machine
+        with inputs, outputs, and states as methods.  When you have declared an
+        input, an output, and a state, calling the input method in that state
+        will produce the specified output.
+        """
+
+        class Machination(object):
+            machine = MethodicalMachine()
+            @machine.input()
+            def anInput(self):
+                "an input"
+
+            @machine.output()
+            def anOutput(self):
+                "an output"
+                return "an-output-value"
+
+            @machine.output()
+            def anotherOutput(self):
+                "another output"
+                return "another-output-value"
+
+            @machine.state(initial=True)
+            def anState(self):
+                "a state"
+
+            @machine.state()
+            def anotherState(self):
+                "another state"
+
+            anState.upon(anInput, enter=anotherState, outputs=[anOutput])
+            anotherState.upon(anInput, enter=anotherState,
+                              outputs=[anotherOutput])
+
+        m = Machination()
+        self.assertEqual(m.anInput(), ["an-output-value"])
+        self.assertEqual(m.anInput(), ["another-output-value"])
+
+
+    def test_machineItselfIsPrivate(self):
+        """
+        L{MethodicalMachine} is an implementation detail.  If you attempt to
+        access it on an instance of your class, you will get an exception.
+        However, since tools may need to access it for the purposes of, for
+        example, visualization, you may access it on the class itself.
+        """
+        expectedMachine = MethodicalMachine()
+        class Machination(object):
+            machine = expectedMachine
+        machination = Machination()
+        with self.assertRaises(AttributeError) as cm:
+            machination.machine
+        self.assertIn("MethodicalMachine is an implementation detail",
+                      str(cm.exception))
+        self.assertIs(Machination.machine, expectedMachine)
+
+
+    def test_outputsArePrivate(self):
+        """
+        One of the benefits of using a state machine is that your output method
+        implementations don't need to take invalid state transitions into
+        account - the methods simply won't be called.  This property would be
+        broken if client code called output methods directly, so output methods
+        are not directly visible under their names.
+        """
+        class Machination(object):
+            machine = MethodicalMachine()
+            counter = 0
+            @machine.input()
+            def anInput(self):
+                "an input"
+            @machine.output()
+            def anOutput(self):
+                self.counter += 1
+            @machine.state(initial=True)
+            def state(self):
+                "a machine state"
+            state.upon(anInput, enter=state, outputs=[anOutput])
+        mach1 = Machination()
+        mach1.anInput()
+        self.assertEqual(mach1.counter, 1)
+        mach2 = Machination()
+        with self.assertRaises(AttributeError) as cm:
+            mach2.anOutput
+        self.assertEqual(mach2.counter, 0)
+
+        self.assertIn(
+            "Machination.anOutput is a state-machine output method; to "
+            "produce this output, call an input method instead.",
+            str(cm.exception)
+        )
+
+
+    def test_multipleMachines(self):
+        """
+        Two machines may co-exist happily on the same instance; they don't
+        interfere with each other.
+        """
+        class MultiMach(object):
+            a = MethodicalMachine()
+            b = MethodicalMachine()
+
+            @a.input()
+            def inputA(self):
+                "input A"
+            @b.input()
+            def inputB(self):
+                "input B"
+            @a.state(initial=True)
+            def initialA(self):
+                "initial A"
+            @b.state(initial=True)
+            def initialB(self):
+                "initial B"
+            @a.output()
+            def outputA(self):
+                return "A"
+            @b.output()
+            def outputB(self):
+                return "B"
+            initialA.upon(inputA, initialA, [outputA])
+            initialB.upon(inputB, initialB, [outputB])
+
+        mm = MultiMach()
+        self.assertEqual(mm.inputA(), ["A"])
+        self.assertEqual(mm.inputB(), ["B"])
+
+
+    def test_collectOutputs(self):
+        """
+        Outputs can be combined with the "collector" argument to "upon".
+        """
+        import operator
+        class Machine(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                "an input"
+            @m.output()
+            def outputA(self):
+                return "A"
+            @m.output()
+            def outputB(self):
+                return "B"
+            @m.state(initial=True)
+            def state(self):
+                "a state"
+            state.upon(input, state, [outputA, outputB],
+                       collector=lambda x: reduce(operator.add, x))
+        m = Machine()
+        self.assertEqual(m.input(), "AB")
+
+
+    def test_methodName(self):
+        """
+        Input methods preserve their declared names.
+        """
+        class Mech(object):
+            m = MethodicalMachine()
+            @m.input()
+            def declaredInputName(self):
+                "an input"
+            @m.state(initial=True)
+            def aState(self):
+                "state"
+        m = Mech()
+        with self.assertRaises(TypeError) as cm:
+            m.declaredInputName("too", "many", "arguments")
+        self.assertIn("declaredInputName", str(cm.exception))
+
+
+    def test_inputWithArguments(self):
+        """
+        If an input takes an argument, it will pass that along to its output.
+        """
+        class Mechanism(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self, x, y=1):
+                "an input"
+            @m.state(initial=True)
+            def state(self):
+                "a state"
+            @m.output()
+            def output(self, x, y=1):
+                self._x = x
+                return x + y
+            state.upon(input, state, [output])
+
+        m = Mechanism()
+        self.assertEqual(m.input(3), [4])
+        self.assertEqual(m._x, 3)
+
+
+    def test_outputWithSubsetOfArguments(self):
+        """
+        Inputs pass arguments that output will accept.
+        """
+        class Mechanism(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self, x, y=1):
+                "an input"
+            @m.state(initial=True)
+            def state(self):
+                "a state"
+            @m.output()
+            def outputX(self, x):
+                self._x = x
+                return x
+            @m.output()
+            def outputY(self, y):
+                self._y = y
+                return y
+            @m.output()
+            def outputNoArgs(self):
+                return None
+            state.upon(input, state, [outputX, outputY, outputNoArgs])
+
+        m = Mechanism()
+
+        # Pass x as positional argument.
+        self.assertEqual(m.input(3), [3, 1, None])
+        self.assertEqual(m._x, 3)
+        self.assertEqual(m._y, 1)
+
+        # Pass x as key word argument.
+        self.assertEqual(m.input(x=4), [4, 1, None])
+        self.assertEqual(m._x, 4)
+        self.assertEqual(m._y, 1)
+
+        # Pass y as positional argument.
+        self.assertEqual(m.input(6, 3), [6, 3, None])
+        self.assertEqual(m._x, 6)
+        self.assertEqual(m._y, 3)
+
+        # Pass y as key word argument.
+        self.assertEqual(m.input(5, y=2), [5, 2, None])
+        self.assertEqual(m._x, 5)
+        self.assertEqual(m._y, 2)
+
+
+    def test_inputFunctionsMustBeEmpty(self):
+        """
+        The wrapped input function must have an empty body.
+        """
+        # input functions are executed to assert that the signature matches,
+        # but their body must be empty
+
+        _methodical._empty() # chase coverage
+        _methodical._docstring()
+
+        class Mechanism(object):
+            m = MethodicalMachine()
+            with self.assertRaises(ValueError) as cm:
+                @m.input()
+                def input(self):
+                    "an input"
+                    list() # pragma: no cover
+            self.assertEqual(str(cm.exception), "function body must be empty")
+
+        # all three of these cases should be valid. Functions/methods with
+        # docstrings produce slightly different bytecode than ones without.
+
+        class MechanismWithDocstring(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                "an input"
+            @m.state(initial=True)
+            def start(self):
+                "starting state"
+            start.upon(input, enter=start, outputs=[])
+        MechanismWithDocstring().input()
+
+        class MechanismWithPass(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                pass
+            @m.state(initial=True)
+            def start(self):
+                "starting state"
+            start.upon(input, enter=start, outputs=[])
+        MechanismWithPass().input()
+
+        class MechanismWithDocstringAndPass(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                "an input"
+                pass
+            @m.state(initial=True)
+            def start(self):
+                "starting state"
+            start.upon(input, enter=start, outputs=[])
+        MechanismWithDocstringAndPass().input()
+
+        class MechanismReturnsNone(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                return None
+            @m.state(initial=True)
+            def start(self):
+                "starting state"
+            start.upon(input, enter=start, outputs=[])
+        MechanismReturnsNone().input()
+
+        class MechanismWithDocstringAndReturnsNone(object):
+            m = MethodicalMachine()
+            @m.input()
+            def input(self):
+                "an input"
+                return None
+            @m.state(initial=True)
+            def start(self):
+                "starting state"
+            start.upon(input, enter=start, outputs=[])
+        MechanismWithDocstringAndReturnsNone().input()
+
+
+    def test_inputOutputMismatch(self):
+        """
+        All the argument lists of the outputs for a given input must match; if
+        one does not the call to C{upon} will raise a C{TypeError}.
+        """
+        class Mechanism(object):
+            m = MethodicalMachine()
+            @m.input()
+            def nameOfInput(self, a):
+                "an input"
+            @m.output()
+            def outputThatMatches(self, a):
+                "an output that matches"
+            @m.output()
+            def outputThatDoesntMatch(self, b):
+                "an output that doesn't match"
+            @m.state()
+            def state(self):
+                "a state"
+            with self.assertRaises(TypeError) as cm:
+                state.upon(nameOfInput, state, [outputThatMatches,
+                                                outputThatDoesntMatch])
+            self.assertIn("nameOfInput", str(cm.exception))
+            self.assertIn("outputThatDoesntMatch", str(cm.exception))
+
+
+    def test_getArgNames(self):
+        """
+        Type annotations should be included in the set of
+        """
+        spec = ArgSpec(
+            args=('a', 'b'),
+            varargs=None,
+            varkw=None,
+            defaults=None,
+            kwonlyargs=(),
+            kwonlydefaults=None,
+            annotations=(('a', int), ('b', str)),
+        )
+        self.assertEqual(
+            _getArgNames(spec),
+            {'a', 'b', ('a', int), ('b', str)},
+        )
+
+
+    def test_filterArgs(self):
+        """
+        filterArgs() should not filter the `args` parameter
+        if outputSpec accepts `*args`.
+        """
+        inputSpec = _getArgSpec(lambda *args, **kwargs: None)
+        outputSpec = _getArgSpec(lambda *args, **kwargs: None)
+        argsIn = ()
+        argsOut, _ = _filterArgs(argsIn, {}, inputSpec, outputSpec)
+        self.assertIs(argsIn, argsOut)
+
+
+    def test_multipleInitialStatesFailure(self):
+        """
+        A L{MethodicalMachine} can only have one initial state.
+        """
+
+        class WillFail(object):
+            m = MethodicalMachine()
+
+            @m.state(initial=True)
+            def firstInitialState(self):
+                "The first initial state -- this is OK."
+
+            with self.assertRaises(ValueError):
+                @m.state(initial=True)
+                def secondInitialState(self):
+                    "The second initial state -- results in a ValueError."
+
+
+    def test_multipleTransitionsFailure(self):
+        """
+        A L{MethodicalMachine} can only have one transition per start/event
+        pair.
+        """
+
+        class WillFail(object):
+            m = MethodicalMachine()
+
+            @m.state(initial=True)
+            def start(self):
+                "We start here."
+            @m.state()
+            def end(self):
+                "Rainbows end."
+
+            @m.input()
+            def event(self):
+                "An event."
+            start.upon(event, enter=end, outputs=[])
+            with self.assertRaises(ValueError):
+                start.upon(event, enter=end, outputs=[])
+
+
+    def test_badTransitionForCurrentState(self):
+        """
+        Calling any input method that lacks a transition for the machine's
+        current state raises an informative L{NoTransition}.
+        """
+
+        class OnlyOnePath(object):
+            m = MethodicalMachine()
+            @m.state(initial=True)
+            def start(self):
+                "Start state."
+            @m.state()
+            def end(self):
+                "End state."
+            @m.input()
+            def advance(self):
+                "Move from start to end."
+            @m.input()
+            def deadEnd(self):
+                "A transition from nowhere to nowhere."
+            start.upon(advance, end, [])
+
+        machine = OnlyOnePath()
+        with self.assertRaises(NoTransition) as cm:
+            machine.deadEnd()
+        self.assertIn("deadEnd", str(cm.exception))
+        self.assertIn("start", str(cm.exception))
+        machine.advance()
+        with self.assertRaises(NoTransition) as cm:
+            machine.deadEnd()
+        self.assertIn("deadEnd", str(cm.exception))
+        self.assertIn("end", str(cm.exception))
+
+
+    def test_saveState(self):
+        """
+        L{MethodicalMachine.serializer} is a decorator that modifies its
+        decoratee's signature to take a "state" object as its first argument,
+        which is the "serialized" argument to the L{MethodicalMachine.state}
+        decorator.
+        """
+
+        class Mechanism(object):
+            m = MethodicalMachine()
+            def __init__(self):
+                self.value = 1
+            @m.state(serialized="first-state", initial=True)
+            def first(self):
+                "First state."
+            @m.state(serialized="second-state")
+            def second(self):
+                "Second state."
+            @m.serializer()
+            def save(self, state):
+                return {
+                    'machine-state': state,
+                    'some-value': self.value,
+                }
+
+        self.assertEqual(
+            Mechanism().save(),
+            {
+                "machine-state": "first-state",
+                "some-value": 1,
+            }
+        )
+
+
+    def test_restoreState(self):
+        """
+        L{MethodicalMachine.unserializer} decorates a function that becomes a
+        machine-state unserializer; its return value is mapped to the
+        C{serialized} parameter to C{state}, and the L{MethodicalMachine}
+        associated with that instance's state is updated to that state.
+        """
+
+        class Mechanism(object):
+            m = MethodicalMachine()
+            def __init__(self):
+                self.value = 1
+                self.ranOutput = False
+            @m.state(serialized="first-state", initial=True)
+            def first(self):
+                "First state."
+            @m.state(serialized="second-state")
+            def second(self):
+                "Second state."
+            @m.input()
+            def input(self):
+                "an input"
+            @m.output()
+            def output(self):
+                self.value = 2
+                self.ranOutput = True
+                return 1
+            @m.output()
+            def output2(self):
+                return 2
+            first.upon(input, second, [output],
+                       collector=lambda x: list(x)[0])
+            second.upon(input, second, [output2],
+                        collector=lambda x: list(x)[0])
+            @m.serializer()
+            def save(self, state):
+                return {
+                    'machine-state': state,
+                    'some-value': self.value,
+                }
+
+            @m.unserializer()
+            def _restore(self, blob):
+                self.value = blob['some-value']
+                return blob['machine-state']
+
+            @classmethod
+            def fromBlob(cls, blob):
+                self = cls()
+                self._restore(blob)
+                return self
+
+        m1 = Mechanism()
+        m1.input()
+        blob = m1.save()
+        m2 = Mechanism.fromBlob(blob)
+        self.assertEqual(m2.ranOutput, False)
+        self.assertEqual(m2.input(), 2)
+        self.assertEqual(
+            m2.save(),
+            {
+                'machine-state': 'second-state',
+                'some-value': 2,
+            }
+        )
+
+
+
+# FIXME: error for wrong types on any call to _oneTransition
+# FIXME: better public API for .upon; maybe a context manager?
+# FIXME: when transitions are defined, validate that we can always get to
+# terminal? do we care about this?
+# FIXME: implementation (and use-case/example) for passing args from in to out
+
+# FIXME: possibly these need some kind of support from core
+# FIXME: wildcard state (in all states, when input X, emit Y and go to Z)
+# FIXME: wildcard input (in state X, when any input, emit Y and go to Z)
+# FIXME: combined wildcards (in any state for any input, emit Y go to Z)

venv/lib/python3.9/site-packages/automat/_test/test_trace.py

@@ -0,0 +1,98 @@
+from unittest import TestCase
+from .._methodical import MethodicalMachine
+
+class SampleObject(object):
+    mm = MethodicalMachine()
+
+    @mm.state(initial=True)
+    def begin(self):
+        "initial state"
+    @mm.state()
+    def middle(self):
+        "middle state"
+    @mm.state()
+    def end(self):
+        "end state"
+
+    @mm.input()
+    def go1(self):
+        "sample input"
+    @mm.input()
+    def go2(self):
+        "sample input"
+    @mm.input()
+    def back(self):
+        "sample input"
+
+    @mm.output()
+    def out(self):
+        "sample output"
+
+    setTrace = mm._setTrace
+
+    begin.upon(go1, middle, [out])
+    middle.upon(go2, end, [out])
+    end.upon(back, middle, [])
+    middle.upon(back, begin, [])
+
+class TraceTests(TestCase):
+    def test_only_inputs(self):
+        traces = []
+        def tracer(old_state, input, new_state):
+            traces.append((old_state, input, new_state))
+            return None # "I only care about inputs, not outputs"
+        s = SampleObject()
+        s.setTrace(tracer)
+
+        s.go1()
+        self.assertEqual(traces, [("begin", "go1", "middle"),
+                                  ])
+
+        s.go2()
+        self.assertEqual(traces, [("begin", "go1", "middle"),
+                                  ("middle", "go2", "end"),
+                                  ])
+        s.setTrace(None)
+        s.back()
+        self.assertEqual(traces, [("begin", "go1", "middle"),
+                                  ("middle", "go2", "end"),
+                                  ])
+        s.go2()
+        self.assertEqual(traces, [("begin", "go1", "middle"),
+                                  ("middle", "go2", "end"),
+                                  ])
+
+    def test_inputs_and_outputs(self):
+        traces = []
+        def tracer(old_state, input, new_state):
+            traces.append((old_state, input, new_state, None))
+            def trace_outputs(output):
+                traces.append((old_state, input, new_state, output))
+            return trace_outputs # "I care about outputs too"
+        s = SampleObject()
+        s.setTrace(tracer)
+
+        s.go1()
+        self.assertEqual(traces, [("begin", "go1", "middle", None),
+                                  ("begin", "go1", "middle", "out"),
+                                  ])
+
+        s.go2()
+        self.assertEqual(traces, [("begin", "go1", "middle", None),
+                                  ("begin", "go1", "middle", "out"),
+                                  ("middle", "go2", "end", None),
+                                  ("middle", "go2", "end", "out"),
+                                  ])
+        s.setTrace(None)
+        s.back()
+        self.assertEqual(traces, [("begin", "go1", "middle", None),
+                                  ("begin", "go1", "middle", "out"),
+                                  ("middle", "go2", "end", None),
+                                  ("middle", "go2", "end", "out"),
+                                  ])
+        s.go2()
+        self.assertEqual(traces, [("begin", "go1", "middle", None),
+                                  ("begin", "go1", "middle", "out"),
+                                  ("middle", "go2", "end", None),
+                                  ("middle", "go2", "end", "out"),
+                                  ])

venv/lib/python3.9/site-packages/automat/_test/test_visualize.py

@@ -0,0 +1,430 @@
+from __future__ import print_function
+import functools
+
+import os
+import subprocess
+from unittest import TestCase, skipIf
+
+import attr
+
+from .._methodical import MethodicalMachine
+
+from .test_discover import isTwistedInstalled
+
+
+def isGraphvizModuleInstalled():
+    """
+    Is the graphviz Python module installed?
+    """
+    try:
+        __import__("graphviz")
+    except ImportError:
+        return False
+    else:
+        return True
+
+
+def isGraphvizInstalled():
+    """
+    Are the graphviz tools installed?
+    """
+    r, w = os.pipe()
+    os.close(w)
+    try:
+        return not subprocess.call("dot", stdin=r, shell=True)
+    finally:
+        os.close(r)
+
+
+
+def sampleMachine():
+    """
+    Create a sample L{MethodicalMachine} with some sample states.
+    """
+    mm = MethodicalMachine()
+    class SampleObject(object):
+        @mm.state(initial=True)
+        def begin(self):
+            "initial state"
+        @mm.state()
+        def end(self):
+            "end state"
+        @mm.input()
+        def go(self):
+            "sample input"
+        @mm.output()
+        def out(self):
+            "sample output"
+        begin.upon(go, end, [out])
+    so = SampleObject()
+    so.go()
+    return mm
+
+
+@skipIf(not isGraphvizModuleInstalled(), "Graphviz module is not installed.")
+class ElementMakerTests(TestCase):
+    """
+    L{elementMaker} generates HTML representing the specified element.
+    """
+
+    def setUp(self):
+        from .._visualize import elementMaker
+        self.elementMaker = elementMaker
+
+    def test_sortsAttrs(self):
+        """
+        L{elementMaker} orders HTML attributes lexicographically.
+        """
+        expected = r'<div a="1" b="2" c="3"></div>'
+        self.assertEqual(expected,
+                         self.elementMaker("div",
+                                           b='2',
+                                           a='1',
+                                           c='3'))
+
+    def test_quotesAttrs(self):
+        """
+        L{elementMaker} quotes HTML attributes according to DOT's quoting rule.
+
+        See U{http://www.graphviz.org/doc/info/lang.html}, footnote 1.
+        """
+        expected = r'<div a="1" b="a \" quote" c="a string"></div>'
+        self.assertEqual(expected,
+                         self.elementMaker("div",
+                                           b='a " quote',
+                                           a=1,
+                                           c="a string"))
+
+    def test_noAttrs(self):
+        """
+        L{elementMaker} should render an element with no attributes.
+        """
+        expected = r'<div ></div>'
+        self.assertEqual(expected, self.elementMaker("div"))
+
+
+@attr.s
+class HTMLElement(object):
+    """Holds an HTML element, as created by elementMaker."""
+    name = attr.ib()
+    children = attr.ib()
+    attributes = attr.ib()
+
+
+def findElements(element, predicate):
+    """
+    Recursively collect all elements in an L{HTMLElement} tree that
+    match the optional predicate.
+    """
+    if predicate(element):
+        return [element]
+    elif isLeaf(element):
+        return []
+
+    return [result
+            for child in element.children
+            for result in findElements(child, predicate)]
+
+
+def isLeaf(element):
+    """
+    This HTML element is actually leaf node.
+    """
+    return not isinstance(element, HTMLElement)
+
+
+@skipIf(not isGraphvizModuleInstalled(), "Graphviz module is not installed.")
+class TableMakerTests(TestCase):
+    """
+    Tests that ensure L{tableMaker} generates HTML tables usable as
+    labels in DOT graphs.
+
+    For more information, read the "HTML-Like Labels" section of
+    U{http://www.graphviz.org/doc/info/shapes.html}.
+    """
+
+    def fakeElementMaker(self, name, *children, **attributes):
+        return HTMLElement(name=name, children=children, attributes=attributes)
+
+    def setUp(self):
+        from .._visualize import tableMaker
+
+        self.inputLabel = "input label"
+        self.port = "the port"
+        self.tableMaker = functools.partial(tableMaker,
+                                            _E=self.fakeElementMaker)
+
+    def test_inputLabelRow(self):
+        """
+        The table returned by L{tableMaker} always contains the input
+        symbol label in its first row, and that row contains one cell
+        with a port attribute set to the provided port.
+        """
+
+        def hasPort(element):
+            return (not isLeaf(element)
+                    and element.attributes.get("port") == self.port)
+
+        for outputLabels in ([], ["an output label"]):
+            table = self.tableMaker(self.inputLabel, outputLabels,
+                                    port=self.port)
+            self.assertGreater(len(table.children), 0)
+            inputLabelRow = table.children[0]
+
+            portCandidates = findElements(table, hasPort)
+
+            self.assertEqual(len(portCandidates), 1)
+            self.assertEqual(portCandidates[0].name, "td")
+            self.assertEqual(findElements(inputLabelRow, isLeaf),
+                             [self.inputLabel])
+
+    def test_noOutputLabels(self):
+        """
+        L{tableMaker} does not add a colspan attribute to the input
+        label's cell or a second row if there no output labels.
+        """
+        table = self.tableMaker("input label", (), port=self.port)
+        self.assertEqual(len(table.children), 1)
+        (inputLabelRow,) = table.children
+        self.assertNotIn("colspan", inputLabelRow.attributes)
+
+    def test_withOutputLabels(self):
+        """
+        L{tableMaker} adds a colspan attribute to the input label's cell
+        equal to the number of output labels and a second row that
+        contains the output labels.
+        """
+        table = self.tableMaker(self.inputLabel, ("output label 1",
+                                                  "output label 2"),
+                                port=self.port)
+
+        self.assertEqual(len(table.children), 2)
+        inputRow, outputRow = table.children
+
+        def hasCorrectColspan(element):
+            return (not isLeaf(element)
+                    and element.name == "td"
+                    and element.attributes.get('colspan') == "2")
+
+        self.assertEqual(len(findElements(inputRow, hasCorrectColspan)),
+                         1)
+        self.assertEqual(findElements(outputRow, isLeaf), ["output label 1",
+                                                           "output label 2"])
+
+
+@skipIf(not isGraphvizModuleInstalled(), "Graphviz module is not installed.")
+@skipIf(not isGraphvizInstalled(), "Graphviz tools are not installed.")
+class IntegrationTests(TestCase):
+    """
+    Tests which make sure Graphviz can understand the output produced by
+    Automat.
+    """
+
+    def test_validGraphviz(self):
+        """
+        L{graphviz} emits valid graphviz data.
+        """
+        p = subprocess.Popen("dot", stdin=subprocess.PIPE,
+                             stdout=subprocess.PIPE)
+        out, err = p.communicate("".join(sampleMachine().asDigraph())
+                                 .encode("utf-8"))
+        self.assertEqual(p.returncode, 0)
+
+
+@skipIf(not isGraphvizModuleInstalled(), "Graphviz module is not installed.")
+class SpotChecks(TestCase):
+    """
+    Tests to make sure that the output contains salient features of the machine
+    being generated.
+    """
+
+    def test_containsMachineFeatures(self):
+        """
+        The output of L{graphviz} should contain the names of the states,
+        inputs, outputs in the state machine.
+        """
+        gvout = "".join(sampleMachine().asDigraph())
+        self.assertIn("begin", gvout)
+        self.assertIn("end", gvout)
+        self.assertIn("go", gvout)
+        self.assertIn("out", gvout)
+
+
+class RecordsDigraphActions(object):
+    """
+    Records calls made to L{FakeDigraph}.
+    """
+
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.renderCalls = []
+        self.saveCalls = []
+
+
+class FakeDigraph(object):
+    """
+    A fake L{graphviz.Digraph}.  Instantiate it with a
+    L{RecordsDigraphActions}.
+    """
+
+    def __init__(self, recorder):
+        self._recorder = recorder
+
+    def render(self, **kwargs):
+        self._recorder.renderCalls.append(kwargs)
+
+    def save(self, **kwargs):
+        self._recorder.saveCalls.append(kwargs)
+
+
+class FakeMethodicalMachine(object):
+    """
+    A fake L{MethodicalMachine}.  Instantiate it with a L{FakeDigraph}
+    """
+
+    def __init__(self, digraph):
+        self._digraph = digraph
+
+    def asDigraph(self):
+        return self._digraph
+
+
+@skipIf(not isGraphvizModuleInstalled(), "Graphviz module is not installed.")
+@skipIf(not isGraphvizInstalled(), "Graphviz tools are not installed.")
+@skipIf(not isTwistedInstalled(), "Twisted is not installed.")
+class VisualizeToolTests(TestCase):
+
+    def setUp(self):
+        self.digraphRecorder = RecordsDigraphActions()
+        self.fakeDigraph = FakeDigraph(self.digraphRecorder)
+
+        self.fakeProgname = 'tool-test'
+        self.fakeSysPath = ['ignored']
+        self.collectedOutput = []
+        self.fakeFQPN = 'fake.fqpn'
+
+    def collectPrints(self, *args):
+        self.collectedOutput.append(' '.join(args))
+
+    def fakeFindMachines(self, fqpn):
+        yield fqpn, FakeMethodicalMachine(self.fakeDigraph)
+
+    def tool(self,
+             progname=None,
+             argv=None,
+             syspath=None,
+             findMachines=None,
+             print=None):
+        from .._visualize import tool
+        return tool(
+            _progname=progname or self.fakeProgname,
+            _argv=argv or [self.fakeFQPN],
+            _syspath=syspath or self.fakeSysPath,
+            _findMachines=findMachines or self.fakeFindMachines,
+            _print=print or self.collectPrints)
+
+    def test_checksCurrentDirectory(self):
+        """
+        L{tool} adds '' to sys.path to ensure
+        L{automat._discover.findMachines} searches the current
+        directory.
+        """
+        self.tool(argv=[self.fakeFQPN])
+        self.assertEqual(self.fakeSysPath[0], '')
+
+    def test_quietHidesOutput(self):
+        """
+        Passing -q/--quiet hides all output.
+        """
+        self.tool(argv=[self.fakeFQPN, '--quiet'])
+        self.assertFalse(self.collectedOutput)
+        self.tool(argv=[self.fakeFQPN, '-q'])
+        self.assertFalse(self.collectedOutput)
+
+    def test_onlySaveDot(self):
+        """
+        Passing an empty string for --image-directory/-i disables
+        rendering images.
+        """
+        for arg in ('--image-directory', '-i'):
+            self.digraphRecorder.reset()
+            self.collectedOutput = []
+
+            self.tool(argv=[self.fakeFQPN, arg, ''])
+            self.assertFalse(any("image" in line
+                                 for line in self.collectedOutput))
+
+            self.assertEqual(len(self.digraphRecorder.saveCalls), 1)
+            (call,) = self.digraphRecorder.saveCalls
+            self.assertEqual("{}.dot".format(self.fakeFQPN),
+                             call['filename'])
+
+            self.assertFalse(self.digraphRecorder.renderCalls)
+
+    def test_saveOnlyImage(self):
+        """
+        Passing an empty string for --dot-directory/-d disables saving dot
+        files.
+        """
+        for arg in ('--dot-directory', '-d'):
+            self.digraphRecorder.reset()
+            self.collectedOutput = []
+            self.tool(argv=[self.fakeFQPN, arg, ''])
+
+            self.assertFalse(any("dot" in line
+                                 for line in self.collectedOutput))
+
+            self.assertEqual(len(self.digraphRecorder.renderCalls), 1)
+            (call,) = self.digraphRecorder.renderCalls
+            self.assertEqual("{}.dot".format(self.fakeFQPN),
+                             call['filename'])
+            self.assertTrue(call['cleanup'])
+
+            self.assertFalse(self.digraphRecorder.saveCalls)
+
+    def test_saveDotAndImagesInDifferentDirectories(self):
+        """
+        Passing different directories to --image-directory and --dot-directory
+        writes images and dot files to those directories.
+        """
+        imageDirectory = 'image'
+        dotDirectory = 'dot'
+        self.tool(argv=[self.fakeFQPN,
+                        '--image-directory', imageDirectory,
+                        '--dot-directory', dotDirectory])
+
+        self.assertTrue(any("image" in line
+                            for line in self.collectedOutput))
+        self.assertTrue(any("dot" in line
+                            for line in self.collectedOutput))
+
+        self.assertEqual(len(self.digraphRecorder.renderCalls), 1)
+        (renderCall,) = self.digraphRecorder.renderCalls
+        self.assertEqual(renderCall["directory"], imageDirectory)
+        self.assertTrue(renderCall['cleanup'])
+
+        self.assertEqual(len(self.digraphRecorder.saveCalls), 1)
+        (saveCall,) = self.digraphRecorder.saveCalls
+        self.assertEqual(saveCall["directory"], dotDirectory)
+
+    def test_saveDotAndImagesInSameDirectory(self):
+        """
+        Passing the same directory to --image-directory and --dot-directory
+        writes images and dot files to that one directory.
+        """
+        directory = 'imagesAndDot'
+        self.tool(argv=[self.fakeFQPN,
+                        '--image-directory', directory,
+                        '--dot-directory', directory])
+
+        self.assertTrue(any("image and dot" in line
+                            for line in self.collectedOutput))
+
+        self.assertEqual(len(self.digraphRecorder.renderCalls), 1)
+        (renderCall,) = self.digraphRecorder.renderCalls
+        self.assertEqual(renderCall["directory"], directory)
+        self.assertFalse(renderCall['cleanup'])
+
+        self.assertFalse(len(self.digraphRecorder.saveCalls))

venv/lib/python3.9/site-packages/automat/_visualize.py

@@ -0,0 +1,182 @@
+from __future__ import print_function
+import argparse
+import sys
+
+import graphviz
+
+from ._discover import findMachines
+
+
+def _gvquote(s):
+    return '"{}"'.format(s.replace('"', r'\"'))
+
+
+def _gvhtml(s):
+    return '<{}>'.format(s)
+
+
+def elementMaker(name, *children, **attrs):
+    """
+    Construct a string from the HTML element description.
+    """
+    formattedAttrs = ' '.join('{}={}'.format(key, _gvquote(str(value)))
+                              for key, value in sorted(attrs.items()))
+    formattedChildren = ''.join(children)
+    return u'<{name} {attrs}>{children}</{name}>'.format(
+        name=name,
+        attrs=formattedAttrs,
+        children=formattedChildren)
+
+
+def tableMaker(inputLabel, outputLabels, port, _E=elementMaker):
+    """
+    Construct an HTML table to label a state transition.
+    """
+    colspan = {}
+    if outputLabels:
+        colspan['colspan'] = str(len(outputLabels))
+
+    inputLabelCell = _E("td",
+                        _E("font",
+                           inputLabel,
+                           face="menlo-italic"),
+                        color="purple",
+                        port=port,
+                        **colspan)
+
+    pointSize = {"point-size": "9"}
+    outputLabelCells = [_E("td",
+                           _E("font",
+                              outputLabel,
+                              **pointSize),
+                           color="pink")
+                        for outputLabel in outputLabels]
+
+    rows = [_E("tr", inputLabelCell)]
+
+    if outputLabels:
+        rows.append(_E("tr", *outputLabelCells))
+
+    return _E("table", *rows)
+
+
+def makeDigraph(automaton, inputAsString=repr,
+                outputAsString=repr,
+                stateAsString=repr):
+    """
+    Produce a L{graphviz.Digraph} object from an automaton.
+    """
+    digraph = graphviz.Digraph(graph_attr={'pack': 'true',
+                                           'dpi': '100'},
+                               node_attr={'fontname': 'Menlo'},
+                               edge_attr={'fontname': 'Menlo'})
+
+    for state in automaton.states():
+        if state is automaton.initialState:
+            stateShape = "bold"
+            fontName = "Menlo-Bold"
+        else:
+            stateShape = ""
+            fontName = "Menlo"
+        digraph.node(stateAsString(state),
+                     fontame=fontName,
+                     shape="ellipse",
+                     style=stateShape,
+                     color="blue")
+    for n, eachTransition in enumerate(automaton.allTransitions()):
+        inState, inputSymbol, outState, outputSymbols = eachTransition
+        thisTransition = "t{}".format(n)
+        inputLabel = inputAsString(inputSymbol)
+
+        port = "tableport"
+        table = tableMaker(inputLabel, [outputAsString(outputSymbol)
+                                        for outputSymbol in outputSymbols],
+                           port=port)
+
+        digraph.node(thisTransition,
+                     label=_gvhtml(table), margin="0.2", shape="none")
+
+        digraph.edge(stateAsString(inState),
+                     '{}:{}:w'.format(thisTransition, port),
+                     arrowhead="none")
+        digraph.edge('{}:{}:e'.format(thisTransition, port),
+                     stateAsString(outState))
+
+    return digraph
+
+
+def tool(_progname=sys.argv[0],
+         _argv=sys.argv[1:],
+         _syspath=sys.path,
+         _findMachines=findMachines,
+         _print=print):
+    """
+    Entry point for command line utility.
+    """
+
+    DESCRIPTION = """
+    Visualize automat.MethodicalMachines as graphviz graphs.
+    """
+    EPILOG = """
+    You must have the graphviz tool suite installed.  Please visit
+    http://www.graphviz.org for more information.
+    """
+    if _syspath[0]:
+        _syspath.insert(0, '')
+    argumentParser = argparse.ArgumentParser(
+        prog=_progname,
+        description=DESCRIPTION,
+        epilog=EPILOG)
+    argumentParser.add_argument('fqpn',
+                                help="A Fully Qualified Path name"
+                                " representing where to find machines.")
+    argumentParser.add_argument('--quiet', '-q',
+                                help="suppress output",
+                                default=False,
+                                action="store_true")
+    argumentParser.add_argument('--dot-directory', '-d',
+                                help="Where to write out .dot files.",
+                                default=".automat_visualize")
+    argumentParser.add_argument('--image-directory', '-i',
+                                help="Where to write out image files.",
+                                default=".automat_visualize")
+    argumentParser.add_argument('--image-type', '-t',
+                                help="The image format.",
+                                choices=graphviz.FORMATS,
+                                default='png')
+    argumentParser.add_argument('--view', '-v',
+                                help="View rendered graphs with"
+                                " default image viewer",
+                                default=False,
+                                action="store_true")
+    args = argumentParser.parse_args(_argv)
+
+    explicitlySaveDot = (args.dot_directory
+                         and (not args.image_directory
+                              or args.image_directory != args.dot_directory))
+    if args.quiet:
+        def _print(*args):
+            pass
+
+    for fqpn, machine in _findMachines(args.fqpn):
+        _print(fqpn, '...discovered')
+
+        digraph = machine.asDigraph()
+
+        if explicitlySaveDot:
+            digraph.save(filename="{}.dot".format(fqpn),
+                         directory=args.dot_directory)
+            _print(fqpn, "...wrote dot into", args.dot_directory)
+
+        if args.image_directory:
+            deleteDot = not args.dot_directory or explicitlySaveDot
+            digraph.format = args.image_type
+            digraph.render(filename="{}.dot".format(fqpn),
+                           directory=args.image_directory,
+                           view=args.view,
+                           cleanup=deleteDot)
+            if deleteDot:
+                msg = "...wrote image into"
+            else:
+                msg = "...wrote image and dot into"
+            _print(fqpn, msg, args.image_directory)