Skip to content

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
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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
18
19
20
21
22
23
24
25
26
27
28
29
30
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