User Guide

Library walk-through

This module holds the stateful encoding/decoding logic. Its functions are directly available in baudot for convenience.
This package hosts the lookup tables, used for encoding/decoding single characters. Standard ITA1 and ITA2 tables are built-in, and the tools for making custom codes are also provided.
This package provides writer and reader classes for a variety of input and output formats.
As its name suggests, this module defines the library’s exceptions. All are subclasses of BaudotException.

Basic usage

The core functions for any operation in this library are baudot.encode() and baudot.decode().

To work, both require three elements:

  1. a text input (for encoding) or output (for decoding) stream
  2. a codec object
  3. a reader (for decoding) or writer (for encoding) object

This is because overall, baudot accomplishes two tasks (and their inverse):

  1. reading 5-bit codes from custom input formats,
  2. converting 5-bit codes to unicode characters.

Codec objects are instances of baudot.codecs.BaudotCodec (or its sub-classes, to be more specific). A codec is a static object capable of converting characters to codes and back. This library includes a few default codecs but others may be user-defined.

Readers and writers are instances of baudot.handlers.BaudotReader and baudot.handlers.BaudotWriter respectively. Currently, all the handlers in this library require a stream to be passed at instantiation, that they will read from or write to. This mimics the way it’s done in the standard library module csv.

The reason I/O in this library depends on streams is so that many types of inputs and outputs are natively supported, such as files or stdin and stdout. Or maybe odd devices that natively support Baudot code! This however can be inconvenient for small tests, so two helper functions baudot.encode_str() and baudot.decode_to_str() are available for using strings as text input. Maybe the handlers could be fitted with a similar feature in the future.

Please keep in mind that this project is very young, and that its API is most likely ill-designed at this point. Suggestions are welcome!


Encoding example

from io import StringIO
from baudot import encode_str, codecs, handlers

input_str = 'HELLO WORLD!'
with StringIO() as output_buffer:
    writer = handlers.TapeWriter(output_buffer)
    encode_str(input_str, codecs.ITA2_STANDARD, writer)

This would output the following:

* *.
   . *
*  .*
*  .*
** .
*  .**
** .
 * .*
*  .*
 * . *
** .**
 **. *

Decoding example

from io import BytesIO
from baudot import decode_to_str, codecs, handlers

code = b'1f14011212180413180a12091b0d'
with BytesIO(code) as code_stream:
    reader = handlers.HexBytesReader(code_stream)
    print(decode_to_str(reader, codecs.ITA2_US))

Should print: