picos.formatting

Console output helpers related to formatting.

Outline

Functions

arguments	A wrapper around parameterized_string for argument lists.
box	Print both a header above and a footer below the context.
detect_range	Return a Python range mirroring the given integer sequence.
doc_cat	Append to a docstring.
natsorted	Sort the given list of strings naturally with respect to numbers.
parameterized_string	Find a string template for the given (algebraic) strings.
picos_box	Print a PICOS header above and a PICOS footer below the context.
print_footer	Print a footer line.
print_header	Print a header line.
solver_box	Print a solver header above and a solver footer below the context.

Data

HEADER_WIDTH

Functions

arguments

picos.formatting.arguments(strings, sep=', ', empty='')

A wrapper around parameterized_string for argument lists.

Parameters

• strings (list(str)) – String descriptions of the arguments.

• sep (str) – Separator.

• empty (str) – Representation of an empty argument list.

box

picos.formatting.box(title, caption, subtitle=None, symbol='-', width=35, show=True)

Print both a header above and a footer below the context.

Parameters

• title (str) – The (long) main title printed at the top.

• caption (str) – The (short) caption printed at the bottom.

• subtitle (str) – The (long) subtitle printed at the top.

• symbol (str) – A single character used to draw lines.

• width (int) – The width of the box.

• show (bool) – Whether anything should be printed at all.

detect_range

picos.formatting.detect_range(sequence, asQuadruple=False, asStringTemplate=False, shortString=False)

Return a Python range mirroring the given integer sequence.

Parameters

• sequence – An integer sequence that can be mirrored by a Python range.

• asQuadruple (bool) – Whether to return a quadruple with factor, inner shift, outer shift, and length, formally (a, i, o, n) such that [a*(x+i)+o for x in range(n)] mirrors the input sequence.

• asStringTemplate (bool) – Whether to return a format string that, if instanciated with numbers from 0 to len(sequence) - 1, yields math expression strings that describe the input sequence members.

• shortString (bool) – Whether to return condensed string templates that are designed to be instanciated with an index character string. Requires asStringTemplate to be True.

Raises

• TypeError – If the input is not an integer sequence.

• ValueError – If the input cannot be mirrored by a Python range.

Returns

A range object, a quadruple of numbers, or a format string.

Example

>>> from picos.formatting import detect_range as dr
>>> R = range(7,30,5)
>>> S = list(R)
>>> S
[7, 12, 17, 22, 27]
>>> # By default, returns a matching range object:
>>> dr(S)
range(7, 28, 5)
>>> dr(S) == R
True
>>> # Sequence elements can also be decomposed w.r.t. range(len(S)):
>>> a, i, o, n = dr(S, asQuadruple=True)
>>> [a*(x+i)+o for x in range(n)] == S
True
>>> # The same decomposition can be returned in a string representation:
>>> dr(S, asStringTemplate=True)
'5·({} + 1) + 2'
>>> # Short string representations are designed to accept index names:
>>> dr(S, asStringTemplate=True, shortString=True).format("i")
'5(i+1)+2'
>>> dr(range(0,100,5), asStringTemplate=True, shortString=True).format("i")
'5i'
>>> dr(range(10,100), asStringTemplate=True, shortString=True).format("i")
'i+10'

Example

>>> # This works with decreasing ranges as well.
>>> R2 = range(10,4,-2)
>>> S2 = list(R2)
>>> S2
[10, 8, 6]
>>> dr(S2)
range(10, 5, -2)
>>> dr(S2) == R2
True
>>> a, i, o, n = dr(S2, asQuadruple=True)
>>> [a*(x+i)+o for x in range(n)] == S2
True
>>> T = dr(S2, asStringTemplate=True, shortString=True)
>>> [T.format(i) for i in range(len(S2))]
['-2(0-5)', '-2(1-5)', '-2(2-5)']

doc_cat

picos.formatting.doc_cat(docstring, append)

Append to a docstring.

natsorted

picos.formatting.natsorted(strings, key=None)

Sort the given list of strings naturally with respect to numbers.

parameterized_string

picos.formatting.parameterized_string(strings, replace='-?\\d+', context='\\W', placeholders='ijklpqr', fallback='?')

Find a string template for the given (algebraic) strings.

Given a list of strings with similar structure, finds a single string with placeholders and an expression that denotes how to instantiate the placeholders in order to obtain each string in the list.

The function is designed to take a number of symbolic string representations of math expressions that differ only with respect to indices.

Parameters

• strings (list) – The list of strings to compare.

• replace (str) – A regular expression describing the bits to replace with placeholders.

• context (str) – A regular expression describing context characters that need to be present next to the bits to be replaced with placeholders.

• placeholders – An iterable of placeholder strings. Usually a string, so that each of its characters becomes a placeholder.

• fallback (str) – A fallback placeholder string, if the given placeholders are not sufficient.

Returns

A tuple of two strings, the first being the template string and the second being a description of the placeholders used.

Example

>>> from picos.formatting import parameterized_string as ps
>>> ps(["A[{}]".format(i) for i in range(5, 31)])
('A[i+5]', 'i ∈ [0…25]')
>>> ps(["A[{}]".format(i) for i in range(5, 31, 5)])
('A[5(i+1)]', 'i ∈ [0…5]')
>>> S=["A[0]·B[2]·C[3]·D[5]·F[0]",
...    "A[1]·B[1]·C[6]·D[6]·F[0]",
...    "A[2]·B[0]·C[9]·D[9]·F[0]"]
>>> ps(S)
('A[i]·B[-(i-2)]·C[3(i+1)]·D[j]·F[0]', '(i,j) ∈ zip([0…2],[5,6,9])')

picos_box

picos.formatting.picos_box(show=True)

Print a PICOS header above and a PICOS footer below the context.

print_footer

picos.formatting.print_footer(caption, symbol='=', width=35)

Print a footer line.

print_header

picos.formatting.print_header(title, subtitle=None, symbol='-', width=35)

Print a header line.

solver_box

picos.formatting.solver_box(longName, shortName, subSolver=None, show=True)

Print a solver header above and a solver footer below the context.

Data

picos.formatting.HEADER_WIDTH

Character length of headers and footers printed by PICOS.