picos.formatting

Console output helpers related to formatting.

Functions

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

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.

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

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.

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

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)']
picos.formatting.doc_cat(docstring, append)[source]

Append to a docstring.

picos.formatting.natsorted(strings, key=None)[source]

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

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

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.formatting.picos_box(show=True)[source]

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

Print a footer line.

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

Print a header line.

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

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

Objects

picos.formatting.HEADER_WIDTH

Character length of headers and footers printed by PICOS.

Default value
35