# HG changeset patch # User Brian Neal # Date 1374344785 18000 # Node ID 72e0bda6df4050a2c1459187d37487d821e55dc1 # Parent a56fca44e0ed09b9c795a789383e7906eda12b3a Split key list docs into own source file. diff -r a56fca44e0ed -r 72e0bda6df40 docs/keylist.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/keylist.rst Sat Jul 20 13:26:25 2013 -0500 @@ -0,0 +1,176 @@ +Key lists +--------- + +Key lists are represented as a named tuple called ``KeyList``. + +.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check) + + As a named tuple, ``KeyList`` has the following attributes: + + * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in + the range ``AA`` - ``ZZ`` + * ``lugs`` - a string representing the drum lug settings; see below + * ``pin_list`` - a list of six strings which represent key wheel pin + settings; see below + * ``letter_check`` - a string representing the letter check used to verify + operator settings; if unknown this can be ``None`` or an empty string + +Lug settings format +~~~~~~~~~~~~~~~~~~~ + +Drum lug settings are often conveniently represented as strings consisting of +at most 27 whitespace-separated pairs of integers separated by dashes. For +example:: + + lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6' + +Each integer pair must be in the form ``m-n`` where m & n are integers +between 0 and 6, inclusive. Each integer represents a lug position where +0 is a neutral position, and 1-6 correspond to key wheel positions. If +m & n are both non-zero, they cannot be equal. + +If a string has less than 27 pairs, it is assumed all remaining bars have both +lugs in the neutral (0) positions. + +Order of the pairs within the string does not matter. + +To reduce typing and to aid in readability, an alternate shortcut notation is +supported:: + + lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6' + +Any pair that is suffixed by ``*k``, where k is a positive integer, means there +are ``k`` copies of the preceeding lug pair combination. For example, these two +strings describe identical drum configurations:: + + lugs1 = '2-4 2-4 2-4 0-1 0-1' + lugs2 = '2-4*3 0-1*2' + +Key wheel pin settings +~~~~~~~~~~~~~~~~~~~~~~ + +Key wheel pin settings are represented as iterables of letters whose pins are +slid to the "effective" position (to the right). Letters not appearing in this +sequence are considered to be in the "ineffective" position (to the left). If +None or empty, all pins are set to be ineffective. + +Examples:: + + all_ineffective = '' + wheel1 = 'ABDEFHIJMQSUXZ' + wheel2 = 'EINPQRTVXZ' + wheel3 = 'DEFGIKNOSUX' + wheel4 = 'BFGJKRS' + wheel5 = 'ABCDFGHIJMPS' + wheel6 = 'ADEFHIJKN' + +Key list example +~~~~~~~~~~~~~~~~ + +An example of using the :class:`~m209.keylist.KeyList` is: + +.. code-block:: python + + from m209.keylist import KeyList + + key_list1 = KeyList( + indicator='AA', + lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6', + pin_list=[ + 'FGIKOPRSUVWYZ', + 'DFGKLMOTUY', + 'ADEFGIORTUVX', + 'ACFGHILMRSU', + 'BCDEFJKLPS', + 'EFGHIJLMNP' + ], + letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J') + +Key list file I/O +~~~~~~~~~~~~~~~~~ + +Key lists can be stored in files in config file ("INI") style format using +functions found in the ``m209.keylist.config`` module. + +.. function:: m209.keylist.config.read_key_list(fname[, indicator=None]) + + Reads key list information from the file given by ``fname``. + + Searches the config file for the key list with the given indicator. If + found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if + not found. + + If ``indicator`` is ``None``, a key list is chosen from the file at random. + +.. function:: m209.keylist.config.write(fname, key_lists) + + Writes the key lists to the file named ``fname`` in config file format. + + ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects. + +Key list file format +++++++++++++++++++++ + +An example key list file in config file format is presented below. The label +for each section of the file is the key list indicator. + +:: + + [CA] + 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 + wheel1 = ABCDFGHJLOPRVWYZ + wheel2 = BCDEIJKPQSUVX + wheel3 = ACDGLNQRSTUV + wheel4 = FGHIJNQRSU + wheel5 = DEIJOQS + wheel6 = BCDEILMNOP + check = RGPRO RTYOO TWYSN GXTPF PNWIH P + + [CD] + 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 + wheel1 = AEFHIKMPQRSUVZ + wheel2 = ABFGHINORSUVZ + wheel3 = BDEHJKLMNOQRSU + wheel4 = CDEFGHJKMRU + wheel5 = FGHIJOQS + wheel6 = EGIJKLP + check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H + +Generating key lists +~~~~~~~~~~~~~~~~~~~~ + +The ``m209`` library contains a function to pseudo-randomly generate a key list +that is based on the procedure described in the 1944 M-209 manual. + +.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS]) + + The only required parameter is ``indicator``, the two-letter indicator for + the key list. + + If successful, a :class:`~m209.keylist.KeyList` object is returned. + + If a :class:`~m209.keylist.KeyList` could not be generated + a ``KeyListGenError`` exception is raised. + + The algorithm is heuristic-based and makes random decisions based upon the + 1944 procedure. The actual procedure is loosely specified in the manual, and + much is left up to the human operator. It is possible that the algorithm + cannot find a solution to meet the key list requirements specified in the + manual, in which case it simply tries again up to some set of limits. These + limits can be tweaked using the optional parameters to the algorithm. If no + solution is found after exhausting the limits, a ``KeyListGenError`` is + raised. + + The optional parameters are: + + * ``lug_selection`` - a list of 6 integers used to drive the lug settings + portion of the algorithm. If not supplied, a list of 6 integers is chosen + from data tables that appear in the 1944 manual. For more information on + the requirements for these integers, see the manual. + + * ``max_lug_attempts`` - the maximum number of times to attempt to create + lug settings before giving up + + * ``max_pin_attempts`` - the maximum number of times to attempt to generate + key wheel pin settings before giving up + diff -r a56fca44e0ed -r 72e0bda6df40 docs/library.rst --- a/docs/library.rst Fri Jul 19 20:29:45 2013 -0500 +++ b/docs/library.rst Sat Jul 20 13:26:25 2013 -0500 @@ -5,179 +5,7 @@ ``m209`` library as part of their own application. This documentation covers the major classes and functions. -Key lists ---------- +.. toctree:: + :maxdepth: 3 -Key lists are represented as a named tuple called ``KeyList``. - -.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check) - - As a named tuple, ``KeyList`` has the following attributes: - - * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in - the range ``AA`` - ``ZZ`` - * ``lugs`` - a string representing the drum lug settings; see below - * ``pin_list`` - a list of six strings which represent key wheel pin - settings; see below - * ``letter_check`` - a string representing the letter check used to verify - operator settings; if unknown this can be ``None`` or an empty string - -Lug settings format -~~~~~~~~~~~~~~~~~~~ - -Drum lug settings are often conveniently represented as strings consisting of -at most 27 whitespace-separated pairs of integers separated by dashes. For -example:: - - lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6' - -Each integer pair must be in the form ``m-n`` where m & n are integers -between 0 and 6, inclusive. Each integer represents a lug position where -0 is a neutral position, and 1-6 correspond to key wheel positions. If -m & n are both non-zero, they cannot be equal. - -If a string has less than 27 pairs, it is assumed all remaining bars have both -lugs in the neutral (0) positions. - -Order of the pairs within the string does not matter. - -To reduce typing and to aid in readability, an alternate shortcut notation is -supported:: - - lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6' - -Any pair that is suffixed by ``*k``, where k is a positive integer, means there -are ``k`` copies of the preceeding lug pair combination. For example, these two -strings describe identical drum configurations:: - - lugs1 = '2-4 2-4 2-4 0-1 0-1' - lugs2 = '2-4*3 0-1*2' - -Key wheel pin settings -~~~~~~~~~~~~~~~~~~~~~~ - -Key wheel pin settings are represented as iterables of letters whose pins are -slid to the "effective" position (to the right). Letters not appearing in this -sequence are considered to be in the "ineffective" position (to the left). If -None or empty, all pins are set to be ineffective. - -Examples:: - - all_ineffective = '' - wheel1 = 'ABDEFHIJMQSUXZ' - wheel2 = 'EINPQRTVXZ' - wheel3 = 'DEFGIKNOSUX' - wheel4 = 'BFGJKRS' - wheel5 = 'ABCDFGHIJMPS' - wheel6 = 'ADEFHIJKN' - -Key list example -~~~~~~~~~~~~~~~~ - -An example of using the :class:`~m209.keylist.KeyList` is: - -.. code-block:: python - - from m209.keylist import KeyList - - key_list1 = KeyList( - indicator='AA', - lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6', - pin_list=[ - 'FGIKOPRSUVWYZ', - 'DFGKLMOTUY', - 'ADEFGIORTUVX', - 'ACFGHILMRSU', - 'BCDEFJKLPS', - 'EFGHIJLMNP' - ], - letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J') - -Key list file I/O -~~~~~~~~~~~~~~~~~ - -Key lists can be stored in files in config file ("INI") style format using -functions found in the ``m209.keylist.config`` module. - -.. function:: m209.keylist.config.read_key_list(fname[, indicator=None]) - - Reads key list information from the file given by ``fname``. - - Searches the config file for the key list with the given indicator. If - found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if - not found. - - If ``indicator`` is ``None``, a key list is chosen from the file at random. - -.. function:: m209.keylist.config.write(fname, key_lists) - - Writes the key lists to the file named ``fname`` in config file format. - - ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects. - -Key list file format -++++++++++++++++++++ - -An example key list file in config file format is presented below. The label -for each section of the file is the key list indicator. - -:: - - [CA] - 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 - wheel1 = ABCDFGHJLOPRVWYZ - wheel2 = BCDEIJKPQSUVX - wheel3 = ACDGLNQRSTUV - wheel4 = FGHIJNQRSU - wheel5 = DEIJOQS - wheel6 = BCDEILMNOP - check = RGPRO RTYOO TWYSN GXTPF PNWIH P - - [CD] - 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 - wheel1 = AEFHIKMPQRSUVZ - wheel2 = ABFGHINORSUVZ - wheel3 = BDEHJKLMNOQRSU - wheel4 = CDEFGHJKMRU - wheel5 = FGHIJOQS - wheel6 = EGIJKLP - check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H - -Generating key lists -~~~~~~~~~~~~~~~~~~~~ - -The ``m209`` library contains a function to pseudo-randomly generate a key list -that is based on the procedure described in the 1944 M-209 manual. - -.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS]) - - The only required parameter is ``indicator``, the two-letter indicator for - the key list. - - If successful, a :class:`~m209.keylist.KeyList` object is returned. - - If a :class:`~m209.keylist.KeyList` could not be generated - a ``KeyListGenError`` exception is raised. - - The algorithm is heuristic-based and makes random decisions based upon the - 1944 procedure. The actual procedure is loosely specified in the manual, and - much is left up to the human operator. It is possible that the algorithm - cannot find a solution to meet the key list requirements specified in the - manual, in which case it simply tries again up to some set of limits. These - limits can be tweaked using the optional parameters to the algorithm. If no - solution is found after exhausting the limits, a ``KeyListGenError`` is - raised. - - The optional parameters are: - - * ``lug_selection`` - a list of 6 integers used to drive the lug settings - portion of the algorithm. If not supplied, a list of 6 integers is chosen - from data tables that appear in the 1944 manual. For more information on - the requirements for these integers, see the manual. - - * ``max_lug_attempts`` - the maximum number of times to attempt to create - lug settings before giving up - - * ``max_pin_attempts`` - the maximum number of times to attempt to generate - key wheel pin settings before giving up - + keylist