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