Additional documentation

LabelGenerator.py

@@ -117,12 +117,6 @@ def __init__(
     num_stickers_vertical=8,
 )
 
-E12 = [ 1.0, 1.2, 1.5, 1.8, 2.2, 2.7, 3.3, 3.9, 4.7, 5.6, 6.8, 8.2 ]
-
-# 1.1, 1.3, and 1.6 are commonly ommitted from the resistor E24 series
-E24 = [ 1.0, 1.2, 1.5, 1.8, 2.0, 2.2, 2.4, 2.7, 3.0, 3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5, 8.2, 9.1]
-E24_ALL = [ 1.0, 1.1, 1.2, 1.3, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.7, 3.0, 3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5, 8.2, 9.1 ]
-
 class StickerRect:
     def __init__(self, c: Canvas, layout: PaperConfig, row: int, column: int, mirror: bool):
         self.left = layout.left_margin + layout.horizontal_stride * column
@@ -607,19 +601,52 @@ def render_outlines(c: Canvas, layout: PaperConfig) -> None:
                 c.setLineWidth(0)
                 c.roundRect(rect.left, rect.bottom, rect.width, rect.height, rect.corner)
 
-def generate_decade(
+
+# Resistor values typically come from an "E series of preferred numbers". This is why apparently
+# random values such as 22, 39, or 47 are common, but some round numbers like 25, 40, or 50
+# are rarely seen.  10% resistors usually come from the E12 series, while 5% resistors usually 
+# come from to an abridged version of the E24 series.
+#
+# The list constants below can be used with the generate_values function to quickly create sets of
+# common resistor values.
+E12_VALUES = [ 1.0, 1.2, 1.5, 1.8, 2.2, 2.7, 3.3, 3.9, 4.7, 5.6, 6.8, 8.2 ]
+E24_COMMON_VALUES = [ 1.0,      1.2,      1.5,      1.8, 2.0, 2.2, 2.4, 2.7, 3.0, 3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5, 8.2, 9.1 ]
+E24_ALL_VALUES =    [ 1.0, 1.1, 1.2, 1.3, 1.5, 1.6, 1.8, 2.0, 2.2, 2.4, 2.7, 3.0, 3.3, 3.6, 3.9, 4.3, 4.7, 5.1, 5.6, 6.2, 6.8, 7.5, 8.2, 9.1 ]
+
+# Scales a list of values by a power of 10. The list may be one of the E constants above, or your
+# own list of values.
+#
+# Examples:
+#   scale_values([1.0, 4.7, 7.5], 2) -> [100, 470, 750]
+#
+#   scale_values(E12_VALUES, 1) -> [ 10, 12, 15, 18, 22, 27, 33, 39, 47, 56, 68, 82 ]
+def scale_values(
         series: List[float], # the base series of resistor values
         power: int           # the power of 10 to scale the series by
 ) -> List[float]:
     scalar = 10 ** power
     return [scalar * x for x in series]
 
-def generate_decades(
-        series: List[float],
-        first_decade: int,
-        last_decade: int
+# Expands a list of values into several lists, each scaled by increasing powers of 10. The list may
+# be one of the E constants above, or your own list of values.
+#
+# Examples:
+#   generate_values([1.0, 4.7, 7.5], 0, 2) -> [
+#      [ 1.0,  4.7, 7.5 ], # 10 ** 0 -> x1
+#      [  10,   47,  75 ], # 10 ** 1 -> x10
+#      [ 100,  470, 750 ]  # 10 ** 2 -> x100
+#    ]
+#
+#   generate_values(E12_VALUES, 1, 2) -> [
+#      [  10,  12,  15,  18,  22,  27,  33,  39,  47,  56,  68,  82 ], # 10 ** 1 -> x10
+#      [ 100, 120, 150, 180, 220, 270, 330, 390, 470, 560, 680, 820 ]  # 10 ** 2 -> x100
+#    ]
+def generate_values(
+        series: List[float], # the base series of resistor values
+        first_power: int,    # the first power of 10 to scale the series by
+        last_power: int      # the last power of 10 to scale the series by
 ) -> ResistorList:
-    return [generate_decade(series, x) for x in range(first_decade, last_decade)]
+    return [scale_values(series, x) for x in range(first_power, last_power)]
 
 def main() -> None:
 
@@ -651,10 +678,10 @@ def main() -> None:
     ]
 
     # ############################################################################
-    # Alternatively, The E12, E24, and E24_ALL constants can be passed to the 
-    # generate_decades function to create typical resistor value sets.
+    # Alternatively, a set of common resistor values can be generated by the 
+    # generate_values function.
     # ############################################################################
-    # resistor_values: ResistorList = [ 0, 0.01 ] + generate_decades(E24, 0, 6)
+    # resistor_values: ResistorList = [ 0, 0.01 ] + generate_values(E24_COMMON_VALUES, 0, 6)
 
     # ############################################################################
     # Further configuration options