convert

import convert

Data conversion between hexadecimal, arbitrary numeric bases, bytes, and decimal numbers.

The convert API

Every public name in convert, wherever it is declared. Each links to the page that documents it.

Functions

hex_to_bytes()

convert.hex_to_bytes(str) -> bytes

Converts a hexadecimal string of any (even) length to bytes.

Parameters

• str (string)

Returns bytes

Raises TypeError if str isn’t a string.

Raises ValueError if str has an odd number of characters: a hex string always encodes whole bytes, so an odd length is ambiguous rather than something this function guesses at.

bytes_to_hex()

convert.bytes_to_hex(data) -> string

Converts binary data (bytes) of any length to its hexadecimal string representation.

Parameters

• data (bytes)

Returns string

Raises TypeError if data isn’t bytes.

decimal_to_hex()

convert.decimal_to_hex(n, digits) -> string

Converts the given decimal number to a hexadecimal string. If digits is given and the result is shorter, it’s padded with leading zeros; if the result is longer, it’s truncated to the least-significant digits characters.

Parameters

• n (number)
• digits (?number)

Returns string

Raises TypeError if n isn’t a number.

Raises ValueError if digits is given but isn’t a number.

hex_to_decimal()

convert.hex_to_decimal(str) -> number

Converts a hexadecimal string to a decimal (base 10) number.

Parameters

• str (string)

Returns number

Raises TypeError if str isn’t a string.

Raises ValueError if str contains a character that isn’t a valid hex digit.

Note: str may either be a plain hex string or carry a leading 0x prefix.

unicode_to_hex()

convert.unicode_to_hex(chr) -> string

Converts a single unicode character to its hexadecimal code point.

Parameters

• char — chr

Returns string

Raises ValueError if chr isn’t exactly one character.

decimal_to_binary()

convert.decimal_to_binary(n, digits) -> string

Converts a decimal number to a binary (base 2) string.

Parameters

• n (number)
• digits (?number) — Zero-pads (or truncates) to this many characters, same as decimal_to_hex()’s digits parameter.

Returns string

binary_to_decimal()

convert.binary_to_decimal(str) -> number

Converts a binary (base 2) string to a decimal number.

Parameters

• str (string)

Returns number

Raises ValueError if str contains a character other than 0 or 1.

decimal_to_octal()

convert.decimal_to_octal(n, digits) -> string

Converts a decimal number to an octal (base 8) string.

Parameters

• n (number)
• digits (?number) — Same as decimal_to_hex()’s digits parameter.

Returns string

octal_to_decimal()

convert.octal_to_decimal(str) -> number

Converts an octal (base 8) string to a decimal number.

Parameters

• str (string)

Returns number

Raises ValueError if str contains a character outside 0-7.

to_base()

convert.to_base(n, base, digits) -> string

Converts a decimal number to a string in the given base, using 0-9 then a-z for digits beyond 9 (so base 16 produces lowercase hex, matching decimal_to_hex()). If digits is given and the result is shorter, it’s padded with leading zeros; if longer, it’s truncated to the least-significant digits characters.

Parameters

• n (number)
• base (number) — Between 2 and 36.
• digits (?number)

Returns string

Raises TypeError if n isn’t a number.

Raises ValueError if base is outside 2-36, or if digits is given but isn’t a number.

from_base()

convert.from_base(str, base) -> number

Converts a string in the given base back to a decimal number. Accepts an optional leading - for a negative value, and digit letters in either case.

Parameters

• str (string)
• base (number) — Between 2 and 36.

Returns number

Raises TypeError if str isn’t a string.

Raises ValueError if base is outside 2-36, or if str contains a character that isn’t a valid digit in that base.

bytes_to_decimal()

convert.bytes_to_decimal(data, little_endian) -> number

Converts bytes (binary data) to a decimal number, treating the bytes as an unsigned integer.

Parameters

• data (bytes)
• little_endian (?bool) — Default false: the most significant byte comes first. Set true to instead treat the least significant byte as first, as many binary file formats and network protocols do.

Returns number

Raises TypeError if data isn’t bytes.

decimal_to_bytes()

convert.decimal_to_bytes(n, length, little_endian) -> bytes

Converts a decimal number to bytes, the reverse of bytes_to_decimal().

Parameters

• n (number) — Must be non-negative: there’s no signedness convention (two’s complement vs. sign-magnitude) implied here, so a negative value is rejected rather than guessed at.
• length (number) — The exact number of bytes to produce. If n doesn’t fit in length bytes, the most significant (excess) bits are silently dropped, the same as fitting a number into a fixed-width integer type would.
• little_endian (?bool) — Default false: the most significant byte is written first. Set true for the least significant byte first.

Returns bytes

Raises TypeError if n isn’t a number.

Raises ValueError if n is negative, or length isn’t a non-negative number.

2021, Richard Ore and Zuri contributors