philiprehberger-base-convert 0.4.0

Convert numbers between any base (2-62) with human-friendly APIs.

philiprehberger-base-convert

Convert numbers between any base (2-62) with human-friendly APIs.

Installation

pip install philiprehberger-base-convert

Usage

Basic Conversion

from philiprehberger_base_convert import to_base, from_base

# Convert to base 16 (hex)
to_base(255, 16)      # "ff"
from_base("ff", 16)   # 255

# Convert to base 62
to_base(999999, 62)   # "4c91"
from_base("4c91", 62) # 999999

Pre-built Codecs

from philiprehberger_base_convert import base16, base36, base58, base62

base62.encode(123456789)       # "8M0kX"
base62.decode("8M0kX")         # 123456789

base58.encode(123456789)       # Bitcoin-style base58
base36.encode(123456789)       # "21i3v9"
base16.encode(255)             # "ff"

Bytes Encoding

Encode arbitrary bytes (UUIDs, hashes, binary data) to compact base-N strings:

from philiprehberger_base_convert import base62

# Encode bytes to base62
data = b"\x00\x01\x02\xff"
encoded = base62.encode_bytes(data)

# Decode back to bytes
decoded = base62.decode_bytes(encoded)
assert decoded == data

# Encode a UUID to a compact string
import uuid
uid = uuid.uuid4().bytes
short_id = base62.encode_bytes(uid)

For one-off bytes conversions without instantiating a codec, use the top-level convenience wrappers:

from philiprehberger_base_convert import bytes_to_base, base_to_bytes

token = bytes_to_base(b"\x00\xff\xab", 62)
base_to_bytes(token, 62)  # b"\x00\xff\xab"

Custom Alphabet

from philiprehberger_base_convert import to_base, from_base, BaseCodec

# Use a custom alphabet for base 3
to_base(42, 3, alphabet="XYZ")   # "YXZX"
from_base("YXZX", 3, alphabet="XYZ")  # 42

# Reusable codec with custom alphabet
codec = BaseCodec(4, alphabet="ACGT")
codec.encode(42)   # "GCAC"
codec.decode("GCAC")  # 42

Fixed-width output

Pass min_length to left-pad the encoded string with the alphabet's zero character. Useful for fixed-width identifiers:

from philiprehberger_base_convert import to_base, base62

to_base(5, 16, min_length=4)        # "0005"
base62.encode(0, min_length=8)      # "00000000"
base62.encode(123, min_length=6)    # zero-padded base62

API

Function / Class	Description
to_base(number, base, *, alphabet="", min_length=0)	Convert int to string in given base (2-62); min_length left-pads with zero char
from_base(value, base, *, alphabet="")	Convert string in given base back to int
BaseCodec(base, *, alphabet="")	Reusable encoder/decoder for a fixed base
BaseCodec.encode(number, *, min_length=0)	Encode int to string with optional left-padding
BaseCodec.decode(value)	Decode string to int
BaseCodec.encode_bytes(data)	Encode bytes to a base-N string (preserves leading zero bytes)
BaseCodec.decode_bytes(value)	Decode a base-N string back to bytes
bytes_to_base(data, base, *, alphabet="")	Convenience wrapper around BaseCodec.encode_bytes
base_to_bytes(value, base, *, alphabet="")	Convenience wrapper around BaseCodec.decode_bytes
base16	Pre-built codec for base 16
base32	Pre-built codec for base 32
base36	Pre-built codec for base 36
base58	Pre-built codec for base 58 (Bitcoin alphabet)
base62	Pre-built codec for base 62

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT