documented attributes

1 files changed, 83 insertions, 35 deletions

diff --git a/oo.py b/oo.py
index 73ef21d..ced8d8f 100644
--- a/oo.py
+++ b/oo.py
@@ -6,10 +6,52 @@ class ooPuzzle:
 
     No rendering information is stored or interpreted here.
 
-    Attributes.
-            X,Y : horizontal and vertical size of the puzzle
-         pieces : dictionary mapping (x,y) to range(6)
-        orients : dictionary mapping (x,y) to range(4)
+    All attributes are intended to be accessed through methods.
+    If direct access is necessary, here are their explanations:
+
+        DIRECTIONS is a dictionary mapping:
+            each direction as a string
+            to a direction index in range(4)
+            
+        DX_DY is a list mapping:
+            each direction index in range(4)
+            to a differential of form (dx, dy)
+            
+        EDGES_TO_PIECE_ORIENT is a dictionary mapping:
+            each tuple of edge-filled statuses in order of direction
+            to a tuple of (piece id in range(6),
+                           orientation direction in range(4))
+                           
+        PIECE_ORIENT_TO_EDGES is an inverse of the previous mapping.
+        
+    (the following are attributes set by __init__)
+
+        X is an integer for the range of x-positions
+
+        Y is an integer for the range of y-positions
+
+        game_id is an integer used by set_pieces_from_game_id
+            It uniquely corresponds to the solution.
+
+        inverted is a bool indicating whether
+            pieces and inverted_pieces have been swapped
+            NOT IMPLEMENTED!
+
+        toroidal is a bool indicating whether
+            the border of the puzzle loops back to the opposite side
+            NOT IMPLEMENTED!
+
+    (the following are variable attributes during normal usage)
+
+        pieces is a dictionary mapping:
+            each position of form (x in range(self.X),
+                                   y in range(self.Y))
+            to a piece id in range(6)
+            
+        orients is a dictionary mapping:
+            each position of form (x in range(self.X),
+                                   y in range(self.Y))
+            to a direction index in range(4)
     """
     def __init__(self, X, Y, game_id=None, inverted=False, toroidal=False):
         """Create a new ooPuzzle instance.
@@ -29,28 +71,20 @@ class ooPuzzle:
         self.orients = {}
         self.set_pieces_from_game_id(game_id)
 
-    EDGES_TO_PIECE_ORIENT = { (0, 0, 0, 0) : (0, 0),
-
-                              (1, 0, 0, 0) : (1, 0),
-                              (0, 1, 0, 0) : (1, 1),
-                              (0, 0, 1, 0) : (1, 2),
-                              (0, 0, 0, 1) : (1, 3),
-
-                              (1, 1, 0, 0) : (2, 0),
-                              (0, 1, 1, 0) : (2, 1),
-                              (0, 0, 1, 1) : (2, 2),
-                              (1, 0, 0, 1) : (2, 3),
-
-                              (1, 0, 1, 0) : (3, 0),
-                              (0, 1, 0, 1) : (3, 1),
-
-                              (0, 1, 1, 1) : (4, 0),
-                              (1, 0, 1, 1) : (4, 1),
-                              (1, 1, 0, 1) : (4, 2),
-                              (1, 1, 1, 0) : (4, 3),
+    # Changing conceptual directions into indices.
+    DIRECTIONS = {'LEFT' : 0,
+                  'UP'   : 1,
+                  'RIGHT': 2,
+                  'DOWN' : 3}
 
-                              (1, 1, 1, 1) : (5, 0) }
+    # Changing direction indices into (dx, dy) pairs.
+    DX_DY = [(-1,  0),
+             ( 0, -1),
+             ( 1,  0),
+             ( 0,  1)]
 
+    # Given piece id and orientation direction,
+    # return edge-filled status for each direction.
     PIECE_ORIENT_TO_EDGES = { (0, 0) : (0, 0, 0, 0),
                               (0, 1) : (0, 0, 0, 0),
                               (0, 2) : (0, 0, 0, 0),
@@ -81,6 +115,29 @@ class ooPuzzle:
                               (5, 2) : (1, 1, 1, 1),
                               (5, 3) : (1, 1, 1, 1) }
 
+    # One choice of inverse of the previous dictionary.
+    EDGES_TO_PIECE_ORIENT = { (0, 0, 0, 0) : (0, 0),
+
+                              (1, 0, 0, 0) : (1, 0),
+                              (0, 1, 0, 0) : (1, 1),
+                              (0, 0, 1, 0) : (1, 2),
+                              (0, 0, 0, 1) : (1, 3),
+
+                              (1, 1, 0, 0) : (2, 0),
+                              (0, 1, 1, 0) : (2, 1),
+                              (0, 0, 1, 1) : (2, 2),
+                              (1, 0, 0, 1) : (2, 3),
+
+                              (1, 0, 1, 0) : (3, 0),
+                              (0, 1, 0, 1) : (3, 1),
+
+                              (0, 1, 1, 1) : (4, 0),
+                              (1, 0, 1, 1) : (4, 1),
+                              (1, 1, 0, 1) : (4, 2),
+                              (1, 1, 1, 0) : (4, 3),
+
+                              (1, 1, 1, 1) : (5, 0) }
+
     def set_pieces_from_edges(self, horiz_edges, vert_edges):
         """Convert edge dictionaries into a puzzle state.
 
@@ -185,17 +242,8 @@ class ooPuzzle:
             for y in range(self.Y):
                 self.orients[x, y] = random.randrange(4)
 
-    DIRECTIONS = {'LEFT' : 0,
-                  'UP'   : 1,
-                  'RIGHT': 2,
-                  'DOWN' : 3}
-
-    DX_DY = [(-1,  0),
-             ( 0, -1),
-             ( 1,  0),
-             ( 0,  1)]
-
-    def position_in_direction(self, x0, y0, direction, return_is_internal=False):
+    def position_in_direction(self, x0, y0, direction,
+            return_is_internal=False):
         """Returns the position adjacent to (x0, y0) in direction.
         
         direction may be any string or integer in the dictionary