Skip to content

Commit 82afcf6

Browse files
dhondtadhondta
committed
Improved README.md
1 parent 20ea31a commit 82afcf6

1 file changed

Lines changed: 102 additions & 59 deletions

File tree

‎README.md‎

Lines changed: 102 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -7,59 +7,10 @@
77
[![Known Vulnerabilities](https://snyk.io/test/github/dhondta/python-codext/badge.svg?targetFile=requirements.txt)](https://snyk.io/test/github/dhondta/python-codext?targetFile=requirements.txt)
88
[![License](https://img.shields.io/pypi/l/codext.svg)](https://pypi.python.org/pypi/codext/)
99

10-
# Codecs Extension
10+
# CODecs EXTension
1111

1212
This library extends the native `codecs` library and provides some new encodings (static or parametrized, like `rot-N` or `xor-N`).
1313

14-
**Codec** | **Conversions** | **Comment**
15-
:---: | :---: | ---
16-
`affine` | text <-> affine ciphertext | aka Affine Cipher
17-
`ascii85` | text <-> ascii85 encoded text | Python 3 only
18-
`atbash` | text <-> Atbash ciphertext | aka Atbash Cipher
19-
`bacon` | text <-> Bacon ciphertext | aka Baconian Cipher
20-
`barbie-N` | text <-> barbie ciphertext | aka Barbie Typewriter (N belongs to [1, 4])
21-
`baseXX` | text <-> baseXX | see [base encodings](https://python-codext.readthedocs.io/en/latest/base.html)
22-
`baudot` | text <-> Baudot code bits | supports CCITT-1, CCITT-2, EU/FR, ITA1, ITA2, MTK-2 (Python3 only), UK, ...
23-
`bcd` | text <-> binary coded decimal text | encodes characters from their (zero-left-padded) ordinals
24-
`braille` | text <-> braille symbols | Python 3 only
25-
`dna` | text <-> DNA-N sequence | implements the 8 rules of DNA sequences (N belongs to [1,8])
26-
`excess3` | text <-> XS3 encoded text | uses Excess-3 (aka Stibitz code) binary encoding to convert characters from their ordinals
27-
`gray` | text <-> gray encoded text | aka reflected binary code
28-
`html` | text <-> HTML entities | implements entities according to [this reference](https://dev.w3.org/html5/html-author/charref)
29-
`leetspeak` | text <-> leetspeak encoded text | based on minimalistic elite speaking rules
30-
`manchester` | text <-> manchester encoded text | XORes each bit of the input with `01`
31-
`markdown` | markdown --> HTML | unidirectional
32-
`morse` | text <-> morse encoded text | uses whitespace as a separator
33-
`navajo` | text <-> Navajo | only handles letters (not full words from the Navajo dictionary)
34-
`octal` | text <-> octal digits | dummy octal conversion (converts to 3-digits groups)
35-
`ordinal` | text <-> ordinal digits | dummy character ordinals conversion (converts to 3-digits groups)
36-
`radio` | text <-> radio words | aka NATO or radio phonetic alphabet
37-
`resistor` | text <-> resistor colors | aka resistor color codes
38-
`rot` | text <-> rot(N) ciphertext | aka Caesar cipher (N belongs to [1,25])
39-
`scytale` | text <-> scytale ciphertext | encrypts with L, the number of letters on the rod (belongs to [1,[)
40-
`shift` | text <-> shift(N) ciphertext | shift ordinals with N (belongs to [1,255])
41-
`sms` | text <-> phone keystrokes | also called T9 code ; uses "`-`" as a separator for encoding, "`-`" or "`_`" or whitespace for decoding
42-
`southpark` | text <-> Kenny's language | converts letters to Kenny's language from Southpark (whitespace is also handled)
43-
`tomtom` | text <-> tom-tom encoded text | similar to `morse`, using slashes and backslashes
44-
`url` | text <-> URL encoded text | aka URL encoding
45-
`xor` | text <-> XOR(N) ciphertext | XOR with a single byte (N belongs to [1,255])
46-
`whitespace` | text <-> whitespaces and tabs | replaces bits with whitespaces and tabs
47-
48-
A few variants are also implemented.
49-
50-
**Codec** | **Conversions** | **Comment**
51-
:---: | :---: | ---
52-
`baudot-spaced` | text <-> Baudot code groups of bits | groups of 5 bits are whitespace-separated
53-
`baudot-tape` | text <-> Baudot code tape | outputs a string that looks like a perforated tape
54-
`bcd-extended0` | text <-> BCD-extended text | encodes characters from their (zero-left-padded) ordinals using prefix bits `0000`
55-
`bcd-extended1` | text <-> BCD-extended text | encodes characters from their (zero-left-padded) ordinals using prefix bits `1111`
56-
`manchester-inverted` | text <-> manchester encoded text | XORes each bit of the input with `10`
57-
`octal-spaced` | text <-> octal digits (whitespace-separated) | dummy octal conversion
58-
`ordinal-spaced` | text <-> ordinal digits (whitespace-separated) | dummy character ordinals conversion
59-
`southpark-icase` | text <-> Kenny's language | same as `southpark` but case insensitive
60-
`whitespace_after_before` | text <-> lines of whitespaces[letter]whitespaces | encodes characters as new characters with whitespaces before and after according to an equation described in the codec name (e.g. "`whitespace+2*after-3*before`")
61-
62-
6314
## Setup
6415

6516
This library is available on [PyPi](https://pypi.python.org/pypi/codext/) and can be simply installed using Pip:
@@ -94,9 +45,32 @@ $ echo -en "test" | codext base100
9445
👫👜👪👫
9546
```
9647

48+
Using codecs chaining:
49+
50+
```sh
51+
$ echo -en "Test string" | codext reverse
52+
gnirts tseT
53+
$ echo -en "Test string" | codext reverse morse
54+
--. -. .. .-. - ... / - ... . -
55+
$ echo -en "Test string" | codext reverse morse dna-2
56+
AGTCAGTCAGTGAGAAAGTCAGTGAGAAAGTGAGTGAGAAAGTGAGTCAGTGAGAAAGTCAGAAAGTGAGTGAGTGAGAAAGTTAGAAAGTCAGAAAGTGAGTGAGTGAGAAAGTGAGAAAGTC
57+
$ echo -en "Test string" | codext reverse morse dna-2 octal
58+
101107124103101107124103101107124107101107101101101107124103101107124107101107101101101107124107101107124107101107101101101107124107101107124103101107124107101107101101101107124103101107101101101107124107101107124107101107124107101107101101101107124124101107101101101107124103101107101101101107124107101107124107101107124107101107101101101107124107101107101101101107124103
59+
$ echo -en "AGTCAGTCAGTGAGAAAGTCAGTGAGAAAGTGAGTGAGAAAGTGAGTCAGTGAGAAAGTCAGAAAGTGAGTGAGTGAGAAAGTTAGAAAGTCAGAAAGTGAGTGAGTGAGAAAGTGAGAAAGTC" | codext -d dna-2 morse reverse
60+
test string
61+
```
62+
9763
## Usage (within Python)
9864

99-
Example with Base58:
65+
Getting the list of available codecs:
66+
67+
```python
68+
>>> import codext
69+
>>> codext.list()
70+
['ascii85', 'base85', 'base100', 'base122', ..., 'tomtom', 'dna', 'html', 'markdown', 'url', 'resistor', 'sms', 'whitespace', 'whitespace-after-before']
71+
```
72+
73+
Usage examples:
10074

10175
```python
10276
>>> codext.encode("this is a test", "base58-bitcoin")
@@ -107,17 +81,13 @@ Example with Base58:
10781
'JN91Wzkpa1nnDbLyjtf'
10882
```
10983

110-
Example with Base100 (emoji's):
111-
11284
```python
11385
>>> codecs.encode("this is a test", "base100")
11486
'👫👟👠👪🐗👠👪🐗👘🐗👫👜👪👫'
11587
>>> codecs.decode("👫👟👠👪🐗👠👪🐗👘🐗👫👜👪👫", "base100")
11688
'this is a test'
11789
```
11890

119-
Example with DNA sequence encoding:
120-
12191
```python
12292
>>> for i in range(8):
12393
print(codext.encode("this is a test", "dna-%d" % (i + 1)))
@@ -133,8 +103,6 @@ CACTCGGTCGGCCATATGTTCGGCCATATGTTCGTCTGTTCACTCGCCCATACACT
133103
'this is a test'
134104
```
135105

136-
Example with morse:
137-
138106
```python
139107
>>> codecs.encode("this is a test", "morse")
140108
'- .... .. ... / .. ... / .- / - . ... -'
@@ -148,8 +116,6 @@ Example with morse:
148116
'this is a test'
149117
```
150118

151-
Example with whitespaces before and after:
152-
153119
```python
154120
>>> codext.decode("""
155121
=
@@ -176,3 +142,80 @@ o
176142
'CSC{not_so_invisible}'
177143
```
178144

145+
```python
146+
>>> print(codext.encode("An example test string", "baudot-tape"))
147+
***.**
148+
. *
149+
***.*
150+
* .
151+
.*
152+
* .*
153+
. *
154+
** .*
155+
***.**
156+
** .**
157+
.*
158+
* .
159+
* *. *
160+
.*
161+
* *.
162+
* *. *
163+
* .
164+
* *.
165+
* *. *
166+
***.
167+
*.*
168+
***.*
169+
* .*
170+
```
171+
172+
## List of codecs
173+
174+
**Codec** | **Conversions** | **Comment**
175+
:---: | :---: | ---
176+
`affine` | text <-> affine ciphertext | aka Affine Cipher
177+
`ascii85` | text <-> ascii85 encoded text | Python 3 only
178+
`atbash` | text <-> Atbash ciphertext | aka Atbash Cipher
179+
`bacon` | text <-> Bacon ciphertext | aka Baconian Cipher
180+
`barbie-N` | text <-> barbie ciphertext | aka Barbie Typewriter (N belongs to [1, 4])
181+
`baseXX` | text <-> baseXX | see [base encodings](https://python-codext.readthedocs.io/en/latest/base.html)
182+
`baudot` | text <-> Baudot code bits | supports CCITT-1, CCITT-2, EU/FR, ITA1, ITA2, MTK-2 (Python3 only), UK, ...
183+
`bcd` | text <-> binary coded decimal text | encodes characters from their (zero-left-padded) ordinals
184+
`braille` | text <-> braille symbols | Python 3 only
185+
`dna` | text <-> DNA-N sequence | implements the 8 rules of DNA sequences (N belongs to [1,8])
186+
`excess3` | text <-> XS3 encoded text | uses Excess-3 (aka Stibitz code) binary encoding to convert characters from their ordinals
187+
`gray` | text <-> gray encoded text | aka reflected binary code
188+
`html` | text <-> HTML entities | implements entities according to [this reference](https://dev.w3.org/html5/html-author/charref)
189+
`leetspeak` | text <-> leetspeak encoded text | based on minimalistic elite speaking rules
190+
`manchester` | text <-> manchester encoded text | XORes each bit of the input with `01`
191+
`markdown` | markdown --> HTML | unidirectional
192+
`morse` | text <-> morse encoded text | uses whitespace as a separator
193+
`navajo` | text <-> Navajo | only handles letters (not full words from the Navajo dictionary)
194+
`octal` | text <-> octal digits | dummy octal conversion (converts to 3-digits groups)
195+
`ordinal` | text <-> ordinal digits | dummy character ordinals conversion (converts to 3-digits groups)
196+
`radio` | text <-> radio words | aka NATO or radio phonetic alphabet
197+
`resistor` | text <-> resistor colors | aka resistor color codes
198+
`rot` | text <-> rot(N) ciphertext | aka Caesar cipher (N belongs to [1,25])
199+
`scytale` | text <-> scytale ciphertext | encrypts with L, the number of letters on the rod (belongs to [1,[)
200+
`shift` | text <-> shift(N) ciphertext | shift ordinals with N (belongs to [1,255])
201+
`sms` | text <-> phone keystrokes | also called T9 code ; uses "`-`" as a separator for encoding, "`-`" or "`_`" or whitespace for decoding
202+
`southpark` | text <-> Kenny's language | converts letters to Kenny's language from Southpark (whitespace is also handled)
203+
`tomtom` | text <-> tom-tom encoded text | similar to `morse`, using slashes and backslashes
204+
`url` | text <-> URL encoded text | aka URL encoding
205+
`xor` | text <-> XOR(N) ciphertext | XOR with a single byte (N belongs to [1,255])
206+
`whitespace` | text <-> whitespaces and tabs | replaces bits with whitespaces and tabs
207+
208+
A few variants are also implemented.
209+
210+
**Codec** | **Conversions** | **Comment**
211+
:---: | :---: | ---
212+
`baudot-spaced` | text <-> Baudot code groups of bits | groups of 5 bits are whitespace-separated
213+
`baudot-tape` | text <-> Baudot code tape | outputs a string that looks like a perforated tape
214+
`bcd-extended0` | text <-> BCD-extended text | encodes characters from their (zero-left-padded) ordinals using prefix bits `0000`
215+
`bcd-extended1` | text <-> BCD-extended text | encodes characters from their (zero-left-padded) ordinals using prefix bits `1111`
216+
`manchester-inverted` | text <-> manchester encoded text | XORes each bit of the input with `10`
217+
`octal-spaced` | text <-> octal digits (whitespace-separated) | dummy octal conversion
218+
`ordinal-spaced` | text <-> ordinal digits (whitespace-separated) | dummy character ordinals conversion
219+
`southpark-icase` | text <-> Kenny's language | same as `southpark` but case insensitive
220+
`whitespace_after_before` | text <-> lines of whitespaces[letter]whitespaces | encodes characters as new characters with whitespaces before and after according to an equation described in the codec name (e.g. "`whitespace+2*after-3*before`")
221+

0 commit comments

Comments
 (0)