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 positions, i.e. 0-0.

The 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 KeyList is:

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.

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 KeyList object. Returns None if not found.

If indicator is None, a key list is chosen from the file at random.

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 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 (see References [4]).

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 KeyList object is returned.

If a 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