Skip to content

Commit c00d3aa

Browse files
dhondtadhondta
committed
Improved the documentation
1 parent 4ff58be commit c00d3aa

9 files changed

Lines changed: 528 additions & 431 deletions

File tree

‎docs/base.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,29 @@ Note that for `base64`, it overwrites the native `base64_codec` to also support
105105

106106
-----
107107

108+
### Ascii85
109+
110+
This encoding relies on the `base64` library and is only supported in Python 3.
111+
112+
**Codec** | **Conversions** | **Aliases** | **Comment**
113+
:---: | :---: | --- | ---
114+
`ascii85` | text <-> ascii85 | none | Python 3 only
115+
116+
```python
117+
>>> codext.encode("this is a test", "ascii85")
118+
"FD,B0+DGm>@3BZ'F*%"
119+
>>> codext.decode("FD,B0+DGm>@3BZ'F*%", "ascii85")
120+
'this is a test'
121+
>>> with open("ascii85.txt", 'w', encoding="ascii85") as f:
122+
f.write("this is a test")
123+
14
124+
>>> with open("ascii85.txt", encoding="ascii85") as f:
125+
f.read()
126+
'this is a test'
127+
```
128+
129+
-----
130+
108131
### Other base encodings
109132

110133
**Codec** | **Conversions** | **Aliases** | **Comment**

