Metadata-Version: 2.1
Name: gotstate
Version: 1.0.2
Summary: A hierarchical finite state machine library
Author-email: Brad Edwards <brad@keplerops.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/hsm
Project-URL: Repository, https://github.com/yourusername/hsm
Project-URL: Documentation, https://github.com/yourusername/hsm#readme
Project-URL: Changelog, https://github.com/yourusername/hsm/blob/main/CHANGELOG.md
Keywords: state-machine,hsm,finite-state-machine,hierarchical-state-machine
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.9.2
Requires-Dist: typing_extensions>=4.12.2

# gotstate

[![Security](https://github.com/KeplerOps/gotstate/actions/workflows/security.yml/badge.svg)](https://github.com/KeplerOps/gotstate/actions/workflows/security.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Brad-Edwards_gotstate&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Brad-Edwards_gotstate)
[![Tests](https://github.com/KeplerOps/gotstate/actions/workflows/test.yml/badge.svg)](https://github.com/KeplerOps/gotstate/actions/workflows/test.yml)
[![Lint](https://github.com/KeplerOps/gotstate/actions/workflows/lint.yml/badge.svg)](https://github.com/KeplerOps/gotstate/actions/workflows/lint.yml)

A hierarchical finite state machine (HFSM) library for Python, focusing on reliability and ease of use.

## Features

- Hierarchical state machines with composite states
- Type-safe state and event handling
- Thread-safe event processing
- Guard conditions and transition actions
- State data management with lifecycle hooks
- Timeout events
- History states (both shallow and deep)
- Error handling
- Activation hooks for monitoring
- Plugin system

## Status

**Version 1.0.X**

Initial release!

## Design Philosophy

`gotstate` is designed with the following principles:

- **Safety**: Runtime validation and type checking
- **Clarity**: Intuitive API design
- **Reliability**: Built for real-world applications
- **Performance**: Minimal overhead
- **Flexibility**: Extensible through plugins

## Example

```python
from hsm.core import StateMachine, State, Event, Transition

# Define states
class Idle(State):
    pass

class Running(State):
    pass

# Define events
class Start(Event):
    pass

class Stop(Event):
    pass

# Create state machine
sm = StateMachine("example")
idle = sm.add_state(Idle("idle"))
running = sm.add_state(Running("running"))

# Add transitions
sm.add_transition(Transition(idle, running, Start))
sm.add_transition(Transition(running, idle, Stop))

# Initialize and use
sm.initialize()
assert sm.current_state == idle
sm.handle_event(Start())
assert sm.current_state == running
```

## Installation

Install using pip:

```bash
pip install gotstate
```

## Requirements

- Python 3.8 or higher
- See `requirements.txt` for full dependencies

## Documentation

Documentation is available in the `docs/` directory:
- API Reference
- Usage Guide
- Examples

## License

Licensed under the MIT License. See the LICENSE file for details.

## Contributing

Contributions are welcome! Please read our contributing guidelines in CONTRIBUTING.md.

## Security

This package follows Python security best practices.
