User Guide¶
Library walk-through¶
baudot.core
- This module holds the stateful encoding/decoding logic. Its functions are
directly available in
baudot
for convenience. baudot.codecs
- 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.
baudot.handlers
- This package provides writer and reader classes for a variety of input and output formats.
baudot.exceptions
- 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:
- a text input (for encoding) or output (for decoding) stream
- a codec object
- a reader (for decoding) or writer (for encoding) object
This is because overall, baudot
accomplishes two tasks
(and their inverse):
- reading 5-bit codes from custom input formats,
- 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!
Examples¶
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)
print(output_buffer.getvalue())
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:
HELLO WORLD!