diff --git a/docs/source/components/components.rst b/docs/source/components/components.rst index 87dee5b..d2cef53 100644 --- a/docs/source/components/components.rst +++ b/docs/source/components/components.rst @@ -23,3 +23,10 @@ Components .. autoclass:: BashMonitor :members: + +.. autoclass:: FSMManagingEventHandler + :members: + +.. autoclass:: CommandsEqual + :members: + diff --git a/lib/tfw/components/__init__.py b/lib/tfw/components/__init__.py index c75365d..2960e38 100644 --- a/lib/tfw/components/__init__.py +++ b/lib/tfw/components/__init__.py @@ -11,3 +11,4 @@ from .log_monitoring_event_handler import LogMonitoringEventHandler from .fsm_managing_event_handler import FSMManagingEventHandler from .snapshot_provider import SnapshotProvider from .directory_snapshotting_event_handler import DirectorySnapshottingEventHandler +from .commands_equal import CommandsEqual diff --git a/lib/tfw/components/commands_equal.py b/lib/tfw/components/commands_equal.py index 5115c71..54700c2 100644 --- a/lib/tfw/components/commands_equal.py +++ b/lib/tfw/components/commands_equal.py @@ -8,11 +8,49 @@ from tfw.decorators.lazy_property import lazy_property class CommandsEqual: + """ + This class is useful for comparing executed commands with + excepted commands (i.e. when triggering a state change when + the correct command is executed). + + Note that in most cases you should test the changes + caused by the commands instead of just checking command history + (stuff can be done in countless ways and preparing for every + single case is impossible). This should only be used when + testing the changes would be very difficult, like when + explaining stuff with cli tools and such. + + This class implicitly converts to bool, use it like + if CommandsEqual(...): ... + + It tries detecting differing command parameter orders with similar + semantics and provides fuzzy logic options. + The rationale behind this is that a few false positives + are better than only accepting a single version of a command + (i.e. using ==). + """ def __init__( self, command_1, command_2, fuzzyness=1, begin_similarly=True, include_patterns=None, exclude_patterns=None ): + """ + :param command_1: Compared command 1 + :param command_2: Compared command 2 + :param fuzzyness: float between 0 and 1. + the percentage of arguments required to + match between commands to result in True. + i.e 1 means 100% - all arguments need to be + present in both commands, while 0.75 + would mean 75% - in case of 4 arguments + 1 could differ between the commands. + :param begin_similarly: bool, the first word of the commands + must match + :param include_patterns: list of regex patterns the commands + must include + :param exclude_patterns: list of regex patterns the commands + must exclude + """ self.command_1 = split(command_1) self.command_2 = split(command_2) self.fuzzyness = fuzzyness