Skip to main content

Encode and decode binary data to English sentences

Project description


Encode and decode text as English sentences. The name is inspired by this xkcd comic.


The batteryhorse module exposes three functions:

encode_data(data: bytes) -> str

Encode the given data into one or more English phrases/sentences. Uses Wordnet from the NLTK library to create sentences in the following format: VERB NOUN ADJECTIVE CONJUNCTION ADJECTIVE. If the bytes can be encoded into fewer parts of speech then the rest will be truncated.

decode_data(data: str, length: int) -> bytes

Decode a string of sentences or phrases back into the original bytes. Also requires the size of the output bytes

create_secret(size=3: int) -> bytes

Creates a random passphrase by using random words from the Wordnet. Size specifies the number of words to use


A basic example that encodes some data

>>> import batteryhorse
>>> batteryhorse.encode_data(b'TEST')
'Unitise annum abasic'

An example showing encoding and decoding data

>>> from hashlib import sha1
>>> import batteryhorse
>>> digest = sha1('test'.encode('utf-8')).digest()
>>> batteryhorse.encode_data(digest)
'Birdnest vara lobed or orthoptic. Wow fencing orthogonal yet anthropomorphic. Scranch rifadin anosmatic'
>>> batteryhorse.decode_data('Birdnest vara lobed or orthoptic. Wow fencing orthogonal yet anthropomorphic. Scranch rifadin anosmatic', len(digest))
>>> print(digest)

Command Line

BatteryHorse is also available on the command line.

  --encode         Accept data to be encoded from STDIN
  --decode         Accept data to be decoded from STDIN
  --generate       Generate a random secret
  --length LENGTH  Specify the length of secret or data to be decoded

And as an example

$ echo "TEST" | python -m batteryhorse --encode
Bare gyrostabilizer amygdaloidal


The original intention of this library was to create a new way of sharing fingerprints of public keys.


Although Batteryhorse can encode data of arbitary lengths it does no padding of the data beforehand resulting in some sentences that may not be complete.

Additionally, since the length of the original data is not encoded the decode function must take the length as a parameter.

Project details

Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
BatteryHorse-1.0.0-py3-none-any.whl (10.8 MB) Copy SHA256 hash SHA256 Wheel py3
BatteryHorse-1.0.0.tar.gz (10.7 MB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page