[stem/master] Replace cell_attributes() with a couple class functions - tor-commits

21 Jan 2018

commit 0a46f3db4bb8a8fc5183041c93a990cb8f6a8eb8
Author: Damian Johnson atagar@torproject.org
Date:   Thu Jan 4 00:05:23 2018 -0800
Replace cell_attributes() with a couple class functions
---
 stem/client.py      | 118 +++++++++++++++++++++++++++++-----------------------
 test/unit/client.py |  25 +++++------
 2 files changed, 79 insertions(+), 64 deletions(-)

diff --git a/stem/client.py b/stem/client.py
index 136fc240..8fe2878d 100644
--- a/stem/client.py
+++ b/stem/client.py
@@ -2,21 +2,21 @@
 # See LICENSE for licensing information
"""
-Module for interacting with the ORPort provided by Tor relays. The
-:class:`~stem.client.Relay` is a wrapper for :class:`~stem.socket.RelaySocket`,
-providing higher level functions in much the same way as our
-:class:`~stem.control.Controller` wraps :class:`~stem.socket.ControlSocket`.
+Interaction with a Tor relay's ORPort. :class:`~stem.client.Relay` is
+a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as
+:class:`~stem.control.Controller` provides higher level functions for
+:class:`~stem.socket.ControlSocket`.
.. versionadded:: 1.7.0
-.. data:: PackType (enum)
+.. data:: Pack (enum)
Unsigned `struct.pack format
   https://docs.python.org/2/library/struct.html#format-characters` for
   network-order fields.
====================  ===========
-  PackType              Description
+  Pack                  Description
   ====================  ===========
   CHAR                  Unsigned char (1 byte)
   SHORT                 Unsigned short (2 bytes)
@@ -36,17 +36,10 @@ import struct
from stem.util import enum
-PackType = enum.Enum(
-  ('CHAR', '!B'),       # 1 byte
-  ('SHORT', '!H'),      # 2 bytes
-  ('LONG', '!L'),       # 4 bytes
-  ('LONG_LONG', '!Q'),  # 8 bytes
-)
-
-class CellAttributes(collections.namedtuple('CellAttributes', ['name', 'value', 'fixed_size', 'for_circuit'])):
+class Cell(collections.namedtuple('Cell', ['name', 'value', 'fixed_size', 'for_circuit'])):
   """
-  Metadata for cells tor will accept on its ORPort.
+  Metadata for ORPort cells.
:var str name: name of the cell type
   :var int value: integer value of the command on the wire
