Metadata-Version: 2.5
Name: akit
Version: 0.0.2
Summary: Crockford base32 encoding: no I, L, O or U to confuse.
Project-URL: Homepage, https://github.com/lqxnjk/akit
Author: lqxnjk
License: MIT
License-File: LICENSE
Keywords: base32,crockford,decode,encode,id
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# akit

Crockford base32: denser than hex, and the alphabet drops `I`, `L`, `O` and `U`
so nothing gets mistyped when a human reads an ID aloud.

## Install

```console
pip install akit
```

## Usage

```python
from akit import decode, encode

encode(b"\x00")              # '80'
encode(b"\xff")              # 'FZ'
decode("FZ")                 # b'\xff'
decode("fz")                 # b'\xff'   case insensitive
decode("F-Z")                # b'\xff'   separators ignored
decode("8O")                 # b'\x00'   O reads as zero
decode("8I")                 # b'\x01'   I and L read as one
```

## Leading zeros

A naive "bytes to integer to base32" conversion silently drops leading zero
bytes, so `decode(encode(b"\x00\x01"))` would come back one byte short. A
sentinel byte is prepended before conversion and stripped after, which keeps
round trips exact:

```python
decode(encode(b"\x00\x01")) == b"\x00\x01"   # True
```

## Why Crockford

| Alphabet | Dropped letters | Safe to dictate |
| --- | --- | --- |
| RFC 4648 base32 | none | no (`0`/`O`, `1`/`I`) |
| Crockford | `I L O U` | yes |

`U` is excluded so accidental obscenities cannot appear in generated IDs.

Invalid characters raise `ValueError`; there is no silent repair.

## License

MIT
