wc32 1.0.0

wc32 custom encoding library

wc32

A custom Python encoding library with optional salt support for non-deterministic output.

Installation

pip install wc32

Usage

Basic Encoding/Decoding

from wc32 import encode, decode

# Encode with a key (deterministic - same input always produces same output)
encoded = encode("Hello, World!", "my_secret_key")
print(encoded)  # e.g., "kR.TV.rx.r-.yU.mD.Hj"

# Decode with the same key
decoded = decode(encoded, "my_secret_key")
print(decoded)  # "Hello, World!"

Non-Deterministic Encoding (Recommended)

By default, encoding is deterministic (same text + key = same output). For security, you can enable random salt:

# With random salt (recommended for sensitive data)
encoded = encode("Hello", "key", salt=True)
# Each call produces different output:
#   "a1b2c3d4.e5f6.g7h8.i9j0.k1l2"  (first call)
#   "f5e6d7c8.9a0b.1c2d.3e4f.5g6h"  (second call)

# Decode works automatically (salt is embedded in encoded string)
decoded = decode(encoded, "key")  # "Hello"

Custom Salt

You can provide your own salt for reproducible non-deterministic output:

# Custom salt (must be 8-32 hex characters)
encoded = encode("Hello", "key", salt="deadbeef12345678")
decoded = decode(encoded, "key")  # "Hello"

API Reference

encode(text: str, key: str, salt: Union[bool, str] = False) -> str

Encodes text using a custom base encoding with optional salt.

• text: The string to encode
• key: Secret key for encoding
• salt:
  • False (default): Deterministic encoding
  • True: Generate random salt
  • str: Use custom hex salt (8-32 characters)

decode(encoded_text: str, key: str) -> str

Decodes previously encoded text.

• encoded_text: The encoded string
• key: Must match the key used for encoding

Error Handling

The library raises descriptive errors for invalid inputs:

from wc32 import encode, decode

# Empty key
encode("text", "")  # ValueError: Key must not be empty

# Wrong key (produces garbage, not an error)
decode(encoded, "wrong_key")  # Returns garbled text

# Invalid characters
decode("invalid!!!", "key")  # ValueError: Invalid character

Security Notes

• This is not encryption. It provides obfuscation only.
• Without salt, output is deterministic - don't use for sensitive data without salt.
• With salt=True, same text produces different outputs (semantically secure).
• For proper security, use established encryption libraries like cryptography.