Reference

Note

xor_cipher.python contains pure-python implementations, while xor_cipher.core uses extensions. Usually imports should happen from xor_cipher, which will use the fastest available functionality.

xor(data: bytes, key: int) -> bytes

Applies XOR operation (byte ^ key) for each byte in data.

This function is its own inverse, meaning

xor(xor(data, key), key) == data

for any data and key.

Parameters:

Name	Type	Description	Default
data	bytes	The data to encode.	required
key	int	The key to use for encoding. Must be in range [0, 255].	required

Raises:

Type	Description
ValueError	If the key is not in [0, 255] range.

Returns:

Type	Description
bytes	The encoded data.

Source code in src/xor_cipher/python.py

def xor(data: bytes, key: int) -> bytes:
    """Applies XOR operation (`byte ^ key`) for each `byte` in `data`.

    This function is its own inverse, meaning

    ```python
    xor(xor(data, key), key) == data
    ```

    for any `data` and `key`.

    Arguments:
        data: The data to encode.
        key: The key to use for encoding. Must be in range `[0, 255]`.

    Raises:
        ValueError: If the `key` is not in `[0, 255]` range.

    Returns:
        The encoded data.
    """
    key = expect_byte(key)

    if not key:
        return data

    return bytes(byte ^ key for byte in data)

cyclic_xor(data: bytes, key: bytes) -> bytes

Applies XOR operation (byte ^ key_byte) for each byte in data and key_byte in key, which is cycled to fit the length of the data.

This function is its own inverse, meaning

cyclic_xor(cyclic_xor(data, key), key) == data

for any data and key.

Parameters:

Name	Type	Description	Default
data	bytes	The data to encode.	required
key	bytes	The key to use for encoding.	required

Returns:

Type	Description
bytes	The encoded data.

Source code in src/xor_cipher/python.py

def cyclic_xor(data: bytes, key: bytes) -> bytes:
    """Applies XOR operation (`byte ^ key_byte`) for each `byte` in `data`
    and `key_byte` in `key`, which is cycled to fit the length of the `data`.

    This function is its own inverse, meaning

    ```python
    cyclic_xor(cyclic_xor(data, key), key) == data
    ```

    for any `data` and `key`.

    Arguments:
        data: The data to encode.
        key: The key to use for encoding.

    Returns:
        The encoded data.
    """
    if not key:
        return data

    return bytes(byte ^ key_byte for byte, key_byte in zip(data, cycle(key)))

xor_in_place(data: bytearray, key: int) -> None

Similar to xor, except it operates in-place.

Parameters:

Name	Type	Description	Default
data	bytearray	The data to encode.	required
key	int	The key to use for encoding. Must be in range [0, 255].	required

Raises:

Type	Description
ValueError	If the key is not in [0, 255] range.

Source code in src/xor_cipher/python.py

def xor_in_place(data: bytearray, key: int) -> None:
    """Similar to [`xor`][xor_cipher.python.xor], except it operates *in-place*.

    Arguments:
        data: The data to encode.
        key: The key to use for encoding. Must be in range `[0, 255]`.

    Raises:
        ValueError: If the `key` is not in `[0, 255]` range.
    """
    key = expect_byte(key)

    if not key:
        return

    length = len(data)

    for index in range(length):
        data[index] ^= key

cyclic_xor_in_place(data: bytearray, key: bytes) -> None

Similar to cyclic_xor, except it operates in-place.

Parameters:

Name	Type	Description	Default
data	bytearray	The data to encode.	required
key	bytes	The key to use for encoding.	required

Source code in src/xor_cipher/python.py

def cyclic_xor_in_place(data: bytearray, key: bytes) -> None:
    """Similar to [`cyclic_xor`][xor_cipher.python.cyclic_xor], except it operates *in-place*.

    Arguments:
        data: The data to encode.
        key: The key to use for encoding.
    """
    if not key:
        return

    key_length = len(key)

    length = len(data)

    for index in range(length):
        data[index] ^= key[index % key_length]

MIN_BYTE: Literal[0] = 0 module-attribute

The minimum byte value.

MAX_BYTE: Literal[255] = 255 module-attribute

The maximum byte value.

expect_byte(value: int) -> int

Ensures the int value provided is in [0, 255] range.

Parameters:

Name	Type	Description	Default
value	int	The value to check.	required

Raises:

Type	Description
ValueError	If the given value is outside the expected range.

Source code in src/xor_cipher/bytes.py

def expect_byte(value: int) -> int:
    """Ensures the [`int`][int] value provided is in `[0, 255]` range.

    Arguments:
        value: The value to check.

    Raises:
        ValueError: If the given value is outside the expected range.
    """
    if is_not_byte(value):
        raise ValueError(EXPECTED_BYTE)

    return value