{"id":18668876,"url":"https://github.com/alysivji/finite-state-machine","last_synced_at":"2025-10-06T20:40:15.558Z","repository":{"id":46631639,"uuid":"270836062","full_name":"alysivji/finite-state-machine","owner":"alysivji","description":"Lightweight, decorator-based Python implementation of a Finite State Machine","archived":false,"fork":false,"pushed_at":"2023-05-22T23:35:03.000Z","size":2331,"stargazers_count":112,"open_issues_count":6,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-09T19:19:30.172Z","etag":null,"topics":["finite-state-machine","hacktoberfest","hacktoberfest2020","python","state-diagram","state-machine-workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alysivji.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-08T21:38:23.000Z","updated_at":"2024-10-14T01:18:50.000Z","dependencies_parsed_at":"2024-06-21T04:10:10.218Z","dependency_job_id":null,"html_url":"https://github.com/alysivji/finite-state-machine","commit_stats":{"total_commits":36,"total_committers":4,"mean_commits":9.0,"dds":0.4444444444444444,"last_synced_commit":"16d93fe2950b36fc7994656c16f49ab8493fdbd4"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffinite-state-machine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffinite-state-machine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffinite-state-machine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alysivji%2Ffinite-state-machine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alysivji","download_url":"https://codeload.github.com/alysivji/finite-state-machine/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094991,"owners_count":21046770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finite-state-machine","hacktoberfest","hacktoberfest2020","python","state-diagram","state-machine-workflow"],"created_at":"2024-11-07T08:45:16.480Z","updated_at":"2025-10-06T20:40:10.513Z","avatar_url":"https://github.com/alysivji.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Finite State Machine Banner](assets/finite-state-machine.png)\n\n# Finite State Machine\n\n[![Latest Release](https://img.shields.io/pypi/v/finite-state-machine)](https://pypi.org/project/finite-state-machine/)\n[![Supports Python 3.6+](https://img.shields.io/badge/Python-3.6+-blue.svg)](https://www.python.org/download/releases/3.6.0/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)\n[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\n[![Build Status](https://github.com/alysivji/finite-state-machine/workflows/build/badge.svg)](https://github.com/alysivji/finite-state-machine/actions?query=workflow%3A%22build%22)\n[![codecov](https://codecov.io/gh/alysivji/finite-state-machine/branch/master/graph/badge.svg)](https://codecov.io/gh/alysivji/finite-state-machine)\n\nLightweight, decorator-based Python implementation of a [Finite State Machine](https://en.wikipedia.org/wiki/Finite-state_machine).\n\n#### Table of Contents\n\n\u003c!-- TOC --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Example](#example)\n- [Asynchronous Support](#asynchronous-support)\n- [State Diagram](#state-diagram)\n- [Contributing](#contributing)\n- [Inspiration](#inspiration)\n\n\u003c!-- /TOC --\u003e\n\n## Installation\n\n```console\npip install finite-state-machine\n```\n\n## Usage\n\nSubclass `StateMachine` and set the `state` instance variable:\n\n```python\nfrom finite_state_machine import StateMachine, transition\n\nclass LightSwitch(StateMachine):\n    def __init__(self):\n        self.state = \"off\"\n        super().__init__()\n```\n\nThe `transition` decorator can be used to specify valid state transitions\nwith an optional parameter for `conditions`.\nStates can be of type: `string`, `int`, `bool`, `Enum`, or `IntEnum`.\nCan specify a single sate or a list of states for the `source` parameter;\ncan only specify a single state as the `target` target.\nAll condition functions need to return `True` for the transition to occur,\nelse a `ConditionsNotMet` exception will be raised.\nCondition functions require the same positional position and\nkeyword arguments present in the transition function.\n\n```python\n    @transition(source=\"off\", target=\"on\", conditions=[light_is_off])\n    def turn_on(self):\n        # transition function\n        # logic to define what happens to \"complete a transition\"\n        # ex. update database record,\n        ...\n\ndef light_is_off(machine):\n    # condition function, first param will always be the state machine class\n    # return a boolean to specify if a transition is valid\n    return machine.state == \"off\"\n```\n\nCan also specify an `on_error` state to handle situations\nwhere the transition function raises an exception:\n\n```python\n    @transition(source=\"off\", target=\"on\", on_error=\"failed\")\n    def turn_on(self):\n        raise ValueError\n```\n\n## Example\n\n```python\nfrom finite_state_machine import StateMachine, transition\n\nclass Turnstile(StateMachine):\n    initial_state = \"close\"\n\n    def __init__(self):\n        self.state = self.initial_state\n        super().__init__()\n\n    @transition(source=[\"close\", \"open\"], target=\"open\")\n    def insert_coin(self):\n        pass\n\n    @transition(source=\"open\", target=\"close\")\n    def pass_thru(self):\n        pass\n```\n\n### REPL\n\n```console\nIn [2]: turnstile = Turnstile()\n\nIn [3]: turnstile.state\nOut[3]: 'close'\n\nIn [4]: turnstile.insert_coin()\n\nIn [5]: turnstile.state\nOut[5]: 'open'\n\nIn [6]: turnstile.insert_coin()\n\nIn [7]: turnstile.state\nOut[7]: 'open'\n\nIn [8]: turnstile.pass_thru()\n\nIn [9]: turnstile.state\nOut[9]: 'close'\n\nIn [10]: turnstile.pass_thru()\n---------------------------------------------------------------------------\nInvalidStartState                         Traceback (most recent call last)\n\u003cipython-input-10-6abc6f4be1cd\u003e in \u003cmodule\u003e\n----\u003e 1 turnstile.pass_thru()\n\n~/state_machine.py in _wrapper(*args, **kwargs)\n     32\n     33             if self.state not in source:\n---\u003e 34                 raise InvalidStartState\n     35\n     36             for condition in conditions:\n\nInvalidStartState:\n```\n\nThe [examples](/examples) folder contains additional workflows.\n\n## Asynchronous Support\n\n`finite-state-machine` can be used to build\nboth synchronous and asynchronous State Machines.\nThe `@transition` decorator supports transition functions\nand condition functions as follows:\n\n||Synchronous transition function|Asynchronous transition function|\n|---|:---:|:---:|\n|**Synchronous condition function**|✅|❌|\n|**Asynchronous condition function**|✅|✅|\n\n## State Diagram\n\nState Machine workflows can be visualized using a\n[state diagram](https://en.wikipedia.org/wiki/State_diagram).\n\n`finite-state-machine` generates diagrams using\n[Mermaid Markdown syntax](https://mermaid-js.github.io),\nwhich can be viewed using the\n[Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor).\n\nUse the `fsm_draw_state_diagram` command and point to\nState Machine workflow class\nthat inherits from `StateMachine`.\n\n```console\n# class parameter is required\n$ fsm_draw_state_diagram --class examples.turnstile:Turnstile\n\n# initial_state parameter is optional\n$ fsm_draw_state_diagram --class examples.turnstile:Turnstile --initial_state close\n```\n\n## Contributing\n\n1. Clone repo\n1. Create a virtual environment\n1. `pip install -r requirements_dev.txt`\n1. Install [pre-commit](https://pre-commit.com/)\n1. Set up pre-commit hooks in repo: `pre-commit install`\n\nTo install a package locally for development, run:\n\n```console\nflit install [--symlink] [--python path/to/python]\n```\n\n### Running Tests\n\n```console\npytest\n```\n\n## Inspiration\n\nThis project is inspired by\n[django-fsm](https://github.com/viewflow/django-fsm/).\nI wanted a decorator-based state machine without having to use Django.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falysivji%2Ffinite-state-machine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falysivji%2Ffinite-state-machine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falysivji%2Ffinite-state-machine/lists"}