Mercurial > public > m209

comparison docs/library.rst @ 63:a56fca44e0ed

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added more key list docs.
author Brian Neal <bgneal@gmail.com>
date Fri, 19 Jul 2013 20:29:45 -0500
parents 42d7e5410dbd
children 72e0bda6df40
comparison
equal deleted inserted replaced
62:42d7e5410dbd 63:a56fca44e0ed
20 * ``pin_list`` - a list of six strings which represent key wheel pin 20 * ``pin_list`` - a list of six strings which represent key wheel pin
21 settings; see below 21 settings; see below
22 * ``letter_check`` - a string representing the letter check used to verify 22 * ``letter_check`` - a string representing the letter check used to verify
23 operator settings; if unknown this can be ``None`` or an empty string 23 operator settings; if unknown this can be ``None`` or an empty string
24 24
25 Lug settings string format 25 Lug settings format
26 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 26 ~~~~~~~~~~~~~~~~~~~
27 27
28 Drum lug settings are often conveniently represented as strings consisting of 28 Drum lug settings are often conveniently represented as strings consisting of
29 at most 27 whitespace-separated pairs of integers separated by dashes. For 29 at most 27 whitespace-separated pairs of integers separated by dashes. For
30 example:: 30 example::
31 31
69 wheel3 = 'DEFGIKNOSUX' 69 wheel3 = 'DEFGIKNOSUX'
70 wheel4 = 'BFGJKRS' 70 wheel4 = 'BFGJKRS'
71 wheel5 = 'ABCDFGHIJMPS' 71 wheel5 = 'ABCDFGHIJMPS'
72 wheel6 = 'ADEFHIJKN' 72 wheel6 = 'ADEFHIJKN'
73 73
74 Key List Example 74 Key list example
75 ~~~~~~~~~~~~~~~~ 75 ~~~~~~~~~~~~~~~~
76 76
77 An example of using the :py:class:`m209.keylist.KeyList` is: 77 An example of using the :class:`~m209.keylist.KeyList` is:
78 78
79 .. code-block:: python 79 .. code-block:: python
80 80
81 from m209.keylist import KeyList 81 from m209.keylist import KeyList
82 82
90 'ACFGHILMRSU', 90 'ACFGHILMRSU',
91 'BCDEFJKLPS', 91 'BCDEFJKLPS',
92 'EFGHIJLMNP' 92 'EFGHIJLMNP'
93 ], 93 ],
94 letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J') 94 letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')
95
96 Key list file I/O
97 ~~~~~~~~~~~~~~~~~
98
99 Key lists can be stored in files in config file ("INI") style format using
100 functions found in the ``m209.keylist.config`` module.
101
102 .. function:: m209.keylist.config.read_key_list(fname[, indicator=None])
103
104 Reads key list information from the file given by ``fname``.
105
106 Searches the config file for the key list with the given indicator. If
107 found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if
108 not found.
109
110 If ``indicator`` is ``None``, a key list is chosen from the file at random.
111
112 .. function:: m209.keylist.config.write(fname, key_lists)
113
114 Writes the key lists to the file named ``fname`` in config file format.
115
116 ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects.
117
118 Key list file format
119 ++++++++++++++++++++
120
121 An example key list file in config file format is presented below. The label
122 for each section of the file is the key list indicator.
123
124 ::
125
126 [CA]
127 lugs = 0-5*5 0-6*2 1-0*7 1-2 1-3*3 1-6 2-0 3-0*3 3-5*2 3-6 4-5
128 wheel1 = ABCDFGHJLOPRVWYZ
129 wheel2 = BCDEIJKPQSUVX
130 wheel3 = ACDGLNQRSTUV
131 wheel4 = FGHIJNQRSU
132 wheel5 = DEIJOQS
133 wheel6 = BCDEILMNOP
134 check = RGPRO RTYOO TWYSN GXTPF PNWIH P
135
136 [CD]
137 lugs = 0-4*4 0-5 1-0*7 1-2*2 1-4*3 2-0*2 2-4*2 2-6*2 3-0*4
138 wheel1 = AEFHIKMPQRSUVZ
139 wheel2 = ABFGHINORSUVZ
140 wheel3 = BDEHJKLMNOQRSU
141 wheel4 = CDEFGHJKMRU
142 wheel5 = FGHIJOQS
143 wheel6 = EGIJKLP
144 check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H
145
146 Generating key lists
147 ~~~~~~~~~~~~~~~~~~~~
148
149 The ``m209`` library contains a function to pseudo-randomly generate a key list
150 that is based on the procedure described in the 1944 M-209 manual.
151
152 .. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS])
153
154 The only required parameter is ``indicator``, the two-letter indicator for
155 the key list.
156
157 If successful, a :class:`~m209.keylist.KeyList` object is returned.
158
159 If a :class:`~m209.keylist.KeyList` could not be generated
160 a ``KeyListGenError`` exception is raised.
161
162 The algorithm is heuristic-based and makes random decisions based upon the
163 1944 procedure. The actual procedure is loosely specified in the manual, and
164 much is left up to the human operator. It is possible that the algorithm
165 cannot find a solution to meet the key list requirements specified in the
166 manual, in which case it simply tries again up to some set of limits. These
167 limits can be tweaked using the optional parameters to the algorithm. If no
168 solution is found after exhausting the limits, a ``KeyListGenError`` is
169 raised.
170
171 The optional parameters are:
172
173 * ``lug_selection`` - a list of 6 integers used to drive the lug settings
174 portion of the algorithm. If not supplied, a list of 6 integers is chosen
175 from data tables that appear in the 1944 manual. For more information on
176 the requirements for these integers, see the manual.
177
178 * ``max_lug_attempts`` - the maximum number of times to attempt to create
179 lug settings before giving up
180
181 * ``max_pin_attempts`` - the maximum number of times to attempt to generate
182 key wheel pin settings before giving up
183