Introduction to Automat

Automat is a Python library designed for streamlining state machine creation, allowing developers to focus on logical state transitions without worrying about low-level implementation details. It is highly efficient and enables the building of robust and well-documented systems for various applications such as workflow automation, network protocols, and more.

Why Use Automat?

Automat simplifies the state machine creation process, ensuring readable, maintainable, and reusable code. With a declarative approach, it provides an intuitive way to define states and their transitions. Let’s explore its features and APIs with code snippets and get hands-on experience by creating an example application.

Automat Key APIs and Examples

1. Defining a State Machine

Automat allows you to define states and transitions with the @automat.MethodicalMachine decorator.

  from automat import MethodicalMachine

  class Door:
      _machine = MethodicalMachine()

      @_machine.state()
      def open(self):
          pass

      @_machine.state(initial=True)
      def closed(self):
          pass

      @_machine.input()
      def open_door(self):
          pass

      @_machine.input()
      def close_door(self):
          pass

      @_machine.output()
      def say_opening(self):
          print("The door is opening!")

      @_machine.output()
      def say_closing(self):
          print("The door is closing!")

      closed.upon(open_door, enter=open, outputs=[say_opening])
      open.upon(close_door, enter=closed, outputs=[say_closing])

The above code defines a basic state machine for a door, starting in the “closed” state.

2. Transitioning States

To transition between states, invoke the defined input methods.

  door = Door()

  door.open_door()  # Output: The door is opening!
  door.close_door() # Output: The door is closing!

3. Retrieving the Current State

Automat allows you to check the current state of the machine at any point.

  print(door._machine.state())  # Example Output: door.open

4. Handling Complex Workflows

Automat supports complex state transitions involving multiple inputs, outputs, and states. Here’s an example for bank account management:

  class BankAccount:
      _machine = MethodicalMachine()

      @_machine.state(initial=True)
      def active(self):
          pass

      @_machine.state()
      def dormant(self):
          pass

      @_machine.state()
      def closed(self):
          pass

      @_machine.input()
      def deposit(self):
          pass

      @_machine.input()
      def withdraw(self):
          pass

      @_machine.input()
      def close_account(self):
          pass

      @_machine.output()
      def log_transaction(self, amount):
          print(f"Transaction of {amount} logged.")

      @_machine.output()
      def deactivate_account(self):
          print("No transactions for a long time. Account is now dormant.")

      active.upon(deposit, enter=active, outputs=[log_transaction])
      active.upon(withdraw, enter=dormant, outputs=[log_transaction, deactivate_account])
      dormant.upon(deposit, enter=active, outputs=[log_transaction])
      active.upon(close_account, enter=closed, outputs=[])

Building a Sample App with Automat

Let’s create an elevator control system using Automat APIs.

  class Elevator:
      _machine = MethodicalMachine()

      @_machine.state(initial=True)
      def at_ground(self):
          pass

      @_machine.state()
      def moving_up(self):
          pass

      @_machine.state()
      def moving_down(self):
          pass

      @_machine.state()
      def at_top(self):
          pass

      @_machine.input()
      def press_up_button(self):
          pass

      @_machine.input()
      def press_down_button(self):
          pass

      @_machine.output()
      def go_up(self):
          print("Elevator is moving up!")

      @_machine.output()
      def go_down(self):
          print("Elevator is moving down!")

      at_ground.upon(press_up_button, enter=moving_up, outputs=[go_up])
      moving_up.upon(press_up_button, enter=at_top, outputs=[])
      at_top.upon(press_down_button, enter=moving_down, outputs=[go_down])
      moving_down.upon(press_down_button, enter=at_ground, outputs=[])

This simple app demonstrates how Automat can be used for real-world applications such as an elevator system.

Conclusion

Automat is a powerful library that simplifies the implementation of state machines. By leveraging its declarative APIs, developers can create robust workflows and applications. Whether you’re managing elevators, door states, or bank accounts, Automat can handle it all!