@@ -56,52 +49,44 @@ class CellAttributes(collections.namedtuple('CellAttributes', ['name', 'value',
     **False** otherwise
   """
+  @staticmethod
+  def by_name(name):
+    """
+    Provides cell attributes by its name.
-CELL_ATTR = (
-  CellAttributes('PADDING', 0, True, False),              # Padding                  (section 7.2)
-  CellAttributes('CREATE', 1, True, True),                # Create a circuit         (section 5.1)
-  CellAttributes('CREATED', 2, True, True),               # Acknowledge create       (section 5.1)
-  CellAttributes('RELAY', 3, True, True),                 # End-to-end data          (section 5.5 and 6)
-  CellAttributes('DESTROY', 4, True, True),               # Stop using a circuit     (section 5.4)
-  CellAttributes('CREATE_FAST', 5, True, True),           # Create a circuit, no PK  (section 5.1)
-  CellAttributes('CREATED_FAST', 6, True, True),          # Circuit created, no PK   (section 5.1)
-  CellAttributes('VERSIONS', 7, False, False),            # Negotiate proto version  (section 4)
-  CellAttributes('NETINFO', 8, True, False),              # Time and address info    (section 4.5)
-  CellAttributes('RELAY_EARLY', 9, True, True),           # End-to-end data; limited (section 5.6)
-  CellAttributes('CREATE2', 10, True, True),              # Extended CREATE cell     (section 5.1)
-  CellAttributes('CREATED2', 11, True, True),             # Extended CREATED cell    (section 5.1)
-  CellAttributes('PADDING_NEGOTIATE', 12, True, False),   # Padding negotiation      (section 7.2)
-  CellAttributes('VPADDING', 128, False, False),          # Variable-length padding  (section 7.2)
-  CellAttributes('CERTS', 129, False, False),             # Certificates             (section 4.2)
-  CellAttributes('AUTH_CHALLENGE', 130, False, False),    # Challenge value          (section 4.3)
-  CellAttributes('AUTHENTICATE', 131, False, False),      # Client authentication    (section 4.5)
-  CellAttributes('AUTHORIZE', 132, False, False),         # Client authorization     (not yet used)
-)
+    :parm str name: name of the cell type to fetch
+    :raise: **ValueError** if cell type is invalid
+    """
-class Relay(object):
-  """
-  Connection with a `Tor relay's ORPort
-  https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt`_.
-  """
+    for cell_type in CELL_TYPES:
+      if name == cell_type.name:
+        return cell_type
+    raise ValueError("'%s' isn't a valid cell type" % name)
-def cell_attributes(cell_type):
-  """
-  Provides attributes of the given cell type.
+  @staticmethod
+  def by_value(value):
+    """
+    Provides cell attributes by its value.
-  :parm str,int cell_type: cell type as either a string or integer
+    :parm int value: value of the cell type to fetch
-  :raise: **ValueError** if cell type is invalid
-  """
+    :raise: **ValueError** if cell type is invalid
+    """
-  param = 'value' if isinstance(cell_type, int) else 'name'
+    for cell_type in CELL_TYPES:
+      if value == cell_type.value:
+        return cell_type
-  for attr in CELL_ATTR:
-    if getattr(attr, param) == cell_type:
-      return attr
+    raise ValueError("'%s' isn't a valid cell value" % value)
-  raise ValueError("'%s' isn't a valid cell type" % cell_type)
+
+class Relay(object):
+  """
+  Connection with a `Tor relay's ORPort
+  https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt`_.
+  """
def serialize_versions(versions):
@@ -113,4 +98,33 @@ def serialize_versions(versions):
   :returns: **bytes** with a payload for these versions
   """
-  return b''.join([struct.pack(PackType.SHORT, +  return b''.join([struct.pack(Pack.SHORT, + + +Pack = enum.Enum( +  ('CHAR', '!B'),       # 1 byte +  ('SHORT', '!H'),      # 2 bytes +  ('LONG', '!L'),       # 4 bytes +  ('LONG_LONG', '!Q'),  # 8 bytes +) + +CELL_TYPES = ( +  Cell('PADDING', 0, True, False), +  Cell('CREATE', 1, True, True), +  Cell('CREATED', 2, True, True), +  Cell('RELAY', 3, True, True), +  Cell('DESTROY', 4, True, True), +  Cell('CREATE_FAST', 5, True, True), +  Cell('CREATED_FAST', 6, True, True), +  Cell('VERSIONS', 7, False, False), +  Cell('NETINFO', 8, True, False), +  Cell('RELAY_EARLY', 9, True, True), +  Cell('CREATE2', 10, True, True), +  Cell('CREATED2', 11, True, True), +  Cell('PADDING_NEGOTIATE', 12, True, False), +  Cell('VPADDING', 128, False, False), +  Cell('CERTS', 129, False, False), +  Cell('AUTH_CHALLENGE', 130, False, False), +  Cell('AUTHENTICATE', 131, False, False), +  Cell('AUTHORIZE', 132, False, False), +) diff --git a/test/unit/client.py index 204c55fd..1d2df417 100644 --- a/test/unit/client.py +++ b/test/unit/client.py @@ -4,21 +4,22 @@ Unit tests

v) for v in versions]) v) for v in versions]) # Padding                  (section 7.2) # Create a circuit         (section 5.1) # Acknowledge create       (section 5.1) # End-to-end data          (section 5.5 and 6) # Stop using a circuit     (section 5.4) # Create a circuit, no PK  (section 5.1) # Circuit created, no PK   (section 5.1) # Negotiate proto version  (section 4) # Time and address info    (section 4.5) # End-to-end data; limited (section 5.6) # Extended CREATE cell     (section 5.1) # Extended CREATED cell    (section 5.1) # Padding negotiation      (section 7.2) # Variable-length padding  (section 7.2) # Certificates             (section 4.2) # Challenge value          (section 4.3) # Client authentication    (section 4.5) # Client authorization     (not yet used) b/test/unit/client.py for the stem.client.
import unittest
-import stem.client
+from stem.client import Cell
class TestClient(unittest.TestCase):
-  def test_cell_attributes(self):
-    attr = stem.client.cell_attributes('NETINFO')
+  def test_cell_fetching(self):
+    cell = Cell.by_name('NETINFO')
-    self.assertEqual('NETINFO', attr.name)
-    self.assertEqual(8, attr.value)
-    self.assertEqual(True, attr.fixed_size)
-    self.assertEqual(False, attr.for_circuit)
+    self.assertEqual('NETINFO', cell.name)
+    self.assertEqual(8, cell.value)
+    self.assertEqual(True, cell.fixed_size)
+    self.assertEqual(False, cell.for_circuit)
-    self.assertEqual(10, stem.client.cell_attributes('CREATE2').value)
-    self.assertEqual('CREATE2', stem.client.cell_attributes(10).name)
+    self.assertEqual(10, Cell.by_name('CREATE2').value)
+    self.assertEqual('CREATE2', Cell.by_value(10).name)
-    self.assertRaises(ValueError, stem.client.cell_attributes, 'NOPE')
-    self.assertRaises(ValueError, stem.client.cell_attributes, 85)
-    self.assertRaises(ValueError, stem.client.cell_attributes, None)
+    self.assertRaises(ValueError, Cell.by_name, 'NOPE')
+    self.assertRaises(ValueError, Cell.by_value, 'NOPE')
+    self.assertRaises(ValueError, Cell.by_name, 85)
+    self.assertRaises(ValueError, Cell.by_name, None)

    