ryu/build/lib.linux-armv7l-2.7/ryu/lib/packet/stream_parser.py

   1 # Copyright (C) 2013 Nippon Telegraph and Telephone Corporation.
   2 # Copyright (C) 2013 YAMAMOTO Takashi <yamamoto at valinux co jp>
   3 #
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at
   7 #
   8 #    http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  13 # implied.
  14 # See the License for the specific language governing permissions and
  15 # limitations under the License.
  16
  17
  18 from abc import ABCMeta, abstractmethod
  19 import six
  20
  21
  22 @six.add_metaclass(ABCMeta)
  23 class StreamParser(object):
  24     """Streaming parser base class.
  25
  26     An instance of a subclass of this class is used to extract messages
  27     from a raw byte stream.
  28
  29     It's designed to be used for data read from a transport which doesn't
  30     preserve message boundaries.  A typical example of such a transport
  31     is TCP.
  32
  33     """
  34     class TooSmallException(Exception):
  35         pass
  36
  37     def __init__(self):
  38         self._q = bytearray()
  39
  40     def parse(self, data):
  41         """Tries to extract messages from a raw byte stream.
  42
  43         The data argument would be python bytes newly read from the input
  44         stream.
  45
  46         Returns an ordered list of extracted messages.
  47         It can be an empty list.
  48
  49         The rest of data which doesn't produce a complete message is
  50         kept internally and will be used when more data is come.
  51         I.e. next time this method is called again.
  52         """
  53         self._q.append(data)
  54         msgs = []
  55         while True:
  56             try:
  57                 msg, self._q = self.try_parse(self._q)
  58             except self.TooSmallException:
  59                 break
  60             msgs.append(msg)
  61         return msgs
  62
  63     @abstractmethod
  64     def try_parse(self, q):
  65         """Try to extract a message from the given bytes.
  66
  67         This is an override point for subclasses.
  68
  69         This method tries to extract a message from bytes given by the
  70         argument.
  71
  72         Raises TooSmallException if the given data is not enough to
  73         extract a complete message but there's still a chance to extract
  74         a message if more data is come later.
  75         """
  76         pass