vc2_conformance.string_formatters: Value-to-string formatting utilities

The vc2_conformance.string_formatters module contains facilities for formatting (or pretty printing) Python values as strings.

When we say ‘string formatter’ we mean a function/callable which takes a value and returns a string representation of that value. Instances of the classes in this module act as formatters. For example, the Hex class may be used as a formatter for n-digit hexadecimal integers:

>>> from vc2_conformance.string_formatters import Hex

>>> # Create a formatter for producing 8-digit hex numbers
>>> hex32_formatter = Hex(8)

>>> # Format some values
>>> hex32_formatter(0)
'0x00000000'
>>> hex32_formatter(0x1234)
'0x00001234'

class Number(format_code, num_digits=0, pad_digit='0', prefix='')

A formatter which uses Python’s built-in str.format() method to apply formatting.

This formatter is quite low level, see Hex, Dec, Oct and Bin for ready to use derivatives.

Parameters

format_codestr

A python str.format() code, e.g. “b” for binary.

prefixstr

A prefix to add before the formatted number

num_digitsint

The length to pad the number to.

pad_digitstr

The value to use to pad absent digits

class Hex(num_digits=0, pad_digit='0', prefix='0x')

Prints numbers in hexadecimal.

Parameters

num_digitsint

Minimum number of digits to show.

pad_digitstr

The value to use to pad absent digits

prefixstr

Defaults to “0x”

class Dec(num_digits=0, pad_digit='0', prefix='')

Prints numbers in decimal.

Parameters

num_digitsint

Minimum number of digits to show.

pad_digitstr

The value to use to pad absent digits

prefixstr

Defaults to “”

class Oct(num_digits=0, pad_digit='0', prefix='0o')

Prints numbers in octal.

Parameters

num_digitsint

Minimum number of digits to show.

pad_digitstr

The value to use to pad absent digits

prefixstr

Defaults to “0o”

class Bin(num_digits=0, pad_digit='0', prefix='0b')

Prints numbers in binary.

Parameters

num_digitsint

Minimum number of digits to show.

pad_digitstr

The value to use to pad absent digits

prefixstr

Defaults to “0b”

class Bool

A formatter for bool (or bool-castable) objects. For the values 0, 1, False and True, just shows ‘True’ or ‘False’. For all other values, shows also the true value in brackets.

For example:

>>> bool_formatter = Bool()
>>> bool_formatter(False)
"False"
>>> bool_formatter(True)
"True"
>>> bool_formatter(0)
"False"
>>> bool_formatter(1)
"True"
>>> bool_formatter(123)
"True (123)"
>>> bool_formatter(None)
"True (None)"

class Bits(prefix='0b', context=4, min_length=8, show_length=16)

A formatter for bitarray.bitarray objects. Shows the value as a string of the form ‘0b0101’, using ellipsise() to shorten very long, values.

Parameters

prefixstr

A prefix to add to the string

contextint

min_lengthint

See ellipsise().

show_lengthint or bool

If an integer, show the length of the bitarray in brackets if above the specified length (in bits). If a bool, force display (or hiding) of the length information.

class Bytes(prefix='0x', separator='_', context=2, min_length=4, show_length=8)

A formatter for bytes strings. Shows the value as a string of the form ‘0xAB_CD_EF’, using ellipsise() to shorten very long, values.

Parameters

prefixstr

A prefix to add to the string

separatorstr

A string to place between each pair of hex digits.

contextint

min_lengthint

See ellipsise().

show_lengthint or bool

If an integer, show the length of the bitarray in brackets if above the specified length (in bytes). If a bool, force display (or hiding) of the length information.

class Object(prefix='<', suffix='>')

A formatter for opaque python Objects. Shows only the object type name.

class List(min_run_length=3, formatter=<class 'str'>)

A formatter for lists which collapses repeated entries.

Examples:

>>> # Use Python-style notation for repeated entries
>>> List()([1, 1, 1, 1])
[1]*4

>>> # Also displays lists with some non-repeated values
>>> List()([1, 2, 3, 0, 0, 0, 0, 0, 4, 5])
[1, 2, 3] + [0]*5 + [4, 5]

>>> # A custom formatter may be supplied for formatting the list
>>> # entries
>>> List(formatter=Hex())([1, 2, 3, 0, 0, 0])
[0x1, 0x2, 0x3] + [0x0]*3

>>> # Equality is based on the string formatted value, not the raw
>>> # value
>>> List(formatter=Object())([1, 2, 3, 0, 0, 0])
[<int>]*6

>>> # The minimum run-length before truncation may be overridden
>>> List(min_run_length=3)([1, 2, 2, 3, 3, 3])
[1, 2, 2] + [3]*3

class MultilineList(heading=None, formatter=<class 'str'>)

A formatter for lists which displays each value on its own line.

Examples:

>>> MultilineList()(["one", "two", "three"])
0: one
1: two
2: three

>>> # A custom formatter may be supplied for formatting the list
>>> # entries
>>> MultilineList(formatter=Hex())([1, 2, 3])
0: 0x1
1: 0x2
2: 0x3

>>> # A heading may be added
>>> MultilineList(heading="MyList")(["one", "two", "three"])
MyList
  0: one
  1: two
  2: three