Basic Finite State Machine (FSM) tools.
*Latest release 20240316*:
Fixed release upload artifacts.
## Class `FSM(cs.gvutils.DOTNodeMixin)`
Base class for a finite state machine (FSM).
The allowed states and transitions are defined by the class
attribute `FSM_TRANSITIONS`, a mapping of
*state*->*event*->*new_state*.
Each instance has the following attributes:
* `fsm_state`: the current state value.
* `fsm_history`: an optional iterable of `FSMTransitionEvent`
state transitions recorded by the `fsm_event` method.
Usually this would be `None` (the default) or a `list`.
*Method `FSM.__init__(self, state=None, *, history=None, lock=None, transitions=None)`*:
Initialise the `FSM` from:
* `state`: optional _positional_ parameter for the initial state,
default `self.FSM_DEFAULT_STATE`
* `history`: an optional object to record state transition
history, default `None`; if not `None` this should be an
iterable object with a `.append(entry)` method such as a
`list`.
* `lock`: an optional mutex to control access;
if presupplied and shared with the caller
it should probably be an `RLock`;
the default is a `Lock`, which is enough for `FSM` private use
* `transitions`: optional *state*->*event*->*state* mapping;
if provided, this will override the class `FSM_TRANSITIONS` mapping
Note that the `FSM` base class does not provide a
`FSM_DEFAULT_STATE` attribute; a default `state` value of
`None` will leave `.fsm_state` _unset_.
This behaviour is is chosen mostly to support subclasses
with unusual behaviour, particularly Django's `Model` class
whose `refresh_from_db` method seems to not refresh fields
which already exist, and setting `.fsm_state` from a
`FSM_DEFAULT_STATE` class attribute thus breaks this method.
Subclasses of this class and `Model` should _not_ provide a
`FSM_DEFAULT_STATE` attribute, instead relying on the field
definition to provide this default in the usual way.
## Class `FSMError(builtins.Exception, builtins.BaseException)`
An exception associated with an `FSM`.
These have a `.fsm` attribute storing an (optional) `FSM`
reference supplied at initialisation.
## `FSMSubType = ~FSMSubType`
Type variable.
Usage::
T = TypeVar('T') # Can be anything
A = TypeVar('A', str, bytes) # Must be str or bytes
Type variables exist primarily for the benefit of static type
checkers. They serve as the parameters for generic types as well
as for generic function definitions. See class Generic for more
information on generic types. Generic functions work as follows:
def repeat(x: T, n: int) -> List[T]:
'''Return a list containing n references to x.'''
return [x]*n
def longest(x: A, y: A) -> A:
'''Return the longest of two strings.'''
return x if len(x) >= len(y) else y
The latter example's signature is essentially the overloading
of (str, str) -> str and (bytes, bytes) -> bytes. Also note
that if the arguments are instances of some subclass of str,
the return type is still plain str.
At runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.
Type variables defined with covariant=True or contravariant=True
can be used to declare covariant or contravariant generic types.
See PEP 484 for more details. By default generic types are invariant
in all type variables.
Type variables can be introspected. e.g.:
T.__name__ == 'T'
T.__constraints__ == ()
T.__covariant__ == False
T.__contravariant__ = False
A.__constraints__ == (str, bytes)
Note that only type variables defined in global scope can be pickled.
## Class `FSMTransitionEvent(builtins.tuple)`
FSMTransitionEvent(old_state, new_state, event, when, extra)
*Method `FSMTransitionEvent.__new__(_cls, old_state, new_state, event, when, extra)`*:
Create new instance of FSMTransitionEvent(old_state, new_state, event, when, extra)
# Release Log
*Release 20240316*:
Fixed release upload artifacts.
*Release 20240305*:
FSM.__getattr__: return None for missing self.fsm_state, happens in too-early call to __str__.
*Release 20231020*:
FSM.__getattr__: known transition names no longerfall through to the superclass if not valid for the current state.
*Release 20231018*:
* FSM.fsm_transitions_as_dot: new optional history_style parameter to style transitioned edges.
* FSM.fsm_as_svg: plumb optional history_style parameter.
*Release 20230816.3*:
Bump cs.gvutils requirement.
*Release 20230816.2*:
FSM.fsm_transitions_as_dot: bugfix: the style needs "style=filled" as well as the fillcolor.
*Release 20230816.1*:
FSM.fsm_transitions_as_dot: now an instance method so that we can colour the current state.
*Release 20230816*:
FSM: new fsm_as_svg method and fsm_svg property.
*Release 20221118*:
* FSM.__init__: make state optional, default from self.FSM_DEFAULT_STATE - now all args are optional.
* FSM.__init__: if the state is None or not supplied, do not set .fsm_state at all; add explaination for this weird design choice.
* FSM.__getattr__: only generate event methods for events with public names (no leading underscore).
* FSM: new .fsm_history property, aiding subclassing elsewhere.
* FSM: drop dot_node_fillcolor, now provided by DOTNodeMixin.__getattr__, provide dot_node_palette_key using self.fsm_state.
* FSM.dot_node_attrs: color from self.dot_node_color.
*Release 20220918*:
Replace callback exception warning() with exception() for the traceback.
*Release 20220805.1*:
* FSM: subclass DOTNodeMixin and provide a hook for a colour palette for node fillcolors.
* Other minor changes.
*Release 20220805*:
Initial PyPI release.
Raw data
{
"_id": null,
"home_page": "",
"name": "cs.fsm",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python3",
"author": "",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/69/29/6a7936564357508108b52dbba438b45e398a81f5e0bc644839c40582565a/cs.fsm-20240316.tar.gz",
"platform": null,
"description": "Basic Finite State Machine (FSM) tools.\n\n*Latest release 20240316*:\nFixed release upload artifacts.\n\n## Class `FSM(cs.gvutils.DOTNodeMixin)`\n\nBase class for a finite state machine (FSM).\n\nThe allowed states and transitions are defined by the class\nattribute `FSM_TRANSITIONS`, a mapping of\n*state*->*event*->*new_state*.\n\nEach instance has the following attributes:\n* `fsm_state`: the current state value.\n* `fsm_history`: an optional iterable of `FSMTransitionEvent`\n state transitions recorded by the `fsm_event` method.\n Usually this would be `None` (the default) or a `list`.\n\n*Method `FSM.__init__(self, state=None, *, history=None, lock=None, transitions=None)`*:\nInitialise the `FSM` from:\n* `state`: optional _positional_ parameter for the initial state,\n default `self.FSM_DEFAULT_STATE`\n* `history`: an optional object to record state transition\n history, default `None`; if not `None` this should be an\n iterable object with a `.append(entry)` method such as a\n `list`.\n* `lock`: an optional mutex to control access;\n if presupplied and shared with the caller\n it should probably be an `RLock`;\n the default is a `Lock`, which is enough for `FSM` private use\n* `transitions`: optional *state*->*event*->*state* mapping;\n if provided, this will override the class `FSM_TRANSITIONS` mapping\n\nNote that the `FSM` base class does not provide a\n`FSM_DEFAULT_STATE` attribute; a default `state` value of\n`None` will leave `.fsm_state` _unset_.\n\nThis behaviour is is chosen mostly to support subclasses\nwith unusual behaviour, particularly Django's `Model` class\nwhose `refresh_from_db` method seems to not refresh fields\nwhich already exist, and setting `.fsm_state` from a\n`FSM_DEFAULT_STATE` class attribute thus breaks this method.\nSubclasses of this class and `Model` should _not_ provide a\n`FSM_DEFAULT_STATE` attribute, instead relying on the field\ndefinition to provide this default in the usual way.\n\n## Class `FSMError(builtins.Exception, builtins.BaseException)`\n\nAn exception associated with an `FSM`.\n\nThese have a `.fsm` attribute storing an (optional) `FSM`\nreference supplied at initialisation.\n\n## `FSMSubType = ~FSMSubType`\n\nType variable.\n\nUsage::\n\n T = TypeVar('T') # Can be anything\n A = TypeVar('A', str, bytes) # Must be str or bytes\n\nType variables exist primarily for the benefit of static type\ncheckers. They serve as the parameters for generic types as well\nas for generic function definitions. See class Generic for more\ninformation on generic types. Generic functions work as follows:\n\n def repeat(x: T, n: int) -> List[T]:\n '''Return a list containing n references to x.'''\n return [x]*n\n\n def longest(x: A, y: A) -> A:\n '''Return the longest of two strings.'''\n return x if len(x) >= len(y) else y\n\nThe latter example's signature is essentially the overloading\nof (str, str) -> str and (bytes, bytes) -> bytes. Also note\nthat if the arguments are instances of some subclass of str,\nthe return type is still plain str.\n\nAt runtime, isinstance(x, T) and issubclass(C, T) will raise TypeError.\n\nType variables defined with covariant=True or contravariant=True\ncan be used to declare covariant or contravariant generic types.\nSee PEP 484 for more details. By default generic types are invariant\nin all type variables.\n\nType variables can be introspected. e.g.:\n\n T.__name__ == 'T'\n T.__constraints__ == ()\n T.__covariant__ == False\n T.__contravariant__ = False\n A.__constraints__ == (str, bytes)\n\nNote that only type variables defined in global scope can be pickled.\n\n## Class `FSMTransitionEvent(builtins.tuple)`\n\nFSMTransitionEvent(old_state, new_state, event, when, extra)\n\n*Method `FSMTransitionEvent.__new__(_cls, old_state, new_state, event, when, extra)`*:\nCreate new instance of FSMTransitionEvent(old_state, new_state, event, when, extra)\n\n# Release Log\n\n\n\n*Release 20240316*:\nFixed release upload artifacts.\n\n*Release 20240305*:\nFSM.__getattr__: return None for missing self.fsm_state, happens in too-early call to __str__.\n\n*Release 20231020*:\nFSM.__getattr__: known transition names no longerfall through to the superclass if not valid for the current state.\n\n*Release 20231018*:\n* FSM.fsm_transitions_as_dot: new optional history_style parameter to style transitioned edges.\n* FSM.fsm_as_svg: plumb optional history_style parameter.\n\n*Release 20230816.3*:\nBump cs.gvutils requirement.\n\n*Release 20230816.2*:\nFSM.fsm_transitions_as_dot: bugfix: the style needs \"style=filled\" as well as the fillcolor.\n\n*Release 20230816.1*:\nFSM.fsm_transitions_as_dot: now an instance method so that we can colour the current state.\n\n*Release 20230816*:\nFSM: new fsm_as_svg method and fsm_svg property.\n\n*Release 20221118*:\n* FSM.__init__: make state optional, default from self.FSM_DEFAULT_STATE - now all args are optional.\n* FSM.__init__: if the state is None or not supplied, do not set .fsm_state at all; add explaination for this weird design choice.\n* FSM.__getattr__: only generate event methods for events with public names (no leading underscore).\n* FSM: new .fsm_history property, aiding subclassing elsewhere.\n* FSM: drop dot_node_fillcolor, now provided by DOTNodeMixin.__getattr__, provide dot_node_palette_key using self.fsm_state.\n* FSM.dot_node_attrs: color from self.dot_node_color.\n\n*Release 20220918*:\nReplace callback exception warning() with exception() for the traceback.\n\n*Release 20220805.1*:\n* FSM: subclass DOTNodeMixin and provide a hook for a colour palette for node fillcolors.\n* Other minor changes.\n\n*Release 20220805*:\nInitial PyPI release.\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Basic Finite State Machine (FSM) tools.",
"version": "20240316",
"project_urls": {
"URL": "https://bitbucket.org/cameron_simpson/css/commits/all"
},
"split_keywords": [
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a30dc749d4b08f60528ccece394ec19bc3f1ade8532682ddf38a1865406caa2d",
"md5": "d79188af29d0782afa52a9dc7763ec41",
"sha256": "59d58e7d54b9705d00cb3df1704b7e04b08cd63cea7e0423996be0e11d2bf7c4"
},
"downloads": -1,
"filename": "cs.fsm-20240316-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d79188af29d0782afa52a9dc7763ec41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8191,
"upload_time": "2024-03-16T07:05:30",
"upload_time_iso_8601": "2024-03-16T07:05:30.202744Z",
"url": "https://files.pythonhosted.org/packages/a3/0d/c749d4b08f60528ccece394ec19bc3f1ade8532682ddf38a1865406caa2d/cs.fsm-20240316-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69296a7936564357508108b52dbba438b45e398a81f5e0bc644839c40582565a",
"md5": "35d574304c59f4434783de55d62dbc98",
"sha256": "88d2716c86634266facdcd9a71946ab8a41bb300157a1b926746834ebccda740"
},
"downloads": -1,
"filename": "cs.fsm-20240316.tar.gz",
"has_sig": false,
"md5_digest": "35d574304c59f4434783de55d62dbc98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8786,
"upload_time": "2024-03-16T07:05:31",
"upload_time_iso_8601": "2024-03-16T07:05:31.980809Z",
"url": "https://files.pythonhosted.org/packages/69/29/6a7936564357508108b52dbba438b45e398a81f5e0bc644839c40582565a/cs.fsm-20240316.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 07:05:31",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "cameron_simpson",
"bitbucket_project": "css",
"lcname": "cs.fsm"
}
JSON