A simple state chain library for Python
Project description
Chainstate
Chainstate is a powerful and intuitive Python library for implementing state machines. It provides a flexible and easy-to-use framework for defining, managing, and transitioning between states in your applications, with built-in support for sharing data between states.
Features
- Simple and intuitive API for defining states and transitions
- Built-in context for sharing data between states
- Error handling for common state machine issues
- Extensible design allowing for custom state behaviors
- Logging support for easy debugging and monitoring
- Type hinting for improved code readability and IDE support
Installation
Install Chainstate using pip:
pip install chainstate
Quick Start
Here's a simple example to get you started with Chainstate:
from chainstate import Chain, State, EndState
class GreetingState(State):
def action(self):
print("Hello! How can I assist you today?")
self.context.data['user_name'] = input("Please enter your name: ")
def next_state(self):
return FarewellState
class FarewellState(EndState):
def action(self):
user_name = self.context.data.get('user_name', 'Guest')
print(f"Thank you for using our service, {user_name}. Goodbye!")
# Create and run the chain
chain = Chain()
chain.add_state(GreetingState)
chain.add_state(FarewellState)
chain.set_initial_state(GreetingState)
chain.run()
This example creates a simple two-state chain that greets the user, asks for their name, and then says farewell using the stored name.
Detailed Usage
Defining States
To create a state, inherit from the State
class and implement the action
and next_state
methods:
class MyState(State):
def action(self):
# Perform the state's action
print("Performing MyState action")
# Store data in the context
self.context.data['my_key'] = 'my_value'
def next_state(self):
# Return the next state class
return NextState
Creating a Chain
Use the Chain
class to manage your states:
chain = Chain()
chain.add_state(MyState)
chain.add_state(NextState)
chain.set_initial_state(MyState)
Running the Chain
Execute the state machine using the run
method:
chain.run()
Using the Context
The context
attribute allows you to store and retrieve data that can be shared between states:
class StateA(State):
def action(self):
self.context.data['shared_value'] = 42
def next_state(self):
return StateB
class StateB(State):
def action(self):
value = self.context.data.get('shared_value')
print(f"Received value from previous state: {value}")
Advanced Features
Error Handling
Chainstate provides built-in error handling for common issues:
InitialStateNotSetError
: Raised when trying to run a chain without setting an initial state.StateTransitionError
: Raised when a state transition is invalid or when a state'snext_state
method is not implemented.
Logging
Chainstate uses Python's built-in logging module. You can configure logging to suit your needs:
import logging
logging.basicConfig(level=logging.DEBUG)
Use Case: Customer Support Chatbot
Let's implement a simple customer support chatbot using Chainstate:
from chainstate import Chain, State, EndState
class GreetingState(State):
def action(self):
print("Bot: Hello! How can I assist you today?")
self.context.data['user_input'] = input("You: ")
def next_state(self):
user_input = self.context.data['user_input'].lower()
if 'order' in user_input:
return OrderState
elif 'refund' in user_input:
return RefundState
else:
return GeneralInfoState
class OrderState(State):
def action(self):
print("Bot: I can help you with your order. What's your order number?")
order_number = input("You: ")
self.context.data['order_number'] = order_number
print(f"Bot: I've found your order {order_number}. It will be delivered in 2 days.")
def next_state(self):
return FarewellState
class RefundState(State):
def action(self):
print("Bot: I'm sorry to hear you need a refund. Please provide your order number.")
order_number = input("You: ")
self.context.data['refund_order'] = order_number
print(f"Bot: I've initiated a refund for order {order_number}. It will be processed in 3-5 business days.")
def next_state(self):
return FarewellState
class GeneralInfoState(State):
def action(self):
print("Bot: For general inquiries, please visit our FAQ page at www.example.com/faq")
def next_state(self):
return FarewellState
class FarewellState(EndState):
def action(self):
if 'order_number' in self.context.data:
print(f"Bot: Is there anything else I can help you with regarding your order {self.context.data['order_number']}? (yes/no)")
elif 'refund_order' in self.context.data:
print(f"Bot: Is there anything else I can help you with regarding your refund for order {self.context.data['refund_order']}? (yes/no)")
else:
print("Bot: Is there anything else I can help you with? (yes/no)")
response = input("You: ")
if response.lower() == 'yes':
return GreetingState
else:
print("Bot: Thank you for using our service. Have a great day!")
# Run the chatbot
chain = Chain()
chain.add_state(GreetingState)
chain.add_state(OrderState)
chain.add_state(RefundState)
chain.add_state(GeneralInfoState)
chain.add_state(FarewellState)
chain.set_initial_state(GreetingState)
chain.run()
This chatbot uses Chainstate to manage different conversation flows based on user input, demonstrating how state machines can be used to create interactive and responsive systems. The context is used to store and retrieve information across different states, allowing for a more personalized interaction.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for chainstate-0.1.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7bbf234c1528891f089726f868202432bd54960ad93a17beec1716fadb941e33 |
|
MD5 | e99f3ba9dc7dc3569baf0460832159e9 |
|
BLAKE2b-256 | d7a153e4dd70d482d57ebbba91c464a0cb16d7dde14426778db284caf9778e51 |