‎docs/binary.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
With `codext`, the `codecs` library has multiple new encodings in addition to [the native ones](https://docs.python.org/3.8/library/codecs.html#standard-encodings), like presented hereafter.
2+
3+
Unless explicitely specified, each codec supports writing to and reading from a file.
4+
5+
!!! warning "Lossy conversion"
6+
7+
Some encodings are lossy, meaning that it is not always possible to decode back to the exact start string. This should be considered especially when chaining codecs.
8+
9+
-----
10+
11+
### Baudot
12+
13+
It supports various formats such as CCITT-1 and CCITT-2, ITA1 and ITA2, and some others.
14+
15+
**Codec** | **Conversions** | **Aliases** | **Comment**
16+
:---: | :---: | --- | ---
17+
`baudot` | text <-> text | Baudot code bits | `baudot-ccitt1`, `baudot_ccitt2_lsb`, ... | supports CCITT-1, CCITT-2, EU/FR, ITA1, ITA2, MTK-2 (Python3 only), UK, ...
18+
`baudot-spaced` | text <-> Baudot code groups of bits | `baudot-spaced-ita1_lsb`, `baudot_spaced_ita2_msb`, ... | groups of 5 bits are whitespace-separated
19+
`baudot-tape` | text <-> Baudot code tape | `baudot-tape-mtk2`, `baudot_tape_murray`, ... | outputs a string that looks like a perforated tape
20+
21+
!!! note "LSB / MSB"
22+
23+
"`_lsb`" or "`_msb`" can be specified in the codec name to set the bits order. If not specified, it defaults to MSB.
24+
25+
26+
```python
27+
>>> codext.encode("12345", "baudot-fr")
28+
'010000000100010001000010100111'
29+
>>> codext.decode("010000000100010001000010100111", "baudot-fr")
30+
'12345'
31+
```
32+
33+
```python
34+
>>> codext.encode("TEST", "baudot-spaced_uk")
35+
'10101 00010 10100 10101'
36+
>>> codext.decode("10101 00010 10100 10101", "baudot-spaced_uk")
37+
'TEST'
38+
```
39+
40+
```python
41+
>>> s = codext.encode("HELLO WORLD!", "baudot-tape_ita2")
42+
>>> print(s)
43+
***.**
44+
* *.
45+
. *
46+
* .*
47+
* .*
48+
** .
49+
*.
50+
* .**
51+
** .
52+
* .*
53+
* .*
54+
* . *
55+
** .**
56+
**. *
57+
>>> codext.decode(s, "baudot-tape_ita2")
58+
'HELLO WORLD!'
59+
```
60+
61+
-----
62+
63+
### Excess-3 Code
64+
65+
Also called *Stibitz code*, it converts letters to ordinals, left-pads with zeros and then applies Excess-3 (Stibitz) code to get groups of 4 bits that are finally reassembled into bytes.
66+
67+
**Codec** | **Conversions** | **Aliases** | **Comment**
68+
:---: | :---: | --- | ---
69+
`excess3` | text <-> XS3 encoded text | `excess-3`, `xs3`, `stibitz` |
70+
71+
```python
72+
>>> codext.encode("This is a test!", "excess-3")
73+
';t7C\x84H6T8D\x83e<£eD\x944D\x84I6`'
74+
>>> codext.decode(";t7C\x84H6T8D\x83e<£eD\x944D\x84I6`", "stibitz")
75+
'This is a test!'
76+
```
77+
78+
-----
79+
80+
### Gray Code
81+
82+
Also called *reflected binary code*, it implements the Gray code applied to characters while converted to bytes.
83+
84+
**Codec** | **Conversions** | **Aliases** | **Comment**
85+
:---: | :---: | --- | ---
86+
`gray` | text <-> gray encoded text | `reflected-bin`, `reflected_binary` |
87+
88+
```python
89+
>>> codext.encode("this is a test", "gray")
90+
'N\\]J0]J0Q0NWJN'
91+
>>> codext.decode("N\\]J0]J0Q0NWJN", "gray")
92+
'this is a test'
93+
>>> codext.encode("THIS IS A TEST", "gray")
94+
'~lmz0mz0a0~gz~'
95+
>>> codext.decode("~lmz0mz0a0~gz~", "gray")
96+
'THIS IS A TEST'
97+
```
98+

‎docs/common.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
With `codext`, the `codecs` library has multiple new encodings in addition to [the native ones](https://docs.python.org/3.8/library/codecs.html#standard-encodings), like presented hereafter.
2+
3+
Unless explicitely specified, each codec supports writing to and reading from a file.
4+
5+
!!! warning "Lossy conversion"
6+
7+
Some encodings are lossy, meaning that it is not always possible to decode back to the exact start string. This should be considered especially when chaining codecs.
8+
9+
-----
10+
11+
### Octal
12+
13+
This simple codec converts characters into their octal values.
14+
15+
**Codec** | **Conversions** | **Aliases** | **Comment**
16+
:---: | :---: | --- | ---
17+
`octal` | text <-> octal digits | `octals` | groups of 3-chars octal values when encoded
18+
`octal-spaced` | text <-> spaced octal digits | `octals-spaced` | whitespace-separated suite of variable-length groups of octal digits when encoded
19+
20+
```python
21+
>>> codext.encode("this is a test", "octal")
22+
'164150151163040151163040141040164145163164'
23+
>>> codext.decode("164150151163040151163040141040164145163164", "octals")
24+
'this is a test'
25+
```
26+
27+
```python
28+
>>> codext.encode("this is a test", "octal-spaced")
29+
'164 150 151 163 40 151 163 40 141 40 164 145 163 164'
30+
>>> codext.decode("164 150 151 163 40 151 163 40 141 40 164 145 163 164", "octals-spaced")
31+
'this is a test'
32+
```
33+
34+
-----
35+
36+
### Ordinal
37+
38+
This simple codec converts characters into their ordinals.
39+
40+
**Codec** | **Conversions** | **Aliases** | **Comment**
41+
:---: | :---: | --- | ---
42+
`ordinal` | text <-> ordinal digits | `ordinals` | groups of 3-chars ordinal values when encoded
43+
`ordinal-spaced` | text <-> spaced ordinal digits | `ordinals-spaced` | whitespace-separated suite of variable-length groups of ordinal digits when encoded
44+
45+
```python
46+
>>> codext.encode("this is a test", "ordinal")
47+
'116104105115032105115032097032116101115116'
48+
>>> codext.decode("116104105115032105115032097032116101115116", "ordinals")
49+
'this is a test'
50+
```
51+
52+
```python
53+
>>> codext.encode("this is a test", "ordinal-spaced")
54+
'116 104 105 115 32 105 115 32 97 32 116 101 115 116'
55+
>>> codext.decode("116 104 105 115 32 105 115 32 97 32 116 101 115 116", "ordinals-spaced")
56+
'this is a test'
57+
```
58+

0 commit comments

Comments
 (0)