Skip to content

Core API Reference

The core module provides high-level functions for encoding and decoding.

Functions

usenc.encode(text, encoder_name, **encoder_params)

Encode a single text string

Source code in src/usenc/core.py 
10
11
12
13
14
15
16
def encode(text: bytes, encoder_name: str, **encoder_params) -> bytes:
    """Encode a single text string"""
    encoder = ENCODERS.get(encoder_name)
    if not encoder:
        raise EncoderNotFoundError(f"Unknown encoder: {encoder_name}")

    return encoder.encode(text, **encoder_params)

usenc.decode(text, encoder_name, **encoder_params)

Decode a single text string

Source code in src/usenc/core.py 
19
20
21
22
23
24
25
def decode(text: bytes, encoder_name: str, **encoder_params) -> bytes:
    """Decode a single text string"""
    encoder = ENCODERS.get(encoder_name)
    if not encoder:
        raise EncoderNotFoundError(f"Unknown encoder: {encoder_name}")

    return encoder.decode(text, **encoder_params)

Python API

usenc can be used as a Python library for programmatic encoding/decoding.

Basic Usage

from usenc import encode, decode

# Simple encoding
encoded = encode(b'hello world', encoder_name='url')
print(encoded)  # b'hello%20world'

# Simple decoding
decoded = decode(b'hello%20world', encoder_name='url')
print(decoded)  # b'hello world'

Using Custom Parameters

Pass encoder-specific parameters as keyword arguments:

from usenc import encode

# Hex encoding with prefix and lowercase
encoded = encode(
    b'hello',
    encoder_name='hex',
    prefix='0x',
    suffix=',',
    lowercase=True
)
print(encoded)  # b'0x68,0x65,0x6c,0x6c,0x6f,'

# URL encoding with include parameter
encoded = encode(
    b'key=value',
    encoder_name='url',
    include='='
)
print(encoded)  # b'key%3Dvalue'

Charset Parameters

from usenc import encode, decode

# UTF-8 to URL encoding
text = 'café'.encode('utf8')
encoded = encode(
    text,
    encoder_name='url',
    input_charset='utf8',
    output_charset='utf8'
)
print(encoded)  # b'caf%C3%A9'

# Latin-1 to URL encoding
text = 'café'.encode('latin1')
encoded = encode(
    text,
    encoder_name='url',
    input_charset='latin1',
    output_charset='latin1'
)
print(encoded)  # b'caf%E9'

Direct Encoder Access

For advanced use cases, you can access encoders directly:

from usenc.encoders import ENCODERS

# Get an encoder
hex_encoder = ENCODERS['hex']

# Use it directly
encoded = hex_encoder.encode(
    b'test',
    lowercase=True,
    prefix='\\x'
)
print(encoded)  # b'\\x74\\x65\\x73\\x74'

# Check available parameters
print(hex_encoder.params)
# {'prefix': {...}, 'suffix': {...}, 'include': {...}, ...}

Error Handling

from usenc import encode, decode
from usenc.encoders.encoder import EncodeError, DecodeError

try:
    # This might fail if the charset is invalid
    encoded = encode(
        b'\xff\xfe',
        encoder_name='url',
        input_charset='ascii'  # ASCII can't handle these bytes
    )
except EncodeError as e:
    print(f"Encoding failed: {e}")

try:
    # This might fail if the input is malformed
    decoded = decode(
        b'invalid%ZZdata',
        encoder_name='url'
    )
except DecodeError as e:
    print(f"Decoding failed: {e}")

Listing Available Encoders

from usenc.encoders import ENCODERS

# List all encoders
print("Available encoders:")
for name in ENCODERS.keys():
    print(f"  - {name}")

# Get encoder info
encoder = ENCODERS['hex']
print(f"\nEncoder: {encoder.__name__}")
print(f"Docstring: {encoder.__doc__}")
print(f"Parameters: {list(encoder.params.keys())}")

See Also