summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEugene Triguba <eugenetriguba@gmail.com>2020-12-20 04:44:54 -0600
committerEugene Triguba <eugenetriguba@gmail.com>2020-12-20 04:44:54 -0600
commit8b4ca1aa2dc4ff6f8e4ded7bfaa3daa23bd0bddc (patch)
tree91ed58b4a176db5a1ccd14810ee30b61ef207de2
parentClean up api spec formatting (diff)
downloadlirc-8b4ca1aa2dc4ff6f8e4ded7bfaa3daa23bd0bddc.zip
Document the reply packet parser
-rw-r--r--lirc/reply_packet_parser.py199
1 files changed, 166 insertions, 33 deletions
diff --git a/lirc/reply_packet_parser.py b/lirc/reply_packet_parser.py
index 1db2527..78dfe33 100644
--- a/lirc/reply_packet_parser.py
+++ b/lirc/reply_packet_parser.py
@@ -1,42 +1,12 @@
from enum import IntEnum, auto
-from typing import List
from .exceptions import LircdInvalidReplyPacketError
class ReplyPacketParser:
- """
- Reads and parses reply packets sent from lircd.
-
- The reply packet is parsed by setting up a fsm
- (finite state machine) and using an internal state
- to keep track of where we are in the process.
-
- Reply packet format:
-
- BEGIN
- <command>
- [SUCCESS|ERROR]
- [DATA
- n
- n lines of data]
- END
-
- SIGHUP Format:
-
- BEGIN
- SIGHUP
- END
-
- The only other situation when lircd broadcasts to all
- clients is when it receives the SIGHUP signal and
- successfully re-reads its config file. Then it will
- send a SIGHUP packet to its clients indicating that
- its configuration might have changed. If we receive
- this signal, we'll need to read in another packet.
- """
-
class State(IntEnum):
+ """States that this FSM can be in."""
+
BEGIN = auto()
COMMAND = auto()
RESULT = auto()
@@ -48,11 +18,60 @@ class ReplyPacketParser:
FINISHED = auto()
class Result(IntEnum):
+ """
+ Packet parsing results. We start at undetermined
+ and move to either success or fail.
+ """
+
SUCCESS = auto()
FAIL = auto()
UNDETERMINED = auto()
def __init__(self):
+ """
+ Reads and parses reply packets sent from lircd.
+
+ The reply packet is parsed by setting up a fsm
+ (finite state machine) and using an internal state
+ to keep track of where we are in the process.
+
+ Reply packet format:
+
+ BEGIN
+ <command>
+ [SUCCESS|ERROR]
+ [DATA
+ n
+ n lines of data]
+ END
+
+ SIGHUP Format:
+
+ BEGIN
+ SIGHUP
+ END
+
+ The only other situation when lircd broadcasts to all
+ clients is when it receives the SIGHUP signal and
+ successfully re-reads its config file. Then it will
+ send a SIGHUP packet to its clients indicating that
+ its configuration might have changed. If we receive
+ this signal, we'll need to read in another packet.
+
+ Usage:
+ parser = ReplyPacketParser()
+ conn = LircdConnection()
+ while not parser.is_finished():
+ parser.feed(conn.readline())
+
+ # Now check parser.data for response data
+ # and parser.success for whether or not the command
+ # succeeded.
+ """
+ # Maps states to functions. This allows us to feed()
+ # the given line to the function at our current state.
+ # That function is then responsible for handling any errors
+ # and advancing the state forward.
self.__fsm = {
self.State.BEGIN: self.__begin,
self.State.COMMAND: self.__command,
@@ -69,18 +88,47 @@ class ReplyPacketParser:
self.__lines_left = None
@property
- def data(self) -> List:
+ def data(self) -> list:
+ """
+ Retrieves the data response of the reply packet.
+
+ Returns:
+ The data response.
+ """
return self.__data_response
@property
def is_finished(self) -> bool:
+ """
+ Checks whether we are in the finished state.
+
+ Returns:
+ True if we are in the finished state; False otherwise.
+ """
return self.__state == self.State.FINISHED
@property
def success(self) -> bool:
+ """
+ Checks whether we have a success result.
+
+ Returns:
+ True if the command result is success; False otherwise.
+ """
return self.__command_result == self.Result.SUCCESS
def __begin(self, line: str) -> None:
+ """
+ Handles the BEGIN state. This should be the
+ state we start in and transition to reading in
+ the command.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If line is not BEGIN.
+ """
if line == "BEGIN":
self.__state = self.State.COMMAND
else:
@@ -89,6 +137,19 @@ class ReplyPacketParser:
)
def __command(self, line: str) -> None:
+ """
+ Handles the COMMAND state. For parsing the reply packet,
+ we don't care too much about this state. As long as we got
+ a command, we move on to check the result. However, the
+ command could be a SIGHUP in which case, we want to ensure
+ it is properly handled.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If the line is empty.
+ """
if line == "SIGHUP":
self.__state = self.State.SIGHUP_END
elif line:
@@ -99,6 +160,16 @@ class ReplyPacketParser:
)
def __result(self, line: str) -> None:
+ """
+ Handles the RESULT state. An lircd result is
+ either SUCCESS or ERROR, followed by data.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If the line is not SUCCESS or ERROR.
+ """
if line in ["SUCCESS", "ERROR"]:
self.__state = self.State.DATA
self.__command_result = (
@@ -110,6 +181,18 @@ class ReplyPacketParser:
)
def __data(self, line: str) -> None:
+ """
+ Handles the DATA state. In this state,
+ we could either be finished now if there is
+ no data from the response or move to reading
+ in how many lines of data there is.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If line is not END or DATA.
+ """
if line == "END":
self.__state = self.State.FINISHED
elif line == "DATA":
@@ -120,6 +203,19 @@ class ReplyPacketParser:
)
def __line_count_left(self, line: str) -> None:
+ """
+ Handles the LINE COUNT LEFT state. This corresponds
+ to the `n` line in the packet format, since it tells
+ us how many lines of data we have to read in.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If line cannot be coerced
+ into an integer, since we expect it to be the remaining
+ lines left at this state.
+ """
try:
self.__lines_left = int(line)
except ValueError:
@@ -132,15 +228,35 @@ class ReplyPacketParser:
)
def __data_body(self, line: str) -> None:
+ """
+ Handles the DATA BODY state by appending
+ every line we recieve to the data response.
+
+ Because the reply packet tells us how many lines
+ of data we have, we can easily reference this to
+ know when we are done and should move on to the
+ END state.
+
+ Args:
+ line: A line read in from an lircd connection.
+ """
self.__data_response.append(line)
if len(self.__data_response) >= self.__lines_left:
self.__state = self.State.END
def __sighup_end(self, line: str) -> None:
"""
+ Handle a SIGHUP END line by resetting the parser.
+
SIGHUP packages may appear just after a command has been sent
to lircd, so this is to make sure they are not confused with
replies. If we encounter it, we reset and read in another packet.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If the line does not contain END.
"""
if line == "END":
self.__init__()
@@ -151,6 +267,17 @@ class ReplyPacketParser:
)
def __end(self, line: str) -> None:
+ """
+ Handle a END line by transitioning the parser's state
+ to finished. This means we have finished reading in the
+ reply packet.
+
+ Args:
+ line: A line read in from an lircd connection.
+
+ Raises:
+ LircdInvalidReplyPacketError: If the line does not contain END.
+ """
if line == "END":
self.__state = self.State.FINISHED
else:
@@ -160,6 +287,12 @@ class ReplyPacketParser:
)
def feed(self, line: str) -> None:
+ """
+ Feed a line from the reply packet into the parser.
+
+ Args:
+ A line from the lircd connection to feed in.
+ """
line = line.strip()
if not line: