ubase-core 0.2.0

Universal base conversion with significant leading zero support

ubase-core

ubase-core encode 1111111110 10 1

ubase-core is a universal base conversion library for encoding integers into arbitrary alphabets and decoding them back into integers.

Unlike traditional converters that are limited to fixed alphabets such as base2, base16, or base64, ubase-core lets you control how the alphabet is built. You can use curated Unicode sets, full Unicode order, emoji ranges, exclusions, and custom seeded alphabets. Base 2-62 are inherently supported.

The package provides both:

• a Python API
• a command-line interface (CLI)

---

Install

pip install ubase-core

---

Import

Top-level import:

from ubase import uBase

Extras:

from ubase import uBase, abc, effBase

Direct module import:

from ubase.core import uBase, abc, effBase

---

Quick Start

from ubase import uBase

x = 1111111110

enc = uBase(x, 16, 1)
dec = uBase(enc, 16, 1)

print(enc)
print(dec)

---

Core API

uBase(n, b, s, m=0, x=None, u=0, safe=1)

Parameters

parameter	meaning
n	integer to encode, or encoded value to decode
b	requested base, or selector 0 / 1
s	significance mode: 1 on, 0 off
m	mode: 0 symbols, 1 codepoint hex, 2 raw digit indices
x	exclusions and/or custom seeded alphabet specification
u	Unicode mode: 0 curated, 1 full Unicode order
safe	safe filter: 1 on, 0 off

---

Features

Standard base conversion

• Encodes integers into positional base systems.
• Decodes encoded values back into integers.
• Works with any base >= 2.
• Supports very large integers.

Example:

1111110 -> base16 -> 10f446
10f446 -> base16 -> 1111110

Configurable alphabets

The digit alphabet used for encoding can be customized.

Supported sources include:

• the default curated alphabet
• full Unicode order
• emoji reservoirs
• custom seed strings
• filtered alphabets with excluded characters or range ids

This allows you to build alphabets such as:

• base16 using 0123456789abcdef
• base64-style alphabets
• emoji-heavy encodings
• Unicode-heavy encodings
• fully custom symbol systems

Custom alphabet seeds

To seed the alphabet with your own ordered symbols, start x with -1.

x = [-1, "0123456789abcdef"]

Behavior:

• those characters are placed at the beginning of the alphabet
• duplicates are removed by first appearance
• remaining symbols are filled from the normal generator only if more are needed

Combined example:

x = [-1, "0123456789abcdef", ("x", "0OIl"), 21]

This means:

• seed with 0123456789abcdef
• exclude the characters 0OIl
• exclude Unicode range id 21
• fill the remainder normally

Character exclusions

You can remove characters from the alphabet.

Exclude visually confusing characters:

x = "0OIl"

Exclude Unicode ranges:

x = [21, 24]

Exclude both:

x = [21, "0OIl"]

Unicode alphabet support

Two modes exist:

Curated mode (u=0)

• Uses a curated set of Unicode blocks.
• Avoids many problematic characters.
• Best for most use cases.

Full Unicode mode (u=1)

• Iterates through the entire Unicode codepoint range.
• Allows extremely large bases.
• May include characters that render differently depending on terminal or font support.

Unicode safety filter

Optional filtering removes problematic Unicode categories.

safe = 1

Filters include:

• control characters
• surrogate ranges
• variation selectors
• private-use ranges
• non-characters
• whitespace-like characters covered by the configured filter rules

Multiple output formats

The encoder can return results in three formats.

Symbol mode (m=0)

Normal encoded output.

uBase(1111110, 16, 1)

Codepoint hex mode (m=1)

Outputs the encoded string as space-separated Unicode codepoint hex values.

uBase(1111110, 16, 1, 1)

Useful for:

• stable transport through shells or text systems
• debugging character output
• inspecting Unicode-heavy alphabets

Digit index mode (m=2)

Returns the raw alphabet index sequence.

uBase(1111110, 16, 1, 2)

Useful for:

• debugging
• testing
• analysis
• building a separate render layer

