[tor-commits] [stem/master] Stub an unpack function

[atagar at torproject.org]

commit e6afab70873d58aea34944f5180940b82fb37c7c
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Jan 10 11:46:08 2018 -0800

    Stub an unpack function
---
 stem/client/cell.py      | 56 +++++++++++++++++++++++++++++++++++++-----------
 test/unit/client/cell.py |  3 +++
 2 files changed, 46 insertions(+), 13 deletions(-)

diff --git a/stem/client/cell.py b/stem/client/cell.py
index 15adceae..7c680c4e 100644
--- a/stem/client/cell.py
+++ b/stem/client/cell.py
@@ -22,15 +22,15 @@ Messages communicated over a Tor relay's ORPort.
     |  |- Create2Cell - Extended CREATE cell.         (section 5.1)
     |  +- Created2Cell - Extended CREATED cell.       (section 5.1)
     |
-    |- PaddingCell - Padding negotiation.           (section 7.2)
-    |- VersionsCell - Negotiate proto version.      (section 4)
-    |- NetinfoCell - Time and address info.         (section 4.5)
-    |- PaddingNegotiateCell - Padding negotiation.  (section 7.2)
-    |- VPaddingCell - Variable-length padding.      (section 7.2)
-    |- CertsCell - Relay certificates.              (section 4.2)
-    |- AuthChallengeCell - Challenge value.         (section 4.3)
-    |- AuthenticateCell - Client authentication.    (section 4.5)
-    |- AuthorizeCell - Client authorization.        (not yet used)
+    |- PaddingCell - Padding negotiation.             (section 7.2)
+    |- VersionsCell - Negotiate proto version.        (section 4)
+    |- NetinfoCell - Time and address info.           (section 4.5)
+    |- PaddingNegotiateCell - Padding negotiation.    (section 7.2)
+    |- VPaddingCell - Variable-length padding.        (section 7.2)
+    |- CertsCell - Relay certificates.                (section 4.2)
+    |- AuthChallengeCell - Challenge value.           (section 4.3)
+    |- AuthenticateCell - Client authentication.      (section 4.5)
+    |- AuthorizeCell - Client authorization.          (not yet used)
     |
     |- pack - Provides encoded bytes for this cell class.
     +- unpack - Decodes bytes for this cell class.
@@ -93,6 +93,22 @@ class Cell(collections.namedtuple('Cell', ['name', 'value', 'fixed_size', 'for_c
 
     raise ValueError("'%s' isn't a valid cell value" % value)
 
+  @staticmethod
+  def unpack(content):
+    """
+    Unpacks encoded bytes into a Cell subclass.
+
+    :param bytes content: payload to decode
+
+    :returns: :class:`~stem.client.cell.Cell` subclass
+
+    :raises:
+      * ValueError if content is malformed
+      * NotImplementedError if unable to unpack this cell type
+    """
+
+    return AuthorizeCell._unpack(content)
+
   @classmethod
   def _pack(cls, link_version, payload, circ_id = 0):
     """
@@ -103,9 +119,9 @@ class Cell(collections.namedtuple('Cell', ['name', 'value', 'fixed_size', 'for_c
     :param bytes payload: cell payload
     :param int circ_id: circuit id, if a CircuitCell
 
-    :raise: **ValueError** if...
-      * cell type or circuit id is invalid
-      * payload is too large
+    :return: **bytes** with the encoded payload
+
+    :raise: **ValueError** if cell type invalid or payload is too large
     """
 
     packed_circ_id = struct.pack(Pack.LONG if link_version > 3 else Pack.SHORT, circ_id)
@@ -125,6 +141,20 @@ class Cell(collections.namedtuple('Cell', ['name', 'value', 'fixed_size', 'for_c
 
     return cell
 
+  @classmethod
+  def _unpack(cls, content):
+    """
+    Subclass implementation for unpacking cell content.
+
+    :param bytes content: payload to decode
+
+    :returns: instance of this cell type
+
+    :raises: **ValueError** if content is malformed
+    """
+
+    raise NotImplementedError('Unpacking not yet implemented for %s cells' % cls.NAME)
+
 
 class CircuitCell(Cell):
   """
@@ -141,7 +171,7 @@ class CircuitCell(Cell):
     :param bytes payload: cell payload
     :param int circ_id: circuit id
 
-    :raise: **ValueError** if cell type is invalid or payload is too large
+    :raise: **ValueError** if cell type invalid or payload is too large
     """
 
     if circ_id is None and cls.NAME.startswith('CREATE'):
diff --git a/test/unit/client/cell.py b/test/unit/client/cell.py
index b688d9e5..1335a77c 100644
--- a/test/unit/client/cell.py
+++ b/test/unit/client/cell.py
@@ -28,6 +28,9 @@ class TestCell(unittest.TestCase):
     self.assertRaises(ValueError, Cell.by_value, 85)
     self.assertRaises(ValueError, Cell.by_value, None)
 
+  def test_unpack_not_implemented(self):
+    self.assertRaisesRegexp(NotImplementedError, 'Unpacking not yet implemented for AUTHORIZE cells', Cell.unpack, 'boom')
+
   def test_versions_pack(self):
     self.assertEqual('\x00\x00\x07\x00\x00', VersionsCell.pack([]))
     self.assertEqual('\x00\x00\x07\x00\x02\x00\x01', VersionsCell.pack([1]))