Significance-preserving width mode

s = 0

Standard positional encoding. No width offset. No preserved leading digit positions.

s = 1

Significance-preserving width mode.

This mode offsets shorter-length buckets so the encoded length remains meaningful and can round-trip without losing leading alphabet-zero positions.

Use the same s value for encode and decode.

Automatic base clamping

If the requested base is larger than the usable alphabet size after filtering, exclusions, and seed rules, the converter does not fail. It clamps to the largest usable base under the current settings.

You can inspect the actual base used with:

from ubase import effBase

print(effBase(758327457298))

Escape parsing inside seed and exclude strings

Seed and exclude strings support escaped Unicode values.

Supported prefixes:

• \u
• \U
• \x

The parser reads hex digits until the next whitespace or the end of the string.

Examples:

r"\u263A"
r"\U1F600"
r"abc\U1F600 def"
r"\x41 \x42 \x43"

Outputs:

• ☺
• 😀
• abc😀def
• ABC

Important rule

Whitespace ends the escape value.

Without a delimiter, letters such as a-f are valid hex digits, so a parser cannot reliably tell where the codepoint stops and where normal text begins. That is why whitespace is not a valid symbol for any base alphabet.

Blocked characters

These never enter the final alphabet, even if you include them in a custom seed:

• backslash \
• forward slash /
• single quote '
• double quote "
• backtick `

Whitespace is also removed from the alphabet.

---

Base Behavior

Standard bases

For b >= 2, the converter resolves an alphabet of up to that many symbols.

Special selectors

value	meaning
b >= 2	normal requested base
b = 0	base62 reservoir plus emoji reservoir
b = 1	emoji reservoir

---

Helper Functions

abc(b, x=None, u=0, safe=1)

Returns the resolved alphabet string.

from ubase import abc

print(abc(64))

effBase(b, x=None, u=0, safe=1)

Returns the effective base after all filtering and clamping.

from ubase import effBase

print(effBase(4096, [-1, "0123456789abcdef"], 1, 1))

---

Example Usage

from ubase import uBase

# basic encode / decode
print(uBase(n=1111110, b=10, s=1))
print(uBase(n=uBase(1111110, 10, 1), b=10, s=1))

# hexadecimal-style base
print(uBase(n=1111110, b=16, s=1))
print(uBase(n=uBase(1111110, 16, 1), b=16, s=1))

# base64-style alphabet
print(uBase(n=1111110, b=64, s=1))

# emoji alphabet
print(uBase(n=1111110, b=1, s=1))

# base62 + emoji reservoir
print(uBase(n=1111110, b=0, s=1))

# return codepoint hex view
print(uBase(n=1111110, b=16, s=1, m=1))

# return raw digit indices
print(uBase(n=1111110, b=16, s=1, m=2))

# decode from digit indices
digits = uBase(n=1111110, b=16, s=1, m=2)
print(uBase(n=digits, b=16, s=1, m=2))

# custom seeded alphabet
print(uBase(
    n=1111110,
    b=16,
    s=1,
    x=[-1, "0123456789abcdef"]
))

# seeded alphabet with exclusions
print(uBase(
    n=1111110,
    b=128,
    s=1,
    x=[-1, "0123456789abcdef", ("x", "0OIl"), 21]
))

# full Unicode ordering
print(uBase(
    n=1111110,
    b=128,
    s=1,
    u=1
))

# disable Unicode safety filter
print(uBase(
    n=1111110,
    b=128,
    s=1,
    u=1,
    safe=0
))

# exclusion of characters
print(uBase(
    n=1111110,
    b=64,
    s=1,
    x="0OIl"
))

# exclusion of Unicode ranges
print(uBase(
    n=1111110,
    b=128,
    s=1,
    x=[21, 24]
))

# escaped Unicode inside seed
print(uBase(
    n=1111110,
    b=64,
    s=1,
    x=[-1, r"abc\U1F600 def"]
))

# very large base request (will clamp automatically)
print(uBase(
    n=1111110,
    b=1000000,
    s=1
))

# round-trip demonstration
x = 1111110
encoded = uBase(x, 64, 1)
decoded = uBase(encoded, 64, 1)

print("encoded:", encoded)
print("decoded:", decoded)

---

CLI

The CLI uses subcommands.

ubase-core --version

Command summary

command	purpose
encode	encode an integer
decode	decode symbols, hex view, or digit indices
alphabet	show the resolved alphabet or a preview
effbase	show the effective base
info	show resolved configuration and alphabet preview
roundtrip	encode in all modes and verify round-trip correctness

CLI basics

Encode

ubase-core encode 1111111110 16 1

Decode

ubase-core decode 4247d0a76 16 1

Hex output mode

ubase-core encode 1111111110 16 1 -m 1

Digit-index mode

ubase-core encode 1111111110 16 1 -m 2

Decode digit indices back:

ubase-core decode "4 2 4 7 13 0 10 7 6" 16 1 -m 2

Comma-separated input also works:

ubase-core decode "4,2,4,7,13,0,10,7,6" 16 1 -m 2

CLI options

option	meaning
-m, --mode	0 symbols, 1 codepoint hex, 2 digit indices
-u, --unicode	0 curated, 1 full Unicode
--safe	safe filter value
--unsafe	shortcut for --safe 0
--seed	custom seed segment, repeatable
--exclude	exclude characters, repeatable
--range	exclude Unicode range id, repeatable
-x, --spec	legacy mixed exclusions: ints exclude ranges, strings exclude chars

Invalid values

The core normalizes invalid values for s, m, x, u, and safe to:

• s = 1
• m = 0
• x = None
• u = 0
• safe = 1

The CLI passes values through to that behavior.

CLI custom seed examples

Hex-style alphabet seed

ubase-core encode 1111111110 16 1 --seed 0123456789abcdef

Base64-style seed

ubase-core encode 1111111110 64 1 --seed 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_

Seed plus exclusions

ubase-core encode 1111111110 128 1 --seed 0123456789abcdef --exclude 0OIl --range 21 -u 1

Multiple seed segments

Order is preserved across repeated --seed flags.

ubase-core encode 1111111110 128 1 --seed abc --seed 123 --seed XYZ

CLI escape examples

Use shell quoting when the seed contains backslashes or spaces.

Unicode smiley

ubase-core alphabet 64 --seed 'abc\u263A def'

Unicode emoji

ubase-core alphabet 64 --seed 'abc\U1F600 def'

Repeated seeds instead of internal spaces

ubase-core alphabet 64 --seed abc --seed '\U1F600' --seed def

CLI alphabet inspection

Preview alphabet

ubase-core alphabet 128

Preview in hex

ubase-core alphabet 128 --hex-view

Full alphabet

ubase-core alphabet 128 --full

Show effective base only

ubase-core effbase 758327457298

Show full config and preview

ubase-core info 128 --seed 0123456789abcdef --exclude 0OIl --range 21 -u 1

CLI round-trip verification

This command encodes the input in all three modes and decodes them back.

ubase-core roundtrip 1111111110 128 1 --seed 0123456789abcdef --exclude 0OIl --range 21 -u 1

It prints:

• requested base
• effective base
• glyph encoding
• hex-view encoding
• digit-index encoding
• all three decoded integers
• pass/fail status

A failing round trip exits with a non-zero exit code.

---

Notes

Use the same configuration for decode

To reverse a value correctly, decode with the same:

• b
• s
• m
• x
• u
• safe

m = 2 returns alphabet indices

Digit-index mode returns indices in the resolved alphabet, not human decimal glyphs.

Terminal rendering varies

Some Unicode glyphs may render differently or not at all depending on terminal, font, and platform.

Use m = 1 or m = 2 when you need a stable textual transport form.

Shell quoting matters

When a CLI argument contains spaces, backslashes, or escape sequences, quote it.

Examples:

--seed 'abc\U1F600 def'
--exclude '0OIl'

---

License

MIT License